ccqa 1.53.0 → 1.55.0

package/dist/bin/ccqa.mjs

@@ -118,8 +118,6 @@ const TestSpecSchema = z.object({
 		message: `\`${key}\` only applies to the agent-browser target — remove it or drop \`target: ${spec.target}\``
 	});
 });
-/** Default mode when `mode:` is absent. */
-const DEFAULT_SPEC_MODE = "deterministic";
 /**
 * A block param declaration. `required` defaults to true; only explicit
 * `required: false` makes it optional. `secret: true` flags the value as
@@ -300,7 +298,7 @@ function evidenceLabels(overrides, language) {
 *
 * The template language is deliberately tiny: `{placeholder}` segments filled
 * from a substitution table the caller owns. Today the table is the spec's own
-* coordinates (`{feature}` / `{spec}`); an intent source that names its cases
+* coordinates (`{feature}` / `{spec}`); a case source that names its cases
 * differently adds keys to the table without touching this module.
 */
 const PLACEHOLDER$1 = /\{([^{}]*)\}/g;
@@ -404,10 +402,6 @@ function caseValues(caseId) {
 function resolveCaseRecordingPath(target, targetConfig, caseId) {
 	return expandPathTemplate(recordingPathTemplate(templateFor(target, targetConfig)), caseValues(caseId));
 }
-/** {@link resolveTestPath}, resolved against the project root. */
-function resolveTestPathAbs(target, targetConfig, ref, cwd) {
-	return resolve(cwd, resolveTestPath(target, targetConfig, ref));
-}
 //#endregion
 //#region src/config/project-config.ts
 /**
@@ -452,38 +446,6 @@ const ConventionsSchema = z.object({
 	operate: z.array(z.string().min(1)).default([])
 }).strict();
 /**
-* Which sections of a markdown test case mean what. The keys are ccqa's
-* vocabulary; the values are the headings the project actually writes, in the
-* project's own language. Every one is optional — a case that states no
-* cleanup simply has none — except `steps`, without which there is nothing to
-* record.
-*
-* A heading no key names is not lost: it reaches the recorder as further
-* information about the case, which is what a precondition usually is.
-*/
-const IntentFieldsSchema = z.object({
-	title: z.string().min(1).default("Title"),
-	precondition: z.string().min(1).default("Precondition"),
-	steps: z.string().min(1).default("Steps"),
-	expected: z.string().min(1).default("Expected"),
-	cleanup: z.string().min(1).default("Cleanup"),
-	priority: z.string().min(1).default("Priority"),
-	link: z.string().min(1).default("Link"),
-	mode: z.string().min(1).optional(),
-	outputPath: z.string().min(1).optional()
-}).strict();
-/**
-* Where a target's test cases are written, when they are not ccqa's own
-* `spec.yaml`. `root` is the directory the cases live under, and a case's id
-* is its path below it without the extension — which is also what `{case}`
-* expands to in `testPath`.
-*/
-const IntentSourceSchema = z.object({
-	kind: z.literal("markdown"),
-	root: z.string().min(1),
-	fields: IntentFieldsSchema.prefault({})
-}).strict();
-/**
 * How a generated test names the unique values it creates. `${CCQA_RUN_ID}` is
 * what the recording holds; a repo with its own helper for this says so here,
 * and the emitter calls that instead of leaving an env read in the test.
@@ -493,7 +455,8 @@ const RunIdConfigSchema = z.object({
 	expression: z.string().min(1)
 }).strict();
 /**
-* A tag the test's title ends with, taken from an intent field. Mechanical on
+* A tag the test's title ends with, taken from one of the case's `fields`.
+* Mechanical on
 * purpose: a title tag is a convention a reviewer greps, and a model that
 * decides it per case gets it wrong in a way nobody notices.
 */
@@ -506,7 +469,7 @@ const TitleTagsSchema = z.object({
 * Per-target settings.
 *
 * `testPath` is the template deciding where a case's generated test lands
-* (`{feature}` / `{spec}` for `spec.yaml`, `{case}` for an intent source);
+* (`{feature}` / `{spec}` for `spec.yaml`, `{case}` for a case source);
 * omitted, the target's own default applies. It is a template rather than a
 * directory because every other command has to find that file without asking
 * the generator — see src/targets/test-path.ts.
@@ -523,7 +486,8 @@ const TitleTagsSchema = z.object({
 const TargetConfigSchema = z.object({
 	kind: z.literal("external").optional(),
 	framework: z.literal("playwright").optional(),
-	intent: IntentSourceSchema.optional(),
+	cases: z.string().min(1).optional(),
+	intent: z.never({ error: "`intent` is gone: ccqa reads its own `spec.yaml` and nothing else. Point `cases` at a module in this repository that reads your format and answers ccqa's case contract (`cases: ./ccqa/cases.mjs`) — see the `cases` section of docs/targets.md" }).optional(),
 	testPath: z.string().min(1).superRefine((template, ctx) => {
 		const error = validateTestPathTemplate(template);
 		if (error) ctx.addIssue({
@@ -640,7 +604,7 @@ const ProjectConfigSchema = z.object({
 		if (target.kind !== "external") {
 			for (const key of [
 				"framework",
-				"intent",
+				"cases",
 				"runId",
 				"header",
 				"titleTags"
@@ -649,7 +613,7 @@ const ProjectConfigSchema = z.object({
 		}
 		if (target.framework === void 0) refuse(at("framework"), "a kind: external target must say which framework its tests are written for (framework: playwright)");
 		if (target.testPath === void 0) refuse(at("testPath"), "a kind: external target must say where its generated tests go (testPath)");
-		if (target.intent !== void 0 && target.testPath !== void 0 && !target.testPath.includes("{case}")) refuse(at("testPath"), "a target reading an intent source addresses cases by their path, so its testPath must use {case} — {spec} is only the last segment, and two cases filed under the same name would collide");
+		if (target.cases !== void 0 && target.testPath !== void 0 && !target.testPath.includes("{case}")) refuse(at("testPath"), "a target reading its own case source addresses cases by their path, so its testPath must use {case} — {spec} is only the last segment, and two cases filed under the same name would collide");
 	}
 	if (config.targets["agent-browser"]?.testPath !== void 0) ctx.addIssue({
 		code: "custom",
@@ -1547,8 +1511,8 @@ function splitCaseId(id) {
 		specName
 	};
 }
-/** The case an intent source names, by its root-relative id (no extension). */
-function intentCase(id, cwd) {
+/** A case a project's own source names, by the path-shaped id it gives it. */
+function sourcedCase(id, cwd) {
 	return {
 		id,
 		dir: join(getCcqaDir(cwd), CASES_DIR, ...id.split("/"))
@@ -1566,7 +1530,7 @@ function intentCase(id, cwd) {
 * that was not asking about the test.
 */
 function caseRefFor(id, cwd, recordingPath) {
-	const base = typeof id === "string" ? intentCase(id, cwd) : specCase(id.featureName, id.specName, cwd);
+	const base = typeof id === "string" ? sourcedCase(id, cwd) : specCase(id.featureName, id.specName, cwd);
 	return recordingPath === void 0 ? base : {
 		...base,
 		recordingPathAbs: resolve(cwd, recordingPath)
@@ -1576,14 +1540,20 @@ async function ensureCcqaDir(cwd) {
 	await mkdir(join(getCcqaDir(cwd), "features"), { recursive: true });
 	await mkdir(join(getCcqaDir(cwd), "blocks"), { recursive: true });
 }
-async function readSpecFile(featureName, specName, cwd) {
-	const specPath = join(getSpecDir(featureName, specName, cwd), SPEC_FILE);
-	return readFile(specPath, "utf-8").catch(() => {
-		throw new Error(`Spec file not found: ${specPath}`);
-	});
+/**
+* Where one case's `spec.yaml` is.
+*
+* Reading it is not here: a case document is read through `src/cases/`, so
+* that no feature can reach one kind of case behind the reader's back. This
+* says where the file is, which the store owns because the `.ccqa` layout is
+* the store's.
+*/
+function specFilePath(featureName, specName, cwd) {
+	return join(getSpecDir(featureName, specName, cwd), SPEC_FILE);
 }
-async function tryReadSpecFile(featureName, specName, cwd) {
-	return readFile(join(getSpecDir(featureName, specName, cwd), SPEC_FILE), "utf-8").catch(() => null);
+/** For the enumerations below only — see `src/cases/spec-source.ts` for the public read. */
+async function readSpecYaml(featureName, specName, cwd) {
+	return readFile(specFilePath(featureName, specName, cwd), "utf-8").catch(() => null);
 }
 async function saveSpecFile(featureName, specName, content, cwd) {
 	const specDir = getSpecDir(featureName, specName, cwd);
@@ -1987,7 +1957,7 @@ async function listAllSpecsWithSpecFile(cwd) {
 async function listActiveSpecs(cwd) {
 	const all = await listAllSpecsWithSpecFile(cwd);
 	return (await Promise.all(all.map(async (ref) => {
-		return tryParseTestSpec(await tryReadSpecFile(ref.featureName, ref.specName, cwd))?.disabled === true ? null : ref;
+		return tryParseTestSpec(await readSpecYaml(ref.featureName, ref.specName, cwd))?.disabled === true ? null : ref;
 	}))).filter((ref) => ref !== null);
 }
 async function listAllSpecsFilteredBy(requiredFilename, cwd) {
@@ -2021,41 +1991,6 @@ async function resolveSpecTargets(target, enumerateAll, cwd) {
 	}
 	return (await listActiveSpecs(cwd)).filter((ref) => ref.featureName === target);
 }
-/**
-* 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.
-*/
-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 specFile = join(testCasesDir, specName, SPEC_FILE);
-				const content = await readFile(specFile, "utf-8").catch(() => null);
-				if (content === null) return {
-					specName,
-					hasSpecFile: false
-				};
-				try {
-					return {
-						specName,
-						hasSpecFile: true,
-						includedBlocks: collectIncludedBlockNames(parseTestSpec(content, specFile))
-					};
-				} catch {
-					return {
-						specName,
-						hasSpecFile: true
-					};
-				}
-			}))
-		};
-	}));
-}
 //#endregion
 //#region src/runtime/bundled-config.ts
 const CANDIDATES = [
@@ -5683,7 +5618,7 @@ async function collectSpecArtifacts(args) {
 	};
 	const dir = specArtifactsDir(args.reportDir, args.feature, args.spec);
 	const relPrefix = posix.join(ARTIFACTS_SUBDIR, `${args.feature}__${args.spec}`);
-	const relFiles = await walkFiles$1(dir);
+	const relFiles = (await walkFiles$1(dir)).filter((rel) => !args.passed || !isTraceArchive(rel));
 	relFiles.sort((a, b) => rowRank(a) - rowRank(b) || a.localeCompare(b));
 	const kept = [];
 	const dropped = [];
@@ -5744,200 +5679,7 @@ function formatBytes(n) {
 	return `${(n / (1024 * 1024)).toFixed(1)} MB`;
 }
 //#endregion
-//#region src/intent/markdown.ts
-/**
-* Split on level-2 headings. Deeper headings belong to the section they sit
-* in — a case that structures its steps with `###` is still one case.
-*/
-function splitSections(source) {
-	const sections = [];
-	let current = null;
-	for (const line of source.split(/\r?\n/)) {
-		const heading = /^##\s+(.*\S)\s*$/.exec(line);
-		if (heading) {
-			if (current) sections.push(current);
-			current = {
-				heading: heading[1],
-				body: ""
-			};
-			continue;
-		}
-		if (current) current.body += `${line}\n`;
-	}
-	if (current) sections.push(current);
-	return sections.map((s) => ({
-		heading: s.heading,
-		body: s.body.trim()
-	}));
-}
-/**
-* `1. text`, `1) text`, `1．text`, at the start of a line.
-*
-* The indent is bounded to three spaces because deeper means a nested list —
-* a sub-item of the step above, not a step. And the literal digits are not the
-* step's number: markdown lets every item be written `1.` and leaves the
-* counting to the renderer, so ccqa counts the same way a reader does.
-*/
-const NUMBERED = /^ {0,3}(\d+)\s*[.)．]\s*(.+)$/;
-/** `- text`, `* text`, `・text` — the bullet characters people actually use. */
-const BULLET = /^\s*(?:[-*+]|・)\s*(.+)$/;
-function numberedItems(body) {
-	const steps = [];
-	for (const line of body.split("\n")) {
-		const m = NUMBERED.exec(line);
-		if (m) steps.push({
-			number: steps.length + 1,
-			text: m[2].trim()
-		});
-		else if (steps.length > 0 && /^\s+\S/.test(line)) {
-			const last = steps[steps.length - 1];
-			last.text = `${last.text} ${line.trim()}`;
-		}
-	}
-	return steps;
-}
-/**
-* A section written as a list, or as a paragraph.
-*
-* The list form is the useful one — each item is placed against the step that
-* makes it true — but a case whose author wrote a sentence has still stated an
-* expectation, and dropping it because of its punctuation would be ccqa losing
-* what the case says. So prose is one item, and nothing is lost either way.
-*/
-function listOrProse(body) {
-	const items = bulletItems(body);
-	if (items.length > 0) return items;
-	const prose = body.trim();
-	return prose.length > 0 ? [prose] : [];
-}
-/** Cleanup, likewise: numbered when numbered, otherwise the paragraph as one step. */
-function cleanupSteps(body) {
-	const numbered = numberedItems(body);
-	if (numbered.length > 0) return numbered;
-	const prose = body.trim();
-	return prose.length > 0 ? [{
-		number: 1,
-		text: prose
-	}] : [];
-}
-/** `- text` at the left margin — not an indented bullet, which continues the step above it. */
-const TOP_LEVEL_BULLET = /^ {0,3}(?:[-*+]|・)\s*(.+)$/;
-/**
-* What a cleanup section says besides its steps. A case that numbers its
-* teardown and then lists what should be true afterwards is stating two
-* different things under one heading, and only the numbered half is a step.
-* An unnumbered section is prose the whole way down and states no separate
-* expectation.
-*/
-function cleanupExpectations(body) {
-	if (numberedItems(body).length === 0) return [];
-	return body.split("\n").map((line) => TOP_LEVEL_BULLET.exec(line)?.[1]?.trim()).filter((text) => text !== void 0 && text.length > 0);
-}
-function bulletItems(body) {
-	return body.split("\n").map((line) => BULLET.exec(line)?.[1]?.trim()).filter((text) => text !== void 0 && text.length > 0);
-}
-/**
-* A labelled bullet's value: `URL: https://…` / `URL：https://…`. Both colons,
-* because a case written in Japanese uses the full-width one and nobody should
-* have to think about it.
-*/
-function labelled(items, label) {
-	for (const item of items) {
-		const m = /^([^:：]+)[:：]\s*(.*)$/.exec(item);
-		if (m && m[1].trim().toLowerCase() === label.toLowerCase()) {
-			const value = m[2].trim();
-			if (value.length > 0) return value;
-		}
-	}
-}
-/**
-* Read one markdown file as a case. A heading the field map names becomes that
-* field; everything else is carried through untouched. The only hard
-* requirement is a numbered list of steps: a case with none describes nothing
-* to record, and failing here beats a recording of nothing.
-*/
-function parseMarkdownCase(input) {
-	const { fields } = input;
-	const sections = splitSections(input.source);
-	const named = new Map(sections.map((s) => [s.heading, s]));
-	const body = (heading) => named.get(heading)?.body ?? "";
-	const steps = numberedItems(body(fields.steps));
-	if (steps.length === 0) throw new Error(`${input.id}: no steps — the "${fields.steps}" section must hold a numbered list of what to do`);
-	const linkItems = bulletItems(body(fields.link));
-	const claimed = new Set(Object.values({
-		...fields,
-		precondition: ""
-	}));
-	claimed.delete("");
-	const title = body(fields.title).trim();
-	return {
-		id: input.id,
-		title: title.length > 0 ? firstLine(title) : input.id,
-		steps,
-		expected: listOrProse(body(fields.expected)),
-		cleanup: cleanupSteps(body(fields.cleanup)),
-		cleanupExpected: cleanupExpectations(body(fields.cleanup)),
-		...body(fields.priority) ? { priority: firstLine(body(fields.priority)) } : {},
-		...fields.mode && body(fields.mode) ? { mode: firstLine(body(fields.mode)) } : {},
-		link: {
-			...labelled(linkItems, "url") ? { url: labelled(linkItems, "url") } : {},
-			...labelled(linkItems, "no") ? { ref: labelled(linkItems, "no") } : {}
-		},
-		other: sections.filter((s) => !claimed.has(s.heading) && s.body.length > 0),
-		sections
-	};
-}
-function firstLine(text) {
-	return text.split("\n")[0].trim();
-}
-/**
-* The same file with one section's body replaced, and every other byte left
-* alone. Used to write a generated test's path back into the case that asked
-* for it — a case file is the project's, and ccqa rewrites exactly the line it
-* was given permission to.
-*/
-function replaceSectionBody(source, heading, body) {
-	const eol = source.includes("\r\n") ? "\r\n" : "\n";
-	const lines = source.split(/\r?\n/);
-	const start = lines.findIndex((line) => /^##\s+(.*\S)\s*$/.exec(line)?.[1] === heading);
-	if (start === -1) return null;
-	let end = start + 1;
-	while (end < lines.length && !/^##\s+/.test(lines[end])) end++;
-	let tail = end;
-	while (tail > start + 1 && lines[tail - 1].trim() === "") tail--;
-	const rest = lines.slice(tail);
-	return [
-		...lines.slice(0, start + 1),
-		"",
-		body,
-		...rest.length > 0 ? rest : [""]
-	].join(eol);
-}
-//#endregion
-//#region src/intent/case.ts
-/**
-* A case's mode, from the heading the project mapped to `intent.fields.mode`.
-*
-* Only `live` turns the browser agent on; everything else is recorded and
-* generated. An unrecognised body is warned about rather than accepted
-* silently — a project that wrote `manual` there meant something by it, and
-* reading that as "record and generate" without a word is how a case ends up
-* automated that nobody meant to automate.
-*/
-function resolveMode(raw, id) {
-	const value = raw?.trim().toLowerCase() ?? "";
-	if (value === "live") return "live";
-	if (value !== "" && !DETERMINISTIC_SPELLINGS.has(value)) warn(`${id}: mode "${raw.trim()}" is not a mode ccqa knows; recording and generating it`);
-	return DEFAULT_SPEC_MODE;
-}
-/** Bodies that plainly mean "not live", so they pass without a warning. */
-const DETERMINISTIC_SPELLINGS = new Set([
-	"deterministic",
-	"recorded",
-	"generated",
-	"auto",
-	"automated"
-]);
+//#region src/cases/case.ts
 /**
 * Step ids are the case's numbering, so evidence and diffs can cite them. The
 * one spelling: `step-comment.ts` rebuilds an id from a comment's number, and
@@ -5952,11 +5694,12 @@ function cleanupId(n) {
 /** ccqa's own spec, expanded — the shape every target has always consumed. */
 function caseFromSpec(featureName, specName, yaml, blocks, cwd) {
 	const spec = parseTestSpec(yaml);
+	const expanded = expandOrName(spec, blocks);
 	return {
 		ref: specCase(featureName, specName, cwd),
 		title: spec.title,
 		mode: spec.mode ?? "deterministic",
-		steps: expandSpec(spec, { blocks }),
+		steps: expanded.steps,
 		cleanup: [],
 		expectations: [],
 		cleanupExpectations: [],
@@ -5965,137 +5708,337 @@ function caseFromSpec(featureName, specName, yaml, blocks, cwd) {
 			case: `${featureName}/${specName}`,
 			title: spec.title
 		},
-		source: {
-			kind: "spec",
-			spec,
-			yaml
-		}
+		disabled: spec.disabled === true,
+		blocked: expanded.blocked,
+		document: {
+			path: specFilePath(featureName, specName, cwd),
+			text: yaml
+		},
+		spec
 	};
 }
-/** A markdown test case, read through the project's field map. */
-function caseFromMarkdown(input) {
-	const parsed = parseMarkdownCase({
-		id: input.id,
-		source: input.source,
-		fields: input.intent.fields
-	});
+/**
+* The spec's steps with its blocks inlined — or, when a block cannot be
+* resolved, each step named as the document writes it and the reason carried
+* on `blocked`. Naming the block is what a reader of the document sees; it is
+* not a step anything may act on, which is what `blocked` says.
+*/
+function expandOrName(spec, blocks) {
+	try {
+		return {
+			steps: expandSpec(spec, { blocks }),
+			blocked: null
+		};
+	} catch (err) {
+		return {
+			steps: spec.steps.map((step, i) => {
+				const body = isIncludeStep(step) ? {
+					instruction: `include block: ${step.include}`,
+					expected: ""
+				} : step;
+				return {
+					id: stepId(i + 1),
+					source: "case",
+					...body
+				};
+			}),
+			blocked: err instanceof Error ? err.message : String(err)
+		};
+	}
+}
+/**
+* Lift what a source answered (see `./contract.ts`) into the shape every
+* feature consumes.
+*/
+function caseFromDocument(read, cwd) {
 	return {
-		ref: intentCase(input.id, input.cwd),
-		title: parsed.title,
-		mode: resolveMode(parsed.mode, input.id),
-		steps: parsed.steps.map((step) => ({
-			id: stepId(step.number),
+		ref: sourcedCase(read.id, cwd),
+		title: read.title,
+		mode: read.mode,
+		steps: read.steps.map((step, i) => ({
+			id: stepId(i + 1),
 			source: "case",
-			instruction: step.text,
-			expected: ""
+			instruction: step.instruction,
+			expected: step.expected ?? ""
 		})),
-		cleanup: parsed.cleanup.map((step) => ({
-			id: cleanupId(step.number),
+		cleanup: (read.cleanup ?? []).map((step, i) => ({
+			id: cleanupId(i + 1),
 			source: "cleanup",
-			instruction: step.text,
-			expected: ""
+			instruction: step.instruction,
+			expected: step.expected ?? ""
 		})),
-		expectations: parsed.expected,
-		cleanupExpectations: parsed.cleanupExpected,
-		context: parsed.other,
+		expectations: [...read.expectations ?? []],
+		cleanupExpectations: [...read.cleanupExpectations ?? []],
+		context: [...read.context ?? []],
 		fields: {
-			case: input.id,
-			title: parsed.title,
-			...parsed.priority ? { priority: parsed.priority } : {},
-			...parsed.link.url ? { "link.url": parsed.link.url } : {},
-			...parsed.link.ref ? { "link.ref": parsed.link.ref } : {}
+			case: read.id,
+			title: read.title,
+			...read.fields
 		},
-		source: {
-			kind: "markdown",
-			path: input.path,
-			text: input.source,
-			parsed
-		}
+		disabled: read.disabled === true,
+		blocked: null,
+		document: {
+			path: read.path,
+			text: read.text
+		},
+		spec: null
 	};
 }
+//#endregion
+//#region src/cases/case-schema.ts
 /**
-* The case a CLI argument names, for a target that reads an intent source.
-* Both forms work: the file as the user sees it in their editor
-* (`docs/testcase/todo/add_item.md`) and the id the rest of ccqa uses
-* (`todo/add_item`) — the same case, named the two ways people reach for.
+* The published contract, as something ccqa can check an answer against.
+*
+* Internal on purpose: `ccqa/case-source` exports types only, so a reader
+* module never has to resolve ccqa's zod. The two are kept in step by the
+* assertions below rather than by one being derived from the other — the
+* public shape stays hand-written and readable, and a field added to either
+* without the other stops the build.
 */
-async function loadMarkdownCase(argument, intent, cwd) {
-	const rootAbs = resolve(cwd, intent.root);
-	const id = caseIdFor(argument, intent, cwd);
-	const path = resolve(rootAbs, `${id}.md`);
-	return caseFromMarkdown({
-		id,
-		path,
-		source: await readFile(path, "utf8").catch(() => {
-			throw new Error(`No test case at ${relative(cwd, path)} (${intent.kind} source under ${intent.root})`);
-		}),
-		intent,
-		cwd
-	});
-}
+const CaseStepSchema = z.object({
+	instruction: z.string().min(1),
+	expected: z.string().optional()
+}).strict();
+const CaseSchema = z.object({
+	id: z.string().min(1).regex(/^[^/\\][^\\]*$/, "a case id is a '/'-separated path with no leading slash and no backslashes").refine((id) => !id.endsWith("/") && !id.split("/").includes(".."), { message: "a case id must not end in '/' or contain '..'" }),
+	path: z.string().min(1),
+	text: z.string(),
+	title: z.string().min(1),
+	mode: z.enum(["deterministic", "live"]),
+	steps: z.array(CaseStepSchema).min(1),
+	cleanup: z.array(CaseStepSchema).optional(),
+	expectations: z.array(z.string().min(1)).optional(),
+	cleanupExpectations: z.array(z.string().min(1)).optional(),
+	context: z.array(z.object({
+		heading: z.string().min(1),
+		body: z.string()
+	}).strict()).optional(),
+	fields: z.record(z.string().min(1), z.string()).optional(),
+	disabled: z.boolean().optional()
+}).strict();
+//#endregion
+//#region src/cases/module-source.ts
 /**
-* Every case the intent source holds, by id, sorted.
+* The project's own case reader, loaded from the module `targets.<id>.cases`
+* names.
 *
-* A sweep enumerates cases the same way a person finds them — by looking in
-* the directory the project pointed at — because there is no manifest to read
-* and a case that exists only on disk still has to be audited.
-*
-* A `.md` that does not parse as a case is not one: the directory holds a
-* project's own documents, and a README or a template sitting beside the
-* cases must not be swept into a run or an audit. Naming such a file on the
-* command line still fails loudly — this only decides what a sweep picks up.
+* ccqa imports it and validates everything it returns. Nothing about the
+* project's format reaches ccqa — not a heading, not a bullet character, not a
+* punctuation mark — which is the point: a format-specific accommodation has
+* nowhere here to land.
 */
-async function listMarkdownCases(intent, cwd) {
-	const rootAbs = resolve(cwd, intent.root);
-	const files = [];
-	const walk = async (dirAbs) => {
-		const entries = await readdir(dirAbs, { withFileTypes: true }).catch(() => []);
-		for (const entry of entries) {
-			if (entry.name.startsWith(".")) continue;
-			const abs = join(dirAbs, entry.name);
-			if (entry.isDirectory()) await walk(abs);
-			else if (entry.name.endsWith(".md")) files.push({
-				id: relative(rootAbs, abs).slice(0, -3).split(/[\\/]+/).join("/"),
-				abs
+/** Extensions Node can import on its own, on every version ccqa supports. */
+const LOADABLE = [
+	".mjs",
+	".js",
+	".cjs"
+];
+function moduleCaseSource(modulePath, cwd, targetId) {
+	const at = `targets.${targetId}.cases (${modulePath})`;
+	let opened = null;
+	const source = () => opened ??= open$1(modulePath, at, cwd);
+	return {
+		async list() {
+			const listed = await (await source()).list();
+			if (!Array.isArray(listed) || listed.some((id) => typeof id !== "string")) throw new RunUsageError(`${at}: list() must return an array of case ids`);
+			return [...new Set(listed)].sort();
+		},
+		idFor: (ref) => ref,
+		async read(ref) {
+			const absent = (error) => ({
+				id: ref,
+				case: null,
+				document: null,
+				error
 			});
+			let loaded;
+			try {
+				loaded = CaseSchema.parse(await (await source()).load(ref));
+			} catch (err) {
+				if (err instanceof RunUsageError) throw err;
+				if (err instanceof ZodError) return absent(`${at}: load(${JSON.stringify(ref)}) returned ${describe(err)}`);
+				return absent(errMessage(err));
+			}
+			return {
+				id: loaded.id,
+				case: caseFromDocument(loaded, cwd),
+				document: {
+					path: loaded.path,
+					text: loaded.text
+				},
+				error: null
+			};
 		}
 	};
-	await walk(rootAbs);
-	return (await Promise.all(files.map(async ({ id, abs }) => {
-		const source = await readFile(abs, "utf8").catch(() => null);
-		if (source === null) return null;
-		try {
-			parseMarkdownCase({
-				id,
-				source,
-				fields: intent.fields
-			});
-			return id;
-		} catch {
-			return null;
-		}
-	}))).filter((id) => id !== null).sort();
+}
+async function open$1(modulePath, at, cwd) {
+	if (!LOADABLE.some((ext) => modulePath.endsWith(ext))) throw new RunUsageError(`${at}: cannot be loaded — ${notJavaScript()}`);
+	let mod;
+	try {
+		mod = await import(pathToFileURL(modulePath).href);
+	} catch (err) {
+		const hint = err?.code === "ERR_UNKNOWN_FILE_EXTENSION" ? ` ${notJavaScript()}` : "";
+		throw new RunUsageError(`${at}: could not be loaded — ${errMessage(err)}${hint}`);
+	}
+	if (typeof mod.default !== "function") throw new RunUsageError(`${at}: must default-export a function taking { cwd } and returning { list, load } — see https://github.com/shibukazu/ccqa/blob/main/docs/targets.md`);
+	const opened = await mod.default({ cwd });
+	if (typeof opened !== "object" || opened === null || typeof opened.list !== "function" || typeof opened.load !== "function") throw new RunUsageError(`${at}: the default export must return an object with list() and load()`);
+	return opened;
+}
+/**
+* The mistake that is actually likely, in the terms it is made in. Consumers
+* write TypeScript, and an extension error alone reads as a broken install.
+*/
+function notJavaScript() {
+	return `a case source is plain JavaScript (${LOADABLE.join(", ")}): ccqa imports it with no loader, so a TypeScript file cannot be read. Write it as .mjs — \`// @ts-check\` plus \`@type {import("ccqa/case-source").CaseSourceFactory}\` type-checks it without a build step — or point \`cases\` at compiled output.`;
+}
+/** A zod rejection as one line per offending field. */
+function describe(err) {
+	return `a value that is not a case — ${err.issues.map((issue) => {
+		return `${issue.path.join(".") || "(the case)"}: ${issue.message}`;
+	}).join("; ")}`;
+}
+//#endregion
+//#region src/cases/spec-source.ts
+/**
+* ccqa's own `spec.yaml` as a case source.
+*
+* The functions that read a spec file live here rather than in the store, so
+* that a feature wanting a case document has no import that reaches one kind
+* of case directly. The store still says where the file is (`specFilePath`)
+* and still enumerates the tree — the layout is its business; reading a case
+* is not.
+*/
+/** One case's `spec.yaml`, null when there is no such file. */
+async function tryReadSpecFile(featureName, specName, cwd) {
+	return readFile(specFilePath(featureName, specName, cwd), "utf-8").catch(() => null);
 }
 /**
-* The case ids an invocation named, or every case when it named none.
+* 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.
 *
-* Both commands that sweep a project's own documents ask this, and they must
-* agree: what a `<case>` argument names has one answer, not one per command.
+* Only `ccqa draft` still asks for this: it authors ccqa's own format, so it
+* is the one command whose subject is the tree rather than the cases in it.
 */
-async function intentCaseIds(named, intent, cwd) {
-	if (named.length === 0) return listMarkdownCases(intent, cwd);
-	return [...new Set(named.map((argument) => caseIdFor(argument, intent, cwd)))];
+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 specFile = join(testCasesDir, specName, "spec.yaml");
+				const content = await readFile(specFile, "utf-8").catch(() => null);
+				if (content === null) return {
+					specName,
+					hasSpecFile: false
+				};
+				try {
+					return {
+						specName,
+						hasSpecFile: true,
+						includedBlocks: collectIncludedBlockNames(parseTestSpec(content, specFile))
+					};
+				} catch {
+					return {
+						specName,
+						hasSpecFile: true
+					};
+				}
+			}))
+		};
+	}));
+}
+function specCaseSource(cwd) {
+	let blocks = null;
+	return {
+		async list() {
+			return (await listAllSpecsWithSpecFile(cwd)).map(specKey).sort();
+		},
+		idFor: (ref) => specKey(parseSpecPath(ref)),
+		async read(id) {
+			const { featureName, specName } = parseSpecPath(id);
+			const path = specFilePath(featureName, specName, cwd);
+			const yaml = await tryReadSpecFile(featureName, specName, cwd);
+			if (yaml === null) return {
+				id,
+				case: null,
+				document: null,
+				error: `Spec file not found: ${path}`
+			};
+			const document = {
+				path,
+				text: yaml
+			};
+			blocks ??= loadAllBlocks(cwd);
+			try {
+				return {
+					id,
+					case: caseFromSpec(featureName, specName, yaml, await blocks, cwd),
+					document,
+					error: null
+				};
+			} catch (err) {
+				return {
+					id,
+					case: null,
+					document,
+					error: errMessage(err)
+				};
+			}
+		}
+	};
 }
+//#endregion
+//#region src/cases/reader.ts
 /**
-* A path below the intent root, or an id already in that form. Only a `.md`
-* suffix is stripped — a case named `add.item` is a case, not an id with an
-* extension, and the two spellings this exists to make equivalent have to
-* agree about that.
+* The target whose cases live in the project, when that is what we resolve to.
+*
+* Which of the two places a project keeps its cases in is settled by its
+* target, not by guessing at an argument's shape: a target that declares a
+* case source of its own reads the project's documents, and one that does not
+* reads ccqa's `spec.yaml`.
 */
-function caseIdFor(argument, intent, cwd) {
-	const below = relative(resolve(cwd, intent.root), isAbsolute(argument) ? argument : resolve(cwd, argument));
-	const id = below !== "" && !below.startsWith("..") && !isAbsolute(below) ? below : argument;
-	return (id.endsWith(".md") ? id.slice(0, -3) : id).split(/[\\/]+/).join("/");
+function caseTargetFor(config, cwd, targetOverride) {
+	const id = targetOverride ?? config.defaultTarget;
+	const targetConfig = config.targets[id];
+	const module = targetConfig?.cases;
+	if (targetConfig === void 0 || module === void 0) return null;
+	return {
+		id,
+		targetConfig,
+		module,
+		modulePath: isAbsolute(module) ? module : resolve(cwd, module)
+	};
+}
+function openCaseReader(config, cwd, opts = {}) {
+	const target = caseTargetFor(config, cwd, opts.targetOverride);
+	const source = target ? moduleCaseSource(target.modulePath, cwd, target.id) : specCaseSource(cwd);
+	const byId = /* @__PURE__ */ new Map();
+	const read = (ref) => {
+		const key = source.idFor(ref);
+		const cached = byId.get(key);
+		if (cached !== void 0) return cached;
+		const pending = source.read(key);
+		byId.set(key, pending);
+		pending.then((result) => {
+			if (!byId.has(result.id)) byId.set(result.id, pending);
+		}, () => {});
+		return pending;
+	};
+	return {
+		list: () => source.list(),
+		read,
+		async load(ref) {
+			const result = await read(ref);
+			if (result.case === null) throw new RunUsageError(result.error ?? `no test case named "${ref}"`);
+			if (result.case.blocked !== null) throw new RunUsageError(result.case.blocked);
+			return result.case;
+		},
+		target
+	};
 }
 //#endregion
 //#region src/targets/agent-browser/judge-steps.ts
@@ -13833,13 +13776,14 @@ async function loadEvidenceForSpec(evidenceDir, reportDir, descriptionByStepId)
 	const reportRoot = resolve(reportDir);
 	const jsonFiles = entries.filter((n) => n.endsWith(".json"));
 	const metas = (await Promise.all(jsonFiles.map((name) => readEvidenceMeta(join(evidenceDir, name), evidenceDir, reportRoot, descriptionByStepId)))).filter((m) => m !== null);
-	metas.sort((a, b) => {
-		if (a.stepId === "failure") return 1;
-		if (b.stepId === "failure") return -1;
-		return a.stepId.localeCompare(b.stepId);
-	});
+	metas.sort((a, b) => phase(a.stepId) - phase(b.stepId) || a.stepId.localeCompare(b.stepId));
 	return metas.length > 0 ? metas : null;
 }
+/** Steps, then cleanup, then the failure capture. */
+function phase(stepId) {
+	if (stepId === "failure") return 2;
+	return stepId.startsWith("cleanup-") ? 1 : 0;
+}
 async function readEvidenceMeta(metaPath, evidenceDir, reportRoot, descriptionByStepId) {
 	let raw;
 	try {
@@ -13856,7 +13800,7 @@ async function readEvidenceMeta(metaPath, evidenceDir, reportRoot, descriptionBy
 	if (typeof parsed !== "object" || parsed === null) return null;
 	const pngFile = parsed.pngFile;
 	if (typeof pngFile !== "string") return null;
-	const relToReport = (file) => posix.relative(toPosix(reportRoot), toPosix(join(evidenceDir, file)));
+	const relToReport = (file) => posix.relative(toPosix$1(reportRoot), toPosix$1(join(evidenceDir, file)));
 	const pngPath = relToReport(pngFile);
 	const beforePngFile = parsed.beforePngFile;
 	const beforePngPath = typeof beforePngFile === "string" ? relToReport(beforePngFile) : null;
@@ -13878,20 +13822,27 @@ async function readEvidenceMeta(metaPath, evidenceDir, reportRoot, descriptionBy
 	return result.success ? result.data : null;
 }
 /**
-* Build `step id → expected` so the report can caption each evidence
-* screenshot. Returns an empty map on expansion failure (evidence still
-* surfaces, just without captions).
+* Build `step id → caption` so the report can label each evidence screenshot.
+* Empty when the case could not be read — evidence still surfaces, just
+* without captions.
+*
+* What the step must make true, falling back to what it does. A case that
+* states its expectations once for the whole flow leaves every step's own
+* `expected` empty, and a filmstrip captioned with blanks says less than the
+* instructions the case's author wrote.
+*
+* Cleanup steps are captioned too: they have step ids of their own and leave
+* screenshots of their own, and an uncaptioned row reads as a step nobody
+* described rather than as the undo it is.
 */
-function buildStepDescriptions(spec, blocks) {
-	if (!spec) return /* @__PURE__ */ new Map();
-	try {
-		const expanded = expandSpec(spec, { blocks });
-		return new Map(expanded.map((s) => [s.id, (isExpandedJudgeByLlmStep(s) ? s.judgeByLlm : s.expected).trim()]));
-	} catch {
-		return /* @__PURE__ */ new Map();
-	}
+function stepCaptions(testCase) {
+	if (!testCase) return /* @__PURE__ */ new Map();
+	return new Map([...testCase.steps, ...testCase.cleanup].map((s) => {
+		if (isExpandedJudgeByLlmStep(s)) return [s.id, s.judgeByLlm.trim()];
+		return [s.id, (s.expected.trim() || s.instruction).trim()];
+	}));
 }
-function toPosix(p) {
+function toPosix$1(p) {
 	return p.split(/[\\/]/).join("/");
 }
 //#endregion
@@ -13990,14 +13941,14 @@ function parseTraceEvents(jsonl) {
 			});
 		} else if (type === "action") {
 			if (typeof event.callId === "string" && typeof event.startTime === "number" && typeof event.endTime === "number") steps.push({
-				title: titleOf(event),
+				title: titleOf$1(event),
 				startTime: event.startTime,
 				endTime: event.endTime,
 				...errorOf(event)
 			});
 		} else if (type === "before") {
 			if (typeof event.callId === "string" && typeof event.startTime === "number") pendingByCallId.set(event.callId, {
-				title: titleOf(event),
+				title: titleOf$1(event),
 				startTime: event.startTime
 			});
 		} else if (type === "after") {
@@ -14035,7 +13986,7 @@ function errorOf(event) {
 	}
 	return {};
 }
-function titleOf(event) {
+function titleOf$1(event) {
 	if (typeof event.apiName === "string") return event.apiName;
 	if (typeof event.title === "string") return event.title;
 	return "";
@@ -14208,12 +14159,11 @@ function substituteRunCommandFiles(runCommand, testFiles) {
 */
 const runCommandRunner = { async run(specs, opts) {
 	const concurrency = Math.max(1, opts.concurrency);
-	const blocks = opts.stepEvidence.supported ? await loadAllBlocks(opts.cwd) : /* @__PURE__ */ new Map();
 	return runPool(specs, concurrency, async (spec) => {
 		const key = `${spec.featureName}/${spec.specName}`;
 		let row;
 		try {
-			row = await withBuffer(key, concurrency > 1, () => runOneSpec(spec, opts, blocks));
+			row = await withBuffer(key, concurrency > 1, () => runOneSpec(spec, opts));
 		} catch (err) {
 			const message = err instanceof Error ? err.message : String(err);
 			error(`${key}: runner error: ${message}`);
@@ -14237,11 +14187,10 @@ const runCommandRunner = { async run(specs, opts) {
 		return row;
 	}, { resources: opts.resources });
 } };
-async function runOneSpec(ref, opts, blocks) {
-	const { featureName, specName } = ref;
-	const specYaml = await tryReadSpecFile(featureName, specName, opts.cwd);
-	const parsedSpec = tryParseTestSpec(specYaml);
-	const title = parsedSpec?.title ?? null;
+async function runOneSpec(ref, opts) {
+	const { featureName, specName, testCase } = ref;
+	const specYaml = testCase?.document.text ?? null;
+	const title = testCase?.title ?? null;
 	const failedRow = (detail) => ({
 		...emptySpecRow({
 			feature: featureName,
@@ -14267,9 +14216,9 @@ async function runOneSpec(ref, opts, blocks) {
 	const runCommand = opts.targetConfig.runCommand;
 	if (runCommand === void 0) return didNotExecute(`target "${opts.targetId}" has no runCommand configured in .ccqa/config.yaml`, "the target has no runCommand");
 	run(`${featureName}/${specName}`);
-	const testFile = resolveTestPath(opts, opts.targetConfig, ref);
+	const testFile = resolveCaseTestPath(opts, opts.targetConfig, ref.caseId);
 	if (!await stat(resolve(opts.cwd, testFile)).then(() => true, () => false)) {
-		const detail = `no generated test at ${testFile} — run 'ccqa generate ${featureName}/${specName}' first`;
+		const detail = `no generated test at ${testFile} — run 'ccqa generate ${ref.caseId}' first`;
 		error(detail);
 		return didNotExecute(detail, "no generated tests");
 	}
@@ -14368,6 +14317,7 @@ async function runOneSpec(ref, opts, blocks) {
 			reportDir: opts.reportDir,
 			feature: featureName,
 			spec: specName,
+			passed: outcome.exitCode === 0,
 			warn
 		});
 	} catch (err) {
@@ -14378,8 +14328,7 @@ async function runOneSpec(ref, opts, blocks) {
 		opts,
 		evidence,
 		artifactsDir,
-		spec: parsedSpec,
-		blocks,
+		testCase,
 		...traceUnavailable !== void 0 ? { traceUnavailable } : {}
 	});
 	if (outcome.exitCode === 0) return {
@@ -14436,7 +14385,7 @@ async function loadStepEvidence(args) {
 		artifactsDir: args.artifactsDir,
 		evidenceDir
 	});
-	const descriptions = buildStepDescriptions(args.spec, args.blocks);
+	const descriptions = stepCaptions(args.testCase);
 	const evidence = await loadEvidenceForSpec(evidenceDir, opts.reportDir, descriptions);
 	if (evidence) return { evidence };
 	return {
@@ -16374,90 +16323,39 @@ function resolveTargetFrom(spec, config, registry) {
 	return plugin;
 }
 //#endregion
-//#region src/cli/resolve-case.ts
-async function resolveCase(argument, config, cwd, opts = {}) {
-	const intentTarget = intentTargetFor(config, opts.targetOverride);
-	if (intentTarget) {
-		const { id, targetConfig, intent } = intentTarget;
-		const target = registryFor(config).get(id);
-		const testCase = await loadMarkdownCase(argument, intent, cwd);
-		const testPath = resolveCaseTestPath(target, targetConfig, testCase.ref.id);
-		const recordingPath = (opts.targetOverride === void 0 ? void 0 : ownIntentRecordingPath(config, intent, testCase.ref.id)) ?? resolveCaseRecordingPath(target, targetConfig, testCase.ref.id);
-		const ref = caseRefFor(testCase.ref.id, cwd, recordingPath);
-		return {
-			testCase: {
-				...testCase,
-				ref
-			},
-			target,
-			targetConfig,
-			testPath
-		};
-	}
-	const { featureName, specName } = parseSpecPath(argument);
-	const testCase = caseFromSpec(featureName, specName, await readSpecFile(featureName, specName, cwd), await loadAllBlocks(cwd), cwd);
-	const spec = testCase.source.kind === "spec" ? testCase.source.spec : null;
-	const target = opts.targetOverride !== void 0 ? resolveTargetOverride(spec, opts.targetOverride, config) : resolveTarget(spec, config);
-	const targetConfig = targetConfigFor(config, target.id);
-	const specRef = {
-		featureName,
-		specName
-	};
-	const testPath = resolveTestPath(target, targetConfig, specRef);
-	const ref = caseRefFor(specRef, cwd, opts.targetOverride === void 0 ? resolveRecordingPath(target, targetConfig, specRef) : ownRecordingPath(spec, config, specRef));
-	return {
-		testCase: {
-			...testCase,
-			ref
-		},
-		target,
-		targetConfig,
-		testPath
-	};
+//#region src/drift/types.ts
+/** How everything downstream spells this case: its intent-source id, or `feature/spec`. */
+function caseIdOf(target) {
+	return target.caseId ?? `${target.featureName}/${target.specName}`;
 }
 /**
-* Where the spec's own target keeps this case's recording, ignoring any
-* `--target`. Undefined when that target no longer resolves: overriding the
-* target is how a spec with an unusable one is generated at all, so it must
-* not be what stops the command.
+* What the audit says about one locator code could not find in the product.
 *
-* Only the resolution is guarded. A target that resolved and then could not
-* expand its own `testPath` is a broken config, and swallowing that would put
-* the recording somewhere else without a word.
+* `drifted` says the test asks for something the product no longer renders;
+* `fine` says the miss has another explanation — a selector built at runtime, a
+* component this case never reaches, a file the scan did not read. Either is an
+* answer; silence is not, which is what the required list below is for.
 */
-function ownRecordingPath(spec, config, ref) {
-	let target;
-	try {
-		target = resolveTarget(spec, config);
-	} catch {
-		return;
-	}
-	return resolveRecordingPath(target, targetConfigFor(config, target.id), ref);
-}
+const LocatorVerdictSchema = z.object({
+	id: z.string().min(1),
+	verdict: z.enum(["drifted", "fine"]),
+	note: z.string().default("")
+});
+/** The model's reply: a diagnosis, or `null` for "the spec still matches the code". */
+const DriftReplySchema = z.object({
+	drift: DriftDiagnosisSchema.nullable(),
+	locators: z.array(LocatorVerdictSchema).default([])
+});
 /**
-* The intent branch's half of the same rule: where the project's own default
-* target keeps this case's recording.
-*
-* Undefined when that target reads a different set of cases than the one this
-* invocation resolved through — a target pointed at another directory is
-* describing a different case that happens to share an id, and its route is
-* not this case's.
+* How a label reads against `--exit-on`. The threshold asks "would a
+* deterministic replay fail today". `TEST_DRIFT` and `SPEC_CHANGE` answer yes
+* and name the repair, so they hold the gate shut. The other three do not: a
+* suspected product bug or a dependency on data the source does not decide is
+* settled by running the case, not by refusing to run it, and `UNKNOWN` says
+* the audit could not tell.
 */
-function ownIntentRecordingPath(config, reading, caseId) {
-	const own = intentTargetFor(config);
-	if (own === null || own.intent.root !== reading.root) return void 0;
-	const plugin = registryFor(config).get(own.id);
-	return plugin ? resolveCaseRecordingPath(plugin, own.targetConfig, caseId) : void 0;
-}
-/** The target whose cases live in the project, when that is what we resolve to. */
-function intentTargetFor(config, targetOverride) {
-	const id = targetOverride ?? config.defaultTarget;
-	const targetConfig = config.targets[id];
-	return targetConfig?.intent ? {
-		id,
-		targetConfig,
-		intent: targetConfig.intent
-	} : null;
+function driftSeverity(label) {
+	return label === "TEST_DRIFT" || label === "SPEC_CHANGE" ? "error" : "warn";
 }
 //#endregion
 //#region src/drift/artifacts.ts
@@ -16468,30 +16366,38 @@ function intentTargetFor(config, targetOverride) {
 * is always named in `unaudited`.
 */
 const MAX_GENERATED_BYTES = 64 * 1024;
-/** Read the sweep-wide inputs once, before the first spec. */
-async function loadSpecArtifactsContext(cwd) {
+/**
+* Read the sweep-wide inputs once, before the first spec. A caller that
+* already holds a reader passes it, so its cases are read once for the whole
+* command rather than once per phase.
+*/
+async function loadSpecArtifactsContext(cwd, reader) {
 	const [config, tsconfig] = await Promise.all([loadProjectConfig(cwd), loadTsconfigPaths(cwd)]);
 	return {
 		config,
 		tsconfig,
-		intentTarget: intentTargetFor(config)
+		reader: reader ?? openCaseReader(config, cwd)
 	};
 }
 /**
 * Read one case's documents. Throws when the document itself cannot be read —
 * a case enumerated and then gone is an error to report, not an empty audit.
+*
+* A document that is there but will not parse is still audited: what its
+* author wrote is what the audit is for, and refusing to look at it would
+* clear a case nobody read.
 */
 async function collectCaseArtifacts(target, cwd, ctx) {
-	return target.caseId === void 0 ? await collectSpecCase(target.featureName, target.specName, cwd, ctx) : await collectIntentCase(target.caseId, cwd, ctx);
-}
-async function collectSpecCase(featureName, specName, cwd, ctx) {
-	const specYaml = await readSpecFile(featureName, specName, cwd);
+	const read = await ctx.reader.read(caseIdOf(target));
+	if (read.document === null) throw new Error(read.error ?? `${caseIdOf(target)}: no such test case`);
 	const intent = {
-		kind: "spec",
-		path: `.ccqa/features/${featureName}/test-cases/${specName}/spec.yaml`,
-		body: specYaml
+		kind: ctx.reader.target ? "project" : "spec",
+		path: relative(cwd, read.document.path),
+		body: read.document.text
 	};
-	const { live, title } = describe(specYaml);
+	const testCase = read.case;
+	const live = testCase?.mode === "live";
+	const title = testCase?.title ?? null;
 	if (live) return {
 		intent,
 		generated: [],
@@ -16502,114 +16408,109 @@ async function collectSpecCase(featureName, specName, cwd, ctx) {
 	};
 	return {
 		intent,
-		...await collectSpecGenerated(featureName, specName, specYaml, cwd, ctx),
+		...await readGenerated(testFileOf(testCase, ctx, cwd), cwd, ctx),
 		live,
 		title
 	};
 }
 /**
-* The generated half alone, for a caller that already holds the spec — the
-* failure classifier, which reads the same code the audit does but brings its
-* own account of what happened.
+* The generated half alone, for a caller that brings its own account of what
+* happened — the failure classifier, which reads the same code the audit does.
 */
-async function collectSpecGenerated(featureName, specName, specYaml, cwd, ctx) {
-	return readGenerated(specTestFile(featureName, specName, specYaml, cwd, ctx.config), cwd, ctx);
+async function collectGeneratedFor(caseId, cwd, ctx) {
+	const read = await ctx.reader.read(caseId);
+	if (read.case === null && read.error !== null) warn(`${caseId}: ${read.error}`);
+	return readGenerated(testFileOf(read.case, ctx, cwd), cwd, ctx);
 }
-async function collectIntentCase(caseId, cwd, ctx) {
-	if (!ctx.intentTarget) throw new Error(`${caseId}: no target reads this project's own test cases`);
-	const { targetConfig, intent: source } = ctx.intentTarget;
-	const testCase = await loadMarkdownCase(caseId, source, cwd);
-	const intent = {
-		kind: "markdown",
-		path: relative(cwd, testCase.source.path),
-		body: testCase.source.text
-	};
-	const live = testCase.mode === "live";
-	if (live) return {
-		intent,
-		generated: [],
-		unaudited: [],
-		reached: [],
-		live,
-		title: testCase.title
-	};
-	return {
-		intent,
-		...await readGenerated(resolve(cwd, resolveCaseTestPath(registryFor(ctx.config).get(ctx.intentTarget.id), targetConfig, caseId)), cwd, ctx),
-		live,
-		title: testCase.title
+/**
+* Where this case's files live, resolved through the target that owns them.
+*
+* All three together because one target resolution answers all three, and a
+* case that has one must not be reported as missing another. Every path is
+* null when nothing resolves — an unreadable case must cost its own paths,
+* not the sweep.
+*/
+async function caseFiles(target, ctx) {
+	const none = {
+		testPath: null,
+		recordingPath: null,
+		writeRoots: []
 	};
+	const read = await ctx.reader.read(caseIdOf(target));
+	if (read.case === null && read.error !== null) warn(`${caseIdOf(target)}: ${read.error}`);
+	const testCase = read.case;
+	const owner = testCase && targetOf$1(testCase, ctx);
+	if (!testCase || !owner) return none;
+	try {
+		return {
+			testPath: resolveCaseTestPath(owner.plugin, owner.targetConfig, testCase.ref.id),
+			recordingPath: resolveCaseRecordingPath(owner.plugin, owner.targetConfig, testCase.ref.id),
+			writeRoots: owner.targetConfig.writeRoots
+		};
+	} catch {
+		return none;
+	}
 }
 /**
 * Where this case's generated test lives, project-relative — or null when it
 * has none (a live case, or a document whose target cannot be resolved).
 */
-async function caseTestPath(target, cwd, ctx) {
-	if (target.caseId !== void 0) {
-		if (!ctx.intentTarget) return null;
-		return resolveCaseTestPath(registryFor(ctx.config).get(ctx.intentTarget.id), ctx.intentTarget.targetConfig, target.caseId);
-	}
-	const specYaml = await readSpecFile(target.featureName, target.specName, cwd).catch(() => null);
-	if (specYaml === null) return null;
-	const abs = specTestFile(target.featureName, target.specName, specYaml, cwd, ctx.config);
-	return abs === null ? null : relative(cwd, abs);
+async function caseTestPath(target, ctx) {
+	return (await caseFiles(target, ctx)).testPath;
 }
 /**
 * Where this case's recording lives, project-relative, resolved through the
 * same target as its test — null on the same terms as {@link caseTestPath}.
 */
-async function caseRecordingPath(target, cwd, ctx) {
-	if (target.caseId !== void 0) {
-		if (!ctx.intentTarget) return null;
-		return resolveCaseRecordingPath(registryFor(ctx.config).get(ctx.intentTarget.id), ctx.intentTarget.targetConfig, target.caseId);
-	}
-	const specYaml = await readSpecFile(target.featureName, target.specName, cwd).catch(() => null);
-	if (specYaml === null) return null;
-	return specTargetPaths(target.featureName, target.specName, specYaml, cwd, ctx.config)?.recordingPath ?? null;
+async function caseRecordingPath(target, ctx) {
+	return (await caseFiles(target, ctx)).recordingPath;
 }
 /**
-* Where this case's test lands, and where its target lets ccqa write.
-*
-* Together because they answer one question — which files a finding about this
-* case could be repaired by regenerating it — and because resolving the target
-* once is what keeps the two consistent for a spec that names a non-default one.
+* Where this case's test lands, and where its target lets ccqa write: the two
+* halves of "which files a finding about this case could be repaired in".
 */
-async function caseWriteArea(target, cwd, ctx) {
-	const testPath = await caseTestPath(target, cwd, ctx);
-	if (target.caseId !== void 0) return {
+async function caseWriteArea(target, ctx) {
+	const { testPath, writeRoots } = await caseFiles(target, ctx);
+	return {
 		testPath,
-		writeRoots: ctx.intentTarget?.targetConfig.writeRoots ?? []
-	};
-	const specYaml = await readSpecFile(target.featureName, target.specName, cwd).catch(() => null);
-	if (specYaml === null) return {
-		testPath,
-		writeRoots: []
+		writeRoots
 	};
+}
+/**
+* The target that owns this case's generated files.
+*
+* A case the project states itself belongs to the target that declared the
+* source; a `spec.yaml` case names its own. Null when nothing resolves — an
+* unreadable target must cost this one case's paths, not the sweep.
+*/
+function targetOf$1(testCase, ctx) {
+	if (ctx.reader.target) {
+		const plugin = registryFor(ctx.config).get(ctx.reader.target.id);
+		return plugin ? {
+			plugin,
+			targetConfig: ctx.reader.target.targetConfig
+		} : null;
+	}
+	if (testCase.spec === null) return null;
 	try {
-		const resolved = resolveTarget(parseTestSpec(specYaml), ctx.config);
+		const plugin = resolveTarget(testCase.spec, ctx.config);
 		return {
-			testPath,
-			writeRoots: targetConfigFor(ctx.config, resolved.id).writeRoots
+			plugin,
+			targetConfig: targetConfigFor(ctx.config, plugin.id)
 		};
 	} catch {
-		return {
-			testPath,
-			writeRoots: []
-		};
+		return null;
 	}
 }
-function describe(specYaml) {
+/** The generated test's absolute path, or null when this case compiles into none. */
+function testFileOf(testCase, ctx, cwd) {
+	if (testCase === null) return null;
+	const owner = targetOf$1(testCase, ctx);
+	if (owner === null) return null;
 	try {
-		const spec = parseTestSpec(specYaml);
-		return {
-			live: spec.mode === "live",
-			title: spec.title ?? null
-		};
+		return resolve(cwd, resolveCaseTestPath(owner.plugin, owner.targetConfig, testCase.ref.id));
 	} catch {
-		return {
-			live: false,
-			title: null
-		};
+		return null;
 	}
 }
 /**
@@ -16657,35 +16558,6 @@ async function readGenerated(testAbs, cwd, ctx) {
 		reached
 	};
 }
-/**
-* Where this spec's two files live, resolved through its target: the test, and
-* the recording it compiles from. A spec that will not parse, whose target
-* cannot be resolved, or whose `testPath` will not expand has neither to
-* derive — the audit then reads the spec alone rather than guessing at a file.
-*
-* Both together because one target resolution answers both, and a spec that
-* has one must not be reported as missing the other.
-*/
-function specTargetPaths(featureName, specName, specYaml, cwd, config) {
-	try {
-		const target = resolveTarget(parseTestSpec(specYaml), config);
-		const targetConfig = targetConfigFor(config, target.id);
-		const ref = {
-			featureName,
-			specName
-		};
-		return {
-			testAbs: resolveTestPathAbs(target, targetConfig, ref, cwd),
-			recordingPath: resolveRecordingPath(target, targetConfig, ref)
-		};
-	} catch {
-		return null;
-	}
-}
-/** Where this spec's test lives, resolved through its target. */
-function specTestFile(featureName, specName, specYaml, cwd, config) {
-	return specTargetPaths(featureName, specName, specYaml, cwd, config)?.testAbs ?? null;
-}
 //#endregion
 //#region src/cli/colors.ts
 /**
@@ -16768,7 +16640,7 @@ function createFailureAnalysisPass(deps) {
 		};
 		if (input.specYaml === null) return {
 			...fields,
-			analysisSkipped: "no spec.yaml found for this spec"
+			analysisSkipped: "the case's own document could not be read"
 		};
 		const baselineMissing = specDiffResult.ok ? null : specDiffResult.skip;
 		info(`failure analysis: ${featureName}/${specName}${baselineMissing ? " (no baseline — classifying from current source)" : ""}`);
@@ -16856,9 +16728,9 @@ function needsAnalysis(row) {
 * invents would land in the confusion matrix and the project's learned prompt.
 * The recorded reason is both accurate and cheaper.
 */
-async function analyzeExternalRows(rows, run) {
+async function analyzeExternalRows(rows, run, caseIds = /* @__PURE__ */ new Map()) {
 	const { deps, pass } = run;
-	const context = await loadSpecArtifactsContext(deps.cwd);
+	const context = await loadSpecArtifactsContext(deps.cwd, deps.reader);
 	const out = [];
 	for (const row of rows) {
 		if (!needsAnalysis(row)) {
@@ -16869,9 +16741,10 @@ async function analyzeExternalRows(rows, run) {
 			featureName: row.feature,
 			specName: row.spec
 		};
+		const caseId = caseIds.get(specKey(ref)) ?? specKey(ref);
 		const fields = await pass.analyze({
 			...ref,
-			readScript: () => readGeneratedTestSources(ref, row.specYaml, deps.cwd, context),
+			readScript: () => readGeneratedTestSources(caseId, deps.cwd, context),
 			failureLog: row.failureLogExcerpt ?? "",
 			specYaml: row.specYaml,
 			parsedSpec: tryParseTestSpec(row.specYaml),
@@ -16902,9 +16775,8 @@ function readableArtifactsDir(ref, deps) {
 * both surfaces read the same set. Best-effort: an ungenerated or unreadable
 * spec just means less context, never a failed analysis.
 */
-async function readGeneratedTestSources(ref, specYaml, cwd, context) {
-	if (specYaml === null) return "";
-	const { generated, unaudited } = await collectSpecGenerated(ref.featureName, ref.specName, specYaml, cwd, context);
+async function readGeneratedTestSources(caseId, cwd, context) {
+	const { generated, unaudited } = await collectGeneratedFor(caseId, cwd, context);
 	const parts = generated.map((f) => `// ${f.path}\n${f.content}`);
 	if (unaudited.length > 0) parts.push(`// [not shown: ${unaudited.join(", ")} — Read them for their full state]`);
 	return parts.join("\n\n");
@@ -18326,7 +18198,7 @@ function failureBody(row) {
 }
 /** A row's stored path (relative to `reportDir`), re-expressed relative to where the XML itself lives. */
 function rewriteEvidencePath(storedPath, reportDir, junitDir) {
-	return toPosix(relative(junitDir, resolve(reportDir, storedPath)));
+	return toPosix$1(relative(junitDir, resolve(reportDir, storedPath)));
 }
 /** Step-boundary screenshot paths for one row, in capture order, for `<system-out>`. */
 function evidencePaths(row, reportDir, junitDir) {
@@ -18391,35 +18263,22 @@ function currentReportCost() {
 }
 //#endregion
 //#region src/run/spec-catalog.ts
-async function readSpecs(refs, cwd) {
+async function readSpecs(refs, reader) {
 	const entries = await Promise.all(refs.map(async (ref) => {
-		const yaml = await tryReadSpecFile(ref.featureName, ref.specName, cwd);
-		if (yaml === null) return [specKey(ref), {
-			spec: null,
-			yaml: null,
-			error: null
+		const read = await reader.read(specKey(ref));
+		return [specKey(ref), {
+			case: read.case,
+			yaml: read.document?.text ?? null,
+			error: read.document === null ? null : read.error
 		}];
-		try {
-			return [specKey(ref), {
-				spec: parseTestSpec(yaml),
-				yaml,
-				error: null
-			}];
-		} catch (err) {
-			return [specKey(ref), {
-				spec: null,
-				yaml,
-				error: errMessage(err)
-			}];
-		}
 	}));
 	return new Map(entries);
 }
-/** Spec-declared `mode:` wins; otherwise `DEFAULT_SPEC_MODE`. */
+/** Case-declared `mode:` wins; otherwise `DEFAULT_SPEC_MODE`. */
 function resolveSpecsModes(specs, catalog) {
 	return specs.map((s) => ({
 		...s,
-		mode: catalog.get(specKey(s))?.spec?.mode ?? "deterministic"
+		mode: catalog.get(specKey(s))?.case?.mode ?? "deterministic"
 	}));
 }
 //#endregion
@@ -19994,7 +19853,7 @@ function runsLive(testCase) {
 	return testCase.mode === "live";
 }
 function liveCaseFrom(testCase, opts = {}) {
-	const spec = testCase.source.kind === "spec" ? testCase.source.spec : null;
+	const spec = testCase.spec;
 	const own = attachCaseExpectations(requireActionSteps(testCase.steps, testCase.ref.id, {
 		id: AGENT_BROWSER_TARGET,
 		reason: AGENT_BROWSER_JUDGE_STEPS.reason
@@ -20006,7 +19865,7 @@ function liveCaseFrom(testCase, opts = {}) {
 		title: testCase.title,
 		steps,
 		cleanupFrom: own.length,
-		document: testCase.source.kind === "spec" ? testCase.source.yaml : testCase.source.text,
+		document: testCase.document.text,
 		blocks: spec ? collectIncludedBlockNames(spec) : [],
 		session: {
 			names: spec?.session ?? [],
@@ -20040,135 +19899,74 @@ function attachCaseExpectations(steps, expectations) {
 //#endregion
 //#region src/select/inventory.ts
 /**
-* Read every test case the project states into the shape the selection
-* prompt consumes: ccqa's own specs under `.ccqa/features/`, or — for a
-* project whose target reads an intent source — its own markdown cases.
-* Which one a project has is a property of its target, never both at once
-* (see `intentTargetFor`), so this reads one enumeration or the other.
+* Read every test case the project states into the shape the selection prompt
+* consumes — ccqa's own specs, or the documents the project writes itself,
+* whichever this project has. One enumeration, one read per case, through the
+* one reader: what the two kinds share is everything the prompt is shown.
 */
 async function loadSpecInventory(cwd) {
 	const config = await loadProjectConfig(cwd);
-	const intentTarget = intentTargetFor(config);
-	if (intentTarget) return loadMarkdownInventory(intentTarget, config, cwd);
-	return loadSpecFileInventory(config, cwd);
-}
-/**
-* Specs without a spec file are skipped: there is nothing to judge and
-* nothing to run.
-*
-* Enumeration (`listAllSpecsWithSpecFile`, a directory walk) is kept separate
-* from reading and parsing each spec's own content, so every spec.yaml is
-* read and parsed exactly once — and the reads run in parallel.
-*/
-async function loadSpecFileInventory(config, cwd) {
-	const [refs, blocks] = await Promise.all([listAllSpecsWithSpecFile(cwd), loadAllBlocks(cwd)]);
-	return (await Promise.all(refs.map(async ({ featureName, specName }) => {
-		const content = await tryReadSpecFile(featureName, specName, cwd);
-		if (content === null) return null;
-		const spec = parseTestSpec(content, `${featureName}/${specName}/spec.yaml`);
-		if (spec.disabled) return null;
-		return {
-			featureName,
-			specName,
-			title: spec.title,
-			steps: describeSteps(spec, blocks, `${featureName}/${specName}`),
-			includedBlocks: collectIncludedBlockNames(spec),
-			...resolveSpecPaths(spec, config, featureName, specName),
-			sourcePath: `.ccqa/features/${featureName}/test-cases/${specName}/spec.yaml`
-		};
-	}))).filter((s) => s !== null);
-}
-/**
-* Same shape, for a project whose cases are its own markdown documents. No
-* `disabled` flag to drop here — that concept belongs to `spec.yaml`, and an
-* intent source has nothing that plays the same role.
-*/
-async function loadMarkdownInventory(intentTarget, config, cwd) {
-	const { id: targetId, targetConfig, intent } = intentTarget;
-	const target = registryFor(config).get(targetId);
-	const ids = await listMarkdownCases(intent, cwd);
-	return Promise.all(ids.map(async (caseId) => {
-		const testCase = await loadMarkdownCase(caseId, intent, cwd);
+	const reader = openCaseReader(config, cwd);
+	const ids = await reader.list();
+	return (await Promise.all(ids.map(async (id) => {
+		const read = await reader.read(id);
+		if (read.case === null) throw new Error(read.error ?? `${id}: could not be read`);
+		const testCase = read.case;
+		if (testCase.blocked !== null) warn(`${id}: ${testCase.blocked}`);
+		if (testCase.disabled) return null;
 		const { featureName, specName } = splitCaseId(testCase.ref.id);
 		return {
 			featureName,
 			specName,
 			title: testCase.title,
-			steps: describeMarkdownSteps(testCase),
-			includedBlocks: [],
-			testPath: runsLive(testCase) ? "" : resolveCaseTestPath(target, targetConfig, testCase.ref.id),
-			recordingPath: runsLive(testCase) ? "" : resolveCaseRecordingPath(target, targetConfig, testCase.ref.id),
-			sourcePath: markdownSourcePath(testCase, caseId, cwd)
+			steps: testCase.steps.map(describeStepBody),
+			includedBlocks: testCase.spec ? collectIncludedBlockNames(testCase.spec) : [],
+			...resolveCasePaths(testCase, config, reader),
+			sourcePath: relative(cwd, testCase.document.path)
 		};
-	}));
-}
-/** The case's own file, project-root-relative, or its id when the source somehow isn't markdown. */
-function markdownSourcePath(testCase, id, cwd) {
-	return testCase.source.kind === "markdown" ? relative(cwd, testCase.source.path) : id;
+	}))).filter((s) => s !== null);
 }
 /**
 * `--format paths` needs a real file to hand a test runner, so a target that
-* can't be resolved (bad `target:`/`defaultTarget`) degrades this one spec's
+* can't be resolved (bad `target:`/`defaultTarget`) degrades this one case's
 * path to "" instead of failing the whole inventory — the other formats don't
-* depend on it. A live spec resolves to "" for the same reason: it is driven
-* from the spec every run and has compiled nothing a runner could take.
+* depend on it. A live case resolves to "" for the same reason: it is driven
+* from the document every run and has compiled nothing a runner could take.
 */
-function resolveSpecPaths(spec, config, featureName, specName) {
+function resolveCasePaths(testCase, config, reader) {
 	const none = {
 		testPath: "",
 		recordingPath: ""
 	};
-	if (spec.mode === "live") return none;
+	if (runsLive(testCase)) return none;
 	try {
-		const target = resolveTarget(spec, config);
-		const targetConfig = targetConfigFor(config, target.id);
-		const ref = {
-			featureName,
-			specName
-		};
+		const owner = reader.target;
+		const target = owner ? registryFor(config).get(owner.id) : resolveTarget(testCase.spec, config);
+		const targetConfig = owner ? owner.targetConfig : targetConfigFor(config, target.id);
 		return {
-			testPath: resolveTestPath(target, targetConfig, ref),
-			recordingPath: resolveRecordingPath(target, targetConfig, ref)
+			testPath: resolveCaseTestPath(target, targetConfig, testCase.ref.id),
+			recordingPath: resolveCaseRecordingPath(target, targetConfig, testCase.ref.id)
 		};
 	} catch (e) {
-		warn(`${featureName}/${specName}: could not resolve test path (${e.message})`);
+		warn(`${testCase.ref.id}: could not resolve test path (${e.message})`);
 		return none;
 	}
 }
 /**
-* One line per step, with include steps expanded to the block's own steps —
-* the selection prompt is told to weigh shared login/navigation/layout
-* against each spec, which only works if those steps are actually visible
-* here rather than hidden behind a block name.
+* One line per step, in order. Include steps arrive already expanded to the
+* block's own steps — the selection prompt is told to weigh shared
+* login/navigation/layout against each case, which only works if those steps
+* are actually visible here rather than hidden behind a block name.
 *
-* Falls back to naming the block (the old behavior) when a block can't be
-* resolved, so one broken include degrades this spec's evidence rather than
-* failing selection for the whole inventory. Logged, not silent.
+* A step with no `expected` of its own prints as the instruction alone: a case
+* that states its expectations once for the whole flow has nothing to put
+* after the arrow, and an empty one reads as a step that checks nothing.
 */
-function describeSteps(spec, blocks, specKey) {
-	try {
-		return expandSpec(spec, { blocks }).map(describeStepBody);
-	} catch (e) {
-		warn(`${specKey}: could not expand include steps (${e.message}) — showing block names instead`);
-		return spec.steps.map(describeStep);
-	}
-}
-function describeStep(step) {
-	if (isIncludeStep(step)) return `include block: ${step.include}`;
-	return describeStepBody(step);
-}
 function describeStepBody(step) {
 	if (isJudgeBody(step)) return `judge: ${oneLine$1(step.judgeByLlm)}`;
-	return `${oneLine$1(step.instruction)} → ${oneLine$1(step.expected)}`;
-}
-/**
-* One line per step, in order — no `include:` to expand, since a markdown
-* case's steps are never block references. Unlike a spec step, a markdown
-* step carries no per-step `expected` (the case lists its expectations once,
-* for the whole flow), so only the instruction goes on the line.
-*/
-function describeMarkdownSteps(testCase) {
-	return testCase.steps.map((step) => isJudgeBody(step) ? `judge: ${oneLine$1(step.judgeByLlm)}` : oneLine$1(step.instruction));
+	const expected = oneLine$1(step.expected);
+	const instruction = oneLine$1(step.instruction);
+	return expected.length > 0 ? `${instruction} → ${expected}` : instruction;
 }
 function oneLine$1(text) {
 	return text.trim().replace(/\s+/g, " ");
@@ -21817,7 +21615,7 @@ async function copyEvidenceIntoReport(absPath, evidenceDir, reportDir) {
 	const dest = join(evidenceDir, basename(absPath));
 	try {
 		await cp(absPath, dest);
-		return posix.relative(toPosix(resolve(reportDir)), toPosix(dest));
+		return posix.relative(toPosix$1(resolve(reportDir)), toPosix$1(dest));
 	} catch (err) {
 		warn(`failed to copy live evidence ${absPath}: ${err instanceof Error ? err.message : String(err)}`);
 		return null;
@@ -22294,6 +22092,10 @@ var CoverageInbox = class {
 };
 //#endregion
 //#region src/run/target-dispatch.ts
+/** The title a report row carries for a case, or null when it could not be read. */
+function titleOf(spec) {
+	return spec.testCase?.title ?? null;
+}
 /**
 * Resolve each spec's target and group. A spec with no spec.yaml at all falls
 * through to the agent-browser path, whose runner surfaces the real error
@@ -22318,16 +22120,20 @@ function groupSpecsByTarget(specs, catalog, config, resolve = resolveTargetFor(c
 	const unresolved = [];
 	for (const ref of specs) {
 		const read = catalog.get(specKey(ref));
+		const dispatched = () => ({
+			...ref,
+			caseId: specKey(ref),
+			testCase: read?.case ?? null
+		});
 		if (read?.error) {
 			unresolved.push({
-				...ref,
-				title: null,
+				...dispatched(),
 				reason: read.error,
 				targetId: null
 			});
 			continue;
 		}
-		const spec = read?.spec ?? null;
+		const spec = (read?.case ?? null)?.spec ?? null;
 		if (spec === null) {
 			agentBrowser.push(ref);
 			continue;
@@ -22337,8 +22143,7 @@ function groupSpecsByTarget(specs, catalog, config, resolve = resolveTargetFor(c
 			plugin = resolve(spec, config);
 		} catch (err) {
 			unresolved.push({
-				...ref,
-				title: spec.title ?? null,
+				...dispatched(),
 				reason: err instanceof Error ? err.message : String(err),
 				targetId: spec.target ?? config.defaultTarget ?? null
 			});
@@ -22348,10 +22153,7 @@ function groupSpecsByTarget(specs, catalog, config, resolve = resolveTargetFor(c
 			agentBrowser.push(ref);
 			continue;
 		}
-		const entry = {
-			...ref,
-			title: spec.title ?? null
-		};
+		const entry = dispatched();
 		const targetConfig = targetConfigFor(config, plugin.id);
 		const routed = externalRunnability(plugin, plugin.id, targetConfig);
 		if ("reason" in routed) skipped.push({
@@ -22403,16 +22205,16 @@ function externalGroupFor(plugin, targetConfig) {
 	};
 }
 /**
-* The external group for a project whose cases are its own documents.
+* The external group for a project whose cases come from its own source.
 *
 * Such a case is not dispatched by reading a `spec.yaml` `target:` — the
-* target that declares the intent source already owns every case under it — so
+* target that declares the case source already owns every case under it — so
 * the routing is one lookup rather than a walk. What it shares with
 * {@link groupSpecsByTarget} is the two conditions that decide whether ccqa
 * can execute a generated test at all: the plugin has a runner, and the
 * project configured the command to run it with.
 */
-function groupIntentCases(cases, targetId, config) {
+function groupOwnCases(cases, targetId, config) {
 	if (cases.length === 0) return {
 		external: [],
 		skipped: []
@@ -22453,7 +22255,7 @@ async function runExternalSpecs(dispatch, ctx) {
 			...emptySpecRow({
 				feature: u.featureName,
 				spec: u.specName,
-				title: u.title,
+				title: titleOf(u),
 				status: "failed"
 			}),
 			...u.targetId ? { target: u.targetId } : {},
@@ -22467,7 +22269,7 @@ async function runExternalSpecs(dispatch, ctx) {
 			...emptySpecRow({
 				feature: s.featureName,
 				spec: s.specName,
-				title: s.title,
+				title: titleOf(s),
 				status: "skipped"
 			}),
 			...s.targetId ? { target: s.targetId } : {},
@@ -22508,7 +22310,7 @@ async function runExternalSpecs(dispatch, ctx) {
 				...emptySpecRow({
 					feature: s.featureName,
 					spec: s.specName,
-					title: s.title,
+					title: titleOf(s),
 					status: "failed"
 				}),
 				target: group.targetId,
@@ -23086,18 +22888,16 @@ function asHubReadError$1(err) {
 	throw new RunUsageError(`could not read from the hub: ${errMessage(err)}`);
 }
 /**
-* The cases a project's own documents hold, as this invocation named them:
-* every one under the intent root, or exactly the ones the arguments name.
-* An argument is read both ways a person writes it — the path they see in
-* their editor, or the id everything else cites (see `caseIdFor`).
+* The cases a project's own source holds, as this invocation named them:
+* every one the source holds, or exactly the ones the arguments name. An
+* argument is read both ways a person writes it — the path they see in their
+* editor, or the id everything else cites.
 */
-async function readIntentCases(targets, intent, cwd) {
-	const ids = await intentCaseIds(targets, intent, cwd);
-	try {
-		return await Promise.all(ids.map((id) => loadMarkdownCase(id, intent, cwd)));
-	} catch (err) {
-		throw new RunUsageError(errMessage(err));
-	}
+async function readOwnCases(targets, reader) {
+	const named = targets.length > 0;
+	const refs = named ? [...new Set(targets)] : await reader.list();
+	const cases = await Promise.all(refs.map((ref) => reader.load(ref)));
+	return named ? cases : cases.filter((c) => !c.disabled);
 }
 /** De-dupe by `featureName/specName`, keeping first-seen order. */
 function dedupeSpecs(specs) {
@@ -23278,6 +23078,8 @@ async function executeRun(targets, opts) {
 	const triageUserPromptHash = triageUserPrompt ? hashTriageUserPrompt(triageUserPrompt) : null;
 	const reportDir = resolveReportDir(opts.reportDir, cwd);
 	const parsedBlocks = await loadAllBlocks(cwd);
+	const projectConfig = await loadProjectConfig(cwd);
+	const reader = openCaseReader(projectConfig, cwd);
 	const analysisDeps = {
 		diffProvider,
 		auth: diffProvider ? driftAuthAvailable() : {
@@ -23286,6 +23088,7 @@ async function executeRun(targets, opts) {
 		},
 		cwd,
 		reportDir,
+		reader,
 		blocks: projectAvailableBlocks(parsedBlocks),
 		parsedBlocks,
 		...opts.model ? { model: opts.model } : {},
@@ -23293,18 +23096,15 @@ async function executeRun(targets, opts) {
 		customPrompt,
 		triageUserPrompt
 	};
-	const projectConfig = await loadProjectConfig(cwd);
 	await loadEnvFiles(projectConfig.envFiles, cwd);
-	const intentTarget = intentTargetFor(projectConfig);
-	const intentRun = intentTarget === null ? null : {
-		id: intentTarget.id,
-		root: intentTarget.intent.root,
-		cases: await readIntentCases(targets, intentTarget.intent, cwd)
+	const ownRun = reader.target === null ? null : {
+		id: reader.target.id,
+		module: reader.target.module,
+		cases: await readOwnCases(targets, reader)
 	};
-	if (intentRun !== null && opts.onlyHubRerunNeeded) throw new RunUsageError("--only-hub-rerun-needed reads the hub's per-spec rerun verdicts, which a project whose cases are its own documents has none of — name the cases to run instead");
 	const enumerateAll = () => listActiveSpecs(cwd);
-	const resolved = intentRun ? [] : await Promise.all((targets.length ? targets : [void 0]).map((t) => resolveSpecTargets(t, enumerateAll, cwd)));
-	let specs = intentRun ? intentRun.cases.map((c) => splitCaseId(c.ref.id)) : dedupeSpecs(resolved.flat());
+	const resolved = ownRun ? [] : await Promise.all((targets.length ? targets : [void 0]).map((t) => resolveSpecTargets(t, enumerateAll, cwd)));
+	let specs = ownRun ? ownRun.cases.map((c) => splitCaseId(c.ref.id)) : dedupeSpecs(resolved.flat());
 	if (filtering) {
 		const before = specs.length;
 		let inProgress = 0;
@@ -23336,16 +23136,16 @@ async function executeRun(targets, opts) {
 		}
 	}
 	const selectedKeys = new Set(specs.map(specKey));
-	const selectedCases = intentRun?.cases.filter((c) => selectedKeys.has(specKey(splitCaseId(c.ref.id)))) ?? [];
+	const selectedCases = ownRun?.cases.filter((c) => selectedKeys.has(specKey(splitCaseId(c.ref.id)))) ?? [];
 	const liveCaseCount = selectedCases.filter(runsLive).length;
 	const generatedCases = opts.coverage === true || targets.length > 0 ? selectedCases.filter((c) => !runsLive(c)) : [];
-	if (specs.length === 0 || intentRun !== null && liveCaseCount + generatedCases.length === 0) {
-		if (intentRun === null) {
+	if (specs.length === 0 || ownRun !== null && liveCaseCount + generatedCases.length === 0) {
+		if (ownRun === null) {
 			warn("no specs to run");
-			if (Object.values(projectConfig.targets).some((t) => t.intent)) hint(`this project has a target whose cases come from its own files, but its defaultTarget (${projectConfig.defaultTarget}) is not that target, so this run enumerated .ccqa/features/ instead`);
-		} else if (intentRun.cases.length === 0) warn(`no test cases under ${intentRun.root}`);
+			if (Object.values(projectConfig.targets).some((t) => t.cases)) hint(`this project has a target whose cases come from its own files, but its defaultTarget (${projectConfig.defaultTarget}) is not that target, so this run enumerated .ccqa/features/ instead`);
+		} else if (ownRun.cases.length === 0) warn(`${ownRun.module} lists no test cases`);
 		else {
-			warn(`nothing to run: ${intentRun.cases.length} test case(s) under ${intentRun.root}, none of them live`);
+			warn(`nothing to run: ${ownRun.module} lists ${ownRun.cases.length} test case(s), none of them live`);
 			hint("ccqa runs a case itself only when its mode says `live`; every other case's test is executed by the project's own test command, which `ccqa select-specs --format paths` feeds");
 			hint("pass --coverage, or name the cases, to have ccqa run their generated tests through the target's runCommand — which is how a measurement observes what they reach");
 		}
@@ -23355,7 +23155,7 @@ async function executeRun(targets, opts) {
 			reportDir: null
 		};
 	}
-	const catalog = await readSpecs(intentRun ? [] : specs, cwd);
+	const catalog = await readSpecs(ownRun ? [] : specs, reader);
 	const actors = opts.coverage === true && forExecution ? await resolveActors(projectConfig.coverage?.actors ?? {}, cwd) : NO_ACTORS;
 	const resources = mergeGroups(await resolveSerialGroups(projectConfig.serialGroups, cwd), actorGroups(actors));
 	const declared = [...new Set(specs.flatMap(resources))];
@@ -23385,31 +23185,33 @@ async function executeRun(targets, opts) {
 	}
 	let dispatch;
 	try {
-		dispatch = groupSpecsByTarget(intentRun ? [] : specs, catalog, projectConfig);
-		if (intentRun !== null && generatedCases.length > 0) {
-			const routed = groupIntentCases(generatedCases.map((c) => ({
+		dispatch = groupSpecsByTarget(ownRun ? [] : specs, catalog, projectConfig);
+		if (ownRun !== null && generatedCases.length > 0) {
+			const routed = groupOwnCases(generatedCases.map((c) => ({
 				...splitCaseId(c.ref.id),
-				title: c.title
-			})), intentRun.id, projectConfig);
+				caseId: c.ref.id,
+				testCase: c
+			})), ownRun.id, projectConfig);
 			dispatch.external.push(...routed.external);
 			dispatch.skipped.push(...routed.skipped);
 		}
 		for (const { spec, groups } of waitingOnGroup) dispatch.skipped.push({
 			...spec,
-			title: catalog.get(specKey(spec))?.spec?.title ?? null,
+			caseId: specKey(spec),
+			testCase: catalog.get(specKey(spec))?.case ?? null,
 			reason: `waiting on ${groups.join(", ")}, held by another job`,
 			targetId: null
 		});
 	} catch (err) {
 		throw new RunUsageError(errMessage(err));
 	}
-	const withMode = intentRun ? selectedCases.map((c) => ({
+	const withMode = ownRun ? selectedCases.map((c) => ({
 		...splitCaseId(c.ref.id),
 		mode: c.mode
 	})) : resolveSpecsModes(dispatch.agentBrowser, catalog);
-	const detSpecs = intentRun ? [] : withMode.filter((s) => s.mode === "deterministic");
+	const detSpecs = ownRun ? [] : withMode.filter((s) => s.mode === "deterministic");
 	const liveSpecs = withMode.filter((s) => s.mode === "live");
-	meta("modes", intentRun ? `${selectedCases.length} case(s) / ${liveSpecs.length} live / ${generatedCases.length} generated, run here / ${selectedCases.length - liveSpecs.length - generatedCases.length} for the project's own test command` : `${detSpecs.length} deterministic / ${liveSpecs.length} live`);
+	meta("modes", ownRun ? `${selectedCases.length} case(s) / ${liveSpecs.length} live / ${generatedCases.length} generated, run here / ${selectedCases.length - liveSpecs.length - generatedCases.length} for the project's own test command` : `${detSpecs.length} deterministic / ${liveSpecs.length} live`);
 	if (dispatch.external.length > 0) meta("external", dispatch.external.map((g) => `${g.targetId} ${g.specs.length}`).join(" / "));
 	const storedMaps = hubCtx !== null && deployedSha !== null ? createStoredSourceMaps(hubCtx, deployedSha) : void 0;
 	const coverage = opts.coverage && forExecution ? await startCoverage(cwd, projectConfig.coverage, actors, dispatch, opts.teardown, coverageInbox, storedMaps?.read, hubCtx !== null) : void 0;
@@ -23424,17 +23226,18 @@ async function executeRun(targets, opts) {
 	blank();
 	if (opts.dryRun) {
 		const runningHere = new Set(generatedCases.map((c) => specKey(splitCaseId(c.ref.id))));
-		const notOurs = (intentRun ? withMode.filter((s) => s.mode !== "live" && !runningHere.has(specKey(s))) : []).map((s) => ({
+		const notOurs = (ownRun ? withMode.filter((s) => s.mode !== "live" && !runningHere.has(specKey(s))) : []).map((s) => ({
 			...s,
-			title: null,
+			caseId: specKey(s),
+			testCase: null,
 			reason: "run by the project's own test command",
-			targetId: intentRun?.id ?? null
+			targetId: ownRun?.id ?? null
 		}));
 		const routed = {
 			...dispatch,
 			skipped: [...dispatch.skipped, ...notOurs]
 		};
-		const ours = intentRun ? liveSpecs : withMode;
+		const ours = ownRun ? liveSpecs : withMode;
 		for (const line of formatDryRunLines(ours, routed, resources)) emitRaw(line + "\n");
 		blank();
 		info("dry run: nothing was executed and no report was written");
@@ -23531,10 +23334,10 @@ async function executeRun(targets, opts) {
 		report: incrementalReport,
 		conventions: targetConfigFor(projectConfig, AGENT_BROWSER_TARGET).conventions.operate
 	};
-	const liveCases = intentRun ? selectedCases.filter(runsLive).map((c) => liveCaseFrom(c, liveCaseOpts)) : liveSpecs.map((ref) => {
-		const yaml = catalog.get(specKey(ref))?.yaml;
-		if (yaml == null) throw new Error(`${specKey(ref)}: spec.yaml is no longer readable`);
-		return liveCaseFrom(caseFromSpec(ref.featureName, ref.specName, yaml, parsedBlocks, cwd), liveCaseOpts);
+	const liveCases = ownRun ? selectedCases.filter(runsLive).map((c) => liveCaseFrom(c, liveCaseOpts)) : liveSpecs.map((ref) => {
+		const testCase = catalog.get(specKey(ref))?.case;
+		if (testCase == null) throw new Error(`${specKey(ref)}: spec.yaml is no longer readable`);
+		return liveCaseFrom(testCase, liveCaseOpts);
 	});
 	const live = await runLiveSpecs(liveCases, liveOpts);
 	let streamedEdges = {};
@@ -23556,8 +23359,8 @@ async function executeRun(targets, opts) {
 			featureName: r.feature,
 			specName: r.spec
 		}))], analysisDeps);
-		const detResults = await analyzeDeterministicSummaries(det.summaries, cwd, reportDir, analysisRun);
-		const analyzedExternalRows = await analyzeExternalRows(externalRows, analysisRun);
+		const detResults = await analyzeDeterministicSummaries(det.summaries, catalog, reportDir, analysisRun);
+		const analyzedExternalRows = await analyzeExternalRows(externalRows, analysisRun, new Map(dispatch.external.flatMap((g) => g.specs.map((c) => [specKey(c), c.caseId]))));
 		const results = await rerunExplainedFailures([
 			...detResults,
 			...analyzedExternalRows,
@@ -23960,18 +23763,18 @@ function failedSpec(s) {
 * specs share). Degrades — never throws — when Claude auth or the git diff
 * aren't available. Caller writes report.json.
 */
-async function analyzeDeterministicSummaries(summaries, cwd, reportDir, { pass, deps }) {
+async function analyzeDeterministicSummaries(summaries, catalog, reportDir, { pass, deps }) {
 	const results = [];
 	for (const s of summaries) {
 		const assertions = collectAssertions(s);
-		const specYaml = await tryReadSpecFile(s.featureName, s.specName, cwd);
-		const parsedSpec = tryParseTestSpec(specYaml);
-		const stepDescriptions = buildStepDescriptions(parsedSpec, deps.parsedBlocks);
-		const evidence = await loadEvidenceForSpec(s.evidenceDir, reportDir, stepDescriptions);
+		const testCase = catalog.get(specKey(s))?.case ?? null;
+		const specYaml = testCase?.document.text ?? null;
+		const parsedSpec = testCase?.spec ?? null;
+		const evidence = await loadEvidenceForSpec(s.evidenceDir, reportDir, stepCaptions(testCase));
 		const base = {
 			feature: s.featureName,
 			spec: s.specName,
-			title: parsedSpec?.title ?? null,
+			title: testCase?.title ?? null,
 			target: AGENT_BROWSER_TARGET,
 			startedAt: s.startedAt,
 			finishedAt: s.finishedAt,
@@ -24064,7 +23867,7 @@ function createRerunExecutor(ctx) {
 			}
 			const group = ctx.dispatch.external.find((g) => g.specs.some((s) => specKey(s) === key));
 			if (group === void 0) throw new Error(`${key} has no execution path to re-run`);
-			const [row] = await group.runner.run([ref], {
+			const [row] = await group.runner.run([group.specs.find((c) => specKey(c) === key)], {
 				cwd: ctx.cwd,
 				reportDir: scratch,
 				concurrency: 1,
@@ -24403,7 +24206,7 @@ function installTeardownSignalHandlers(teardown, onSignal) {
 }
 //#endregion
 //#region src/cli/run.ts
-const runCommand = addHubOptions(addProfileOption(addLanguageOption(new Command("run").argument("[targets...]", "Specs to run, space-separated: each '<feature>/<spec>', '<feature>', or omit for all. For a target that reads an intent source, each is a case id or the path of its source file. Duplicates are de-duped.").description("Run specs, on any target. Agent-browser specs replay the recorded test.spec.ts under vitest (default), or, with spec.yaml `mode: live`, have Claude drive agent-browser live per step. External-target specs (playwright, runn) run through the target's configured `runCommand`. Where the project writes its cases as markdown, ccqa runs the ones whose mode says `live`; the rest are executed by the project's own test command (see `ccqa select-specs --format paths`). A structured report (report.json + evidence) is always written; use --report-to-hub to also stream it to a hub.").optionsGroup("Which specs to run:").option("--only-affected-by <ref>", "Only specs `ccqa select-specs` decides the diff against <ref> reaches (e.g. origin/main), by intersecting it with each spec's measured coverage from the hub. In pull_request CI, pass $GITHUB_BASE_REF. Cannot be combined with an explicit spec id.").option("--only-hub-rerun-needed", "Only specs the hub answers `rerunNeeded` for: the audit cleared them, and their last result does not cover what is deployed — including every spec the deploy log cannot place, which is assumed reached rather than skipped. A spec whose audit has not caught up answers `inProgress`, and one the audit rejected or whose last run failed answers `needsRepair`; neither is taken, because running them races the audit or repairs nothing. No git diff involved. Requires a hub connection and --hub-profile.").option("--dry-run", "Print the specs this invocation would run, then exit 0 without executing anything and without writing a report. Works with every selection flag.").optionsGroup("How to run them:").option("--concurrency <n>", "Run up to N specs in parallel within each phase (deterministic / external-target / live), never across phases. Default 1 (sequential). Specs in the same `serialGroups` entry of .ccqa/config.yaml still take turns. Live specs each get an isolated agent-browser session; high values spawn many headed Chrome instances.", parseConcurrency$1, 1).option("-m, --model <name>", "Claude model alias ('sonnet'|'opus'|'haiku') or full ID. Overrides CCQA_MODEL.").option("--live-step-retry <n>", "(live only) Retry each failed step up to N more times before recording failure. This retries a step, not the whole spec — see --on-fail-explain-rerun for that.", (raw) => {
+const runCommand = addHubOptions(addProfileOption(addLanguageOption(new Command("run").argument("[targets...]", "Specs to run, space-separated: each '<feature>/<spec>', '<feature>', or omit for all. For a target with a `cases` module, each is a case id or the path of its source file. Duplicates are de-duped.").description("Run specs, on any target. Agent-browser specs replay the recorded test.spec.ts under vitest (default), or, with spec.yaml `mode: live`, have Claude drive agent-browser live per step. External-target specs (playwright, runn) run through the target's configured `runCommand`. Where the project writes its cases as markdown, ccqa runs the ones whose mode says `live`; the rest are executed by the project's own test command (see `ccqa select-specs --format paths`). A structured report (report.json + evidence) is always written; use --report-to-hub to also stream it to a hub.").optionsGroup("Which specs to run:").option("--only-affected-by <ref>", "Only specs `ccqa select-specs` decides the diff against <ref> reaches (e.g. origin/main), by intersecting it with each spec's measured coverage from the hub. In pull_request CI, pass $GITHUB_BASE_REF. Cannot be combined with an explicit spec id.").option("--only-hub-rerun-needed", "Only specs the hub answers `rerunNeeded` for: the audit cleared them, and their last result does not cover what is deployed — including every spec the deploy log cannot place, which is assumed reached rather than skipped. A spec whose audit has not caught up answers `inProgress`, and one the audit rejected or whose last run failed answers `needsRepair`; neither is taken, because running them races the audit or repairs nothing. No git diff involved. Requires a hub connection and --hub-profile.").option("--dry-run", "Print the specs this invocation would run, then exit 0 without executing anything and without writing a report. Works with every selection flag.").optionsGroup("How to run them:").option("--concurrency <n>", "Run up to N specs in parallel within each phase (deterministic / external-target / live), never across phases. Default 1 (sequential). Specs in the same `serialGroups` entry of .ccqa/config.yaml still take turns. Live specs each get an isolated agent-browser session; high values spawn many headed Chrome instances.", parseConcurrency$1, 1).option("-m, --model <name>", "Claude model alias ('sonnet'|'opus'|'haiku') or full ID. Overrides CCQA_MODEL.").option("--live-step-retry <n>", "(live only) Retry each failed step up to N more times before recording failure. This retries a step, not the whole spec — see --on-fail-explain-rerun for that.", (raw) => {
 	const n = Number(raw);
 	if (!Number.isFinite(n) || n < 0 || Math.floor(n) !== n) throw new Error(`--live-step-retry must be a non-negative integer, got "${raw}"`);
 	return n;
@@ -25661,7 +25464,7 @@ function stepsWithoutAsserts(stepIds, actions) {
 async function runTrace(testCase, model, validationMode = "lenient", language, opts = {}) {
 	header("trace", testCase.ref.id);
 	await preflightAgentBrowserCommand();
-	const specSteps = testCase.source.kind === "spec" ? testCase.source.spec.steps : [];
+	const specSteps = testCase.spec?.steps ?? [];
 	const expanded = [...testCase.steps, ...testCase.cleanup];
 	const steps = expanded.filter(isExpandedActionStep);
 	const sessionName = generateSessionName();
@@ -25675,7 +25478,7 @@ async function runTrace(testCase, model, validationMode = "lenient", language, o
 	meta("case", testCase.title);
 	meta("steps", steps.length);
 	if (testCase.cleanup.length > 0) meta("cleanup steps", testCase.cleanup.length);
-	const includes = testCase.source.kind === "spec" ? collectIncludedBlockNames(testCase.source.spec) : [];
+	const includes = testCase.spec ? collectIncludedBlockNames(testCase.spec) : [];
 	if (includes.length > 0) meta("blocks", includes.join(", "));
 	blank();
 	opts.teardown?.trackSession(sessionName);
@@ -26264,6 +26067,85 @@ function dropList(drops) {
 	return drops.slice(0, 5).map((d) => `  - ${describeStepAction(d.action)} — ${d.reason}`).join("\n");
 }
 //#endregion
+//#region src/cli/resolve-case.ts
+async function resolveCase(argument, config, cwd, opts = {}) {
+	const reader = openCaseReader(config, cwd, opts);
+	const testCase = await reader.load(argument);
+	if (reader.target) {
+		const { id, targetConfig, modulePath } = reader.target;
+		const target = registryFor(config).get(id);
+		const testPath = resolveCaseTestPath(target, targetConfig, testCase.ref.id);
+		const recordingPath = (opts.targetOverride === void 0 ? void 0 : ownCaseRecordingPath(config, cwd, modulePath, testCase.ref.id)) ?? resolveCaseRecordingPath(target, targetConfig, testCase.ref.id);
+		const ref = caseRefFor(testCase.ref.id, cwd, recordingPath);
+		return {
+			testCase: {
+				...testCase,
+				ref
+			},
+			target,
+			targetConfig,
+			testPath
+		};
+	}
+	const spec = testCase.spec;
+	const specRef = splitSpecRef(testCase.ref.id);
+	const target = opts.targetOverride !== void 0 ? resolveTargetOverride(spec, opts.targetOverride, config) : resolveTarget(spec, config);
+	const targetConfig = targetConfigFor(config, target.id);
+	const testPath = resolveTestPath(target, targetConfig, specRef);
+	const ref = caseRefFor(specRef, cwd, opts.targetOverride === void 0 ? resolveRecordingPath(target, targetConfig, specRef) : ownRecordingPath(spec, config, specRef));
+	return {
+		testCase: {
+			...testCase,
+			ref
+		},
+		target,
+		targetConfig,
+		testPath
+	};
+}
+/** A spec case's id is its two coordinates joined, and only ever those two. */
+function splitSpecRef(id) {
+	const [featureName, specName] = id.split("/");
+	return {
+		featureName,
+		specName
+	};
+}
+/**
+* Where the spec's own target keeps this case's recording, ignoring any
+* `--target`. Undefined when that target no longer resolves: overriding the
+* target is how a spec with an unusable one is generated at all, so it must
+* not be what stops the command.
+*
+* Only the resolution is guarded. A target that resolved and then could not
+* expand its own `testPath` is a broken config, and swallowing that would put
+* the recording somewhere else without a word.
+*/
+function ownRecordingPath(spec, config, ref) {
+	let target;
+	try {
+		target = resolveTarget(spec, config);
+	} catch {
+		return;
+	}
+	return resolveRecordingPath(target, targetConfigFor(config, target.id), ref);
+}
+/**
+* The case-source branch's half of the same rule: where the project's own
+* default target keeps this case's recording.
+*
+* Undefined when that target reads its cases through a different module than
+* the one this invocation resolved through — another module is describing a
+* different case that happens to share an id, and its route is not this
+* case's.
+*/
+function ownCaseRecordingPath(config, cwd, readingModule, caseId) {
+	const own = caseTargetFor(config, cwd);
+	if (own === null || own.modulePath !== readingModule) return void 0;
+	const plugin = registryFor(config).get(own.id);
+	return plugin ? resolveCaseRecordingPath(plugin, own.targetConfig, caseId) : void 0;
+}
+//#endregion
 //#region src/cli/build-generate-run-summary.ts
 /**
 * Compact, prompt-friendly summary of one `ccqa generate` pass for the
@@ -26337,7 +26219,7 @@ async function runGenerate(resolved, opts) {
 async function runGenerateLocked(resolved, opts, cwd) {
 	const { testCase, target, targetConfig, testPath } = resolved;
 	const { sessionState } = await loadProjectConfig(cwd);
-	const spec = testCase.source.kind === "spec" ? testCase.source.spec : null;
+	const spec = testCase.spec;
 	if (spec?.mode === "live") {
 		error(`this spec is 'mode: live' — a live spec runs without generated code. Run 'ccqa run ${testCase.ref.id}' instead`);
 		process.exit(2);
@@ -26394,7 +26276,7 @@ async function runGenerateLocked(resolved, opts, cwd) {
 			title: testCase.title,
 			steps: []
 		},
-		specYaml: testCase.source.kind === "spec" ? testCase.source.yaml : "",
+		specYaml: spec ? testCase.document.text : "",
 		featureName,
 		specName,
 		ref: testCase.ref,
@@ -26425,7 +26307,6 @@ async function runGenerateLocked(resolved, opts, cwd) {
 		const written = await stampGeneratedTest(testCase.ref, testPathAbs);
 		if (written !== null && movedRecording !== void 0) info(`recording moved beside its test: ${written}`);
 	}
-	if (result.passed) await writeBackOutputPath(testCase, targetConfig, testPath);
 	if (opts.updateAgentPrompt) await runGenerateAgentPromptUpdate(target, testCase.ref.id, result, opts, cwd);
 	if (!result.passed) warn("auto-fix exhausted; test still failing");
 	else hint(`run 'ccqa run ${testCase.ref.id}' to execute the test`);
@@ -26454,28 +26335,6 @@ async function runGenerateAgentPromptUpdate(target, caseId, result, opts, cwd) {
 	});
 }
 /**
-* Write the generated test's path into the case's own `outputPath` section.
-*
-* Only when the project named that section and the case actually has it: a
-* case file belongs to the project, and ccqa rewrites the one heading it was
-* given permission to rewrite, leaving every other byte alone.
-*/
-async function writeBackOutputPath(testCase, targetConfig, testPath) {
-	const heading = targetConfig.intent?.fields.outputPath;
-	if (!heading || testCase.source.kind !== "markdown") return;
-	const { path } = testCase.source;
-	const before = await readFile(path, "utf8").catch(() => null);
-	if (before === null) return;
-	const after = replaceSectionBody(before, heading, testPath);
-	if (after === null) {
-		warn(`the case has no "${heading}" section, so the generated test's path was not written back`);
-		return;
-	}
-	if (after === before) return;
-	await writeFile(path, after, "utf8");
-	meta("wrote back", `${heading} in ${relative(process.cwd(), path) || path}`);
-}
-/**
 * The reason regeneration is refused because the test on disk is not the one
 * the last generation wrote — or null when it may proceed. A matching stamp
 * means ccqa produced this file, so regenerating it costs nobody anything and
@@ -26522,13 +26381,11 @@ function staleRecordingWarning(caseId, editedAt, recordedAt) {
 	return `the case was edited after it was recorded (case ${editedAt.toISOString()}, recording ${recordedAt}). Generation compiles the recording, so anything added to the case since is not in it — run 'ccqa record ${caseId}' if the steps or the expected results changed.`;
 }
 async function warnIfCaseOutranRecording(testCase, recordedAt) {
-	const path = testCase.source.path;
-	if (path === void 0) return;
-	const editedAt = await stat(path).then((st) => st.mtime, () => null);
+	const editedAt = await stat(testCase.document.path).then((st) => st.mtime, () => null);
 	const warning = staleRecordingWarning(testCase.ref.id, editedAt, recordedAt);
 	if (warning !== null) warn(warning);
 }
-const generateCommand = addHubOptions(addProfileOption(addLanguageOption(new Command("generate").argument("<case>", "The case to generate from: a spec id ('<feature>/<spec>'), or — for a target that reads an intent source — a case id or the path of its source file").description("Generate test code from a case via its target. Recording-backed targets compile the case's existing recording (run `ccqa record` first); spec-input targets generate directly from the spec.").optionsGroup("How to generate:").option("-m, --model <name>", "Claude model alias ('sonnet'|'opus'|'haiku') or full ID. Overrides CCQA_MODEL.").option("--target <id>", "Generate through this target instead of the spec's own — e.g. emit a Playwright spec from an agent-browser recording. The spec's `target:` stays the default for `ccqa run`.").option("--auto-fix <mode>", "Auto-fix behaviour during script generation: 'interactive' (default, prompt y/N; declines on non-TTY), 'auto' (apply without prompt, for CI), 'skip' (agent-browser: apply only high-confidence fixes; external targets like playwright/runn: no fix pass at all).", parseAutoFixFlag, "interactive").option("--auto-fix-max-retries <n>", "Maximum number of auto-fix retries", "3").option("--no-replay", "Skip replaying the saved recording before regenerating from it. The replay drives your application for real — it performs the recorded actions, and whatever they create the recorded cleanup then tries to remove — and it needs a browser and the spec's variables. Skip it where that is unwelcome or unavailable, and accept that a route the application has outgrown regenerates into a test that cannot pass.").option("--no-session-pin", "Don't pin AGENT_BROWSER_SESSION / capture page snapshots after a failure (debug toggle)").optionsGroup("What to do with the result:").option("--overwrite", "Replace an existing generated test without the y/N prompt (declines on a non-TTY)").optionsGroup("Learning:").option("--learn-hub-codegen-prompt", "After generation, ask Claude to refresh the target's \"<target>.agent\" learning prompt on the hub from a summary of the run. LLM-generating targets (playwright, runn) only; requires a hub connection.").optionsGroup("Environment and connection:").option("--cwd <path>", "Working directory containing the .ccqa/ tree (monorepo support). Defaults to the current directory.").option("--project <name>", "Project name for the hub. Defaults to the current directory's name.")))).action(withUsageErrors(async (specPath, opts) => {
+const generateCommand = addHubOptions(addProfileOption(addLanguageOption(new Command("generate").argument("<case>", "The case to generate from: a spec id ('<feature>/<spec>'), or — for a target with a `cases` module — a case id or the path of its source file").description("Generate test code from a case via its target. Recording-backed targets compile the case's existing recording (run `ccqa record` first); spec-input targets generate directly from the spec.").optionsGroup("How to generate:").option("-m, --model <name>", "Claude model alias ('sonnet'|'opus'|'haiku') or full ID. Overrides CCQA_MODEL.").option("--target <id>", "Generate through this target instead of the spec's own — e.g. emit a Playwright spec from an agent-browser recording. The spec's `target:` stays the default for `ccqa run`.").option("--auto-fix <mode>", "Auto-fix behaviour during script generation: 'interactive' (default, prompt y/N; declines on non-TTY), 'auto' (apply without prompt, for CI), 'skip' (agent-browser: apply only high-confidence fixes; external targets like playwright/runn: no fix pass at all).", parseAutoFixFlag, "interactive").option("--auto-fix-max-retries <n>", "Maximum number of auto-fix retries", "3").option("--no-replay", "Skip replaying the saved recording before regenerating from it. The replay drives your application for real — it performs the recorded actions, and whatever they create the recorded cleanup then tries to remove — and it needs a browser and the spec's variables. Skip it where that is unwelcome or unavailable, and accept that a route the application has outgrown regenerates into a test that cannot pass.").option("--no-session-pin", "Don't pin AGENT_BROWSER_SESSION / capture page snapshots after a failure (debug toggle)").optionsGroup("What to do with the result:").option("--overwrite", "Replace an existing generated test without the y/N prompt (declines on a non-TTY)").optionsGroup("Learning:").option("--learn-hub-codegen-prompt", "After generation, ask Claude to refresh the target's \"<target>.agent\" learning prompt on the hub from a summary of the run. LLM-generating targets (playwright, runn) only; requires a hub connection.").optionsGroup("Environment and connection:").option("--cwd <path>", "Working directory containing the .ccqa/ tree (monorepo support). Defaults to the current directory.").option("--project <name>", "Project name for the hub. Defaults to the current directory's name.")))).action(withUsageErrors(async (specPath, opts) => {
 	await withCostReporting("generate", () => runGenerateCli(specPath, opts));
 }));
 async function runGenerateCli(caseArgument, opts) {
@@ -26598,7 +26455,7 @@ async function runGenerateCli(caseArgument, opts) {
 //#endregion
 //#region src/cli/record.ts
 const VALIDATION_MODES = ["lenient", "strict"];
-const recordCommand = addHubOptions(addProfileOption(addLanguageOption(new Command("record").argument("<case>", "The case to record: a spec id ('<feature>/<spec>'), or — for a target that reads an intent source — a case id or the path of its source file").description("Record a test from a case: run agent-browser to collect actions (trace), then compile them into runnable code via the case's target (generate) — a vitest test.spec.ts for agent-browser, a @playwright/test spec for playwright and for a target the project defines. Recording-backed targets only; spec-input targets like runn have no trace step (use `ccqa generate`), and agent-browser live specs need no recording.").optionsGroup("How to record:").option("-m, --model <name>", "Claude model alias ('sonnet'|'opus'|'haiku') or full ID. Overrides CCQA_MODEL.").option("--instruction <text>", "Extra guidance for the recording agent — e.g. the drift audit's finding when re-recording a drifted spec.").option("--trace-validation <mode>", "What to do with actions that fail post-trace validation: 'lenient' (default) tags them; 'strict' drops them.", (raw) => {
+const recordCommand = addHubOptions(addProfileOption(addLanguageOption(new Command("record").argument("<case>", "The case to record: a spec id ('<feature>/<spec>'), or — for a target with a `cases` module — a case id or the path of its source file").description("Record a test from a case: run agent-browser to collect actions (trace), then compile them into runnable code via the case's target (generate) — a vitest test.spec.ts for agent-browser, a @playwright/test spec for playwright and for a target the project defines. Recording-backed targets only; spec-input targets like runn have no trace step (use `ccqa generate`), and agent-browser live specs need no recording.").optionsGroup("How to record:").option("-m, --model <name>", "Claude model alias ('sonnet'|'opus'|'haiku') or full ID. Overrides CCQA_MODEL.").option("--instruction <text>", "Extra guidance for the recording agent — e.g. the drift audit's finding when re-recording a drifted spec.").option("--trace-validation <mode>", "What to do with actions that fail post-trace validation: 'lenient' (default) tags them; 'strict' drops them.", (raw) => {
 	if (VALIDATION_MODES.includes(raw)) return raw;
 	throw new Error(`--trace-validation must be one of ${VALIDATION_MODES.join(" | ")}`);
 }, "lenient").option("--auto-fix <mode>", "Auto-fix behaviour during script generation: 'interactive' (default, prompt y/N; declines on non-TTY), 'auto' (apply without prompt, for CI), 'skip' (agent-browser: apply only high-confidence fixes; external targets like playwright/runn: no fix pass at all).", parseAutoFixFlag, "interactive").option("--auto-fix-max-retries <n>", "Maximum number of auto-fix retries", "3").option("--timeout <seconds>", "Abort the recording after this many seconds, wherever it is (trace, generate, auto-fix): reap the browser session, seal the open hub run (--report-to-hub) with a 'timed out' note, and exit 124. Prefer this over wrapping the command in an external `timeout`, whose SIGTERM may never reach this process.", parseTimeoutSeconds).option("--trace-only", "Stop after the trace step; do not generate test code").option("--no-session-pin", "Don't pin AGENT_BROWSER_SESSION / capture page snapshots after a failure (debug toggle)").optionsGroup("What to do with the result:").option("--report-to-hub", "Leave a run (kind: record) on the hub saying this spec was recorded and what the recording spent on Claude, so a budget summed over the hub's runs sees it. It advances no ledger: a recording verifies nothing.").optionsGroup("Learning:").option("--learn-hub-trace-prompt", "After the trace finishes, ask Claude to refresh the \"record.agent\" prompt on the hub from a summary of the run. Requires a hub connection.").optionsGroup("Environment and connection:").option("--cwd <path>", "Working directory containing the .ccqa/ tree (monorepo support). Defaults to the current directory.").option("--project <name>", "Project name for the hub. Defaults to the current directory's name.")))).action(withUsageErrors(async (specPath, opts) => {
@@ -26613,7 +26470,7 @@ async function runRecord(caseArgument, opts) {
 	const resolved = await resolveCase(caseArgument, config, cwdForProfile);
 	const { testCase, target } = resolved;
 	const caseId = testCase.ref.id;
-	const spec = testCase.source.kind === "spec" ? testCase.source.spec : null;
+	const spec = testCase.spec;
 	if (target.input === "spec") {
 		error(`target "${target.id}" does not use a browser recording — run 'ccqa generate ${caseId}' instead`);
 		process.exit(2);
@@ -27594,7 +27451,7 @@ function buildDriftUserPrompt(artifacts, sourceRoots = [], locators) {
 	const { kind, path, body } = artifacts.intent;
 	return `## ${kind === "spec" ? "spec.yaml" : `Test case document — ${path}`}
 
-\`\`\`${kind === "spec" ? "yaml" : "markdown"}
+\`\`\`${kind === "spec" ? "yaml" : extname(path).replace(/^\./, "")}
 ${body}
 \`\`\`
 
@@ -27637,9 +27494,9 @@ What renders a screen is often a template rather than a script — a \`.vue\`, \
 
 `;
 }
-/** What states the case, in the vocabulary of the document the project writes. */
+/** What states the case: ccqa's own format, or one it does not know. */
 function intentSurfaceBlock(kind) {
-	if (kind === "markdown") return `- **the test case document** — always present. Markdown the project's own authors wrote and own: a heading for what to do, a heading for what must then be true, and whatever else their format carries. Read it as prose stating intent — the headings are theirs, not ccqa's.`;
+	if (kind === "project") return `- **the test case document** — always present. Written and owned by the project's own authors, in whatever format they keep their test cases in; ccqa does not parse it and neither should you assume a shape. Read it as a statement of intent: what the case does, and what must then be true. Its structure and vocabulary are theirs, not ccqa's.`;
 	return `- **spec.yaml** — always present. Pure YAML: \`title\`, then \`steps\`, each either an action (\`instruction\` + \`expected\`) or \`include: <block-name>\` with \`params\`. \`expected\` names something observable — visible text, an aria-label, a URL, an element state.`;
 }
 function generatedSection(artifacts) {
@@ -28076,41 +27933,6 @@ function repairTargetsOutside(evidence, area) {
 	return outside.length > 0 ? outside : null;
 }
 //#endregion
-//#region src/drift/types.ts
-/** How everything downstream spells this case: its intent-source id, or `feature/spec`. */
-function caseIdOf(target) {
-	return target.caseId ?? `${target.featureName}/${target.specName}`;
-}
-/**
-* What the audit says about one locator code could not find in the product.
-*
-* `drifted` says the test asks for something the product no longer renders;
-* `fine` says the miss has another explanation — a selector built at runtime, a
-* component this case never reaches, a file the scan did not read. Either is an
-* answer; silence is not, which is what the required list below is for.
-*/
-const LocatorVerdictSchema = z.object({
-	id: z.string().min(1),
-	verdict: z.enum(["drifted", "fine"]),
-	note: z.string().default("")
-});
-/** The model's reply: a diagnosis, or `null` for "the spec still matches the code". */
-const DriftReplySchema = z.object({
-	drift: DriftDiagnosisSchema.nullable(),
-	locators: z.array(LocatorVerdictSchema).default([])
-});
-/**
-* How a label reads against `--exit-on`. The threshold asks "would a
-* deterministic replay fail today". `TEST_DRIFT` and `SPEC_CHANGE` answer yes
-* and name the repair, so they hold the gate shut. The other three do not: a
-* suspected product bug or a dependency on data the source does not decide is
-* settled by running the case, not by refusing to run it, and `UNKNOWN` says
-* the audit could not tell.
-*/
-function driftSeverity(label) {
-	return label === "TEST_DRIFT" || label === "SPEC_CHANGE" ? "error" : "warn";
-}
-//#endregion
 //#region src/drift/analyze.ts
 const DEFAULT_CONCURRENCY$1 = 3;
 /**
@@ -28217,7 +28039,7 @@ async function checkSpec(target, opts) {
 				correctSurface(drift, {
 					cwd: opts.cwd,
 					sourceRoots: opts.sourceRoots.map((r) => r.abs),
-					...await caseWriteArea(target, opts.cwd, opts.context)
+					...await caseWriteArea(target, opts.context)
 				});
 			}
 			return {
@@ -28225,7 +28047,8 @@ async function checkSpec(target, opts) {
 				ok: true,
 				drift,
 				live: artifacts.live,
-				title: artifacts.title
+				title: artifacts.title,
+				documentPath: artifacts.intent.path
 			};
 		} catch (e) {
 			lastError = `failed to parse drift reply: ${e.message}`;
@@ -28297,7 +28120,7 @@ function renderGithub(results, cwd) {
 	const repoRoot = process.env["GITHUB_WORKSPACE"] ?? process.cwd();
 	const lines = [];
 	for (const r of results) {
-		const file = githubRelPath(cwd, repoRoot, r.target.featureName, r.target.specName);
+		const file = githubRelPath(cwd, repoRoot, r);
 		if (r.error) {
 			lines.push(`::error file=${file}::${escapeGhMessage(r.error)}`);
 			continue;
@@ -28310,8 +28133,15 @@ function renderGithub(results, cwd) {
 	}
 	return lines.length === 0 ? "" : `${lines.join("\n")}\n`;
 }
-function githubRelPath(cwd, repoRoot, featureName, specName) {
-	const abs = resolve(cwd, ".ccqa", "features", featureName, "test-cases", specName, "spec.yaml");
+/**
+* The file an annotation points at: the document this case is stated in.
+*
+* Falls back to the case's directory when the audit never got far enough to
+* read one — an annotation on a directory still lands a reviewer in the right
+* place, and one on a `spec.yaml` that a project does not use lands nowhere.
+*/
+function githubRelPath(cwd, repoRoot, result) {
+	const abs = resolve(cwd, result.documentPath ?? join(".ccqa", "features", result.target.featureName, "test-cases", result.target.specName));
 	const rel = relative(repoRoot, abs);
 	return rel.startsWith("..") ? abs : rel;
 }
@@ -28357,7 +28187,7 @@ function determineExitCode(results, threshold) {
 //#endregion
 //#region src/drift/to-report.ts
 /** Tracks the drift prompt's own version — the two must never drift apart. */
-const DRIFT_REPORT_PROMPT_VERSION = "10";
+const DRIFT_REPORT_PROMPT_VERSION = "11";
 /**
 * Spec-level status under the given threshold, mirroring determineExitCode's
 * per-spec logic (exit-code.ts) but scoped to a single SpecResult.
@@ -28437,7 +28267,7 @@ async function writeAuditBriefs(input) {
 async function buildBrief(result, cwd, ctx) {
 	const drift = result.drift;
 	const id = caseIdOf(result.target);
-	const test = result.live ? null : await caseTestPath(result.target, cwd, ctx);
+	const test = result.live ? null : await caseTestPath(result.target, ctx);
 	return {
 		case: id,
 		kind: drift.label,
@@ -28469,7 +28299,7 @@ async function repairRoute(result, test, cwd, ctx) {
 	const stamp = (await getRecording(caseRefFor(result.target.caseId ?? {
 		featureName: result.target.featureName,
 		specName: result.target.specName
-	}, cwd, await caseRecordingPath(result.target, cwd, ctx) ?? void 0)).catch(() => null))?.generated;
+	}, cwd, await caseRecordingPath(result.target, ctx) ?? void 0)).catch(() => null))?.generated;
 	if (!stamp) return {
 		route: "external",
 		reason: "no generation stamp: ccqa did not write this test, or it predates the stamp"
@@ -28738,10 +28568,10 @@ async function runAudit(specPath, opts) {
 	}
 	const artifactsContext = await loadSpecArtifactsContext(cwd);
 	const config = artifactsContext.config;
-	const intent = artifactsContext.intentTarget;
+	const intent = artifactsContext.reader.target;
 	const sourceRoots = await resolveSourceRoots(cwd, config.sourceRoots);
-	let targets = await collectTargets(specPath, cwd, intent);
-	if (targets.length === 0) exitWithNoSpecs(format, "noSpecsFound", `no test cases found under ${intent ? intent.intent.root : ".ccqa/features/"}`);
+	let targets = await collectTargets(specPath, cwd, artifactsContext.reader);
+	if (targets.length === 0) exitWithNoSpecs(format, "noSpecsFound", `no test cases found under ${intent ? intent.module : ".ccqa/features/"}`);
 	if (format === "text") {
 		header("audit", specPath ?? `${targets.length} case${targets.length > 1 ? "s" : ""}`);
 		if (opts.cwd) meta("cwd", cwd);
@@ -28979,39 +28809,24 @@ function exitWithNoSpecs(format, reason, message) {
 * The cases this sweep audits.
 *
 * Which of the two places a project keeps them in is settled by its target,
-* not guessed at: one that declares an `intent` source has its cases read from
-* the project's own directory, one that does not from `.ccqa/features/`. A
-* case named on the command line is resolved the same way, which is exactly
-* how `ccqa generate` reads the same argument.
+* not guessed at, and the reader already answers that — so this asks the same
+* question of both kinds. A case named on the command line is resolved the
+* same way, which is exactly how `ccqa generate` reads the same argument.
 */
-async function collectTargets(specPath, cwd, intent) {
-	if (intent) return (await intentCaseIds(specPath ? [specPath] : [], intent.intent, cwd)).map((id) => ({
+async function collectTargets(specPath, cwd, reader) {
+	const asTarget = (id) => reader.target === null ? splitCaseId(id) : {
 		...splitCaseId(id),
 		caseId: id
-	}));
-	const tree = await listFeatureTree(cwd);
+	};
 	if (specPath) {
-		const { featureName, specName } = parseSpecPath(specPath);
-		if (!(tree.find((f) => f.featureName === featureName)?.specs.find((s) => s.specName === specName))?.hasSpecFile) {
-			error(`spec not found: ${featureName}/${specName} (under ${cwd})`);
+		const read = await reader.read(specPath);
+		if (read.document === null) {
+			error(read.error ?? `test case not found: ${specPath} (under ${cwd})`);
 			process.exit(1);
 		}
-		return [{
-			featureName,
-			specName
-		}];
+		return [asTarget(read.id)];
 	}
-	const active = new Set((await listActiveSpecs(cwd)).map(specKey));
-	const out = [];
-	for (const feature of tree) for (const spec of feature.specs) {
-		if (!spec.hasSpecFile) continue;
-		const target = {
-			featureName: feature.featureName,
-			specName: spec.specName
-		};
-		if (active.has(specKey(target))) out.push(target);
-	}
-	return out;
+	return (await Promise.all((await reader.list()).map((id) => reader.read(id)))).filter((read) => read.case?.disabled !== true).map((read) => asTarget(read.id));
 }
 function parseFormat$1(raw) {
 	const v = raw ?? "text";
@@ -29124,29 +28939,41 @@ For each test case above, write a 1–2 sentence factual \`summary\` of what it
 //#endregion
 //#region src/spec/spec-changed-at.ts
 /**
-* One `git log` over the spec tree, walked newest-first. The first time a spec's
-* directory appears is that spec's last edit.
+* One `git log` over the cases' own files, walked newest-first. The first time
+* a case's file appears is that case's last edit.
+*
+* Asked about the documents rather than a directory, because where a case is
+* filed is the project's business: ccqa's own specs live under `.ccqa`, and a
+* project that writes its own cases keeps them wherever it keeps them.
 *
 * Best-effort: outside a repository (or with no history) this returns an empty
 * map and every caller falls back to what it did before. A missing timestamp
-* must never make a spec look fresher than it is.
+* must never make a case look fresher than it is.
 */
-async function readSpecChangedAt(cwd) {
+async function readCaseChangedAt(cwd, documentPaths) {
 	const out = /* @__PURE__ */ new Map();
+	const byRelPath = new Map(documentPaths.map((abs) => [toPosix(relative(cwd, abs)), abs]).filter(([rel]) => rel !== "" && !rel.startsWith("../")));
+	const paths = [...byRelPath.keys()];
+	for (let i = 0; i < paths.length; i += PATHSPEC_CHUNK) await readChunk(cwd, paths.slice(i, i + PATHSPEC_CHUNK), byRelPath, out);
+	return out;
+}
+const PATHSPEC_CHUNK = 500;
+async function readChunk(cwd, paths, byRelPath, out) {
 	let stdout;
 	try {
 		({stdout} = await execFileP("git", [
 			"log",
 			"--pretty=format:%x00%cI",
 			"--name-only",
+			"--relative",
 			"--",
-			".ccqa/features"
+			...paths
 		], {
 			cwd,
 			maxBuffer: 64 * 1024 * 1024
 		}));
 	} catch {
-		return out;
+		return;
 	}
 	let when = "";
 	for (const line of stdout.split("\n")) {
@@ -29154,19 +28981,12 @@ async function readSpecChangedAt(cwd) {
 			when = line.slice(1).trim();
 			continue;
 		}
-		const key = specKeyOf(line.trim());
-		if (key && when && !out.has(key)) out.set(key, when);
+		const abs = byRelPath.get(line.trim());
+		if (abs && when && !out.has(abs)) out.set(abs, when);
 	}
-	return out;
 }
-/**
-* "feature/spec" for a path under the spec tree, or null for anything else.
-* Every file in a case's directory counts: the generated code moving is as
-* much a change to the test as the spec.yaml moving.
-*/
-function specKeyOf(path) {
-	const m = /^\.ccqa\/features\/([^/]+)\/test-cases\/([^/]+)\//.exec(path);
-	return m ? `${m[1]}/${m[2]}` : null;
+function toPosix(p) {
+	return p.split(/[\\/]/).join("/");
 }
 //#endregion
 //#region src/cli/perspectives.ts
@@ -29185,7 +29005,7 @@ async function runPerspectivesCheck(opts) {
 	const hub = requireHubOrExit(opts);
 	const project = resolveProject(opts);
 	header("perspectives", `check (project: ${project})`);
-	const skeleton = await buildSkeleton(await listFeatureTree());
+	const skeleton = await buildSkeleton(await openLocalCases());
 	const localCount = skeleton.reduce((n, f) => n + f.specs.length, 0);
 	const existingDoc = await hub.getPerspectives(project);
 	if (existingDoc === null) {
@@ -29261,15 +29081,16 @@ async function runPerspectives(opts) {
 	const hub = requireHubOrExit(opts);
 	const project = resolveProject(opts);
 	header("perspectives", `project: ${project}`);
-	const skeleton = await buildSkeleton(await listFeatureTree());
+	const local = await openLocalCases();
+	const skeleton = await buildSkeleton(local);
 	const allSpecs = skeleton.flatMap((f) => f.specs);
 	if (allSpecs.length === 0) {
-		info("no test cases found under .ccqa/features — nothing to inventory.");
+		info(`no test cases found under ${local.where} — nothing to inventory.`);
 		return;
 	}
 	const existingDoc = await hub.getPerspectives(project);
 	const noteMap = extractNotes(existingDoc);
-	const specBodies = await loadSpecBodies(skeleton);
+	const specBodies = loadSpecBodies(skeleton, local);
 	meta("language", opts.language ?? "auto");
 	info(`Summarising ${allSpecs.length} test case(s) across ${skeleton.length} feature(s)...`);
 	const summaries = await requestSummaries(specBodies, opts);
@@ -29313,40 +29134,50 @@ async function cleanupLegacyLocalFiles() {
 	for (const path of removed) meta("removed legacy file", path);
 }
 /**
-* Turn the feature tree into the skeleton perspectives features: title
-* transcribed from each spec, status derived mechanically from on-disk
-* artifacts. `summary` is left empty here; Claude fills it later. Specs whose
-* spec.yaml is missing or unparsable are skipped.
-*/
-async function buildSkeleton(tree) {
-	const config = await loadProjectConfig(process.cwd()).catch(() => null);
-	const changedAt = await readSpecChangedAt(process.cwd());
-	return (await Promise.all(tree.map(async (feature) => {
-		const built = await Promise.all(feature.specs.filter((s) => s.hasSpecFile).map(async (s) => {
-			const specYaml = await tryReadSpecFile(feature.featureName, s.specName);
-			const meta = readSpecMeta(s.specName, specYaml);
-			const plugin = resolveSpecTarget(specYaml, config);
-			const status = await deriveStatus(feature.featureName, s.specName, meta.mode, plugin, config);
-			const lastEdit = changedAt.get(`${feature.featureName}/${s.specName}`);
-			return {
-				specName: s.specName,
-				title: meta.title,
-				summary: "",
-				...meta.steps.length > 0 ? { steps: meta.steps } : {},
-				status,
-				...lastEdit ? { changedAt: lastEdit } : {},
-				...meta.disabled ? { disabled: true } : {}
-			};
-		}));
-		return {
-			featureName: feature.featureName,
-			specs: built
+* Turn the project's cases into the skeleton perspectives features: title
+* transcribed from each case, status derived mechanically from on-disk
+* artifacts, grouped by the feature half of the case's id. `summary` is left
+* empty here; Claude fills it later.
+*/
+async function buildSkeleton(local) {
+	const changedAt = await readCaseChangedAt(process.cwd(), local.cases.map((c) => c.document.path));
+	const byFeature = /* @__PURE__ */ new Map();
+	for (const read of local.cases) {
+		const { featureName, specName } = splitCaseId(read.id);
+		const testCase = read.case;
+		if (testCase === null) warn(`${read.id}: ${read.error ?? "could not be read"}`);
+		const steps = testCase ? transcribeSteps(testCase.spec?.steps ?? testCase.steps) : [];
+		const lastEdit = changedAt.get(read.document.path);
+		const built = {
+			specName,
+			title: testCase?.title ?? specName,
+			summary: "",
+			...steps.length > 0 ? { steps } : {},
+			status: await deriveStatus(read.id, testCase, local),
+			...lastEdit ? { changedAt: lastEdit } : {},
+			...testCase?.disabled ? { disabled: true } : {}
 		};
-	}))).filter((f) => f.specs.length > 0).map((f) => ({
-		featureName: f.featureName,
-		specs: [...f.specs].sort((a, b) => a.specName.localeCompare(b.specName))
+		const specs = byFeature.get(featureName);
+		if (specs) specs.push(built);
+		else byFeature.set(featureName, [built]);
+	}
+	return [...byFeature.entries()].map(([featureName, specs]) => ({
+		featureName,
+		specs: [...specs].sort((a, b) => a.specName.localeCompare(b.specName))
 	})).sort((a, b) => a.featureName.localeCompare(b.featureName));
 }
+async function openLocalCases() {
+	const cwd = process.cwd();
+	const config = await loadProjectConfig(cwd).catch(() => ProjectConfigSchema.parse({}));
+	const reader = openCaseReader(config, cwd);
+	const ids = await reader.list();
+	return {
+		cases: (await Promise.all(ids.map((id) => reader.read(id)))).filter((r) => r.document !== null),
+		config,
+		reader,
+		where: reader.target ? reader.target.module : ".ccqa/features"
+	};
+}
 /**
 * `(featureName, specName)` → human note, extracted from the hub's current
 * perspectives document. Notes are preserved across regeneration; everything
@@ -29404,39 +29235,16 @@ function noteKey(featureName, specName) {
 	return `${featureName}/${specName}`;
 }
 /**
-* Lenient read of an already-loaded spec.yaml. A file that is missing or will
-* not parse falls back to `defaults`, which reports the spec as enabled: a
-* spec nobody could read has not asked to be skipped.
-*/
-function readSpecMeta(specName, specYaml) {
-	const defaults = {
-		title: specName,
-		mode: DEFAULT_SPEC_MODE,
-		steps: [],
-		disabled: false
-	};
-	if (specYaml === null) return defaults;
-	try {
-		const parsed = parse(specYaml);
-		const title = typeof parsed.title === "string" && parsed.title.length > 0 ? parsed.title : specName;
-		const modeResult = SpecModeSchema.safeParse(parsed.mode);
-		return {
-			title,
-			mode: modeResult.success ? modeResult.data : DEFAULT_SPEC_MODE,
-			steps: transcribeSteps(parsed.steps),
-			disabled: tryParseTestSpec(specYaml)?.disabled === true
-		};
-	} catch {
-		return defaults;
-	}
-}
-/**
-* The spec's procedure, copied verbatim for the inventory: an include step
-* keeps only the block name (its params are wiring, not procedure), an
-* action step keeps its instruction/expected text, a judge step its claim.
-* Anything malformed is
-* skipped — the inventory never fails over one bad step, matching how the
-* rest of this sweep treats a broken spec.
+* The case's procedure, copied verbatim for the inventory: an include step
+* keeps only the block name (its params are wiring, not procedure), an action
+* step keeps its instruction/expected text, a judge step its claim.
+*
+* Read off the document rather than off the expanded steps, so a `spec.yaml`
+* case still shows the block it includes rather than that block's contents —
+* the inventory is a stock-take of what each case says, and inlining a shared
+* login into forty cases says the same thing forty times.
+*
+* Anything malformed is skipped: the inventory never fails over one bad step.
 */
 function transcribeSteps(raw) {
 	if (!Array.isArray(raw)) return [];
@@ -29454,41 +29262,37 @@ function transcribeSteps(raw) {
 	return steps;
 }
 /**
-* Resolve a spec's generation target for coverage derivation, from its
-* already-read spec.yaml. Best-effort: an unparseable spec or a target that
-* can't be resolved (unknown id, agent-browser-only field misuse) falls back
-* to agent-browser (null), so the inventory never fails over one bad spec.
+* The target that owns this case's generated files.
+*
+* A case the project states itself belongs to the target that declared the
+* source; a `spec.yaml` case names its own. Best-effort: an unresolvable
+* target falls back to agent-browser, so the inventory never fails over one
+* bad case.
 */
-function resolveSpecTarget(specYaml, config) {
-	if (config === null || specYaml === null) return null;
-	const spec = tryParseTestSpec(specYaml);
-	if (!spec) return null;
+function targetOf(testCase, local) {
+	if (local.reader.target) return registryFor(local.config).get(local.reader.target.id) ?? null;
+	if (testCase?.spec == null) return null;
 	try {
-		return resolveTarget(spec, config);
+		return resolveTarget(testCase.spec, local.config);
 	} catch {
 		return null;
 	}
 }
 /**
-* Coverage facts for one spec, interpreted through its target (see
-* `PerspectiveStatusSchema`). `plugin` null means the default agent-browser
-* target (also the fallback for a spec whose target couldn't be resolved) —
-* every caller must resolve it (via `resolveSpecTarget`) and pass it, so the
-* write path and the `--check` comparison agree on the target dimension.
+* Coverage facts for one case, interpreted through its target (see
+* `PerspectiveStatusSchema`).
 */
-async function deriveStatus(featureName, specName, mode, plugin, config) {
+async function deriveStatus(id, testCase, local) {
 	const cwd = process.cwd();
-	const ref = {
-		featureName,
-		specName
-	};
+	const plugin = targetOf(testCase, local);
 	const target = plugin ?? agentBrowserTarget;
-	const targetConfig = targetConfigFor(config, target.id);
-	const generated = await exists(resolveTestPathAbs(target, targetConfig, ref, cwd));
-	const hasRecording = await findRecordingPath(caseRefFor(ref, cwd, resolveRecordingPath(target, targetConfig, ref))) !== null;
+	const targetConfig = local.reader.target?.targetConfig ?? targetConfigFor(local.config, target.id);
+	const generated = await exists(resolve(cwd, resolveCaseTestPath(target, targetConfig, id)));
+	const hasRecording = await findRecordingPath(caseRefFor(id, cwd, resolveCaseRecordingPath(target, targetConfig, id))) !== null;
+	const traced = target.input === "recording" ? hasRecording : true;
 	return {
-		mode,
-		traced: target.input === "recording" ? hasRecording : true,
+		mode: testCase?.mode ?? "deterministic",
+		traced,
 		generated,
 		...plugin && plugin.id !== "agent-browser" ? { target: plugin.id } : {}
 	};
@@ -29496,15 +29300,18 @@ async function deriveStatus(featureName, specName, mode, plugin, config) {
 function exists(path) {
 	return stat(path).then(() => true, () => false);
 }
-async function loadSpecBodies(skeleton) {
-	return await Promise.all(skeleton.flatMap((feature) => feature.specs.map(async (spec) => {
-		const specYaml = await tryReadSpecFile(feature.featureName, spec.specName) ?? "";
-		return {
-			featureName: feature.featureName,
-			specName: spec.specName,
-			title: spec.title,
-			specYaml
-		};
+/** `splitCaseId` as the two positional arguments `noteKey` takes. */
+function splitPair(id) {
+	const { featureName, specName } = splitCaseId(id);
+	return [featureName, specName];
+}
+function loadSpecBodies(skeleton, local) {
+	const byKey = new Map(local.cases.map((c) => [noteKey(...splitPair(c.id)), c.document?.text ?? ""]));
+	return skeleton.flatMap((feature) => feature.specs.map((spec) => ({
+		featureName: feature.featureName,
+		specName: spec.specName,
+		title: spec.title,
+		specYaml: byKey.get(noteKey(feature.featureName, spec.specName)) ?? ""
 	})));
 }
 async function requestSummaries(specs, opts) {
@@ -29619,7 +29426,7 @@ async function runSelectSpecs(opts) {
 	}
 	const specs = specsResult.specs;
 	if (specs.length === 0) {
-		error("no test specs found under .ccqa/features/");
+		error("this project states no test cases");
 		process.exit(1);
 	}
 	if (!changedResult.ok) {
@@ -31531,18 +31338,21 @@ z.object({
 //#endregion
 //#region src/hub/api/auth.ts
 /**
-* Constant-time comparison against the hub's bearer token, so response
-* timing can't be used to guess the token character-by-character. Accepts
-* the token either as an `Authorization: Bearer <token>` header or, for
-* read-only GET endpoints only (the artifacts download is a browser `<a>` that can't
-* carry a header), a `?token=` query parameter — see docs/hub-api.md for
-* the security tradeoff that accepts.
+* Reads the token from `Authorization: Bearer <token>`, or — on GET only —
+* from `?token=`. A query token leaks through `Referer`, history and proxy
+* logs, so it is accepted only where a browser `<a>` can't send a header;
+* see docs/hub-api.md.
 */
 function extractToken(req, url) {
 	const header = req.headers.authorization;
 	if (header?.startsWith("Bearer ")) return header.slice(7);
+	if (req.method !== "GET") return null;
 	return url.searchParams.get("token");
 }
+/**
+* Constant-time comparison against the hub's bearer token, so response
+* timing can't be used to guess the token character-by-character.
+*/
 function isValidToken(provided, expected) {
 	if (provided === null) return false;
 	const a = Buffer.from(provided);