ccqa 0.3.8 → 0.3.10

package/dist/bin/ccqa.mjs

@@ -1,26 +1,33 @@
 #!/usr/bin/env node
 import { createRequire } from "node:module";
 import { Command } from "commander";
-import { accessSync, readFileSync } from "node:fs";
+import { accessSync, readFileSync, statSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { access, mkdir, mkdtemp, readFile, readdir, rm, stat, unlink, writeFile } from "node:fs/promises";
-import { delimiter, dirname, join, resolve } from "node:path";
+import { delimiter, dirname, join, relative, resolve } from "node:path";
 import { query } from "@anthropic-ai/claude-agent-sdk";
 import matter from "gray-matter";
-import { spawn } from "node:child_process";
+import { execFile, spawn } from "node:child_process";
 import { createInterface } from "node:readline";
 import { tmpdir } from "node:os";
+import { createInterface as createInterface$1 } from "node:readline/promises";
+import { z } from "zod";
+import { promisify } from "node:util";
 //#region src/prompts/trace.ts
 function generateSessionName() {
 	return `ccqa-trace-${(/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-")}`;
 }
 function buildTraceSystemPrompt(spec, options) {
+	return buildTraceSystemPromptInner(spec, options, true);
+}
+function buildTraceSystemPromptInner(spec, options, emitRelatedPaths) {
 	const sessionName = options?.sessionName ?? generateSessionName();
 	const skipCookiesClear = options?.skipCookiesClear ?? false;
 	const stepsText = spec.steps.map((step) => `### ${step.id}: ${step.title}
 - **Instruction**: ${step.instruction}
 - **Expected**: ${step.expected}`).join("\n\n");
 	const prereqText = spec.prerequisites ? `## Prerequisites\n${spec.prerequisites}\n\n` : "";
+	const relatedPathsBlock = emitRelatedPaths ? buildRelatedPathsInstruction() : "";
 	return `You are an expert QA engineer executing a browser E2E test. Execute each step precisely and record every browser action as a structured log line.
 
 ## Session
@@ -106,6 +113,7 @@ For each step:
 - Do NOT retry a selector without taking a fresh snapshot first
 - Do NOT work around blockers (login walls, missing data, captchas) — stop and report
 - **Do NOT suppress errors** — never use \`2>/dev/null\`, \`|| true\`, \`; other-command\`, or any other technique that hides agent-browser failures. Each \`agent-browser\` command must run standalone so failures are properly detected and recorded.
+- **If \`agent-browser\` is not found, stop immediately.** Do not run \`which\`, \`find\`, \`npm ls\`, \`npm install\`, \`npx\`, \`brew\`, or any other discovery / installation command. Do not try alternate paths. The ccqa host already validates the binary before launching you, so if you see \`command not found\` it is a host-environment problem you cannot fix from inside the test run. Emit one line and terminate: \`ASSERTION_FAILED|step-XX|agent-browser binary not available in PATH\`.
 
 ## Source Code Reference
 
@@ -237,7 +245,7 @@ After each step (outside any code block):
 ROUTE_STEP|<step-id>|<step-title>|ACTION:<what you did>|OBSERVATION:<what you verified>|STATUS:<PASSED|FAILED|SKIPPED>
 \`\`\`
 
-## Start
+${relatedPathsBlock}## Start
 
 ${skipCookiesClear ? `A setup procedure has already been executed in this session. Do NOT clear cookies — keep the existing session state.
 
@@ -261,15 +269,49 @@ AB_ACTION|open|${spec.baseUrl}
 
 Then emit \`STEP_START|step-01|...\` and begin.`;
 }
+function buildRelatedPathsInstruction() {
+	return `## Post-run: emit \`relatedPaths\` block
+
+After all steps are complete (regardless of pass/fail) and **before** \`RUN_COMPLETED\`, you MUST emit a single \`RELATED_PATHS\` block. The host (not you) writes these paths into the spec's frontmatter — your only job is to emit the block.
+
+\`relatedPaths\` is a list of glob patterns identifying the source files this spec depends on. CI uses them to decide whether a code change should trigger a drift check for this spec.
+
+**Do NOT modify any source files.** You have only \`Read\`, \`Grep\`, and \`Glob\` for source inspection. The block you emit is the only output the host uses to update the spec.
+
+**Inputs to consider:**
+- The URLs you opened (\`AB_ACTION|open|...\`)
+- The aria-labels, placeholders, and visible texts you clicked / filled / waited on
+- The component / page / route files that render those strings (find them with \`Grep\`/\`Read\`/\`Glob\`)
+
+**How to choose paths:**
+1. For each URL the test navigates to, locate the route/page file and include it (e.g. \`src/app/tasks/page.tsx\`, \`src/pages/tasks/index.tsx\`).
+2. For each unique aria-label / placeholder / visible text you interacted with, \`Grep\` the codebase, find the defining component, and include either the file or its parent feature directory.
+3. Prefer **directory globs** (e.g. \`src/features/tasks/**\`) over individual files when several related components live in the same area. Otherwise list specific files.
+4. Skip third-party files (\`node_modules/\`), build output (\`dist/\`, \`.next/\`), and generated code.
+5. Be conservative — false positives (extra paths) are fine; false negatives (missing paths) cause drift to be missed in CI. When unsure whether a path is relevant, include it.
+
+**Output format (STRICT — one line per path, no leading dashes, no commentary inside the block):**
+
+\`\`\`
+RELATED_PATHS_BEGIN
+src/features/tasks/**
+src/app/tasks/page.tsx
+RELATED_PATHS_END
+\`\`\`
+
+Emit the block outside any other code block, on its own lines. If the test could not exercise the feature at all (e.g. blocked early), emit the block anyway with whatever paths you can identify; emit \`RELATED_PATHS_BEGIN\` immediately followed by \`RELATED_PATHS_END\` only if you genuinely could not identify any related file.
+
+`;
+}
 function buildTracePrompt(spec) {
 	return `Execute the test for "${spec.title}" at ${spec.baseUrl}.`;
 }
 function buildSetupTraceSystemPrompt(spec) {
-	return buildTraceSystemPrompt({
+	return buildTraceSystemPromptInner({
 		title: spec.title,
 		baseUrl: "about:blank",
 		steps: spec.steps
-	});
+	}, void 0, false);
 }
 function buildSetupTracePrompt(spec) {
 	return `Execute the setup procedure "${spec.title}". Follow each step precisely.`;
@@ -345,7 +387,7 @@ function resolveModel(explicit) {
 	return envModel && envModel.length > 0 ? envModel : void 0;
 }
 async function invokeClaudeStreaming(options, onEvent) {
-	const { prompt, systemPrompt, allowedTools, disableBuiltinTools = false, maxTurns, env, model, onAbAction, onAbActionFailed } = options;
+	const { prompt, systemPrompt, allowedTools, disableBuiltinTools = false, maxTurns, env, model, cwd, onAbAction, onAbActionFailed, silenceBashLog = false } = options;
 	const resolvedModel = resolveModel(model);
 	let lastAbToolUseId = null;
 	const sdkOptions = {
@@ -355,6 +397,7 @@ async function invokeClaudeStreaming(options, onEvent) {
 		permissionMode: "bypassPermissions",
 		allowDangerouslySkipPermissions: true,
 		...resolvedModel ? { model: resolvedModel } : {},
+		...cwd ? { cwd } : {},
 		...env ? { env: {
 			...process.env,
 			...env
@@ -397,7 +440,7 @@ async function invokeClaudeStreaming(options, onEvent) {
 	const q = await buildMessageStream(prompt, sdkOptions);
 	for await (const msg of q) {
 		onEvent(msg);
-		if (msg.type === "assistant") {
+		if (msg.type === "assistant" && !silenceBashLog) {
 			for (const block of msg.message.content ?? []) if (block.type === "tool_use" && block.name === "Bash") {
 				const cmd = block.input?.["command"];
 				if (typeof cmd === "string") bash(cmd);
@@ -518,20 +561,93 @@ async function* replayMockMessages(path) {
 	}
 }
 //#endregion
+//#region src/spec/parser.ts
+function parseTestSpec(content) {
+	const { data, content: body } = matter(content);
+	const steps = parseSteps(body);
+	const prerequisites = parsePrerequisites(body);
+	return {
+		title: String(data["title"] ?? "Untitled"),
+		baseUrl: String(data["baseUrl"] ?? "http://localhost:3000"),
+		prerequisites: prerequisites || void 0,
+		setups: parseSetupRefs(data["setups"]),
+		relatedPaths: parseRelatedPaths(data["relatedPaths"]),
+		steps
+	};
+}
+function parseRelatedPaths(raw) {
+	if (!Array.isArray(raw)) return void 0;
+	const paths = [];
+	for (const item of raw) if (typeof item === "string" && item.trim().length > 0) paths.push(item.trim());
+	return paths.length > 0 ? paths : void 0;
+}
+function parseSetupSpec(content) {
+	const { data, content: body } = matter(content);
+	const steps = parseSteps(body);
+	const placeholders = parsePlaceholders(data["placeholders"]);
+	return {
+		title: String(data["title"] ?? "Untitled"),
+		placeholders: Object.keys(placeholders).length > 0 ? placeholders : void 0,
+		steps
+	};
+}
+function parsePlaceholders(raw) {
+	if (!raw || typeof raw !== "object") return {};
+	const result = {};
+	for (const [key, val] of Object.entries(raw)) if (val && typeof val === "object" && "dummy" in val) {
+		const v = val;
+		result[key] = {
+			dummy: String(v["dummy"]),
+			description: v["description"] ? String(v["description"]) : void 0
+		};
+	}
+	return result;
+}
+function parseSetupRefs(raw) {
+	if (!Array.isArray(raw)) return void 0;
+	const refs = [];
+	for (const item of raw) if (typeof item === "object" && item !== null && "name" in item) {
+		const i = item;
+		refs.push({
+			name: String(i["name"]),
+			params: i["params"] && typeof i["params"] === "object" ? Object.fromEntries(Object.entries(i["params"]).map(([k, v]) => [k, String(v)])) : void 0
+		});
+	}
+	return refs.length > 0 ? refs : void 0;
+}
+function parsePrerequisites(body) {
+	const match = body.match(/##\s+Prerequisites\s+([\s\S]*?)(?=##|$)/);
+	if (!match || !match[1]) return null;
+	return match[1].trim();
+}
+function parseSteps(body) {
+	const stepBlocks = body.split(/###\s+Step\s+\d+:/);
+	const steps = [];
+	for (let i = 1; i < stepBlocks.length; i++) {
+		const block = stepBlocks[i];
+		if (!block) continue;
+		const titleMatch = block.match(/^(.+)/);
+		const instructionMatch = block.match(/\*\*Instruction\*\*:\s*(.+)/);
+		const expectedMatch = block.match(/\*\*Expected\*\*:\s*(.+)/);
+		if (!titleMatch || !instructionMatch || !expectedMatch) continue;
+		steps.push({
+			id: `step-${String(i).padStart(2, "0")}`,
+			title: titleMatch[1]?.trim() ?? "",
+			instruction: instructionMatch[1]?.trim() ?? "",
+			expected: expectedMatch[1]?.trim() ?? ""
+		});
+	}
+	return steps;
+}
+//#endregion
 //#region src/store/index.ts
 const CCQA_DIR = ".ccqa";
 function getCcqaDir(cwd = process.cwd()) {
 	return join(cwd, CCQA_DIR);
 }
-/**
-* Accepts both the canonical 2-segment alias and the on-disk 4-segment path
-* (which is what shell tab-completion produces):
-*   - "tasks/create-and-complete"
-*   - "features/tasks/test-cases/create-and-complete"
-*   - ".ccqa/features/tasks/test-cases/create-and-complete"
-* All forms resolve to { featureName: "tasks", specName: "create-and-complete" }.
-* Trailing slashes are tolerated.
-*/
+function specKey(ref) {
+	return `${ref.featureName}/${ref.specName}`;
+}
 function parseSpecPath(specPath) {
 	const parts = specPath.replace(/^\.\/+/, "").replace(/\/+$/, "").split("/").filter((p) => p.length > 0);
 	if (parts[0] === ".ccqa") parts.shift();
@@ -560,6 +676,32 @@ async function readSpecFile(featureName, specName, cwd) {
 		throw new Error(`Spec file not found: ${specPath}`);
 	});
 }
+async function tryReadSpecFile(featureName, specName, cwd) {
+	return readFile(join(getSpecDir(featureName, specName, cwd), "test-spec.md"), "utf-8").catch(() => null);
+}
+async function saveSpecFile(featureName, specName, content, cwd) {
+	const specDir = getSpecDir(featureName, specName, cwd);
+	await mkdir(specDir, { recursive: true });
+	const specPath = join(specDir, "test-spec.md");
+	await writeFile(specPath, content.endsWith("\n") ? content : content + "\n", "utf-8");
+	return specPath;
+}
+/**
+* Replace (or insert) the `relatedPaths` key in the spec's YAML frontmatter.
+* Preserves every other frontmatter key and the entire body. Returns the
+* absolute path that was written, or null if the spec file does not exist.
+*/
+async function updateSpecRelatedPaths(featureName, specName, relatedPaths, cwd) {
+	const specPath = join(getSpecDir(featureName, specName, cwd), "test-spec.md");
+	const existing = await readFile(specPath, "utf-8").catch(() => null);
+	if (existing === null) return null;
+	const parsed = matter(existing);
+	const data = { ...parsed.data };
+	if (relatedPaths.length > 0) data["relatedPaths"] = relatedPaths;
+	else delete data["relatedPaths"];
+	await writeFile(specPath, matter.stringify(parsed.content, data), "utf-8");
+	return specPath;
+}
 async function saveRoute(featureName, specName, route, cwd) {
 	const specDir = getSpecDir(featureName, specName, cwd);
 	await mkdir(specDir, { recursive: true });
@@ -645,6 +787,44 @@ async function listAllSpecs(cwd) {
 async function listSpecsForFeature(featureName, cwd) {
 	return readdir(join(getFeatureDir(featureName, cwd), "test-cases")).catch(() => []);
 }
+/**
+* Lists every feature/spec dir under .ccqa/features/, regardless of whether
+* the spec is fully drafted yet. Each spec file is read at most once: title
+* and relatedPaths are both extracted from the same parse.
+*/
+async function listFeatureTree(cwd) {
+	const featuresDir = join(getCcqaDir(cwd), "features");
+	const featureDirs = await readdir(featuresDir).catch(() => []);
+	return Promise.all(featureDirs.map(async (featureName) => {
+		const testCasesDir = join(featuresDir, featureName, "test-cases");
+		const specDirs = await readdir(testCasesDir).catch(() => []);
+		return {
+			featureName,
+			specs: await Promise.all(specDirs.map(async (specName) => {
+				const content = await readFile(join(testCasesDir, specName, "test-spec.md"), "utf-8").catch(() => null);
+				if (content === null) return {
+					specName,
+					hasSpecFile: false
+				};
+				try {
+					const spec = parseTestSpec(content);
+					const entry = {
+						specName,
+						hasSpecFile: true
+					};
+					if (spec.title && spec.title !== "Untitled") entry.title = spec.title;
+					if (spec.relatedPaths) entry.relatedPaths = spec.relatedPaths;
+					return entry;
+				} catch {
+					return {
+						specName,
+						hasSpecFile: true
+					};
+				}
+			}))
+		};
+	}));
+}
 function routeToMarkdown(route) {
 	const lines = [
 		"---",
@@ -665,76 +845,28 @@ function routeToMarkdown(route) {
 	return lines.join("\n");
 }
 //#endregion
-//#region src/spec/parser.ts
-function parseTestSpec(content) {
-	const { data, content: body } = matter(content);
-	const steps = parseSteps(body);
-	const prerequisites = parsePrerequisites(body);
-	return {
-		title: String(data["title"] ?? "Untitled"),
-		baseUrl: String(data["baseUrl"] ?? "http://localhost:3000"),
-		prerequisites: prerequisites || void 0,
-		setups: parseSetupRefs(data["setups"]),
-		steps
-	};
-}
-function parseSetupSpec(content) {
-	const { data, content: body } = matter(content);
-	const steps = parseSteps(body);
-	const placeholders = parsePlaceholders(data["placeholders"]);
-	return {
-		title: String(data["title"] ?? "Untitled"),
-		placeholders: Object.keys(placeholders).length > 0 ? placeholders : void 0,
-		steps
-	};
-}
-function parsePlaceholders(raw) {
-	if (!raw || typeof raw !== "object") return {};
-	const result = {};
-	for (const [key, val] of Object.entries(raw)) if (val && typeof val === "object" && "dummy" in val) {
-		const v = val;
-		result[key] = {
-			dummy: String(v["dummy"]),
-			description: v["description"] ? String(v["description"]) : void 0
-		};
-	}
-	return result;
-}
-function parseSetupRefs(raw) {
-	if (!Array.isArray(raw)) return void 0;
-	const refs = [];
-	for (const item of raw) if (typeof item === "object" && item !== null && "name" in item) {
-		const i = item;
-		refs.push({
-			name: String(i["name"]),
-			params: i["params"] && typeof i["params"] === "object" ? Object.fromEntries(Object.entries(i["params"]).map(([k, v]) => [k, String(v)])) : void 0
-		});
-	}
-	return refs.length > 0 ? refs : void 0;
-}
-function parsePrerequisites(body) {
-	const match = body.match(/##\s+Prerequisites\s+([\s\S]*?)(?=##|$)/);
-	if (!match || !match[1]) return null;
-	return match[1].trim();
-}
-function parseSteps(body) {
-	const stepBlocks = body.split(/###\s+Step\s+\d+:/);
-	const steps = [];
-	for (let i = 1; i < stepBlocks.length; i++) {
-		const block = stepBlocks[i];
-		if (!block) continue;
-		const titleMatch = block.match(/^(.+)/);
-		const instructionMatch = block.match(/\*\*Instruction\*\*:\s*(.+)/);
-		const expectedMatch = block.match(/\*\*Expected\*\*:\s*(.+)/);
-		if (!titleMatch || !instructionMatch || !expectedMatch) continue;
-		steps.push({
-			id: `step-${String(i).padStart(2, "0")}`,
-			title: titleMatch[1]?.trim() ?? "",
-			instruction: instructionMatch[1]?.trim() ?? "",
-			expected: expectedMatch[1]?.trim() ?? ""
-		});
+//#region src/drift/parse-related-paths.ts
+/**
+* Pull a `RELATED_PATHS_BEGIN ... RELATED_PATHS_END` block out of the trace
+* agent's combined text output. Lines inside the block become entries; blank
+* lines, bullet markers, and code fences are tolerated. Returns null when the
+* agent did not emit a block at all so the caller can warn instead of silently
+* clearing the spec's existing relatedPaths.
+*/
+function parseRelatedPathsBlock(text) {
+	const match = text.match(/RELATED_PATHS_BEGIN\s*\n?([\s\S]*?)\n?RELATED_PATHS_END/);
+	if (!match || match[1] === void 0) return null;
+	const seen = /* @__PURE__ */ new Set();
+	const out = [];
+	for (const raw of match[1].split("\n")) {
+		const line = raw.replace(/^```.*$/, "").trim();
+		if (!line) continue;
+		const cleaned = line.replace(/^[-*]\s+/, "").trim();
+		if (!cleaned || seen.has(cleaned)) continue;
+		seen.add(cleaned);
+		out.push(cleaned);
 	}
-	return steps;
+	return out;
 }
 //#endregion
 //#region src/runtime/bundled-config.ts
@@ -834,22 +966,46 @@ function waitExit(child) {
 //#endregion
 //#region src/runtime/agent-browser-bin.ts
 const require$1 = createRequire(import.meta.url);
+function hasAgentBrowserShim(dir) {
+	try {
+		statSync(join(dir, "agent-browser"));
+		return true;
+	} catch {
+		return false;
+	}
+}
+/**
+* Walks up from `start` looking for a `node_modules/.bin/agent-browser` shim.
+* Returns the .bin directory containing the shim, or null if none is found.
+*/
+function findNodeModulesBin(start) {
+	let cur = start;
+	while (true) {
+		const candidate = join(cur, "node_modules", ".bin");
+		if (hasAgentBrowserShim(candidate)) return candidate;
+		const parent = dirname(cur);
+		if (parent === cur) return null;
+		cur = parent;
+	}
+}
 /**
 * Resolves the directory containing the `agent-browser` shim that npm/pnpm
 * exposes on PATH for the peer-installed package. Used by `ccqa trace` to
 * prepend this directory to PATH so the Claude subprocess can invoke
 * `agent-browser ...` without requiring a global install.
 *
-* Returns null if agent-browser cannot be resolved (peer not installed).
+* Returns null if agent-browser cannot be located.
 */
 function resolveAgentBrowserBinDir() {
-	let pkgJsonPath;
+	const fromCwd = findNodeModulesBin(process.cwd());
+	if (fromCwd) return fromCwd;
+	const fromSelf = findNodeModulesBin(dirname(require$1.resolve("agent-browser/package.json")));
+	if (fromSelf) return fromSelf;
 	try {
-		pkgJsonPath = require$1.resolve("agent-browser/package.json");
-	} catch {
-		return null;
-	}
-	return join(dirname(pkgJsonPath), "node_modules", ".bin");
+		const candidate = join(dirname(require$1.resolve("agent-browser/package.json")), "node_modules", ".bin");
+		if (hasAgentBrowserShim(candidate)) return candidate;
+	} catch {}
+	return null;
 }
 /**
 * Returns a PATH string with the agent-browser shim directory prepended,
@@ -863,6 +1019,48 @@ function pathWithAgentBrowserShim(currentPath) {
 	if (path.split(delimiter).includes(dir)) return path;
 	return dir + delimiter + path;
 }
+/**
+* Confirms before launching Claude that an `agent-browser` shim is reachable
+* via PATH. We do this up front so a missing peer dependency fails fast with
+* a clear message, instead of Claude burning tokens probing the system with
+* `which`, `find`, `npm install`, etc.
+*
+* The `resolver` argument is for tests; production calls take no args.
+*/
+function assertAgentBrowserAvailable(resolver = resolveAgentBrowserBinDir) {
+	const dir = resolver();
+	if (!dir) throw new AgentBrowserUnavailableError();
+	const shim = join(dir, "agent-browser");
+	try {
+		const s = statSync(shim);
+		if (!s.isFile() && !s.isSymbolicLink()) throw new AgentBrowserUnavailableError();
+	} catch {
+		throw new AgentBrowserUnavailableError();
+	}
+	return dir;
+}
+var AgentBrowserUnavailableError = class extends Error {
+	constructor() {
+		super("agent-browser binary not found on PATH");
+		this.name = "AgentBrowserUnavailableError";
+	}
+};
+/** Human-readable explanation shown to the user when the guard fires. */
+function formatAgentBrowserUnavailableMessage() {
+	return [
+		"agent-browser is not installed or not on PATH.",
+		"",
+		"ccqa drives the browser via the peer-installed `agent-browser` package.",
+		"Install it in this project:",
+		"",
+		"  pnpm add -D agent-browser",
+		"  # or",
+		"  npm install -D agent-browser",
+		"",
+		"If it is already installed, make sure you are running ccqa from the",
+		"project root (or via your package runner, e.g. `pnpm exec ccqa ...`)."
+	].join("\n");
+}
 //#endregion
 //#region src/runtime/env-vars.ts
 const ENV_VAR_RE = /\$\{([A-Z_][A-Z0-9_]*)\}|\$([A-Z_][A-Z0-9_]*)/g;
@@ -921,6 +1119,15 @@ const traceCommand = new Command("trace").argument("<feature/spec>", "Spec id in
 });
 async function runTrace(featureName, specName, model) {
 	header("trace", `${featureName}/${specName}`);
+	try {
+		meta("agent-browser", assertAgentBrowserAvailable());
+	} catch (e) {
+		if (e instanceof AgentBrowserUnavailableError) {
+			error(formatAgentBrowserUnavailableMessage());
+			process.exit(1);
+		}
+		throw e;
+	}
 	await ensureCcqaDir();
 	const spec = parseTestSpec(await readSpecFile(featureName, specName));
 	const hasSetups = (spec.setups?.length ?? 0) > 0;
@@ -945,6 +1152,7 @@ async function runTrace(featureName, specName, model) {
 	const routeSteps = [];
 	let overallStatus = "passed";
 	const traceActions = [];
+	let relatedPathsBuffer = null;
 	const { isError } = await invokeClaudeStreaming({
 		prompt,
 		systemPrompt,
@@ -971,6 +1179,11 @@ async function runTrace(featureName, specName, model) {
 		for (const block of msg.message.content ?? []) {
 			if (block.type !== "text" || !block.text) continue;
 			const text = block.text;
+			if (relatedPathsBuffer !== null) relatedPathsBuffer += text + "\n";
+			else {
+				const idx = text.indexOf("RELATED_PATHS_BEGIN");
+				if (idx !== -1) relatedPathsBuffer = text.slice(idx) + "\n";
+			}
 			const statusLine = parseStatusLine(text);
 			if (statusLine) step(statusLine.type, statusLine.stepId, statusLine.detail);
 			for (const line of text.split("\n")) {
@@ -1001,6 +1214,11 @@ async function runTrace(featureName, specName, model) {
 	meta("saved", actionsPath);
 	meta("actions", traceActions.length);
 	meta("status", overallStatus.toUpperCase());
+	const relatedPaths = relatedPathsBuffer !== null ? parseRelatedPathsBlock(relatedPathsBuffer) : null;
+	if (relatedPaths !== null) {
+		const written = await updateSpecRelatedPaths(featureName, specName, relatedPaths);
+		if (written) meta("relatedPaths", `${relatedPaths.length} path(s) written to ${written}`);
+	} else warn("trace did not emit a RELATED_PATHS block; drift --changed cannot scope this spec");
 	hint(`run 'ccqa generate ${featureName}/${specName}' to generate a test script`);
 }
 /**
@@ -1567,7 +1785,7 @@ async function diagnose(input, options = {}) {
 				reason: "diagnose returned no parseable diagnosis JSON"
 			},
 			confidence: 0,
-			reasoning: truncate$1(raw, 1e3)
+			reasoning: truncate$2(raw, 1e3)
 		},
 		raw,
 		sdkError: false
@@ -1624,7 +1842,7 @@ function extractJsonCandidates(raw) {
 	}
 	return out;
 }
-function truncate$1(s, max) {
+function truncate$2(s, max) {
 	return s.length <= max ? s : `${s.slice(0, max)}... [truncated, ${s.length - max} more chars]`;
 }
 function stripFence(raw) {
@@ -1852,11 +2070,11 @@ async function captureSnapshot(sessionName) {
 				resolve(null);
 				return;
 			}
-			resolve(truncate(trimmed, MAX_OUTPUT_BYTES));
+			resolve(truncate$1(trimmed, MAX_OUTPUT_BYTES));
 		});
 	});
 }
-function truncate(s, maxBytes) {
+function truncate$1(s, maxBytes) {
 	if (s.length <= maxBytes) return s;
 	return `${s.slice(0, maxBytes)}\n... [truncated, ${s.length - maxBytes} more chars]`;
 }
@@ -2426,6 +2644,15 @@ const traceSetupCommand = new Command("trace-setup").argument("<name>", "Setup n
 });
 async function runTraceSetup(name, model) {
 	header("trace-setup", name);
+	try {
+		meta("agent-browser", assertAgentBrowserAvailable());
+	} catch (e) {
+		if (e instanceof AgentBrowserUnavailableError) {
+			error(formatAgentBrowserUnavailableMessage());
+			process.exit(1);
+		}
+		throw e;
+	}
 	await ensureCcqaDir();
 	const spec = parseSetupSpec(await readSetupSpecFile(name));
 	const resolvedSpec = replacePlaceholdersWithDummies(spec);
@@ -2695,6 +2922,1256 @@ async function cleanupActions(actions, model) {
 	return actions;
 }
 //#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.
+*/
+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/draft.ts
+function buildNamingSystemPrompt() {
+	return `You name a new ccqa test case based on the user's intent and the existing feature tree.
+
+ccqa test cases live under \`.ccqa/features/<featureName>/test-cases/<specName>/test-spec.md\`.
+
+## Naming rules
+
+- featureName and specName are kebab-case ASCII (lowercase, words separated by '-').
+- featureName: a broad area (e.g. "tasks", "auth", "billing", "search").
+- specName: a short scenario name (e.g. "create-and-complete", "login-with-email", "search-by-tag").
+- Reuse existing featureName when the user's intent fits an existing area. Only invent a new featureName when the existing tree clearly does not cover the area.
+- specName must NOT collide with an existing spec under the chosen feature. If the natural name collides, pick a different one that distinguishes the new scenario from the existing ones.
+- Use the codebase (Read/Grep/Glob) sparingly to confirm domain vocabulary if helpful. Do not over-explore.
+
+## Output (STRICT)
+
+Output ONE fenced \`\`\`json block, nothing else outside it:
+
+{
+  "featureName": "<kebab-case>",
+  "specName": "<kebab-case>",
+  "reason": "<one short sentence: why this name and how it relates to existing specs>"
+}
+`;
+}
+function buildNamingPrompt(intent, tree) {
+	return `## User intent
+
+${intent}
+
+## Existing feature tree
+
+${tree.length === 0 ? "(no existing features yet)" : tree.map((f) => {
+		const specLines = f.specs.length === 0 ? "  (no specs yet)" : f.specs.map((s) => `  - ${s.specName}${s.title ? ` — ${s.title}` : ""}`).join("\n");
+		return `- ${f.featureName}/\n${specLines}`;
+	}).join("\n")}
+
+## Task
+
+Pick featureName and specName for the new test case. Follow the naming rules. Avoid colliding with any existing specName under the chosen feature.
+`;
+}
+function buildDraftSystemPrompt() {
+	return `You are a QA engineer drafting and refining a ccqa test-spec.md.
+
+The CLI runs you in a loop: each turn the user gives an intent (first run) or a refinement instruction (later runs). You read the codebase, validate the spec, and return a single JSON report. The CLI displays a diff and asks the user whether to apply.
+
+## test-spec.md format (STRICT)
+
+YAML frontmatter + Markdown body.
+
+Frontmatter fields:
+- title: string (required)
+- baseUrl: string (required, e.g. http://localhost:3000)
+- prerequisites: string (optional, free text)
+- setups: array of { name: string, params?: Record<string,string> } (optional)
+- relatedPaths: array of string (optional) — glob patterns identifying source files this spec depends on. Used by \`ccqa drift --changed\` in CI to skip drift checks for unrelated changes.
+
+Body must contain a \`## Steps\` section followed by step blocks:
+
+\`\`\`
+### Step 1: <short title>
+- **Instruction**: <imperative, one sentence>
+- **Expected**: <observable outcome>
+
+### Step 2: <short title>
+...
+\`\`\`
+
+## Quality rules
+
+- One user-facing action per step (login, click, fill, navigate, ...).
+- **Expected** must be assertion-friendly: visible text, URL pattern, element state.
+- Forbidden in **Expected**: timestamps, exact counts, session IDs, internal state.
+- 3–8 steps is typical. Fewer means too coarse; more means too fine.
+
+## Workflow (use Read / Grep / Glob extensively)
+
+1. Read the codebase under cwd to find concrete strings: routes, button labels, aria-labels, page titles, placeholders. Use those exact strings in **Expected**.
+2. If the spec references setups, Read \`.ccqa/setups/<name>/setup-spec.md\` and verify each \`params\` key matches the setup's \`placeholders\`.
+3. Populate \`relatedPaths\` in the frontmatter with **provisional** glob patterns pointing at the source files this spec touches: the route/page file for each URL the spec visits, plus the component files (or their parent feature directory) that render the aria-labels, placeholders, or visible texts the spec asserts on. Prefer directory globs (e.g. \`src/features/tasks/**\`) when several files in one area are involved. Be conservative — include a path if you're unsure rather than omit it. \`ccqa trace\` will refine this list later from real browser observations.
+4. Validate the (current or proposed) spec on four axes — emit one issue per finding:
+   - **assertable**: each Expected can be verified against a string/URL/state that exists in code.
+   - **setups**: referenced setup exists; params keys match placeholders.
+   - **granularity**: not too coarse (multiple actions per step) nor too fine (snapshot-only steps); order is logical.
+   - **unimplemented**: any feature mentioned in the spec that you cannot find in code.
+
+## Output contract (STRICT)
+
+Output exactly ONE fenced \`\`\`json code block, and nothing else outside it. No prose before or after.
+
+Schema:
+
+\`\`\`json
+{
+  "issues": [
+    {
+      "severity": "OK" | "WARN" | "ERROR",
+      "category": "assertable" | "setups" | "granularity" | "unimplemented",
+      "stepId": "step-01" | null,
+      "message": "<one-line summary>",
+      "detail": "<optional, multiline explanation>"
+    }
+  ],
+  "patch": "<COMPLETE rewritten test-spec.md, or empty string if no changes>"
+}
+\`\`\`
+
+## Patch rules
+
+- \`patch\` must be the COMPLETE file content if non-empty (never a diff fragment).
+- The CLI replaces the file atomically with \`patch\`.
+- For **create** mode: produce a fresh spec from the user intent.
+- For **refine** mode with a non-empty user instruction: apply the user's request, plus fix any issues it introduces. Preserve the user's wording elsewhere.
+- For **refine** mode with an empty user instruction: only fix issues you find against the current spec; if everything is fine, return \`patch: ""\`.
+- If \`patch\` is the same as the current spec, return \`patch: ""\` instead.
+`;
+}
+function buildDraftPrompt(input) {
+	const { mode, existing, userInput } = input;
+	if (mode === "create") return `## Mode
+
+create — no spec exists yet at the target path. Produce a fresh test-spec.md.
+
+## User intent
+
+${userInput}
+
+## Task
+
+Read the codebase under cwd. Discover concrete strings (routes, labels, titles). Produce a complete test-spec.md as the \`patch\` field, plus any issues you'd flag about your own draft.
+`;
+	return `## Mode
+
+refine — a spec already exists. Apply the user's instruction (if any) and validate against the codebase.
+
+## Current spec
+
+\`\`\`markdown
+${existing}\`\`\`
+
+${userInput ? `## User refinement instruction\n\n${userInput}\n` : `## User refinement instruction\n\n(empty — re-validate the current spec against the codebase; only emit a non-empty patch if something is actually wrong)\n`}
+## Task
+
+1. Read the codebase under cwd and any referenced setups.
+2. If the user's instruction is non-empty, apply it to the spec.
+3. Validate the resulting spec on the four axes. Emit issues.
+4. Return the complete updated spec as \`patch\`. If no changes are needed, return \`patch: ""\`.
+`;
+}
+//#endregion
+//#region src/types.ts
+const TestStepSchema = z.object({
+	id: z.string(),
+	title: z.string(),
+	instruction: z.string(),
+	expected: z.string()
+});
+const SetupRefSchema = z.object({
+	name: z.string(),
+	params: z.record(z.string(), z.string()).optional()
+});
+z.object({
+	title: z.string(),
+	baseUrl: z.string(),
+	prerequisites: z.string().optional(),
+	setups: z.array(SetupRefSchema).optional(),
+	relatedPaths: z.array(z.string()).optional(),
+	steps: z.array(TestStepSchema)
+});
+const PlaceholderDefSchema = z.object({
+	dummy: z.string(),
+	description: z.string().optional()
+});
+z.object({
+	title: z.string(),
+	placeholders: z.record(z.string(), PlaceholderDefSchema).optional(),
+	steps: z.array(TestStepSchema)
+});
+const RouteStepSchema = z.object({
+	title: z.string(),
+	action: z.string(),
+	observation: z.string(),
+	status: z.enum([
+		"PASSED",
+		"FAILED",
+		"SKIPPED"
+	]),
+	reason: z.string().optional()
+});
+z.object({
+	specName: z.string(),
+	timestamp: z.string(),
+	status: z.enum(["passed", "failed"]),
+	steps: z.array(RouteStepSchema)
+});
+const DraftIssueSchema = z.object({
+	severity: z.enum([
+		"OK",
+		"WARN",
+		"ERROR"
+	]),
+	category: z.enum([
+		"assertable",
+		"setups",
+		"granularity",
+		"unimplemented"
+	]),
+	stepId: z.string().nullable(),
+	message: z.string(),
+	detail: z.string().optional()
+});
+const DraftReportSchema = z.object({
+	issues: z.array(DraftIssueSchema),
+	patch: z.string()
+});
+const DraftNamingSchema = z.object({
+	featureName: z.string().min(1),
+	specName: z.string().min(1),
+	reason: z.string().optional()
+});
+//#endregion
+//#region src/cli/draft.ts
+const CATEGORY_LABEL$1 = {
+	assertable: "Assertability",
+	setups: "Setup references",
+	granularity: "Step granularity",
+	unimplemented: "Unimplemented checks"
+};
+const draftCommand = new Command("draft").argument("[feature/spec]", "Optional spec path (e.g. tasks/create-and-complete). If omitted, Claude proposes one from your intent.").description("Interactively draft and refine a test-spec.md with Claude Code").option("--instruction <text>", "Non-interactive single-shot instruction (skips the interactive loop)").option("--apply", "Auto-apply each generated patch without [y/N] confirmation", false).action(async (specPath, opts) => {
+	await ensureCcqaDir();
+	let featureName;
+	let specName;
+	let prefilledIntent = null;
+	if (specPath) ({featureName, specName} = parseSpecPath(specPath));
+	else {
+		const { naming, intent } = await proposeNaming(opts);
+		featureName = naming.featureName;
+		specName = naming.specName;
+		prefilledIntent = intent;
+	}
+	await runDraft(featureName, specName, opts, prefilledIntent);
+});
+async function runDraft(featureName, specName, opts, prefilledIntent) {
+	header("draft", `${featureName}/${specName}`);
+	const oneShot = opts.instruction !== void 0;
+	let useIntentOnce = prefilledIntent !== null && !oneShot;
+	while (true) {
+		const existing = await tryReadSpecFile(featureName, specName);
+		const isFirstRun = existing === null;
+		let userInput;
+		if (oneShot) userInput = opts.instruction ?? "";
+		else if (useIntentOnce && isFirstRun) {
+			userInput = prefilledIntent ?? "";
+			useIntentOnce = false;
+		} else userInput = await prompt(isFirstRun ? "What do you want to test? > " : "How would you like to refine? (empty = re-validate) > ");
+		if (isFirstRun && !userInput.trim()) {
+			error("intent required for the first draft (no spec exists yet)");
+			process.exit(1);
+		}
+		const turnResult = await runOneTurn({
+			featureName,
+			specName,
+			existing,
+			userInput: userInput.trim(),
+			autoApply: opts.apply === true
+		});
+		if (oneShot) process.exit(turnResult.hasError && !turnResult.applied ? 1 : 0);
+		blank();
+		if (/^y/i.test(await prompt("Are you done with this draft? [y/N] "))) {
+			info("draft session complete.");
+			hint(`run 'ccqa trace ${featureName}/${specName}' to record actions`);
+			process.exit(0);
+		}
+	}
+}
+async function runOneTurn(input) {
+	const { featureName, specName, existing, userInput, autoApply } = input;
+	const isFirstRun = existing === null;
+	const systemPrompt = buildDraftSystemPrompt();
+	const userPrompt = buildDraftPrompt({
+		mode: isFirstRun ? "create" : "refine",
+		existing: existing ?? "",
+		userInput
+	});
+	info(isFirstRun ? "Reading codebase and drafting spec..." : "Re-validating spec against codebase...");
+	const toolCounts = {};
+	const startedAt = Date.now();
+	const { result, isError } = await invokeClaudeStreaming({
+		prompt: userPrompt,
+		systemPrompt,
+		allowedTools: [
+			"Read",
+			"Grep",
+			"Glob"
+		],
+		silenceBashLog: true
+	}, (msg) => {
+		if (msg.type !== "assistant") return;
+		for (const block of msg.message.content ?? []) if (block.type === "tool_use") toolCounts[block.name] = (toolCounts[block.name] ?? 0) + 1;
+	});
+	printToolSummary(toolCounts, Date.now() - startedAt);
+	if (isError) {
+		error("Claude returned an error result");
+		return {
+			hasError: true,
+			applied: false
+		};
+	}
+	const json = extractJsonBlock(result);
+	if (!json) {
+		error("Claude did not return a json block");
+		warn(`raw tail: ${truncate(result, 200)}`);
+		return {
+			hasError: true,
+			applied: false
+		};
+	}
+	let report;
+	try {
+		report = DraftReportSchema.parse(JSON.parse(json));
+	} catch (e) {
+		error(`failed to parse draft report: ${e.message}`);
+		return {
+			hasError: true,
+			applied: false
+		};
+	}
+	const hasError = printReviewBlock(report.issues);
+	const original = existing ?? "";
+	if (!report.patch || report.patch === original) {
+		blank();
+		info("no changes proposed.");
+		return {
+			hasError,
+			applied: false
+		};
+	}
+	blank();
+	info("--- proposed changes ---");
+	printUnifiedDiff(original, report.patch);
+	blank();
+	if (!(autoApply ? true : /^y/i.test(await prompt("Apply this patch? [y/N] ")))) {
+		info("aborted — no changes applied.");
+		return {
+			hasError,
+			applied: false
+		};
+	}
+	try {
+		parseTestSpec(report.patch);
+	} catch (e) {
+		error(`refused to apply: patch failed validation (${e.message})`);
+		return {
+			hasError: true,
+			applied: false
+		};
+	}
+	meta("saved", await saveSpecFile(featureName, specName, report.patch));
+	return {
+		hasError,
+		applied: true
+	};
+}
+async function prompt(question) {
+	const rl = createInterface$1({
+		input: process.stdin,
+		output: process.stdout
+	});
+	rl.on("SIGINT", () => {
+		rl.close();
+		process.exit(130);
+	});
+	try {
+		return (await rl.question(question)).trim();
+	} finally {
+		rl.close();
+	}
+}
+/** Aggregated tool-call counts shown after each Claude turn. */
+function formatToolSummary(counts, elapsedMs) {
+	const entries = Object.entries(counts).filter(([, n]) => n > 0).sort((a, b) => b[1] - a[1]).map(([name, n]) => `${n} ${name}`);
+	return `  ✓ ${entries.length === 0 ? "no tool calls" : entries.join(", ")}  (${(elapsedMs / 1e3).toFixed(1)}s)`;
+}
+function printToolSummary(counts, elapsedMs) {
+	process.stdout.write(`${formatToolSummary(counts, elapsedMs)}\n`);
+}
+/**
+* Renders the review report as a visually separated block, grouped by
+* severity. ERROR and WARN findings get full detail; OK findings collapse
+* to a one-line summary of category names. Returns whether any ERROR
+* severity was emitted.
+*/
+function printReviewBlock(issues) {
+	const RULE = "─".repeat(67);
+	const errors = issues.filter((i) => i.severity === "ERROR");
+	const warnings = issues.filter((i) => i.severity === "WARN");
+	const passed = issues.filter((i) => i.severity === "OK");
+	const headerParts = [];
+	if (errors.length) headerParts.push(`${errors.length} error${errors.length > 1 ? "s" : ""}`);
+	if (warnings.length) headerParts.push(`${warnings.length} warning${warnings.length > 1 ? "s" : ""}`);
+	if (passed.length) headerParts.push(`${passed.length} passed`);
+	const headerSuffix = headerParts.length ? `  (${headerParts.join(", ")})` : "";
+	const ruleLen = Math.max(0, 60 - headerSuffix.length);
+	process.stdout.write(`\n── Review${headerSuffix} ${"─".repeat(ruleLen)}\n\n`);
+	if (issues.length === 0) {
+		process.stdout.write("  (no findings)\n");
+		process.stdout.write(`\n${RULE}\n\n`);
+		return false;
+	}
+	if (errors.length) {
+		process.stdout.write(`  ERRORS (${errors.length})\n`);
+		for (const issue of errors) writeFinding$1(issue);
+		process.stdout.write("\n");
+	}
+	if (warnings.length) {
+		process.stdout.write(`  WARNINGS (${warnings.length})\n`);
+		for (const issue of warnings) writeFinding$1(issue);
+		process.stdout.write("\n");
+	}
+	if (passed.length) {
+		const names = passed.map((i) => CATEGORY_LABEL$1[i.category]).join(", ");
+		process.stdout.write(`  PASSED (${passed.length})\n    ${names}\n`);
+	}
+	process.stdout.write(`\n${RULE}\n\n`);
+	return errors.length > 0;
+}
+function writeFinding$1(issue) {
+	const stepPart = issue.stepId ? `  ${issue.stepId}` : "";
+	process.stdout.write(`    ${CATEGORY_LABEL$1[issue.category]}${stepPart}\n`);
+	process.stdout.write(`      ${issue.message}\n`);
+	if (issue.detail) process.stdout.write(`      └ ${issue.detail.replace(/\n/g, "\n        ")}\n`);
+}
+async function proposeNaming(opts) {
+	const oneShot = opts.instruction !== void 0;
+	const intent = oneShot ? opts.instruction ?? "" : await prompt("What do you want to test? > ");
+	if (!intent.trim()) {
+		error("intent required to propose a feature/spec name");
+		process.exit(1);
+	}
+	const tree = await listFeatureTree();
+	const treeForPrompt = tree.map((f) => ({
+		featureName: f.featureName,
+		specs: f.specs.map((s) => ({
+			specName: s.specName,
+			...s.title ? { title: s.title } : {}
+		}))
+	}));
+	info("Proposing a feature/spec name based on your intent...");
+	const { result, isError } = await invokeClaudeStreaming({
+		silenceBashLog: true,
+		prompt: buildNamingPrompt(intent.trim(), treeForPrompt),
+		systemPrompt: buildNamingSystemPrompt(),
+		allowedTools: [
+			"Read",
+			"Grep",
+			"Glob"
+		]
+	}, () => {});
+	if (isError) {
+		error("Claude failed during naming");
+		process.exit(1);
+	}
+	const json = extractJsonBlock(result);
+	if (!json) {
+		error("Claude did not return a json block for naming");
+		process.exit(1);
+	}
+	let proposed;
+	try {
+		proposed = DraftNamingSchema.parse(JSON.parse(json));
+	} catch (e) {
+		error(`failed to parse naming response: ${e.message}`);
+		process.exit(1);
+	}
+	const sanitized = {
+		featureName: sanitizeNamePart(proposed.featureName),
+		specName: sanitizeNamePart(proposed.specName)
+	};
+	if (!sanitized.featureName || !sanitized.specName) {
+		error(`Claude returned an invalid name: ${proposed.featureName}/${proposed.specName}`);
+		process.exit(1);
+	}
+	const final = ensureUnique(tree, sanitized.featureName, sanitized.specName);
+	meta("proposed", `${final.featureName}/${final.specName}`);
+	if (proposed.reason) meta("reason", proposed.reason);
+	if (oneShot || opts.apply === true) return {
+		naming: final,
+		intent: intent.trim()
+	};
+	const answer = await prompt(`Use this name? [y/N/edit] > `);
+	if (/^y/i.test(answer)) return {
+		naming: final,
+		intent: intent.trim()
+	};
+	if (/^e/i.test(answer)) {
+		const manual = await prompt("Enter feature/spec (e.g. tasks/create-and-complete) > ");
+		const parts = manual.split("/");
+		if (parts.length !== 2 || !parts[0] || !parts[1]) {
+			error(`invalid spec path: "${manual}". Expected "<feature>/<spec>"`);
+			process.exit(1);
+		}
+		const featureName = sanitizeNamePart(parts[0]);
+		const specName = sanitizeNamePart(parts[1]);
+		if (!featureName || !specName) {
+			error(`invalid characters in name: ${parts[0]}/${parts[1]}`);
+			process.exit(1);
+		}
+		return {
+			naming: {
+				featureName,
+				specName
+			},
+			intent: intent.trim()
+		};
+	}
+	info("aborted — no draft created.");
+	process.exit(0);
+}
+/**
+* Restrict to kebab-case-friendly characters: lowercase letters, digits, hyphen.
+* Anything else is dropped or replaced with '-'. Collapses repeated/edge hyphens.
+*/
+function sanitizeNamePart(raw) {
+	return raw.trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 60);
+}
+function ensureUnique(tree, featureName, specName) {
+	const feature = tree.find((f) => f.featureName === featureName);
+	if (!feature) return {
+		featureName,
+		specName
+	};
+	const taken = new Set(feature.specs.map((s) => s.specName));
+	if (!taken.has(specName)) return {
+		featureName,
+		specName
+	};
+	for (let i = 2; i < 100; i++) {
+		const candidate = `${specName}-${i}`;
+		if (!taken.has(candidate)) return {
+			featureName,
+			specName: candidate
+		};
+	}
+	return {
+		featureName,
+		specName: `${specName}-${Date.now()}`
+	};
+}
+function printUnifiedDiff(before, after) {
+	const lines = computeLineDiff(before.split("\n"), after.split("\n"));
+	for (const line of lines) process.stdout.write(line + "\n");
+}
+function computeLineDiff(a, b) {
+	const n = a.length;
+	const m = b.length;
+	const dp = Array.from({ length: n + 1 }, () => new Array(m + 1).fill(0));
+	for (let i = n - 1; i >= 0; i--) for (let j = m - 1; j >= 0; j--) dp[i][j] = a[i] === b[j] ? dp[i + 1][j + 1] + 1 : Math.max(dp[i + 1][j], dp[i][j + 1]);
+	const out = [];
+	let i = 0;
+	let j = 0;
+	while (i < n && j < m) if (a[i] === b[j]) {
+		out.push({
+			kind: "ctx",
+			text: a[i]
+		});
+		i++;
+		j++;
+	} else if (dp[i + 1][j] >= dp[i][j + 1]) {
+		out.push({
+			kind: "del",
+			text: a[i]
+		});
+		i++;
+	} else {
+		out.push({
+			kind: "add",
+			text: b[j]
+		});
+		j++;
+	}
+	while (i < n) out.push({
+		kind: "del",
+		text: a[i++]
+	});
+	while (j < m) out.push({
+		kind: "add",
+		text: b[j++]
+	});
+	return out.map((l) => l.kind === "add" ? `+ ${l.text}` : l.kind === "del" ? `- ${l.text}` : `  ${l.text}`);
+}
+function truncate(s, n) {
+	if (s.length <= n) return s;
+	return s.slice(s.length - n);
+}
+//#endregion
+//#region src/prompts/drift.ts
+function buildDriftSystemPrompt() {
+	return `${buildDraftSystemPrompt()}
+
+## Drift mode
+
+You are running non-interactively in CI. The user will not see or apply the patch — only the \`issues\` array.
+
+- Always set \`patch\` to "" in your response.
+- Focus issue messages on what is **out of sync** between the spec and the current codebase: missing aria-labels, renamed routes, removed buttons, placeholders that no longer exist, setup references that point to non-existent files.
+- Do NOT raise issues about stylistic preferences in the spec wording.
+- Treat \`category: unimplemented\` as the primary signal for drift: anything the spec asserts that you cannot find in code is a drift finding.
+
+## Drift severity policy (STRICT)
+
+The CLI exits non-zero when any issue has \`severity: "ERROR"\` (default) or — with \`--severity warn\` — when any \`WARN\` is present. Pick severity by **whether a deterministic replay of this spec would fail today**, not by how confident you are in your own analysis.
+
+Use **ERROR** when the spec would break on replay:
+- A selector the spec relies on (\`aria-label\`, \`placeholder\`, \`data-testid\`, button text) **does not exist anywhere in the source**.
+- A URL / route the spec navigates to is no longer defined.
+- An **Expected** asserts a string or visible text that is no longer rendered by the relevant component.
+- A \`setups[].name\` does not resolve to \`.ccqa/setups/<name>/setup-spec.md\`, or a \`params\` key is not declared in that setup's \`placeholders\`.
+- The spec references a feature/page that has been removed from the codebase.
+
+Use **WARN** when the spec is still likely to work, but quality could improve:
+- The Expected is vague ("a message appears") when a precise string exists in code.
+- A step bundles multiple actions, or a needed intermediate verification step is missing.
+- Stable signals exist that the spec could leverage but currently doesn't.
+- You are unsure whether a referenced string exists (give the user the benefit of the doubt; do not hard-fail CI on uncertainty).
+
+Use **OK** for axes you actively verified and found no issue.
+
+If you cannot decide between ERROR and WARN, choose WARN. Reserve ERROR for findings you can back up with a specific file path or grep result that proves the drift.
+`;
+}
+function buildDriftUserPrompt(existing) {
+	return buildDraftPrompt({
+		mode: "refine",
+		existing,
+		userInput: ""
+	});
+}
+//#endregion
+//#region src/drift/affected.ts
+const execFileP = promisify(execFile);
+/**
+* Resolve the base ref to diff against for `ccqa drift --changed`.
+* Precedence: explicit override > GITHUB_BASE_REF > origin/main.
+*/
+function resolveBaseRef(explicit) {
+	if (explicit && explicit.length > 0) return explicit;
+	const ghBase = process.env["GITHUB_BASE_REF"];
+	if (ghBase && ghBase.length > 0) return ghBase.startsWith("origin/") ? ghBase : `origin/${ghBase}`;
+	return "origin/main";
+}
+/**
+* Run `git diff --name-status base...HEAD` from `cwd` and return one entry per
+* changed file. Renames are reported under their NEW path with status
+* "renamed" — the OLD path is dropped because the spec mapping is against the
+* post-rename layout.
+*
+* Paths are re-rooted to be relative to `cwd`, not the git repo root. In a
+* monorepo where `cwd` is a sub-package (e.g. `js/apps/knowledge-webapp`),
+* git emits paths relative to the repo root, but specs declare relatedPaths
+* relative to their own package. Changes outside `cwd` are dropped so an
+* unrelated PR can never accidentally scope a sub-package's specs in.
+*/
+async function getChangedFiles(base, cwd) {
+	const [{ stdout: rootOut }, { stdout: diffOut }] = await Promise.all([execFileP("git", ["rev-parse", "--show-toplevel"], { cwd }), execFileP("git", [
+		"diff",
+		"--name-status",
+		"-M",
+		`${base}...HEAD`
+	], {
+		cwd,
+		maxBuffer: 32 * 1024 * 1024
+	})]);
+	return rerootChangedFiles(parseGitDiffOutput(diffOut), rootOut.trim(), cwd);
+}
+/**
+* Convert paths in `entries` from git-repo-root relative to `cwd` relative,
+* dropping anything outside `cwd`. Exported for unit tests.
+*/
+function rerootChangedFiles(entries, repoRoot, cwd) {
+	const prefix = relative(repoRoot, cwd);
+	if (!prefix) return entries;
+	const out = [];
+	for (const e of entries) {
+		const rel = relative(prefix, e.path);
+		if (rel.startsWith("..") || rel === "") continue;
+		out.push({
+			...e,
+			path: rel
+		});
+	}
+	return out;
+}
+function parseGitDiffOutput(stdout) {
+	const out = [];
+	for (const line of stdout.split("\n")) {
+		if (!line.trim()) continue;
+		const parts = line.split("	");
+		const code = parts[0];
+		if (!code) continue;
+		if (code.startsWith("R")) {
+			const newPath = parts[2];
+			if (newPath) out.push({
+				path: newPath,
+				status: "renamed"
+			});
+			continue;
+		}
+		if (code.startsWith("C")) {
+			const newPath = parts[2];
+			if (newPath) out.push({
+				path: newPath,
+				status: "added"
+			});
+			continue;
+		}
+		const path = parts[1];
+		if (!path) continue;
+		switch (code[0]) {
+			case "A":
+				out.push({
+					path,
+					status: "added"
+				});
+				break;
+			case "M":
+			case "T":
+				out.push({
+					path,
+					status: "modified"
+				});
+				break;
+			case "D":
+				out.push({
+					path,
+					status: "deleted"
+				});
+				break;
+			default: out.push({
+				path,
+				status: "modified"
+			});
+		}
+	}
+	return out;
+}
+function stripLeadingDotSlash(s) {
+	return s.startsWith("./") ? s.slice(2) : s;
+}
+const REGEX_CACHE = /* @__PURE__ */ new Map();
+/** Compiles `pattern` to a RegExp, memoized so repeated `--changed` matches don't re-build. */
+function compileGlob(pattern) {
+	const cached = REGEX_CACHE.get(pattern);
+	if (cached) return cached;
+	const compiled = globToRegExp(stripLeadingDotSlash(pattern));
+	REGEX_CACHE.set(pattern, compiled);
+	return compiled;
+}
+function globToRegExp(pattern) {
+	let re = "^";
+	let i = 0;
+	while (i < pattern.length) {
+		const ch = pattern[i];
+		if (ch === "?") {
+			re += "[^/]";
+			i++;
+			continue;
+		}
+		if (ch !== "*") {
+			re += /[.+^${}()|[\]\\]/.test(ch) ? "\\" + ch : ch;
+			i++;
+			continue;
+		}
+		if (pattern[i + 1] !== "*") {
+			re += "[^/]*";
+			i++;
+			continue;
+		}
+		const hasLeadingSlash = re.endsWith("/");
+		const hasTrailingSlash = pattern[i + 2] === "/";
+		if (hasLeadingSlash) re = re.slice(0, -1);
+		if (hasLeadingSlash || hasTrailingSlash) re += "(?:/?.*)?";
+		else re += ".*";
+		i += hasTrailingSlash ? 3 : 2;
+	}
+	return new RegExp(re + "$");
+}
+/**
+* Returns true if `changedPath` is covered by any of `relatedPaths`. An empty
+* `relatedPaths` returns false — callers handle the "unscoped spec" case
+* separately (treat the spec as always-affected) before calling this.
+*/
+function isPathAffectedBy(changedPath, relatedPaths) {
+	const stripped = stripLeadingDotSlash(changedPath);
+	for (const pattern of relatedPaths) if (compileGlob(pattern).test(stripped)) return true;
+	return false;
+}
+//#endregion
+//#region src/drift/route-new-files.ts
+/**
+* Lightweight Claude call: given a list of new files in the PR and the existing
+* specs (with their relatedPaths globs as a hint), return the spec keys (in
+* "<feature>/<spec>" form) that the new files plausibly affect.
+*
+* Conservative by design — false positives are safer than false negatives,
+* because a missed spec turns into undetected drift in CI. When the router
+* call itself fails, we log a warning rather than fail-close: the surrounding
+* glob match is the primary signal; the router only adds coverage for new
+* paths no glob captures.
+*/
+async function routeNewFilesToSpecs(input) {
+	const { newFiles, specs, cwd, model } = input;
+	const empty = /* @__PURE__ */ new Set();
+	if (newFiles.length === 0 || specs.length === 0) return empty;
+	const { result, isError } = await invokeClaudeStreaming({
+		prompt: buildRouterPrompt(await Promise.all(newFiles.map(async (path) => ({
+			path,
+			head: await readHead(join(cwd, path))
+		}))), specs),
+		systemPrompt: buildRouterSystemPrompt(),
+		allowedTools: [
+			"Read",
+			"Grep",
+			"Glob"
+		],
+		silenceBashLog: true,
+		cwd,
+		...model ? { model } : {}
+	}, (_msg) => {});
+	if (isError) {
+		warn("new-file router: Claude returned an error; skipping router signal");
+		return empty;
+	}
+	const json = extractJsonBlock(result);
+	if (!json) {
+		warn("new-file router: no JSON block in response; skipping router signal");
+		return empty;
+	}
+	let parsed;
+	try {
+		parsed = JSON.parse(json);
+	} catch (e) {
+		warn(`new-file router: failed to parse JSON (${e.message}); skipping router signal`);
+		return empty;
+	}
+	const out = /* @__PURE__ */ new Set();
+	const validKeys = new Set(specs.map((s) => `${s.featureName}/${s.specName}`));
+	if (typeof parsed === "object" && parsed !== null && "affectedSpecs" in parsed) {
+		const arr = parsed.affectedSpecs;
+		if (Array.isArray(arr)) {
+			for (const item of arr) if (typeof item === "string" && validKeys.has(item)) out.add(item);
+		}
+	}
+	return out;
+}
+async function readHead(absPath) {
+	const content = await readFile(absPath, "utf-8").catch(() => "");
+	if (!content) return "";
+	return content.split("\n").slice(0, 40).join("\n");
+}
+function buildRouterSystemPrompt() {
+	return `You triage which ccqa test specs are potentially affected by NEW source files added in a pull request.
+
+You will receive:
+- A list of new files (path + first ~40 lines of each)
+- A list of existing specs with their declared relatedPaths globs
+
+Your job: return the spec keys (in "<feature>/<spec>" form) whose behaviour might depend on any of the new files.
+
+## Rules
+
+- Be **conservative**: when in doubt, include the spec. A spurious inclusion costs one extra drift check; a missed spec lets real drift slip through CI.
+- Use \`Read\`, \`Grep\`, \`Glob\` if you need to inspect the spec body or related code, but stay focused — this is a triage step, not a full review.
+- Ignore specs whose relatedPaths clearly point to a different area than every new file (e.g. \`src/auth/**\` specs vs new files only under \`src/billing/**\`).
+- Files like tests, generated code, build artifacts, vendor dirs typically do not affect any spec. Skip them.
+
+## Output (STRICT)
+
+Output ONE fenced \`\`\`json block, nothing else:
+
+\`\`\`json
+{
+  "affectedSpecs": ["feature/spec", "feature/spec"]
+}
+\`\`\`
+
+Use exactly the keys you saw in the input ("<feature>/<spec>"). Return an empty array if no spec is affected.
+`;
+}
+function buildRouterPrompt(previews, specs) {
+	return `## New files
+
+${previews.map((p) => {
+		const headBlock = p.head ? `\n\`\`\`\n${p.head}\n\`\`\`` : "\n(empty or unreadable)";
+		return `### ${p.path}${headBlock}`;
+	}).join("\n\n")}
+
+## Existing specs
+
+${specs.map((s) => {
+		const title = s.title ? ` — ${s.title}` : "";
+		const paths = s.relatedPaths.length === 0 ? "  (no relatedPaths declared)" : s.relatedPaths.map((p) => `  - ${p}`).join("\n");
+		return `- ${s.featureName}/${s.specName}${title}\n${paths}`;
+	}).join("\n")}
+
+## Task
+
+Return the spec keys that might be affected by any of the new files. Conservative inclusion is preferred over missing real drift.
+`;
+}
+//#endregion
+//#region src/cli/drift.ts
+const DEFAULT_CONCURRENCY = 3;
+const driftCommand = new Command("drift").argument("[feature/spec]", "Optional spec id. If omitted, every spec under .ccqa/features/ is checked.").description("Check whether each test-spec.md is still in sync with the current codebase (CI-friendly, no patches applied).").option("--format <fmt>", "Output format: text | json | github", "text").option("--severity <level>", "Exit non-zero on this severity or higher: warn | error", "error").option("--concurrency <n>", `Parallel spec checks (default: ${DEFAULT_CONCURRENCY})`).option("-m, --model <name>", "Claude model alias ('sonnet'|'opus'|'haiku') or full ID. Overrides CCQA_MODEL.").option("--cwd <path>", "Working directory used as both the .ccqa root and the codebase Claude reads. Useful for monorepos. Defaults to process.cwd().").option("--changed", "Restrict drift checks to specs whose relatedPaths intersect the git diff against --base (or, in CI, $GITHUB_BASE_REF, else origin/main). New files are routed to specs via a single lightweight Claude call.").option("--base <ref>", "Base ref to diff against when --changed is set. Defaults to $GITHUB_BASE_REF (CI) or origin/main.").action(async (specPath, opts) => {
+	const format = parseFormat(opts.format);
+	const threshold = parseSeverity(opts.severity);
+	const concurrency = parseConcurrency(opts.concurrency);
+	const cwd = opts.cwd ? resolve(opts.cwd) : process.cwd();
+	await ensureCcqaDir(cwd);
+	if (opts.changed && specPath) {
+		error("--changed and an explicit spec id cannot be combined; --changed only applies to a full sweep");
+		process.exit(2);
+	}
+	let targets = await collectTargets(specPath, cwd);
+	if (targets.length === 0) exitWithNoSpecs(format, "no test specs found under .ccqa/features/");
+	if (format === "text") {
+		header("drift", specPath ?? `${targets.length} spec${targets.length > 1 ? "s" : ""}`);
+		if (opts.cwd) meta("cwd", cwd);
+	}
+	if (opts.changed) {
+		const total = targets.length;
+		targets = await filterByChanged({
+			targets,
+			cwd,
+			baseOverride: opts.base,
+			format,
+			model: opts.model
+		});
+		if (format === "text") meta("scoped", `${targets.length} of ${total} spec${total > 1 ? "s" : ""}`);
+		if (targets.length === 0) exitWithNoSpecs(format, "no specs intersect the changed file set; nothing to check");
+	}
+	const results = await runChecks(targets, concurrency, opts.model, cwd, format);
+	emitReport(results, format, cwd);
+	process.exit(determineExitCode(results, threshold));
+});
+function exitWithNoSpecs(format, message) {
+	if (format === "json") process.stdout.write(`${JSON.stringify({ specs: [] }, null, 2)}\n`);
+	else if (format === "text") info(message);
+	process.exit(0);
+}
+async function filterByChanged(input) {
+	const { targets, cwd, baseOverride, format, model } = input;
+	const base = resolveBaseRef(baseOverride);
+	let changed;
+	try {
+		changed = await getChangedFiles(base, cwd);
+	} catch (e) {
+		error(`failed to run 'git diff' against ${base}: ${e.message}`);
+		process.exit(2);
+	}
+	if (format === "text") {
+		meta("changed-base", base);
+		meta("changed-files", changed.length);
+	}
+	if (changed.length === 0) return [];
+	const newFiles = changed.filter((f) => f.status === "added");
+	const existingChanges = changed.filter((f) => f.status !== "added");
+	const affected = /* @__PURE__ */ new Set();
+	for (const t of targets) {
+		if (!t.relatedPaths) {
+			affected.add(specKey(t));
+			continue;
+		}
+		if (existingChanges.some((f) => isPathAffectedBy(f.path, t.relatedPaths)) || newFiles.some((f) => isPathAffectedBy(f.path, t.relatedPaths))) affected.add(specKey(t));
+	}
+	if (newFiles.length > 0) {
+		if (format === "text") info(`routing ${newFiles.length} new file(s) to specs via Claude...`);
+		const routed = await routeNewFilesToSpecs({
+			newFiles: newFiles.map((f) => f.path),
+			specs: targets.filter((t) => t.relatedPaths).map((t) => ({
+				featureName: t.featureName,
+				specName: t.specName,
+				title: t.title,
+				relatedPaths: t.relatedPaths
+			})),
+			cwd,
+			model
+		});
+		for (const key of routed) affected.add(key);
+	}
+	return targets.filter((t) => affected.has(specKey(t)));
+}
+async function collectTargets(specPath, cwd) {
+	if (specPath) {
+		const { featureName, specName } = parseSpecPath(specPath);
+		if (await tryReadSpecFile(featureName, specName, cwd) === null) {
+			error(`spec not found: ${featureName}/${specName} (under ${cwd})`);
+			process.exit(1);
+		}
+		return [{
+			featureName,
+			specName
+		}];
+	}
+	const tree = await listFeatureTree(cwd);
+	const out = [];
+	for (const feature of tree) for (const spec of feature.specs) {
+		if (!spec.hasSpecFile) continue;
+		const t = {
+			featureName: feature.featureName,
+			specName: spec.specName
+		};
+		if (spec.relatedPaths) t.relatedPaths = spec.relatedPaths;
+		if (spec.title) t.title = spec.title;
+		out.push(t);
+	}
+	return out;
+}
+async function runChecks(targets, concurrency, model, cwd, format) {
+	const results = new Array(targets.length);
+	let cursor = 0;
+	const worker = async () => {
+		while (true) {
+			const idx = cursor++;
+			if (idx >= targets.length) return;
+			const target = targets[idx];
+			results[idx] = await checkSpec(target, model, cwd, format);
+		}
+	};
+	const pool = Array.from({ length: Math.min(concurrency, targets.length) }, () => worker());
+	await Promise.all(pool);
+	return results;
+}
+async function checkSpec(target, model, cwd, format) {
+	const { featureName, specName } = target;
+	const existing = await tryReadSpecFile(featureName, specName, cwd);
+	if (existing === null) return {
+		target,
+		ok: false,
+		issues: [],
+		error: `spec file disappeared after enumeration: ${featureName}/${specName}`
+	};
+	if (format === "text") info(`checking ${featureName}/${specName}`);
+	const { result, isError } = await invokeClaudeStreaming({
+		prompt: buildDriftUserPrompt(existing),
+		systemPrompt: buildDriftSystemPrompt(),
+		allowedTools: [
+			"Read",
+			"Grep",
+			"Glob"
+		],
+		silenceBashLog: true,
+		cwd,
+		...model ? { model } : {}
+	}, (_msg) => {});
+	if (isError) return {
+		target,
+		ok: false,
+		issues: [],
+		error: "Claude returned an error result"
+	};
+	const json = extractJsonBlock(result);
+	if (!json) return {
+		target,
+		ok: false,
+		issues: [],
+		error: "Claude did not return a json block"
+	};
+	let report;
+	try {
+		report = DraftReportSchema.parse(JSON.parse(json));
+	} catch (e) {
+		return {
+			target,
+			ok: false,
+			issues: [],
+			error: `failed to parse drift report: ${e.message}`
+		};
+	}
+	return {
+		target,
+		ok: true,
+		issues: report.issues
+	};
+}
+function emitReport(results, format, cwd) {
+	if (format === "json") {
+		emitJson(results);
+		return;
+	}
+	if (format === "github") {
+		emitGithub(results, cwd);
+		return;
+	}
+	emitText(results);
+}
+const CATEGORY_LABEL = {
+	assertable: "Assertability",
+	setups: "Setup references",
+	granularity: "Step granularity",
+	unimplemented: "Unimplemented checks"
+};
+const HEAVY_RULE = "═".repeat(72);
+function emitText(results) {
+	for (const r of results) {
+		blank();
+		const heading = `══ ${r.target.featureName}/${r.target.specName} `;
+		const tail = "═".repeat(Math.max(3, 72 - heading.length));
+		process.stdout.write(`${heading}${tail}\n`);
+		if (r.error) {
+			process.stdout.write(`  ERROR  ${r.error}\n`);
+			continue;
+		}
+		const errors = r.issues.filter((i) => i.severity === "ERROR");
+		const warnings = r.issues.filter((i) => i.severity === "WARN");
+		const passed = r.issues.filter((i) => i.severity === "OK");
+		if (errors.length === 0 && warnings.length === 0) {
+			const label = passed.length === 1 ? "check" : "checks";
+			const detail = passed.length > 0 ? `all ${passed.length} ${label} passed` : "no issues";
+			process.stdout.write(`  ✓  ${detail}\n`);
+			continue;
+		}
+		for (const issue of errors) writeFinding("ERROR", issue);
+		for (const issue of warnings) writeFinding("WARN", issue);
+		if (passed.length > 0) {
+			const names = passed.map((i) => CATEGORY_LABEL[i.category]).join(", ");
+			process.stdout.write(`\n  ✓  passed (${passed.length}): ${names}\n`);
+		}
+	}
+	blank();
+	process.stdout.write(`${HEAVY_RULE}\n`);
+	const totals = summarize(results);
+	meta("specs", `${results.length} (${totals.errored} errored)`);
+	meta("findings", `${totals.error} error, ${totals.warn} warn, ${totals.ok} ok`);
+}
+function writeFinding(level, issue) {
+	const stepPart = issue.stepId ? ` ${issue.stepId}` : "";
+	process.stdout.write(`\n  ${level}  ${CATEGORY_LABEL[issue.category]}${stepPart}\n`);
+	process.stdout.write(`    ${issue.message}\n`);
+	if (issue.detail) process.stdout.write(`    └ ${issue.detail.replace(/\n/g, "\n      ")}\n`);
+}
+function emitJson(results) {
+	const payload = { specs: results.map((r) => ({
+		feature: r.target.featureName,
+		spec: r.target.specName,
+		ok: r.ok,
+		...r.error ? { error: r.error } : {},
+		issues: r.issues.map((i) => ({
+			severity: i.severity,
+			category: i.category,
+			stepId: i.stepId,
+			message: i.message,
+			...i.detail ? { detail: i.detail } : {}
+		}))
+	})) };
+	process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+}
+function emitGithub(results, cwd) {
+	const repoRoot = process.env["GITHUB_WORKSPACE"] ?? process.cwd();
+	for (const r of results) {
+		const file = githubRelPath(cwd, repoRoot, r.target.featureName, r.target.specName);
+		if (r.error) {
+			process.stdout.write(`::error file=${file}::${escapeGhMessage(r.error)}\n`);
+			continue;
+		}
+		for (const issue of r.issues) {
+			if (issue.severity === "OK") continue;
+			const level = issue.severity === "ERROR" ? "error" : "warning";
+			const title = `${r.target.featureName}/${r.target.specName} — ${issue.category}${issue.stepId ? ` (${issue.stepId})` : ""}`;
+			const body = issue.detail ? `${issue.message}\n${issue.detail}` : issue.message;
+			process.stdout.write(`::${level} file=${file},title=${escapeGhProp(title)}::${escapeGhMessage(body)}\n`);
+		}
+	}
+}
+function githubRelPath(cwd, repoRoot, featureName, specName) {
+	const abs = resolve(cwd, ".ccqa", "features", featureName, "test-cases", specName, "test-spec.md");
+	const rel = relative(repoRoot, abs);
+	return rel.startsWith("..") ? abs : rel;
+}
+function escapeGhMessage(s) {
+	return s.replace(/%/g, "%25").replace(/\r/g, "%0D").replace(/\n/g, "%0A");
+}
+function escapeGhProp(s) {
+	return s.replace(/%/g, "%25").replace(/\r/g, "%0D").replace(/\n/g, "%0A").replace(/,/g, "%2C").replace(/:/g, "%3A");
+}
+function summarize(results) {
+	let error = 0;
+	let warn = 0;
+	let ok = 0;
+	let errored = 0;
+	for (const r of results) {
+		if (r.error) errored++;
+		for (const issue of r.issues) if (issue.severity === "ERROR") error++;
+		else if (issue.severity === "WARN") warn++;
+		else ok++;
+	}
+	return {
+		error,
+		warn,
+		ok,
+		errored
+	};
+}
+function determineExitCode(results, threshold) {
+	for (const r of results) {
+		if (r.error) return 1;
+		for (const issue of r.issues) {
+			if (issue.severity === "ERROR") return 1;
+			if (threshold === "warn" && issue.severity === "WARN") return 1;
+		}
+	}
+	return 0;
+}
+function parseFormat(raw) {
+	const v = raw ?? "text";
+	if (v === "text" || v === "json" || v === "github") return v;
+	error(`invalid --format: ${v} (expected text|json|github)`);
+	process.exit(2);
+}
+function parseSeverity(raw) {
+	const v = raw ?? "error";
+	if (v === "warn" || v === "error") return v;
+	error(`invalid --severity: ${v} (expected warn|error)`);
+	process.exit(2);
+}
+function parseConcurrency(raw) {
+	if (raw === void 0) return DEFAULT_CONCURRENCY;
+	const n = Number.parseInt(raw, 10);
+	if (!Number.isFinite(n) || n < 1) {
+		error(`invalid --concurrency: ${raw} (expected positive integer)`);
+		process.exit(2);
+	}
+	return n;
+}
+//#endregion
 //#region src/cli/index.ts
 const packageJsonPath = resolvePackageJson();
 const { version } = JSON.parse(readFileSync(packageJsonPath, "utf8"));
@@ -2710,6 +4187,8 @@ function resolvePackageJson() {
 }
 const program = new Command();
 program.name("ccqa").description("E2E test CLI using Claude Code + agent-browser").version(version);
+program.addCommand(draftCommand);
+program.addCommand(driftCommand);
 program.addCommand(traceCommand);
 program.addCommand(generateCommand);
 program.addCommand(runCommand);