ccqa 0.3.8 → 0.3.9

package/README.md

@@ -45,7 +45,7 @@ pnpm add -D agent-browser
 
 ## Usage
 
-**1. Write a spec**
+**1. Write a spec** — by hand, or interactively with [`ccqa draft`](#draft--co-author-test-specmd-with-claude)
 
 ```markdown
 <!-- .ccqa/features/tasks/test-cases/create-and-complete/test-spec.md -->
@@ -103,6 +103,74 @@ ccqa generate tasks/create-and-complete
 ccqa run tasks/create-and-complete
 ```
 
+## Draft — co-author test-spec.md with Claude
+
+Writing a `test-spec.md` from scratch means digging into your codebase to find the right aria-labels, URLs, and button text. `ccqa draft` puts Claude in the loop: you describe what you want to test in plain language, Claude reads the relevant code, and you refine the spec interactively.
+
+```bash
+ccqa draft
+```
+
+The first run asks for your intent, proposes a `feature/spec` name, and writes a draft. Each subsequent invocation lets you give a refinement instruction — empty input means "just re-check the current spec against the code." Press `y` at the final "Are you done with this draft?" prompt to end the session.
+
+```
+ccqa draft
+
+What do you want to test? > Select a category on the AI Maintenance page and run a check
+Proposing a feature/spec name based on your intent...
+  proposed: ai-maintenance/run-check-with-category
+Use this name? [y/N/edit] > y
+
+Reading codebase and drafting spec...
+  ✓ 5 Read, 3 Grep, 2 Glob  (4.2s)
+
+── Review  (1 warning, 3 passed) ───────────────────────────────────
+
+  WARNINGS (1)
+    Assertability  step-05
+      Result row may still show "running" right after the click
+      └ ContentQualityCheck.tsx polls every 5s; the status starts at
+        IN_PROGRESS and only flips to SUCCEEDED later.
+
+  PASSED (3)
+    Setup references, Step granularity, Unimplemented checks
+
+────────────────────────────────────────────────────────────────────
+
+--- proposed changes ---
++ ---
++ title: "AI Maintenance — content quality check"
+...
+
+Apply this patch? [y/N] y
+  saved: .ccqa/features/ai-maintenance/test-cases/run-check-with-category/test-spec.md
+
+How would you like to refine? (empty = re-validate) >
+```
+
+You can also edit `test-spec.md` directly in your editor between turns — `ccqa draft` re-reads the file each iteration.
+
+### What gets reviewed
+
+Every turn Claude grades the spec on four axes and reports issues:
+
+| Check | What it verifies |
+|---|---|
+| **Assertability** | Each step's **Expected** references concrete, observable signals (visible text, URL pattern, element state) that actually exist in the code. Flags timestamps, exact counts, and session-specific values that won't be stable across runs. |
+| **Setup references** | Every `setups[].name` in the frontmatter resolves to an existing `.ccqa/setups/<name>/setup-spec.md`, and every `params` key matches that setup's `placeholders`. See [Setup Specs](#setup-specs--reusable-shared-procedures). |
+| **Step granularity** | Steps aren't too coarse (multiple actions in one) or too fine (snapshot-only filler), and the order is logical. |
+| **Unimplemented checks** | Anything the spec describes that Claude couldn't find in the codebase — a hint that you may be specifying behavior that doesn't exist yet. |
+
+Findings with severity `WARN` or `ERROR` are shown in full; `OK` checks collapse to a one-line summary.
+
+### Flags
+
+```
+ccqa draft [feature/spec]               # arg is optional; Claude proposes a name if omitted
+  --instruction <text>                  # single-shot, non-interactive
+  --apply                               # auto-apply patches without [y/N] confirmation
+```
+
 ## Setup Specs — Reusable shared procedures
 
 Setup specs let you define reusable procedures (login, data preparation, etc.) that run before your test steps. Define once, use across multiple test specs.
@@ -253,6 +321,10 @@ ccqa generate tasks/create-and-complete --max-retries 5
 ## Commands
 
 ```
+ccqa draft [feature/spec]          Co-author a test spec with Claude
+  --instruction <text>              Single-shot, non-interactive
+  --apply                           Auto-apply patches without [y/N] confirmation
+
 ccqa trace <feature/spec>          Record browser actions for a test spec
 ccqa generate <feature/spec>       Generate test script from recorded actions
   --auto                            Apply auto-fixes without confirmation (CI)

package/dist/bin/ccqa.mjs

@@ -1,7 +1,7 @@
 #!/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";
@@ -10,6 +10,8 @@ import matter from "gray-matter";
 import { 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";
 //#region src/prompts/trace.ts
 function generateSessionName() {
 	return `ccqa-trace-${(/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-")}`;
@@ -106,6 +108,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
 
@@ -345,7 +348,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, onAbAction, onAbActionFailed, silenceBashLog = false } = options;
 	const resolvedModel = resolveModel(model);
 	let lastAbToolUseId = null;
 	const sdkOptions = {
@@ -397,7 +400,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);
@@ -560,6 +563,16 @@ 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;
+}
 async function saveRoute(featureName, specName, route, cwd) {
 	const specDir = getSpecDir(featureName, specName, cwd);
 	await mkdir(specDir, { recursive: true });
@@ -645,6 +658,34 @@ 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. Used by `ccqa draft` to suggest non-colliding
+* feature/spec names that fit the existing structure.
+*/
+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
+				};
+				return {
+					specName,
+					hasSpecFile: true,
+					title: content.match(/^title:\s*"?([^"\n]+)"?/m)?.[1]?.trim()
+				};
+			}))
+		};
+	}));
+}
 function routeToMarkdown(route) {
 	const lines = [
 		"---",
@@ -834,22 +875,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 +928,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 +1028,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;
@@ -1567,7 +1683,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 +1740,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 +1968,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 +2542,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 +2820,607 @@ async function cleanupActions(actions, model) {
 	return actions;
 }
 //#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)
+
+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. 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(),
+	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 = {
+	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(issue);
+		process.stdout.write("\n");
+	}
+	if (warnings.length) {
+		process.stdout.write(`  WARNINGS (${warnings.length})\n`);
+		for (const issue of warnings) writeFinding(issue);
+		process.stdout.write("\n");
+	}
+	if (passed.length) {
+		const names = passed.map((i) => CATEGORY_LABEL[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(issue) {
+	const stepPart = issue.stepId ? `  ${issue.stepId}` : "";
+	process.stdout.write(`    ${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`);
+}
+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 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;
+}
+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/cli/index.ts
 const packageJsonPath = resolvePackageJson();
 const { version } = JSON.parse(readFileSync(packageJsonPath, "utf8"));
@@ -2710,6 +3436,7 @@ 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(traceCommand);
 program.addCommand(generateCommand);
 program.addCommand(runCommand);

package/dist/package.json

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

package/package.json

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