ccqa 1.0.0 → 1.1.1

package/dist/bin/ccqa.mjs

@@ -414,55 +414,20 @@ async function saveSpecFile(featureName, specName, content, cwd) {
 	await writeFile(specPath, content.endsWith("\n") ? content : content + "\n", "utf-8");
 	return specPath;
 }
-/** Absolute path to the single repo-wide `.ccqa/perspectives.yaml`. */
-function getPerspectivesPath(cwd) {
-	return join(getCcqaDir(cwd), PERSPECTIVES_FILE);
-}
-/**
-* Read `.ccqa/perspectives.yaml` raw. Returns null when the file does not
-* exist (first-ever generation) so callers can treat it as optional.
-*/
-async function tryReadPerspectives(cwd) {
-	return readFile(getPerspectivesPath(cwd), "utf-8").catch(() => null);
-}
-/**
-* Write `.ccqa/perspectives.yaml`. Mirrors `saveSpecFile`: ensures the
-* directory exists and the content ends in a trailing newline.
-*/
-async function savePerspectives(content, cwd) {
-	await mkdir(getCcqaDir(cwd), { recursive: true });
-	const path = getPerspectivesPath(cwd);
-	await writeFile(path, content.endsWith("\n") ? content : content + "\n", "utf-8");
-	return path;
-}
-/**
-* Human-readable Markdown companion to perspectives.yaml. The `.yaml` is the
-* machine-readable source of truth; the `.md` is a rendered view for review.
-*/
-function getPerspectivesMarkdownPath(cwd) {
-	return join(getCcqaDir(cwd), PERSPECTIVES_MD_FILE);
-}
-async function savePerspectivesMarkdown(content, cwd) {
-	await mkdir(getCcqaDir(cwd), { recursive: true });
-	const path = getPerspectivesMarkdownPath(cwd);
-	await writeFile(path, content.endsWith("\n") ? content : content + "\n", "utf-8");
-	return path;
-}
 /**
-* Per-category detail view: `.ccqa/features/<feature>/perspectives.md`. The
-* root `perspectives.md` is a thin category index that links here; this file
-* carries the full per-case tables for one feature. The feature dir already
-* exists (it holds the test cases), but `mkdir -p` keeps this safe when called
-* in isolation.
+* The perspectives document now lives on the hub only. Earlier versions wrote
+* it into the repo as `.ccqa/perspectives.yaml` + `.ccqa/perspectives.md` +
+* `.ccqa/features/<feature>/perspectives.md`; remove any of those leftovers.
+* Returns the paths that were actually deleted.
 */
-function getFeaturePerspectivesMarkdownPath(featureName, cwd) {
-	return join(getFeatureDir(featureName, cwd), PERSPECTIVES_MD_FILE);
-}
-async function saveFeaturePerspectivesMarkdown(featureName, content, cwd) {
-	await mkdir(getFeatureDir(featureName, cwd), { recursive: true });
-	const path = getFeaturePerspectivesMarkdownPath(featureName, cwd);
-	await writeFile(path, content.endsWith("\n") ? content : content + "\n", "utf-8");
-	return path;
+async function removeLegacyPerspectivesFiles(cwd) {
+	const candidates = [join(getCcqaDir(cwd), PERSPECTIVES_FILE), join(getCcqaDir(cwd), PERSPECTIVES_MD_FILE)];
+	const featuresDir = join(getCcqaDir(cwd), "features");
+	const featureNames = await readdir(featuresDir).catch(() => []);
+	for (const name of featureNames) candidates.push(join(featuresDir, name, PERSPECTIVES_MD_FILE));
+	const removed = [];
+	for (const path of candidates) if (await unlink(path).then(() => true).catch(() => false)) removed.push(path);
+	return removed;
 }
 /**
 * Replace (or insert) the `relatedPaths` key in the spec. Preserves every
@@ -5562,7 +5527,7 @@ async function runLiveSpecs(specs, opts) {
 	if (userPromptBundle !== null) meta("prompt", userPromptBundle.loaded.join(" + "));
 	const userPromptSuffix = userPromptBundle?.text ?? null;
 	const failureAnalysisEnabled = opts.failureAnalysis !== false;
-	const driftBySpec = failureAnalysisEnabled && opts.driftAudit !== false ? await runDriftAudit(specs, opts, cwd) : /* @__PURE__ */ new Map();
+	const driftAuditEnabled = failureAnalysisEnabled && opts.driftAudit !== false;
 	const auth = failureAnalysisEnabled ? driftAuthAvailable() : {
 		ok: false,
 		reason: "disabled"
@@ -5597,12 +5562,12 @@ async function runLiveSpecs(specs, opts) {
 				row: null
 			};
 			const row = await buildLiveReportRow(outcome, {
-				driftBySpec,
 				auth,
 				diff,
 				baseRef,
 				reportDir,
-				failureAnalysisEnabled
+				failureAnalysisEnabled,
+				driftAuditEnabled
 			}, opts, cwd);
 			await opts.report?.upsert(row);
 			return {
@@ -5622,13 +5587,13 @@ async function runLiveSpecs(specs, opts) {
 	};
 }
 /**
-* Build one spec's report row: the live-run base row plus drift findings and
-* (for a failed spec) the failure-analysis fields. Runs inside the pool worker
-* so the row can be upserted incrementally the moment the spec finishes.
+* Build one spec's report row: the live-run base row plus (for a failed spec)
+* the drift audit and failure-analysis fields. Runs inside the pool worker so
+* the row can be upserted incrementally the moment the spec finishes. The
+* drift audit only runs for failed specs — passing specs get no driftIssues,
+* matching the deterministic path.
 */
 async function buildLiveReportRow(r, ctx, opts, cwd) {
-	const key = `${r.featureName}/${r.specName}`;
-	const driftForSpec = ctx.driftBySpec.get(key) ?? null;
 	const base = await liveRunToReportResult({
 		featureName: r.featureName,
 		specName: r.specName,
@@ -5636,6 +5601,7 @@ async function buildLiveReportRow(r, ctx, opts, cwd) {
 		result: r.result,
 		reportDir: ctx.reportDir
 	});
+	const driftForSpec = ctx.driftAuditEnabled && r.result.status === "failed" ? await runDriftAuditOne(r, opts, cwd) : null;
 	const analysis = ctx.failureAnalysisEnabled && r.result.status === "failed" ? await analyzeOneLiveFailure(r, ctx.diff, ctx.baseRef, driftForSpec, ctx.auth, opts, cwd) : void 0;
 	return {
 		...base,
@@ -5659,39 +5625,31 @@ function analysisFieldsFor(a, status, failureAnalysisEnabled) {
 	return {};
 }
 /**
-* Run `analyzeDrift` against every spec and return a
-* `featureName/specName → driftIssues` map. This is a static spec↔code audit,
-* so it takes the spec list directly and runs before execution — each worker
-* then has its spec's drift context in hand for the failure-analysis prompt.
-* Drift findings are advisory — they show in the report (report.json / hub UI)
-* but do not change the live-run exit code.
+* Run `analyzeDrift` for one failed spec, used as evidence for its
+* failure-analysis prompt and shown in its report row. Mirrors the
+* deterministic path (src/run/pipeline.ts), which also scopes the audit to
+* failed specs only. Drift findings are advisory — they never change the
+* live-run exit code.
 */
-async function runDriftAudit(specs, opts, cwd) {
-	const targets = specs.map((s) => ({
-		featureName: s.featureName,
-		specName: s.specName
-	}));
-	const out = /* @__PURE__ */ new Map();
-	if (targets.length === 0) return out;
-	blank();
-	info(`drift audit: ${targets.length} spec${targets.length > 1 ? "s" : ""}`);
-	const results = await analyzeDrift({
-		targets,
+async function runDriftAuditOne(r, opts, cwd) {
+	const key = `${r.featureName}/${r.specName}`;
+	info(`drift audit: ${key}`);
+	const blocks = await loadAvailableBlocks(cwd);
+	const [result] = await analyzeDrift({
+		targets: [{
+			featureName: r.featureName,
+			specName: r.specName
+		}],
 		cwd,
-		blocks: await loadAvailableBlocks(cwd),
+		blocks,
 		...opts.model ? { model: opts.model } : {},
-		...opts.language ? { language: opts.language } : {},
-		onSpecStart: (t) => info(`  checking ${t.featureName}/${t.specName}`)
+		...opts.language ? { language: opts.language } : {}
 	});
-	for (const r of results) {
-		const key = `${r.target.featureName}/${r.target.specName}`;
-		if (r.ok) out.set(key, r.issues.length > 0 ? r.issues : null);
-		else {
-			warn(`drift audit failed for ${key}: ${r.error}`);
-			out.set(key, null);
-		}
+	if (!result || !result.ok) {
+		warn(`drift audit failed for ${key}: ${result?.error ?? "no result"}`);
+		return null;
 	}
-	return out;
+	return result.issues.length > 0 ? result.issues : null;
 }
 /**
 * Resolve `spec.session` names to a single state file to restore, fetching
@@ -11489,543 +11447,247 @@ async function resolveCwdPrefix(cwd) {
 	}
 }
 //#endregion
-//#region src/cli/generate.ts
-const AUTO_FIX_MODES = [
-	"interactive",
-	"auto",
-	"skip"
-];
-function toFixMode(autoFix) {
-	switch (autoFix) {
-		case "auto": return "auto";
-		case "skip": return "non-interactive";
-		case "interactive": return "interactive";
-	}
-}
-/** Shared `--auto-fix` parser for the record / generate commands. */
-function parseAutoFixFlag(raw) {
-	if (AUTO_FIX_MODES.includes(raw)) return raw;
-	throw new Error(`--auto-fix must be one of ${AUTO_FIX_MODES.join(" | ")}`);
-}
+//#region src/prompts/perspectives.ts
 /**
-* The `generate` flow shared by `ccqa generate` and the codegen half of
-* `ccqa record`: resolve the spec's target plugin, load its input (the
-* recording, for input:"recording" targets), and dispatch to the plugin.
-* This layer owns the CLI concerns — overwrite confirmation, logging,
-* exit-code policy — while the plugin owns the generation pipeline.
+* Build the system prompt. By default the descriptive fields follow the
+* spec's own language (Japanese specs → Japanese fields). An explicit
+* `--language` is applied by the CLI via `languageDirective`, appended to
+* this prompt, so the language handling lives in one shared place.
 */
-async function runGenerate(featureName, specName, opts) {
-	header("generate", `${featureName}/${specName}`);
-	const cwd = opts.cwd ?? process.cwd();
-	await ensureCcqaDir(cwd);
-	const releaseLock = await acquireSpecLock(featureName, specName, "generate", cwd);
-	try {
-		await runGenerateLocked(featureName, specName, opts, cwd);
-	} finally {
-		await releaseLock();
-	}
+function buildPerspectivesSystemPrompt() {
+	return `You produce a factual inventory of the E2E test coverage that already exists in a ccqa project.
+
+Think of it as a QA coverage stock-take: for each existing test case, fill in a few short, neutral descriptive fields derived from its steps. Nothing more.
+
+## Hard boundaries (do NOT cross)
+
+- Do NOT assign severity, importance, priority, or risk. Whether a failure hurts the customer is a human + PdM decision; you are not authoring that here.
+- Do NOT do gap analysis. Do NOT list untested areas, missing coverage, or things the code has but the tests lack.
+- Do NOT evaluate whether the feature is good, complete, or correct.
+- Do NOT propose new test cases.
+- Do NOT restate the full step-by-step procedure or the per-step expected results — the spec.yaml is the source of truth for those and the inventory links to it.
+- Do NOT touch status, relatedPaths, feature names, or spec names — the CLI already fixed those.
+
+## Fields to write (per spec)
+
+- \`summary\`: 1–2 sentences, factual and neutral. What the test exercises and what it ultimately asserts, derived from the spec's \`steps\` (\`instruction\` / \`expected\`).
+- \`startScreen\`: the screen/URL the test first lands on after setup (e.g. "Dashboard (/dashboard)"). Derive from the first non-login \`instruction\`. Omit if genuinely unclear.
+- \`testCondition\`: the state/precondition the scenario assumes, phrased as a condition (e.g. "Logged in as an admin", "Unauthenticated user"). Omit if none.
+- \`preconditions\`: array of short setup prerequisites (e.g. which role logs in, required prior state). Derive from \`include: login\` params and the opening steps. Empty/omit if none.
+
+## How to write
+
+- Same language as the spec's title (if titles are Japanese, write these fields in Japanese).
+- Keep each field short. These are index entries, not the test itself.
+- You may use Read/Grep/Glob sparingly to clarify domain vocabulary, but the steps are the primary source. Do not over-explore.
+
+## Output contract (STRICT)
+
+Output exactly ONE fenced \`\`\`json code block, and nothing else outside it. No prose before or after.
+
+Schema:
+
+\`\`\`json
+{
+  "summaries": [
+    {
+      "featureName": "<verbatim from input>",
+      "specName": "<verbatim from input>",
+      "summary": "<1–2 sentence factual description of what this test verifies>",
+      "startScreen": "<opening screen/URL, or omit>",
+      "testCondition": "<assumed state phrased as a condition, or omit>",
+      "preconditions": ["<setup prerequisite>", "..."]
+    }
+  ]
 }
-async function runGenerateLocked(featureName, specName, opts, cwd) {
-	const specYaml = await readSpecFile(featureName, specName, cwd);
-	const spec = parseTestSpec(specYaml);
-	const config = await loadProjectConfig(cwd);
-	const target = opts.targetOverride !== void 0 ? resolveTargetOverride(spec, opts.targetOverride) : resolveTarget(spec, config);
-	meta("target", target.id + (opts.targetOverride !== void 0 ? " (--target override)" : ""));
-	const existingOutput = await target.existingOutput?.({
-		featureName,
-		specName
-	}, cwd) ?? null;
-	if (existingOutput && !opts.force) {
-		if (!await confirmOverwrite(existingOutput)) {
-			info("aborted; pass --force to overwrite without prompting");
-			return;
-		}
-	}
-	let recording;
-	if (target.input === "recording") {
-		const { path: recordingPath, actions } = await getRecording(featureName, specName, cwd);
-		meta("recording", recordingPath);
-		meta("actions", actions.length);
-		recording = actions;
+\`\`\`
+
+Return one entry per spec given in the input. Echo featureName and specName verbatim so the CLI can match them. \`startScreen\`, \`testCondition\`, and \`preconditions\` are optional — omit a field (or use an empty array for preconditions) when the spec does not express it.
+`;
+}
+function buildPerspectivesPrompt(specs, instruction) {
+	return `## Existing test cases to summarise
+
+${specs.map((s) => `### ${s.featureName}/${s.specName}
+title: ${s.title}
+
+\`\`\`yaml
+${s.specYaml.trimEnd()}
+\`\`\`
+`).join("\n")}
+${instruction?.trim() ? `## Extra guidance from the user\n\n${instruction.trim()}\n\n` : ""}## Task
+
+For each test case above, write a 1–2 sentence factual \`summary\` of what it verifies, derived from its steps. Return one entry per spec in the JSON contract. Do not assign severity, do gap analysis, or invent new cases.
+`;
+}
+//#endregion
+//#region src/cli/draft.ts
+const CATEGORY_LABEL = DRAFT_CATEGORY_LABEL;
+const draftCommand = addLanguageOption(new Command("draft").argument("[feature/spec]", "Optional spec path (e.g. tasks/create-and-complete). If omitted, Claude proposes one from your intent.").description("Interactively draft and refine a spec.yaml with Claude Code").option("--instruction <text>", "Non-interactive single-shot instruction (skips the interactive loop)").option("--apply", "Auto-apply each generated patch without [y/N] confirmation", false)).action(async (specPath, opts) => {
+	await ensureCcqaDir();
+	let featureName;
+	let specName;
+	let prefilledIntent = null;
+	if (specPath) ({featureName, specName} = parseSpecPath(specPath));
+	else {
+		const { naming, intent } = await proposeNaming(opts);
+		featureName = naming.featureName;
+		specName = naming.specName;
+		prefilledIntent = intent;
 	}
-	await warnStaleBlockArtifacts();
-	const targetConfig = config.targets[target.id] ?? TargetConfigSchema.parse({});
-	const ctx = {
-		spec,
-		specYaml,
-		featureName,
-		specName,
-		cwd,
-		recording,
-		resources: targetConfig.resources,
-		conventions: targetConfig.conventions,
-		targetConfig,
-		language: opts.language,
-		model: opts.model,
-		hub: opts.hubContext ?? null,
-		fix: {
-			maxRetries: opts.maxRetries,
-			mode: opts.fixMode,
-			useSnapshot: opts.useSnapshot
+	await runDraft(featureName, specName, opts, prefilledIntent);
+});
+async function runDraft(featureName, specName, opts, prefilledIntent) {
+	header("draft", `${featureName}/${specName}`);
+	const ja = useJapanesePrompts(opts.language);
+	const oneShot = opts.instruction !== void 0;
+	let useIntentOnce = prefilledIntent !== null && !oneShot;
+	while (true) {
+		const existing = await tryReadSpecFile(featureName, specName);
+		const isFirstRun = existing === null;
+		let userInput;
+		if (oneShot) userInput = opts.instruction ?? "";
+		else if (useIntentOnce && isFirstRun) {
+			userInput = prefilledIntent ?? "";
+			useIntentOnce = false;
+		} else userInput = await prompt(isFirstRun ? ja ? "何をテストしたいですか? > " : "What do you want to test? > " : ja ? "どのように修正しますか? (空欄で再検証) > " : "How would you like to refine? (empty = re-validate) > ");
+		if (isFirstRun && !userInput.trim()) {
+			error("intent required for the first draft (no spec exists yet)");
+			process.exit(1);
+		}
+		const turnResult = await runOneTurn({
+			featureName,
+			specName,
+			existing,
+			userInput: userInput.trim(),
+			autoApply: opts.apply === true,
+			language: opts.language
+		});
+		if (oneShot) process.exit(turnResult.hasError && !turnResult.applied ? 1 : 0);
+		blank();
+		if (/^y/i.test(await prompt(ja ? "このドラフトは完了ですか? [y/N] " : "Are you done with this draft? [y/N] "))) {
+			info("draft session complete.");
+			hint(`run 'ccqa trace ${featureName}/${specName}' to record actions`);
+			process.exit(0);
 		}
-	};
-	if (!(await target.generate(ctx)).passed) {
-		warn("auto-fix exhausted; test still failing");
-		process.exit(1);
 	}
-	hint(`run 'ccqa run ${featureName}/${specName}' to execute the test`);
 }
-async function confirmOverwrite(path) {
-	if (!process.stdin.isTTY) {
-		warn(`${path} exists and stdin is not a TTY; refusing to overwrite. Pass --force to allow.`);
-		return false;
-	}
-	const rl = createInterface({
-		input: process.stdin,
-		output: process.stdout
+async function runOneTurn(input) {
+	const { featureName, specName, existing, userInput, autoApply, language } = input;
+	const isFirstRun = existing === null;
+	const systemPrompt = buildDraftSystemPrompt(await loadAvailableBlocks()) + languageDirective(language);
+	const userPrompt = buildDraftPrompt({
+		mode: isFirstRun ? "create" : "refine",
+		existing: existing ?? "",
+		userInput
 	});
-	try {
-		process.stdout.write("\n");
-		process.stdout.write(`[warn] ${path} already exists.\n`);
-		process.stdout.write(`[warn] generate will regenerate it and any manual edits will be lost.\n`);
-		const norm = (await new Promise((res) => rl.question("Overwrite? [y/N] ", res))).trim().toLowerCase();
-		return norm === "y" || norm === "yes";
-	} finally {
-		rl.close();
-	}
-}
-const generateCommand = addHubOptions(addProfileOption(addLanguageOption(new Command("generate").argument("<feature/spec>", "Spec id in '<feature>/<spec>' form (resolves to .ccqa/features/<feature>/test-cases/<spec>/)").description("Generate test code from a spec via its target plugin. Recording-backed targets compile the existing ir.json (run `ccqa record` first); spec-input targets generate directly from the spec.").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), 'auto' (apply without prompt, for CI), 'skip' (never prompt, only apply high-confidence fixes).", parseAutoFixFlag, "interactive").option("--max-retries <n>", "Maximum number of auto-fix retries", "3").option("--force", "Overwrite previously generated test code without warning").option("--no-snapshot", "Don't pin AGENT_BROWSER_SESSION / capture page snapshots after a failure (debug toggle)").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(async (specPath, opts) => {
-	const { featureName, specName } = parseSpecPath(specPath);
-	const language = opts.language ?? "auto";
-	const cwd = resolveCwd(opts.cwd);
-	const project = opts.profile !== void 0 ? resolveProject(opts) : void 0;
-	if (opts.profile !== void 0) await applyProfileFromOption({
-		profile: opts.profile,
-		project,
-		cwd,
-		hubUrl: opts.hubUrl,
-		hubToken: opts.hubToken,
-		hubHeader: opts.hubHeader
-	});
-	else await applyProfileFromOption({
-		profile: void 0,
-		project: "",
-		cwd
-	});
-	const hubClient = resolveHubClient({
-		hubUrl: opts.hubUrl,
-		hubToken: opts.hubToken,
-		hubHeader: opts.hubHeader
+	info(isFirstRun ? "Reading codebase and drafting spec..." : "Re-validating spec against codebase...");
+	const toolCounts = {};
+	const startedAt = Date.now();
+	const { result, isError } = await invokeClaudeStreaming({
+		prompt: userPrompt,
+		systemPrompt,
+		allowedTools: [
+			"Read",
+			"Grep",
+			"Glob"
+		],
+		silenceBashLog: true
+	}, (msg) => {
+		if (msg.type !== "assistant") return;
+		for (const block of msg.message.content ?? []) if (block.type === "tool_use") toolCounts[block.name] = (toolCounts[block.name] ?? 0) + 1;
 	});
-	const hubContext = hubClient && project ? {
-		hub: hubClient,
-		project
-	} : null;
+	printToolSummary(toolCounts, Date.now() - startedAt);
+	if (isError) {
+		error("Claude returned an error result");
+		return {
+			hasError: true,
+			applied: false
+		};
+	}
+	const json = extractJsonBlock(result);
+	if (!json) {
+		error("Claude did not return a json block");
+		warn(`raw tail: ${truncate(result, 200)}`);
+		return {
+			hasError: true,
+			applied: false
+		};
+	}
+	let report;
 	try {
-		await runGenerate(featureName, specName, {
-			maxRetries: parseInt(opts.maxRetries ?? "3", 10),
-			fixMode: toFixMode(opts.autoFix ?? "interactive"),
-			force: opts.force ?? false,
-			useSnapshot: opts.snapshot !== false,
-			language,
-			model: opts.model,
-			targetOverride: opts.target,
-			cwd,
-			hubContext
-		});
+		report = DraftReportSchema.parse(JSON.parse(json));
 	} catch (e) {
-		if (e instanceof SpecLockedError) {
-			error(e.message);
-			process.exit(2);
-		}
-		throw e;
+		error(`failed to parse draft report: ${e.message}`);
+		return {
+			hasError: true,
+			applied: false
+		};
 	}
-});
-//#endregion
-//#region src/cli/record.ts
-const VALIDATION_MODES = ["lenient", "strict"];
-const recordCommand = addHubOptions(addProfileOption(addLanguageOption(new Command("record").argument("<feature/spec>", "Spec id in '<feature>/<spec>' form (resolves to .ccqa/features/<feature>/test-cases/<spec>/)").description("Record a deterministic test from a spec: run agent-browser to collect actions (trace), then generate test.spec.ts with auto-fix retries (generate). After recording, `ccqa run <feature/spec>` replays it under vitest (deterministic specs only — live specs do not need recording).").option("-m, --model <name>", "Claude model alias ('sonnet'|'opus'|'haiku') or full ID. Overrides CCQA_MODEL.").option("--validation-mode <mode>", "Post-trace validation behaviour: 'lenient' (default) tags failing actions; 'strict' drops them.", (raw) => {
-	if (VALIDATION_MODES.includes(raw)) return raw;
-	throw new Error(`--validation-mode must be one of ${VALIDATION_MODES.join(" | ")}`);
-}, "lenient").option("--auto-fix <mode>", "Auto-fix behaviour during script generation: 'interactive' (default, prompt y/N), 'auto' (apply without prompt, for CI), 'skip' (never prompt, only apply high-confidence fixes).", parseAutoFixFlag, "interactive").option("--max-retries <n>", "Maximum number of auto-fix retries", "3").option("--force", "Overwrite an existing test.spec.ts without warning").option("--no-snapshot", "Don't pin AGENT_BROWSER_SESSION / capture page snapshots after a failure (debug toggle)").option("--skip-trace", "Skip the trace step and run codegen against an existing ir.json").option("--skip-codegen", "Run only the trace step (do not generate test.spec.ts)").option("--update-agent-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.").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(async (specPath, opts) => {
-	const { featureName, specName } = parseSpecPath(specPath);
-	const language = opts.language ?? "auto";
-	if (opts.skipTrace && opts.skipCodegen) {
-		error("--skip-trace and --skip-codegen cannot be combined; nothing would run");
-		process.exit(2);
+	const hasError = printReviewBlock(report.issues);
+	const original = existing ?? "";
+	if (!report.patch || report.patch === original) {
+		blank();
+		info("no changes proposed.");
+		return {
+			hasError,
+			applied: false
+		};
 	}
-	const cwdForProfile = resolveCwd(opts.cwd);
-	const target = resolveTarget(parseTestSpec(await readSpecFile(featureName, specName, cwdForProfile)), await loadProjectConfig(cwdForProfile));
-	if (target.input === "spec") {
-		error(`target "${target.id}" does not use a browser recording — run 'ccqa generate ${featureName}/${specName}' instead`);
-		process.exit(2);
+	blank();
+	info("--- proposed changes ---");
+	printUnifiedDiff(original, report.patch);
+	blank();
+	if (!(autoApply ? true : /^y/i.test(await prompt(useJapanesePrompts(language) ? "このパッチを適用しますか? [y/N] " : "Apply this patch? [y/N] ")))) {
+		info("aborted — no changes applied.");
+		return {
+			hasError,
+			applied: false
+		};
 	}
-	const project = opts.profile !== void 0 ? resolveProject(opts) : void 0;
-	if (opts.profile !== void 0) await applyProfileFromOption({
-		profile: opts.profile,
-		project,
-		cwd: cwdForProfile,
-		hubUrl: opts.hubUrl,
-		hubToken: opts.hubToken,
-		hubHeader: opts.hubHeader
-	});
-	else await applyProfileFromOption({
-		profile: void 0,
-		project: "",
-		cwd: cwdForProfile
-	});
-	const hubClientForTrace = resolveHubClient({
-		hubUrl: opts.hubUrl,
-		hubToken: opts.hubToken,
-		hubHeader: opts.hubHeader
+	try {
+		parseTestSpec(report.patch);
+	} catch (e) {
+		error(`refused to apply: patch failed validation (${e.message})`);
+		return {
+			hasError: true,
+			applied: false
+		};
+	}
+	meta("saved", await saveSpecFile(featureName, specName, report.patch));
+	return {
+		hasError,
+		applied: true
+	};
+}
+async function prompt(question) {
+	const rl = createInterface$1({
+		input: process.stdin,
+		output: process.stdout
 	});
-	const hubContext = hubClientForTrace && project ? {
-		hub: hubClientForTrace,
-		project
-	} : null;
-	const releaseLock = await acquireSpecLock(featureName, specName, "record", cwdForProfile).catch((e) => {
-		if (e instanceof SpecLockedError) {
-			error(e.message);
-			process.exit(2);
-		}
-		throw e;
+	rl.on("SIGINT", () => {
+		rl.close();
+		process.exit(130);
 	});
-	let traceResult = null;
 	try {
-		if (!opts.skipTrace) {
-			traceResult = await runTrace(featureName, specName, opts.model, opts.validationMode ?? "lenient", language, {
-				cwd: cwdForProfile,
-				hubContext
-			});
-			blank();
-		}
-		if (!opts.skipCodegen) await runGenerate(featureName, specName, {
-			maxRetries: parseInt(opts.maxRetries ?? "3", 10),
-			fixMode: toFixMode(opts.autoFix ?? "interactive"),
-			force: opts.force ?? false,
-			useSnapshot: opts.snapshot !== false,
-			language,
-			model: opts.model,
-			cwd: cwdForProfile,
-			hubContext
-		});
+		return (await rl.question(question)).trim();
 	} finally {
-		await releaseLock();
-	}
-	if (opts.updateAgentPrompt) if (traceResult === null) warn("--update-agent-prompt is ignored when --skip-trace is set (no run summary available)");
-	else {
-		blank();
-		await updateAgentPrompt({
-			mode: "record",
-			runSummary: buildRecordRunSummary(featureName, specName, traceResult),
-			hubContext,
-			...opts.model ? { model: opts.model } : {},
-			...language ? { language } : {}
-		});
+		rl.close();
 	}
-});
-/**
-* Compact summary of the trace pass for the record agent-prompt refresh.
-* Steps are reconstructed from the trace's status-line protocol (STEP_START
-* gives the title, STEP_DONE / ASSERTION_FAILED / STEP_SKIPPED the outcome),
-* and each step carries its per-action observations plus the **concrete kept
-* commands** — the selectors that actually survived scrub / dedup /
-* validation. The record playbook is told to record canonical selectors, so
-* it needs those exact tokens; the prose alone doesn't carry them. The
-* header's kept/recorded totals flag how much the run thrashed through
-* selectors overall.
-*/
-function buildRecordRunSummary(featureName, specName, t) {
-	const header = `## ${featureName}/${specName} — ${t.status}\nActions: ${t.actionsKept} kept / ${t.actionsRecorded} recorded`;
-	const steps = collectStepSummaries(t.statusLines);
-	if (steps.length === 0) return `${header}\n\n(no step status lines recorded)`;
-	const commandsByStep = groupCommandsByStep(t.actions);
-	const observationsByStep = groupObservationsByStep(t.actions);
-	const unstableByStep = countUnstableByStep(t.actions);
-	return `${header}\n\n${steps.map((s) => {
-		const cmds = commandsByStep.get(s.stepId) ?? [];
-		const observations = observationsByStep.get(s.stepId) ?? [];
-		const churn = t.churnByStep.get(s.stepId);
-		const dropped = churn ? churn.recorded - churn.kept : 0;
-		const redundant = churn?.redundant ?? 0;
-		const unstable = unstableByStep.get(s.stepId) ?? 0;
-		return [
-			`### ${s.stepId} — ${oneLineSummary(s.title)} (${s.status})`,
-			...s.detail ? [`- result: ${oneLineSummary(s.detail)}`] : [],
-			...observations.length > 0 ? [`- observations: ${observations.map(oneLineSummary).join(" ; ")}`] : [],
-			...dropped > 0 ? [`- churn: ${churn.recorded} attempts → ${churn.kept} kept (${dropped} dropped)`] : [],
-			...redundant > 0 ? [`- redundant: ${redundant} field(s) entered via 2+ selectors (kept both — record one canonical selector)`] : [],
-			...unstable > 0 ? [`- replay-unstable: ${unstable} kept command(s) marked [unstable] — do NOT record these as canonical; prefer a more stable locator even if it costs one more probe`] : [],
-			...cmds.length > 0 ? [`- kept commands: ${cmds.join(" ; ")}`] : []
-		].join("\n");
-	}).join("\n\n")}`;
+}
+/** Aggregated tool-call counts shown after each Claude turn. */
+function formatToolSummary(counts, elapsedMs) {
+	const entries = Object.entries(counts).filter(([, n]) => n > 0).sort((a, b) => b[1] - a[1]).map(([name, n]) => `${n} ${name}`);
+	return `  ✓ ${entries.length === 0 ? "no tool calls" : entries.join(", ")}  (${(elapsedMs / 1e3).toFixed(1)}s)`;
+}
+function printToolSummary(counts, elapsedMs) {
+	process.stdout.write(`${formatToolSummary(counts, elapsedMs)}\n`);
 }
 /**
-* Fold the ordered status lines into one entry per step: STEP_START opens
-* the entry (its detail is the step title); the terminal line sets the
-* outcome. A terminal line for a step that never emitted STEP_START still
-* gets an entry so its outcome isn't silently lost.
-*/
-function collectStepSummaries(lines) {
-	const byId = /* @__PURE__ */ new Map();
-	const ordered = [];
-	const ensure = (stepId, title) => {
-		let entry = byId.get(stepId);
-		if (!entry) {
-			entry = {
-				stepId,
-				title,
-				status: "NO_STATUS"
-			};
-			byId.set(stepId, entry);
-			ordered.push(entry);
-		}
-		return entry;
-	};
-	for (const line of lines) {
-		if (!line.stepId || line.type === "RUN_COMPLETED") continue;
-		if (line.type === "STEP_START") {
-			ensure(line.stepId, line.detail);
-			continue;
-		}
-		const entry = ensure(line.stepId, "(untitled)");
-		entry.status = line.type === "STEP_DONE" ? "DONE" : line.type === "ASSERTION_FAILED" ? "FAILED" : "SKIPPED";
-		if (line.detail) entry.detail = line.detail;
-	}
-	return ordered;
-}
-/** Group each kept action's `action selector` form under its stepId. */
-function groupCommandsByStep(actions) {
-	const byStep = /* @__PURE__ */ new Map();
-	for (const a of actions) {
-		if (!a.stepId) continue;
-		const list = byStep.get(a.stepId) ?? [];
-		list.push(formatRecordedAction(a));
-		byStep.set(a.stepId, list);
-	}
-	return byStep;
-}
-/**
-* Group per-action observations (snapshot / assert prose) under their stepId
-* — the trace's own record of what it verified at each step.
-*/
-function groupObservationsByStep(actions) {
-	const byStep = /* @__PURE__ */ new Map();
-	for (const a of actions) {
-		if (!a.stepId || !a.observation) continue;
-		const list = byStep.get(a.stepId) ?? [];
-		list.push(a.observation);
-		byStep.set(a.stepId, list);
-	}
-	return byStep;
-}
-/** Per-step count of kept-but-replay-unstable actions (the flaky selectors). */
-function countUnstableByStep(actions) {
-	const byStep = /* @__PURE__ */ new Map();
-	for (const a of actions) {
-		if (!a.stepId || !a.replayUnstable) continue;
-		byStep.set(a.stepId, (byStep.get(a.stepId) ?? 0) + 1);
-	}
-	return byStep;
-}
-/**
-* One kept action as `action selector` (with the fill value or assert
-* type when present) — the canonical form the record playbook should reuse.
-* Unlike the live summary this keeps selectors verbatim: record learns
-* concrete per-spec selectors, so masking them would defeat the purpose.
-*
-* A replay-unstable action (kept in lenient mode but flagged because its
-* selector wasn't present on a fresh replay) is tagged `[unstable](<reason>)`
-* so the learner does NOT record its selector as canonical — the reason is the
-* teacher signal ("not present within Nms" = timing-fragile, not stable).
-*/
-function formatRecordedAction(a) {
-	const parts = [a.action];
-	if (a.index !== void 0) parts.push(String(a.index));
-	const anchor = a.locator ? formatLocator(a.locator) : a.label;
-	if (anchor) parts.push(anchor);
-	if (a.value) parts.push(`= ${a.value}`);
-	if (a.assert) parts.push(`(${a.assert})`);
-	const line = oneLineSummary(parts.join(" "));
-	return a.replayUnstable ? `${line} [unstable](${oneLineSummary(a.replayReason ?? "no reason")})` : line;
-}
-/** Verbatim locator form: raw selector for css, `by=value` for semantic ones. */
-function formatLocator(locator) {
-	const name = locator.by === "role" && locator.name ? ` name=${locator.name}` : "";
-	return locator.by === "css" ? locator.value : `${locator.by}=${locator.value}${name}`;
-}
-function oneLineSummary(s) {
-	const flat = s.replace(/\s+/g, " ").trim();
-	return flat.length > 240 ? flat.slice(0, 240) + "…" : flat || "(none)";
-}
-//#endregion
-//#region src/cli/draft.ts
-const CATEGORY_LABEL = DRAFT_CATEGORY_LABEL;
-const draftCommand = addLanguageOption(new Command("draft").argument("[feature/spec]", "Optional spec path (e.g. tasks/create-and-complete). If omitted, Claude proposes one from your intent.").description("Interactively draft and refine a spec.yaml with Claude Code").option("--instruction <text>", "Non-interactive single-shot instruction (skips the interactive loop)").option("--apply", "Auto-apply each generated patch without [y/N] confirmation", false)).action(async (specPath, opts) => {
-	await ensureCcqaDir();
-	let featureName;
-	let specName;
-	let prefilledIntent = null;
-	if (specPath) ({featureName, specName} = parseSpecPath(specPath));
-	else {
-		const { naming, intent } = await proposeNaming(opts);
-		featureName = naming.featureName;
-		specName = naming.specName;
-		prefilledIntent = intent;
-	}
-	await runDraft(featureName, specName, opts, prefilledIntent);
-});
-async function runDraft(featureName, specName, opts, prefilledIntent) {
-	header("draft", `${featureName}/${specName}`);
-	const ja = useJapanesePrompts(opts.language);
-	const oneShot = opts.instruction !== void 0;
-	let useIntentOnce = prefilledIntent !== null && !oneShot;
-	while (true) {
-		const existing = await tryReadSpecFile(featureName, specName);
-		const isFirstRun = existing === null;
-		let userInput;
-		if (oneShot) userInput = opts.instruction ?? "";
-		else if (useIntentOnce && isFirstRun) {
-			userInput = prefilledIntent ?? "";
-			useIntentOnce = false;
-		} else userInput = await prompt(isFirstRun ? ja ? "何をテストしたいですか? > " : "What do you want to test? > " : ja ? "どのように修正しますか? (空欄で再検証) > " : "How would you like to refine? (empty = re-validate) > ");
-		if (isFirstRun && !userInput.trim()) {
-			error("intent required for the first draft (no spec exists yet)");
-			process.exit(1);
-		}
-		const turnResult = await runOneTurn({
-			featureName,
-			specName,
-			existing,
-			userInput: userInput.trim(),
-			autoApply: opts.apply === true,
-			language: opts.language
-		});
-		if (oneShot) process.exit(turnResult.hasError && !turnResult.applied ? 1 : 0);
-		blank();
-		if (/^y/i.test(await prompt(ja ? "このドラフトは完了ですか? [y/N] " : "Are you done with this draft? [y/N] "))) {
-			info("draft session complete.");
-			hint(`run 'ccqa trace ${featureName}/${specName}' to record actions`);
-			process.exit(0);
-		}
-	}
-}
-async function runOneTurn(input) {
-	const { featureName, specName, existing, userInput, autoApply, language } = input;
-	const isFirstRun = existing === null;
-	const systemPrompt = buildDraftSystemPrompt(await loadAvailableBlocks()) + languageDirective(language);
-	const userPrompt = buildDraftPrompt({
-		mode: isFirstRun ? "create" : "refine",
-		existing: existing ?? "",
-		userInput
-	});
-	info(isFirstRun ? "Reading codebase and drafting spec..." : "Re-validating spec against codebase...");
-	const toolCounts = {};
-	const startedAt = Date.now();
-	const { result, isError } = await invokeClaudeStreaming({
-		prompt: userPrompt,
-		systemPrompt,
-		allowedTools: [
-			"Read",
-			"Grep",
-			"Glob"
-		],
-		silenceBashLog: true
-	}, (msg) => {
-		if (msg.type !== "assistant") return;
-		for (const block of msg.message.content ?? []) if (block.type === "tool_use") toolCounts[block.name] = (toolCounts[block.name] ?? 0) + 1;
-	});
-	printToolSummary(toolCounts, Date.now() - startedAt);
-	if (isError) {
-		error("Claude returned an error result");
-		return {
-			hasError: true,
-			applied: false
-		};
-	}
-	const json = extractJsonBlock(result);
-	if (!json) {
-		error("Claude did not return a json block");
-		warn(`raw tail: ${truncate(result, 200)}`);
-		return {
-			hasError: true,
-			applied: false
-		};
-	}
-	let report;
-	try {
-		report = DraftReportSchema.parse(JSON.parse(json));
-	} catch (e) {
-		error(`failed to parse draft report: ${e.message}`);
-		return {
-			hasError: true,
-			applied: false
-		};
-	}
-	const hasError = printReviewBlock(report.issues);
-	const original = existing ?? "";
-	if (!report.patch || report.patch === original) {
-		blank();
-		info("no changes proposed.");
-		return {
-			hasError,
-			applied: false
-		};
-	}
-	blank();
-	info("--- proposed changes ---");
-	printUnifiedDiff(original, report.patch);
-	blank();
-	if (!(autoApply ? true : /^y/i.test(await prompt(useJapanesePrompts(language) ? "このパッチを適用しますか? [y/N] " : "Apply this patch? [y/N] ")))) {
-		info("aborted — no changes applied.");
-		return {
-			hasError,
-			applied: false
-		};
-	}
-	try {
-		parseTestSpec(report.patch);
-	} catch (e) {
-		error(`refused to apply: patch failed validation (${e.message})`);
-		return {
-			hasError: true,
-			applied: false
-		};
-	}
-	meta("saved", await saveSpecFile(featureName, specName, report.patch));
-	return {
-		hasError,
-		applied: true
-	};
-}
-async function prompt(question) {
-	const rl = createInterface$1({
-		input: process.stdin,
-		output: process.stdout
-	});
-	rl.on("SIGINT", () => {
-		rl.close();
-		process.exit(130);
-	});
-	try {
-		return (await rl.question(question)).trim();
-	} finally {
-		rl.close();
-	}
-}
-/** Aggregated tool-call counts shown after each Claude turn. */
-function formatToolSummary(counts, elapsedMs) {
-	const entries = Object.entries(counts).filter(([, n]) => n > 0).sort((a, b) => b[1] - a[1]).map(([name, n]) => `${n} ${name}`);
-	return `  ✓ ${entries.length === 0 ? "no tool calls" : entries.join(", ")}  (${(elapsedMs / 1e3).toFixed(1)}s)`;
-}
-function printToolSummary(counts, elapsedMs) {
-	process.stdout.write(`${formatToolSummary(counts, elapsedMs)}\n`);
-}
-/**
-* Renders the review report as a visually separated block, grouped by
-* severity. ERROR and WARN findings get full detail; OK findings collapse
-* to a one-line summary of category names. Returns whether any ERROR
-* severity was emitted.
+* Renders the review report as a visually separated block, grouped by
+* severity. ERROR and WARN findings get full detail; OK findings collapse
+* to a one-line summary of category names. Returns whether any ERROR
+* severity was emitted.
 */
 function printReviewBlock(issues) {
 	const RULE = "─".repeat(67);
@@ -12228,1013 +11890,1361 @@ function truncate(s, n) {
 	return s.slice(s.length - n);
 }
 //#endregion
-//#region src/drift/format.ts
-/**
-* Render drift results as a string. The CLI commands and the `run` failure
-* hook are the only callers; both want the formatted output returned so
-* they can prefix / interleave / pipe it as needed.
+//#region src/cli/perspectives.ts
+const perspectivesCommand = addHubOptions(addLanguageOption(new Command("perspectives").description("Generate/update the project's perspectives document on the hub — a factual inventory of existing test coverage (no severity, no gap analysis)").option("--instruction <text>", "Hint to steer how summaries are written").option("--apply", "Auto-apply without [y/N] confirmation", false).option("--check", "Verify the hub document still matches the local specs (mechanical fields only) and exit 1 when it is stale. No Claude calls — cheap enough for CI.", false).option("-m, --model <name>", "Claude model alias ('sonnet'|'opus'|'haiku') or full ID").option("--project <name>", "Hub project to store the document under (default: cwd directory name)"))).action(withHubErrors(async (opts) => {
+	if (opts.check) await runPerspectivesCheck(opts);
+	else await runPerspectives(opts);
+}));
+/**
+* `--check`: compare the hub document against a freshly-built local skeleton
+* on the CLI-owned mechanical fields only (the spec set, titles,
+* relatedPaths, status). Claude-authored descriptive fields and the human
+* note are deliberately not compared — they are not deterministic, so they
+* can't signal staleness. Exit 1 on any mismatch; this is the CI gate for
+* "someone changed the specs without the inventory catching up".
 */
-function renderDrift(results, format, cwd) {
-	if (format === "json") return renderJson(results);
-	if (format === "github") return renderGithub(results, cwd);
-	return renderText(results);
-}
-const HEAVY_RULE = "═".repeat(72);
-function renderText(results) {
-	const out = [];
-	for (const r of results) {
-		out.push("");
-		const heading = `══ ${r.target.featureName}/${r.target.specName} `;
-		const tail = "═".repeat(Math.max(3, 72 - heading.length));
-		out.push(`${heading}${tail}`);
-		if (r.error) {
-			out.push(`  ERROR  ${r.error}`);
-			continue;
-		}
-		const errors = r.issues.filter((i) => i.severity === "ERROR");
-		const warnings = r.issues.filter((i) => i.severity === "WARN");
-		const passed = r.issues.filter((i) => i.severity === "OK");
-		if (errors.length === 0 && warnings.length === 0) {
-			const label = passed.length === 1 ? "check" : "checks";
-			const detail = passed.length > 0 ? `all ${passed.length} ${label} passed` : "no issues";
-			out.push(`  ✓  ${detail}`);
-			continue;
-		}
-		for (const issue of errors) appendFinding(out, "ERROR", issue);
-		for (const issue of warnings) appendFinding(out, "WARN", issue);
-		if (passed.length > 0) {
-			const names = passed.map((i) => DRAFT_CATEGORY_LABEL[i.category]).join(", ");
-			out.push("");
-			out.push(`  ✓  passed (${passed.length}): ${names}`);
+async function runPerspectivesCheck(opts) {
+	const hub = requireHubOrExit(opts);
+	const project = resolveProject(opts);
+	header("perspectives", `check (project: ${project})`);
+	const skeleton = await buildSkeleton(await listFeatureTree());
+	const localCount = skeleton.reduce((n, f) => n + f.specs.length, 0);
+	const existingDoc = await hub.getPerspectives(project);
+	if (existingDoc === null) {
+		if (localCount === 0) {
+			info("no local test cases and no hub document — nothing to check.");
+			return;
 		}
+		error(`no perspectives document on the hub for project "${project}" — run \`ccqa perspectives\` to create it`);
+		process.exit(1);
 	}
-	out.push("");
-	out.push(HEAVY_RULE);
-	const totals = summarize(results);
-	out.push(`  specs    ${results.length} (${totals.errored} errored)`);
-	out.push(`  findings ${totals.error} error, ${totals.warn} warn, ${totals.ok} ok`);
-	out.push("");
-	return out.join("\n");
-}
-function appendFinding(out, level, issue) {
-	const stepPart = issue.stepId ? ` ${issue.stepId}` : "";
-	out.push("");
-	out.push(`  ${level}  ${DRAFT_CATEGORY_LABEL[issue.category]}${stepPart}`);
-	out.push(`    ${issue.message}`);
-	if (issue.detail) out.push(`    └ ${issue.detail.replace(/\n/g, "\n      ")}`);
-}
-function renderJson(results) {
-	const payload = { specs: results.map((r) => ({
-		feature: r.target.featureName,
-		spec: r.target.specName,
-		ok: r.ok,
-		...r.error ? { error: r.error } : {},
-		issues: r.issues.map((i) => ({
-			severity: i.severity,
-			category: i.category,
-			stepId: i.stepId,
-			message: i.message,
-			...i.detail ? { detail: i.detail } : {}
-		}))
-	})) };
-	return `${JSON.stringify(payload, null, 2)}\n`;
+	const parsed = PerspectivesSchema.safeParse(existingDoc);
+	if (!parsed.success) {
+		error("the hub document does not match the perspectives schema — run `ccqa perspectives` to regenerate it");
+		process.exit(1);
+	}
+	info(`checking ${localCount} local test case(s) against the hub document...`);
+	const issues = comparePerspectivesSkeleton(skeleton, parsed.data);
+	if (issues.length === 0) {
+		blank();
+		info(`perspectives are up to date (${localCount} case(s)).`);
+		return;
+	}
+	blank();
+	for (const issue of issues) error(issue);
+	blank();
+	error(`perspectives are stale (${issues.length} issue(s)) — run \`ccqa perspectives\` to regenerate`);
+	process.exit(1);
 }
-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);
-		if (r.error) {
-			lines.push(`::error file=${file}::${escapeGhMessage(r.error)}`);
+/**
+* Mechanical-field comparison behind `--check`. Returns one human-readable
+* line per out-of-sync spec (empty when in sync). Exported for unit testing.
+*/
+function comparePerspectivesSkeleton(local, remote) {
+	const remoteMap = /* @__PURE__ */ new Map();
+	for (const feature of remote.features) for (const spec of feature.specs) remoteMap.set(noteKey(feature.featureName, spec.specName), spec);
+	const issues = [];
+	const seen = /* @__PURE__ */ new Set();
+	for (const feature of local) for (const spec of feature.specs) {
+		const key = noteKey(feature.featureName, spec.specName);
+		seen.add(key);
+		const remoteSpec = remoteMap.get(key);
+		if (!remoteSpec) {
+			issues.push(`${key}: not in the hub document`);
 			continue;
 		}
-		for (const issue of r.issues) {
-			if (issue.severity === "OK") continue;
-			const level = issue.severity === "ERROR" ? "error" : "warning";
-			const title = `${r.target.featureName}/${r.target.specName} — ${issue.category}${issue.stepId ? ` (${issue.stepId})` : ""}`;
-			const body = issue.detail ? `${issue.message}\n${issue.detail}` : issue.message;
-			lines.push(`::${level} file=${file},title=${escapeGhProp(title)}::${escapeGhMessage(body)}`);
+		const fields = [];
+		if (remoteSpec.title !== spec.title) fields.push("title");
+		if (!sameStringArray(remoteSpec.relatedPaths, spec.relatedPaths)) fields.push("relatedPaths");
+		if (remoteSpec.status.mode !== spec.status.mode || remoteSpec.status.traced !== spec.status.traced || remoteSpec.status.generated !== spec.status.generated) fields.push(`status (local: ${formatStatus(spec.status)}, hub: ${formatStatus(remoteSpec.status)})`);
+		if (fields.length > 0) issues.push(`${key}: out of date — ${fields.join(", ")}`);
+	}
+	for (const key of remoteMap.keys()) if (!seen.has(key)) issues.push(`${key}: no longer exists locally (stale hub entry)`);
+	return issues;
+}
+function formatStatus(status) {
+	return `${status.mode}/traced=${status.traced}/generated=${status.generated}`;
+}
+/** Order-sensitive equality; an absent list and an empty list are the same thing. */
+function sameStringArray(a, b) {
+	const left = a ?? [];
+	const right = b ?? [];
+	return left.length === right.length && left.every((v, i) => v === right[i]);
+}
+/** Perspectives live on the hub only — no hub, no place to store (or check) them. */
+function requireHubOrExit(opts) {
+	try {
+		return requireHubClient(opts);
+	} catch (err) {
+		if (err instanceof HubConnectionError) {
+			error(err.message);
+			hint("perspectives are stored on the hub — start one with `ccqa serve`");
+			process.exit(2);
 		}
+		throw err;
 	}
-	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");
-	const rel = relative(repoRoot, abs);
-	return rel.startsWith("..") ? abs : rel;
-}
-function escapeGhMessage(s) {
-	return s.replace(/%/g, "%25").replace(/\r/g, "%0D").replace(/\n/g, "%0A");
 }
-function escapeGhProp(s) {
-	return s.replace(/%/g, "%25").replace(/\r/g, "%0D").replace(/\n/g, "%0A").replace(/,/g, "%2C").replace(/:/g, "%3A");
-}
-function summarize(results) {
-	let error = 0;
-	let warn = 0;
-	let ok = 0;
-	let errored = 0;
-	for (const r of results) {
-		if (r.error) errored++;
-		for (const issue of r.issues) if (issue.severity === "ERROR") error++;
-		else if (issue.severity === "WARN") warn++;
-		else ok++;
+async function runPerspectives(opts) {
+	const hub = requireHubOrExit(opts);
+	const project = resolveProject(opts);
+	header("perspectives", `project: ${project}`);
+	const skeleton = await buildSkeleton(await listFeatureTree());
+	const allSpecs = skeleton.flatMap((f) => f.specs);
+	if (allSpecs.length === 0) {
+		info("no test cases found under .ccqa/features — nothing to inventory.");
+		return;
 	}
-	return {
-		error,
-		warn,
-		ok,
-		errored
-	};
+	const existingDoc = await hub.getPerspectives(project);
+	const noteMap = extractNotes(existingDoc);
+	const specBodies = await loadSpecBodies(skeleton);
+	meta("language", opts.language ?? "auto");
+	info(`Summarising ${allSpecs.length} test case(s) across ${skeleton.length} feature(s)...`);
+	const summaries = await requestSummaries(specBodies, opts);
+	if (summaries === null) process.exit(1);
+	const merged = mergePerspectives(skeleton, summaries, noteMap);
+	let validated;
+	try {
+		validated = PerspectivesSchema.parse(merged);
+	} catch (e) {
+		error(`refused to push: assembled perspectives failed validation (${e.message})`);
+		process.exit(1);
+	}
+	const existingYaml = existingDoc === null ? "" : stringify(existingDoc, { lineWidth: 0 });
+	const next = stringify(validated, { lineWidth: 0 });
+	if (withoutGeneratedAt(existingYaml) === withoutGeneratedAt(next)) {
+		blank();
+		info("perspectives already up to date — no changes.");
+		await cleanupLegacyLocalFiles();
+		return;
+	}
+	blank();
+	info("--- proposed changes (YAML view of the hub document) ---");
+	printUnifiedDiff(existingYaml, next);
+	blank();
+	if (!(opts.apply === true || /^y/i.test(await prompt(useJapanesePrompts(opts.language) ? "hub に perspectives を保存しますか? [y/N] " : "Push perspectives to the hub? [y/N] ")))) {
+		info("aborted — no changes written.");
+		return;
+	}
+	await hub.putPerspectives(project, validated);
+	meta("pushed", `perspectives (project: ${project})`);
+	await cleanupLegacyLocalFiles();
 }
-//#endregion
-//#region src/drift/exit-code.ts
 /**
-* Map drift results to an exit code. Spec-level errors (Claude call failed)
-* always fail; otherwise ERROR severity always fails, WARN fails only when
-* the threshold is `warn`.
+* Perspectives used to be written into the repo (`.ccqa/perspectives.yaml`,
+* `.ccqa/perspectives.md`, `.ccqa/features/<f>/perspectives.md`). Now that
+* the document is hub-only, sweep those leftovers whenever the command runs
+* so consuming repos converge without a manual cleanup.
 */
-function determineExitCode(results, threshold) {
-	for (const r of results) {
-		if (r.error) return 1;
-		for (const issue of r.issues) {
-			if (issue.severity === "ERROR") return 1;
-			if (threshold === "warn" && issue.severity === "WARN") return 1;
-		}
-	}
-	return 0;
+async function cleanupLegacyLocalFiles() {
+	const removed = await removeLegacyPerspectivesFiles();
+	for (const path of removed) meta("removed legacy file", path);
 }
 /**
-* Spec-level status under the given threshold, mirroring determineExitCode's
-* per-issue logic (exit-code.ts) but scoped to a single SpecResult.
+* Turn the feature tree into the skeleton perspectives features: title +
+* relatedPaths 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.
 */
-function specStatus(result, threshold) {
-	if (result.error) return "failed";
-	for (const issue of result.issues) {
-		if (issue.severity === "ERROR") return "failed";
-		if (threshold === "warn" && issue.severity === "WARN") return "failed";
-	}
-	return "passed";
+async function buildSkeleton(tree) {
+	return (await Promise.all(tree.map(async (feature) => {
+		const specs = await Promise.all(feature.specs.filter((s) => s.hasSpecFile).map(async (s) => {
+			const spec = await readSpecMeta(feature.featureName, s.specName);
+			const status = await deriveStatus(feature.featureName, s.specName, spec.mode);
+			const entry = {
+				specName: s.specName,
+				title: spec.title,
+				summary: "",
+				status
+			};
+			if (s.relatedPaths) entry.relatedPaths = s.relatedPaths;
+			return entry;
+		}));
+		return {
+			featureName: feature.featureName,
+			specs
+		};
+	}))).filter((f) => f.specs.length > 0).map((f) => ({
+		featureName: f.featureName,
+		specs: [...f.specs].sort((a, b) => a.specName.localeCompare(b.specName))
+	})).sort((a, b) => a.featureName.localeCompare(b.featureName));
 }
 /**
-* Adapts `ccqa drift` results into the shared RunReportData shape so they can
-* be pushed to the hub (`ccqa drift --push`) and rendered by the same report
-* UI as `ccqa run`/`ccqa live`. Browser-execution fields (testCounts,
-* evidence, liveRun, ...) don't apply to a drift audit and are always null.
+* `(featureName, specName)` → human note, extracted from the hub's current
+* perspectives document. Notes are preserved across regeneration; everything
+* else (title, status, summary) is recomputed. Returns an empty map when the
+* document is absent or doesn't match the schema — note preservation is
+* best-effort and never blocks regeneration.
 */
-function driftResultsToReport(results, meta) {
-	const specResults = results.map((result) => ({
-		feature: result.target.featureName,
-		spec: result.target.specName,
-		title: null,
-		status: specStatus(result, meta.threshold),
-		testCounts: null,
-		durationMs: null,
-		assertions: null,
-		analysis: null,
-		analysisSkipped: null,
-		driftIssues: result.issues,
-		failureLogExcerpt: null,
-		diffExcerpt: null,
-		specYaml: null,
-		evidence: null,
-		liveRun: null
-	}));
-	return {
-		schemaVersion: 1,
-		kind: "drift",
-		createdAt: meta.createdAt ?? (/* @__PURE__ */ new Date()).toISOString(),
-		runId: meta.runId ?? null,
-		git: meta.git,
-		model: meta.model ?? null,
-		language: meta.language ?? null,
-		promptVersion: meta.promptVersion ?? "1",
-		customPromptVersion: null,
-		results: specResults
-	};
+function extractNotes(existing) {
+	const map = /* @__PURE__ */ new Map();
+	if (existing === null || existing === void 0) return map;
+	const result = PerspectivesSchema.safeParse(existing);
+	if (!result.success) return map;
+	for (const feature of result.data.features) for (const spec of feature.specs) if (spec.note !== void 0 && spec.note !== "") map.set(noteKey(feature.featureName, spec.specName), spec.note);
+	return map;
 }
-//#endregion
-//#region src/drift/route-new-files.ts
 /**
-* Lightweight Claude call: given a list of new files in the PR and the existing
-* specs (with their relatedPaths globs as a hint), return the spec keys (in
-* "<feature>/<spec>" form) that the new files plausibly affect.
-*
-* Conservative by design — false positives are safer than false negatives,
-* because a missed spec turns into undetected drift in CI. When the router
-* call itself fails, we log a warning rather than fail-close: the surrounding
-* glob match is the primary signal; the router only adds coverage for new
-* paths no glob captures.
+* Merge the mechanical skeleton with Claude's summaries and the preserved
+* notes into the final perspectives object. Summaries are matched by
+* (featureName, specName); an unmatched spec keeps its empty summary.
 */
-async function routeNewFilesToSpecs(input) {
-	const { newFiles, specs, cwd, model } = input;
-	const empty = /* @__PURE__ */ new Set();
-	if (newFiles.length === 0 || specs.length === 0) return empty;
+function mergePerspectives(skeleton, summaries, noteMap) {
+	const summaryMap = /* @__PURE__ */ new Map();
+	for (const s of summaries) summaryMap.set(noteKey(s.featureName, s.specName), s);
+	const features = skeleton.map((feature) => ({
+		featureName: feature.featureName,
+		specs: feature.specs.map((spec) => {
+			const key = noteKey(feature.featureName, spec.specName);
+			const entry = summaryMap.get(key);
+			const merged = {
+				...spec,
+				summary: entry?.summary ?? spec.summary
+			};
+			if (entry?.startScreen) merged.startScreen = entry.startScreen;
+			if (entry?.testCondition) merged.testCondition = entry.testCondition;
+			if (entry?.preconditions && entry.preconditions.length > 0) merged.preconditions = entry.preconditions;
+			const note = noteMap.get(key);
+			if (note !== void 0) merged.note = note;
+			return merged;
+		})
+	}));
+	return {
+		generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+		features
+	};
+}
+/**
+* Strip the top-level `generatedAt:` line so two serialised perspectives can
+* be compared for substantive equality without the always-fresh timestamp
+* defeating the "already up to date" check. Exported for unit testing.
+*/
+function withoutGeneratedAt(yamlText) {
+	return yamlText.split("\n").filter((line) => !/^generatedAt:/.test(line)).join("\n").trim();
+}
+function noteKey(featureName, specName) {
+	return `${featureName}/${specName}`;
+}
+async function readSpecMeta(featureName, specName) {
+	const raw = await tryReadSpecFile(featureName, specName);
+	if (raw === null) return {
+		title: specName,
+		mode: DEFAULT_SPEC_MODE
+	};
+	try {
+		const parsed = parse(raw);
+		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
+		};
+	} catch {
+		return {
+			title: specName,
+			mode: DEFAULT_SPEC_MODE
+		};
+	}
+}
+async function deriveStatus(featureName, specName, mode) {
+	return {
+		mode,
+		traced: await stat(join(getSpecDir(featureName, specName), "ir.json")).then(() => true).catch(() => false),
+		generated: await getTestScript(featureName, specName) !== null
+	};
+}
+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
+		};
+	})));
+}
+async function requestSummaries(specs, opts) {
+	const toolCounts = {};
+	const startedAt = Date.now();
 	const { result, isError } = await invokeClaudeStreaming({
-		prompt: buildRouterPrompt(await Promise.all(newFiles.map(async (path) => ({
-			path,
-			head: await readHead(join(cwd, path))
-		}))), specs),
-		systemPrompt: buildRouterSystemPrompt(),
+		prompt: buildPerspectivesPrompt(specs, opts.instruction),
+		systemPrompt: buildPerspectivesSystemPrompt() + languageDirective(opts.language),
 		allowedTools: [
 			"Read",
 			"Grep",
 			"Glob"
 		],
 		silenceBashLog: true,
-		cwd,
-		...model ? { model } : {}
-	}, (_msg) => {});
+		...opts.model ? { model: opts.model } : {}
+	}, (msg) => {
+		if (msg.type !== "assistant") return;
+		for (const block of msg.message.content ?? []) if (block.type === "tool_use") toolCounts[block.name] = (toolCounts[block.name] ?? 0) + 1;
+	});
+	process.stdout.write(`${formatToolSummary(toolCounts, Date.now() - startedAt)}\n`);
 	if (isError) {
-		warn("new-file router: Claude returned an error; skipping router signal");
-		return empty;
+		error("Claude returned an error result");
+		return null;
 	}
 	const json = extractJsonBlock(result);
 	if (!json) {
-		warn("new-file router: no JSON block in response; skipping router signal");
-		return empty;
+		error("Claude did not return a json block");
+		return null;
 	}
-	let parsed;
+	return parseSummaries(json);
+}
+/**
+* Parse the `{ summaries: [...] }` JSON contract into typed entries. Returns
+* null and logs when the payload is malformed. Exported for unit testing.
+*/
+function parseSummaries(json) {
+	let payload;
 	try {
-		parsed = JSON.parse(json);
+		payload = JSON.parse(json);
 	} catch (e) {
-		warn(`new-file router: failed to parse JSON (${e.message}); skipping router signal`);
-		return empty;
+		error(`failed to parse summaries JSON: ${e.message}`);
+		return null;
 	}
-	const out = /* @__PURE__ */ new Set();
-	const validKeys = new Set(specs.map((s) => `${s.featureName}/${s.specName}`));
-	if (typeof parsed === "object" && parsed !== null && "affectedSpecs" in parsed) {
-		const arr = parsed.affectedSpecs;
-		if (Array.isArray(arr)) {
-			for (const item of arr) if (typeof item === "string" && validKeys.has(item)) out.add(item);
+	if (typeof payload !== "object" || payload === null) {
+		error("summaries payload is not an object");
+		return null;
+	}
+	const summaries = payload.summaries;
+	if (!Array.isArray(summaries)) {
+		error("summaries payload missing a `summaries` array");
+		return null;
+	}
+	const out = [];
+	for (const item of summaries) {
+		const rec = item ?? {};
+		const { featureName, specName, summary } = rec;
+		if (typeof featureName === "string" && typeof specName === "string" && typeof summary === "string") {
+			const entry = {
+				featureName,
+				specName,
+				summary
+			};
+			if (typeof rec.startScreen === "string" && rec.startScreen.length > 0) entry.startScreen = rec.startScreen;
+			if (typeof rec.testCondition === "string" && rec.testCondition.length > 0) entry.testCondition = rec.testCondition;
+			if (Array.isArray(rec.preconditions)) {
+				const pre = rec.preconditions.filter((p) => typeof p === "string" && p.length > 0);
+				if (pre.length > 0) entry.preconditions = pre;
+			}
+			out.push(entry);
 		}
 	}
 	return out;
 }
-async function readHead(absPath) {
-	const content = await readFile(absPath, "utf-8").catch(() => "");
-	if (!content) return "";
-	return content.split("\n").slice(0, 40).join("\n");
-}
-function buildRouterSystemPrompt() {
-	return `You triage which ccqa test specs are potentially affected by NEW source files added in a pull request.
-
-You will receive:
-- A list of new files (path + first ~40 lines of each)
-- A list of existing specs with their declared relatedPaths globs
-
-Your job: return the spec keys (in "<feature>/<spec>" form) whose behaviour might depend on any of the new files.
-
-## Rules
-
-- Be **conservative**: when in doubt, include the spec. A spurious inclusion costs one extra drift check; a missed spec lets real drift slip through CI.
-- Use \`Read\`, \`Grep\`, \`Glob\` if you need to inspect the spec body or related code, but stay focused — this is a triage step, not a full review.
-- Ignore specs whose relatedPaths clearly point to a different area than every new file (e.g. \`src/auth/**\` specs vs new files only under \`src/billing/**\`).
-- Files like tests, generated code, build artifacts, vendor dirs typically do not affect any spec. Skip them.
-
-## Output (STRICT)
-
-Output ONE fenced \`\`\`json block, nothing else:
-
-\`\`\`json
-{
-  "affectedSpecs": ["feature/spec", "feature/spec"]
+//#endregion
+//#region src/cli/perspectives-sync.ts
+/**
+* Best-effort incremental update of the hub-stored perspectives document
+* after a successful `ccqa record` / `ccqa generate`: upsert just this spec's
+* entry (mechanical facts recomputed, descriptive fields rewritten by one
+* small Claude call, the human `note` preserved). The full `ccqa perspectives`
+* run remains the way to regenerate everything and prune deleted specs.
+*
+* Never fails the caller: no hub configured → no-op; any error → warning.
+*/
+async function syncSpecPerspectives(hubContext, opts) {
+	if (!hubContext) return;
+	try {
+		await doSync(hubContext, opts);
+	} catch (err) {
+		warn(`perspectives auto-update skipped: ${err instanceof Error ? err.message : String(err)}`);
+	}
 }
-\`\`\`
-
-Use exactly the keys you saw in the input ("<feature>/<spec>"). Return an empty array if no spec is affected.
-`;
+async function doSync(ctx, opts) {
+	const { featureName, specName } = opts.ref;
+	const specYaml = await tryReadSpecFile(featureName, specName);
+	if (specYaml === null) return;
+	const existing = await ctx.hub.getPerspectives(ctx.project);
+	let doc;
+	if (existing === null) doc = {
+		generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+		features: []
+	};
+	else {
+		const parsed = PerspectivesSchema.safeParse(existing);
+		if (!parsed.success) {
+			warn("perspectives auto-update skipped: the hub document does not match the schema — run `ccqa perspectives` to regenerate it");
+			return;
+		}
+		doc = parsed.data;
+	}
+	const meta$1 = await readSpecMeta(featureName, specName);
+	const status = await deriveStatus(featureName, specName, meta$1.mode);
+	const relatedPaths = extractRelatedPaths(specYaml);
+	const previous = findSpec(doc, featureName, specName);
+	const written = (await requestSummaries([{
+		featureName,
+		specName,
+		title: meta$1.title,
+		specYaml
+	}], {
+		...opts.language ? { language: opts.language } : {},
+		...opts.model ? { model: opts.model } : {}
+	}))?.[0];
+	const entry = {
+		specName,
+		title: meta$1.title,
+		summary: written?.summary ?? previous?.summary ?? "",
+		status
+	};
+	const startScreen = written?.startScreen ?? previous?.startScreen;
+	if (startScreen) entry.startScreen = startScreen;
+	const testCondition = written?.testCondition ?? previous?.testCondition;
+	if (testCondition) entry.testCondition = testCondition;
+	const preconditions = written?.preconditions ?? previous?.preconditions;
+	if (preconditions && preconditions.length > 0) entry.preconditions = preconditions;
+	if (relatedPaths.length > 0) entry.relatedPaths = relatedPaths;
+	if (previous?.note) entry.note = previous.note;
+	upsertSpec(doc, featureName, entry);
+	doc.generatedAt = (/* @__PURE__ */ new Date()).toISOString();
+	await ctx.hub.putPerspectives(ctx.project, PerspectivesSchema.parse(doc));
+	meta("perspectives", `updated ${featureName}/${specName} on the hub`);
+}
+function findSpec(doc, featureName, specName) {
+	return doc.features.find((f) => f.featureName === featureName)?.specs.find((s) => s.specName === specName);
+}
+/** Replace-or-insert the spec entry, keeping features and specs name-sorted like a full regeneration. */
+function upsertSpec(doc, featureName, entry) {
+	let feature = doc.features.find((f) => f.featureName === featureName);
+	if (!feature) {
+		feature = {
+			featureName,
+			specs: []
+		};
+		doc.features.push(feature);
+		doc.features.sort((a, b) => a.featureName.localeCompare(b.featureName));
+	}
+	const idx = feature.specs.findIndex((s) => s.specName === entry.specName);
+	if (idx >= 0) feature.specs[idx] = entry;
+	else {
+		feature.specs.push(entry);
+		feature.specs.sort((a, b) => a.specName.localeCompare(b.specName));
+	}
 }
-function buildRouterPrompt(previews, specs) {
-	return `## New files
-
-${previews.map((p) => {
-		const headBlock = p.head ? `\n\`\`\`\n${p.head}\n\`\`\`` : "\n(empty or unreadable)";
-		return `### ${p.path}${headBlock}`;
-	}).join("\n\n")}
-
-## Existing specs
-
-${specs.map((s) => {
-		const paths = s.relatedPaths.length === 0 ? "  (no relatedPaths declared)" : s.relatedPaths.map((p) => `  - ${p}`).join("\n");
-		return `- ${s.featureName}/${s.specName}\n${paths}`;
-	}).join("\n")}
-
-## Task
-
-Return the spec keys that might be affected by any of the new files. Conservative inclusion is preferred over missing real drift.
-`;
+/** `relatedPaths` transcribed verbatim from the spec.yaml (empty when absent/unparsable). */
+function extractRelatedPaths(specYaml) {
+	try {
+		const parsed = parse(specYaml);
+		if (!Array.isArray(parsed?.relatedPaths)) return [];
+		return parsed.relatedPaths.filter((p) => typeof p === "string" && p.length > 0);
+	} catch {
+		return [];
+	}
 }
 //#endregion
-//#region src/cli/drift.ts
-const DEFAULT_CONCURRENCY = 3;
-const driftCommand = addLanguageOption(new Command("drift").argument("[feature/spec]", "Optional spec id. If omitted, every spec under .ccqa/features/ is checked.").description("Standalone spec ↔ codebase static audit. Use for PR checks where the browser isn't run. For run-time audit with a structured report, see `ccqa run --report`.").option("--format <fmt>", "Output format: text | json | github", "text").option("--severity <level>", "Exit non-zero on this severity or higher: warn | error", "error").option("--concurrency <n>", `Parallel spec checks (default: ${DEFAULT_CONCURRENCY})`).option("-m, --model <name>", "Claude model alias ('sonnet'|'opus'|'haiku') or full ID. Overrides CCQA_MODEL.").option("--cwd <path>", "Working directory used as both the .ccqa root and the codebase Claude reads. Useful for monorepos. Defaults to process.cwd().").option("--changed", "Restrict drift checks to specs whose relatedPaths intersect the git diff against --base (or, in CI, $GITHUB_BASE_REF, else origin/main). New files are routed to specs via a single lightweight Claude call.").option("--base <ref>", "Base ref to diff against when --changed is set. Defaults to $GITHUB_BASE_REF (CI) or origin/main.").option("--push", "Push the drift result to a ccqa hub as a run (kind: drift).").option("--project <name>", "Logical project name for the pushed run. Defaults to the current directory's name.").option(...hubUrlOption).option(...hubTokenOption).option(...hubHeaderOption)).action(async (specPath, opts) => {
-	const format = parseFormat(opts.format);
-	const threshold = parseSeverity(opts.severity);
-	const concurrency = parseConcurrency(opts.concurrency);
-	const cwd = resolveCwd(opts.cwd);
-	await ensureCcqaDir(cwd);
-	if (opts.changed && specPath) {
-		error("--changed and an explicit spec id cannot be combined; --changed only applies to a full sweep");
-		process.exit(2);
-	}
-	let targets = await collectTargets(specPath, cwd);
-	if (targets.length === 0) exitWithNoSpecs(format, "no test specs found under .ccqa/features/");
-	if (format === "text") {
-		header("drift", specPath ?? `${targets.length} spec${targets.length > 1 ? "s" : ""}`);
-		if (opts.cwd) meta("cwd", cwd);
+//#region src/cli/generate.ts
+const AUTO_FIX_MODES = [
+	"interactive",
+	"auto",
+	"skip"
+];
+function toFixMode(autoFix) {
+	switch (autoFix) {
+		case "auto": return "auto";
+		case "skip": return "non-interactive";
+		case "interactive": return "interactive";
 	}
-	const baseRef = opts.changed ? resolveBaseRef(opts.base) : null;
-	if (opts.changed) {
-		const total = targets.length;
-		targets = await filterByChanged({
-			targets,
-			cwd,
-			baseOverride: opts.base,
-			format,
-			model: opts.model
-		});
-		if (format === "text") meta("scoped", `${targets.length} of ${total} spec${total > 1 ? "s" : ""}`);
-		if (targets.length === 0) exitWithNoSpecs(format, "no specs intersect the changed file set; nothing to check");
+}
+/** Shared `--auto-fix` parser for the record / generate commands. */
+function parseAutoFixFlag(raw) {
+	if (AUTO_FIX_MODES.includes(raw)) return raw;
+	throw new Error(`--auto-fix must be one of ${AUTO_FIX_MODES.join(" | ")}`);
+}
+/**
+* The `generate` flow shared by `ccqa generate` and the codegen half of
+* `ccqa record`: resolve the spec's target plugin, load its input (the
+* recording, for input:"recording" targets), and dispatch to the plugin.
+* This layer owns the CLI concerns — overwrite confirmation, logging,
+* exit-code policy — while the plugin owns the generation pipeline.
+*/
+async function runGenerate(featureName, specName, opts) {
+	header("generate", `${featureName}/${specName}`);
+	const cwd = opts.cwd ?? process.cwd();
+	await ensureCcqaDir(cwd);
+	const releaseLock = await acquireSpecLock(featureName, specName, "generate", cwd);
+	try {
+		await runGenerateLocked(featureName, specName, opts, cwd);
+	} finally {
+		await releaseLock();
 	}
-	const blocks = await loadAvailableBlocks(cwd);
-	const results = await analyzeDrift({
-		targets,
+}
+async function runGenerateLocked(featureName, specName, opts, cwd) {
+	const specYaml = await readSpecFile(featureName, specName, cwd);
+	const spec = parseTestSpec(specYaml);
+	const config = await loadProjectConfig(cwd);
+	const target = opts.targetOverride !== void 0 ? resolveTargetOverride(spec, opts.targetOverride) : resolveTarget(spec, config);
+	meta("target", target.id + (opts.targetOverride !== void 0 ? " (--target override)" : ""));
+	const existingOutput = await target.existingOutput?.({
+		featureName,
+		specName
+	}, cwd) ?? null;
+	if (existingOutput && !opts.force) {
+		if (!await confirmOverwrite(existingOutput)) {
+			info("aborted; pass --force to overwrite without prompting");
+			return;
+		}
+	}
+	let recording;
+	if (target.input === "recording") {
+		const { path: recordingPath, actions } = await getRecording(featureName, specName, cwd);
+		meta("recording", recordingPath);
+		meta("actions", actions.length);
+		recording = actions;
+	}
+	await warnStaleBlockArtifacts();
+	const targetConfig = config.targets[target.id] ?? TargetConfigSchema.parse({});
+	const ctx = {
+		spec,
+		specYaml,
+		featureName,
+		specName,
 		cwd,
-		blocks,
-		concurrency,
-		...opts.model ? { model: opts.model } : {},
-		...opts.language ? { language: opts.language } : {},
-		onSpecStart: (t) => {
-			if (format === "text") info(`checking ${t.featureName}/${t.specName}`);
+		recording,
+		resources: targetConfig.resources,
+		conventions: targetConfig.conventions,
+		targetConfig,
+		language: opts.language,
+		model: opts.model,
+		hub: opts.hubContext ?? null,
+		fix: {
+			maxRetries: opts.maxRetries,
+			mode: opts.fixMode,
+			useSnapshot: opts.useSnapshot
 		}
+	};
+	if (!(await target.generate(ctx)).passed) {
+		warn("auto-fix exhausted; test still failing");
+		process.exit(1);
+	}
+	hint(`run 'ccqa run ${featureName}/${specName}' to execute the test`);
+}
+async function confirmOverwrite(path) {
+	if (!process.stdin.isTTY) {
+		warn(`${path} exists and stdin is not a TTY; refusing to overwrite. Pass --force to allow.`);
+		return false;
+	}
+	const rl = createInterface({
+		input: process.stdin,
+		output: process.stdout
 	});
-	process.stdout.write(renderDrift(results, format, cwd));
-	if (opts.push) await pushDriftResults({
-		results,
-		threshold,
+	try {
+		process.stdout.write("\n");
+		process.stdout.write(`[warn] ${path} already exists.\n`);
+		process.stdout.write(`[warn] generate will regenerate it and any manual edits will be lost.\n`);
+		const norm = (await new Promise((res) => rl.question("Overwrite? [y/N] ", res))).trim().toLowerCase();
+		return norm === "y" || norm === "yes";
+	} finally {
+		rl.close();
+	}
+}
+const generateCommand = addHubOptions(addProfileOption(addLanguageOption(new Command("generate").argument("<feature/spec>", "Spec id in '<feature>/<spec>' form (resolves to .ccqa/features/<feature>/test-cases/<spec>/)").description("Generate test code from a spec via its target plugin. Recording-backed targets compile the existing ir.json (run `ccqa record` first); spec-input targets generate directly from the spec.").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), 'auto' (apply without prompt, for CI), 'skip' (never prompt, only apply high-confidence fixes).", parseAutoFixFlag, "interactive").option("--max-retries <n>", "Maximum number of auto-fix retries", "3").option("--force", "Overwrite previously generated test code without warning").option("--no-snapshot", "Don't pin AGENT_BROWSER_SESSION / capture page snapshots after a failure (debug toggle)").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(async (specPath, opts) => {
+	const { featureName, specName } = parseSpecPath(specPath);
+	const language = opts.language ?? "auto";
+	const cwd = resolveCwd(opts.cwd);
+	const hubClient = resolveHubClient({
+		hubUrl: opts.hubUrl,
+		hubToken: opts.hubToken,
+		hubHeader: opts.hubHeader
+	});
+	const project = opts.profile !== void 0 || hubClient !== null ? resolveProject(opts) : void 0;
+	if (opts.profile !== void 0) await applyProfileFromOption({
+		profile: opts.profile,
+		project,
 		cwd,
-		opts,
-		format,
-		baseRef
+		hubUrl: opts.hubUrl,
+		hubToken: opts.hubToken,
+		hubHeader: opts.hubHeader
 	});
-	process.exit(determineExitCode(results, threshold));
-});
-/**
-* Push a finished drift audit to a ccqa hub as a `kind: "drift"` run, so it
-* shows up alongside `ccqa run` runs in the hub UI. Best-effort: a missing
-* hub connection warns and returns rather than failing the command (`--push`
-* never changes drift's own exit code).
-*
-* `resolveHub` is injectable so tests can supply a fake `HubClient` without
-* a real hub connection; it defaults to the real flag/env resolution.
-*/
-async function pushDriftResults(args, resolveHub = resolveHubClient) {
-	const { results, threshold, cwd, opts, format, baseRef } = args;
-	const hub = resolveHub(opts);
-	if (!hub) {
-		warn("--push requires a hub connection (--hub-url/--hub-token or CCQA_HUB_URL/CCQA_HUB_TOKEN) — skipping push");
-		return;
-	}
+	else await applyProfileFromOption({
+		profile: void 0,
+		project: "",
+		cwd
+	});
+	const hubContext = hubClient && project ? {
+		hub: hubClient,
+		project
+	} : null;
 	try {
-		const project = resolveProject({
-			project: opts.project,
-			cwd
-		});
-		const [branch, head] = await Promise.all([detectBranch(cwd), getGitHead(cwd)]);
-		const report = driftResultsToReport(results, {
-			threshold,
-			git: {
-				head,
-				base: baseRef ?? null
-			}
+		await runGenerate(featureName, specName, {
+			maxRetries: parseInt(opts.maxRetries ?? "3", 10),
+			fixMode: toFixMode(opts.autoFix ?? "interactive"),
+			force: opts.force ?? false,
+			useSnapshot: opts.snapshot !== false,
+			language,
+			model: opts.model,
+			targetOverride: opts.target,
+			cwd,
+			hubContext
 		});
-		const dir = await mkdtemp(join(tmpdir(), "ccqa-drift-push-"));
-		try {
-			await writeFile(join(dir, "report.json"), JSON.stringify(report, null, 2), "utf8");
-			const archive = await packDirToTarGz(dir);
-			const run = await hub.pushRun(archive, {
-				project,
-				...branch ? { branch } : {},
-				kind: "drift"
-			});
-			if (format === "text") info(`pushed drift result to hub: ${(opts.hubUrl ?? process.env.CCQA_HUB_URL ?? "").replace(/\/+$/, "")}/#/runs/${run.id}`);
-		} finally {
-			await rm(dir, {
-				recursive: true,
-				force: true
-			});
-		}
-	} catch (err) {
-		if (err instanceof HubApiError) {
-			error(`hub request failed (${err.status} ${err.code}): ${err.message}`);
+	} catch (e) {
+		if (e instanceof SpecLockedError) {
+			error(e.message);
 			process.exit(2);
 		}
-		throw err;
+		throw e;
 	}
-}
-function exitWithNoSpecs(format, message) {
-	if (format === "json") process.stdout.write(`${JSON.stringify({ specs: [] }, null, 2)}\n`);
-	else if (format === "text") info(message);
-	process.exit(0);
-}
-async function filterByChanged(input) {
-	const { targets, cwd, baseOverride, format, model } = input;
-	const base = resolveBaseRef(baseOverride);
-	let changed;
-	try {
-		changed = await getChangedFiles(base, cwd);
-	} catch (e) {
-		error(`failed to run 'git diff' against ${base}: ${e.message}`);
+	await syncSpecPerspectives(hubContext, {
+		ref: {
+			featureName,
+			specName
+		},
+		...language ? { language } : {},
+		...opts.model ? { model: opts.model } : {}
+	});
+});
+//#endregion
+//#region src/cli/record.ts
+const VALIDATION_MODES = ["lenient", "strict"];
+const recordCommand = addHubOptions(addProfileOption(addLanguageOption(new Command("record").argument("<feature/spec>", "Spec id in '<feature>/<spec>' form (resolves to .ccqa/features/<feature>/test-cases/<spec>/)").description("Record a deterministic test from a spec: run agent-browser to collect actions (trace), then generate test.spec.ts with auto-fix retries (generate). After recording, `ccqa run <feature/spec>` replays it under vitest (deterministic specs only — live specs do not need recording).").option("-m, --model <name>", "Claude model alias ('sonnet'|'opus'|'haiku') or full ID. Overrides CCQA_MODEL.").option("--validation-mode <mode>", "Post-trace validation behaviour: 'lenient' (default) tags failing actions; 'strict' drops them.", (raw) => {
+	if (VALIDATION_MODES.includes(raw)) return raw;
+	throw new Error(`--validation-mode must be one of ${VALIDATION_MODES.join(" | ")}`);
+}, "lenient").option("--auto-fix <mode>", "Auto-fix behaviour during script generation: 'interactive' (default, prompt y/N), 'auto' (apply without prompt, for CI), 'skip' (never prompt, only apply high-confidence fixes).", parseAutoFixFlag, "interactive").option("--max-retries <n>", "Maximum number of auto-fix retries", "3").option("--force", "Overwrite an existing test.spec.ts without warning").option("--no-snapshot", "Don't pin AGENT_BROWSER_SESSION / capture page snapshots after a failure (debug toggle)").option("--skip-trace", "Skip the trace step and run codegen against an existing ir.json").option("--skip-codegen", "Run only the trace step (do not generate test.spec.ts)").option("--update-agent-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.").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(async (specPath, opts) => {
+	const { featureName, specName } = parseSpecPath(specPath);
+	const language = opts.language ?? "auto";
+	if (opts.skipTrace && opts.skipCodegen) {
+		error("--skip-trace and --skip-codegen cannot be combined; nothing would run");
 		process.exit(2);
 	}
-	if (format === "text") {
-		meta("changed-base", base);
-		meta("changed-files", changed.length);
+	const cwdForProfile = resolveCwd(opts.cwd);
+	const target = resolveTarget(parseTestSpec(await readSpecFile(featureName, specName, cwdForProfile)), await loadProjectConfig(cwdForProfile));
+	if (target.input === "spec") {
+		error(`target "${target.id}" does not use a browser recording — run 'ccqa generate ${featureName}/${specName}' instead`);
+		process.exit(2);
 	}
-	if (changed.length === 0) return [];
-	const newFiles = changed.filter((f) => f.status === "added" && !f.outsideCwd);
-	const existingChanges = changed.filter((f) => f.status !== "added" || f.outsideCwd);
-	const affected = /* @__PURE__ */ new Set();
-	const touchedBlockNames = /* @__PURE__ */ new Set();
-	for (const f of changed) {
-		if (f.outsideCwd) continue;
-		const blockName = parseBlockPath(f.path);
-		if (blockName) touchedBlockNames.add(blockName);
-	}
-	for (const t of targets) {
-		if (!t.relatedPaths) {
-			affected.add(specKey(t));
-			continue;
+	const project = opts.profile !== void 0 ? resolveProject(opts) : void 0;
+	if (opts.profile !== void 0) await applyProfileFromOption({
+		profile: opts.profile,
+		project,
+		cwd: cwdForProfile,
+		hubUrl: opts.hubUrl,
+		hubToken: opts.hubToken,
+		hubHeader: opts.hubHeader
+	});
+	else await applyProfileFromOption({
+		profile: void 0,
+		project: "",
+		cwd: cwdForProfile
+	});
+	const hubClientForTrace = resolveHubClient({
+		hubUrl: opts.hubUrl,
+		hubToken: opts.hubToken,
+		hubHeader: opts.hubHeader
+	});
+	const hubProject = project ?? (hubClientForTrace !== null ? resolveProject(opts) : void 0);
+	const hubContext = hubClientForTrace && hubProject ? {
+		hub: hubClientForTrace,
+		project: hubProject
+	} : null;
+	const releaseLock = await acquireSpecLock(featureName, specName, "record", cwdForProfile).catch((e) => {
+		if (e instanceof SpecLockedError) {
+			error(e.message);
+			process.exit(2);
 		}
-		if (existingChanges.some((f) => isPathAffectedBy(f.path, t.relatedPaths)) || newFiles.some((f) => isPathAffectedBy(f.path, t.relatedPaths))) {
-			affected.add(specKey(t));
-			continue;
+		throw e;
+	});
+	let traceResult = null;
+	try {
+		if (!opts.skipTrace) {
+			traceResult = await runTrace(featureName, specName, opts.model, opts.validationMode ?? "lenient", language, {
+				cwd: cwdForProfile,
+				hubContext
+			});
+			blank();
 		}
-		if (t.includedBlocks?.some((name) => touchedBlockNames.has(name))) affected.add(specKey(t));
+		if (!opts.skipCodegen) await runGenerate(featureName, specName, {
+			maxRetries: parseInt(opts.maxRetries ?? "3", 10),
+			fixMode: toFixMode(opts.autoFix ?? "interactive"),
+			force: opts.force ?? false,
+			useSnapshot: opts.snapshot !== false,
+			language,
+			model: opts.model,
+			cwd: cwdForProfile,
+			hubContext
+		});
+	} finally {
+		await releaseLock();
 	}
-	if (newFiles.length > 0) {
-		if (format === "text") info(`routing ${newFiles.length} new file(s) to specs via Claude...`);
-		const routed = await routeNewFilesToSpecs({
-			newFiles: newFiles.map((f) => f.path),
-			specs: targets.filter((t) => t.relatedPaths).map((t) => ({
-				featureName: t.featureName,
-				specName: t.specName,
-				relatedPaths: t.relatedPaths
-			})),
-			cwd,
-			model
+	if (opts.updateAgentPrompt) if (traceResult === null) warn("--update-agent-prompt is ignored when --skip-trace is set (no run summary available)");
+	else {
+		blank();
+		await updateAgentPrompt({
+			mode: "record",
+			runSummary: buildRecordRunSummary(featureName, specName, traceResult),
+			hubContext,
+			...opts.model ? { model: opts.model } : {},
+			...language ? { language } : {}
 		});
-		for (const key of routed) affected.add(key);
 	}
-	return targets.filter((t) => affected.has(specKey(t)));
+	await syncSpecPerspectives(hubContext, {
+		ref: {
+			featureName,
+			specName
+		},
+		...language ? { language } : {},
+		...opts.model ? { model: opts.model } : {}
+	});
+});
+/**
+* Compact summary of the trace pass for the record agent-prompt refresh.
+* Steps are reconstructed from the trace's status-line protocol (STEP_START
+* gives the title, STEP_DONE / ASSERTION_FAILED / STEP_SKIPPED the outcome),
+* and each step carries its per-action observations plus the **concrete kept
+* commands** — the selectors that actually survived scrub / dedup /
+* validation. The record playbook is told to record canonical selectors, so
+* it needs those exact tokens; the prose alone doesn't carry them. The
+* header's kept/recorded totals flag how much the run thrashed through
+* selectors overall.
+*/
+function buildRecordRunSummary(featureName, specName, t) {
+	const header = `## ${featureName}/${specName} — ${t.status}\nActions: ${t.actionsKept} kept / ${t.actionsRecorded} recorded`;
+	const steps = collectStepSummaries(t.statusLines);
+	if (steps.length === 0) return `${header}\n\n(no step status lines recorded)`;
+	const commandsByStep = groupCommandsByStep(t.actions);
+	const observationsByStep = groupObservationsByStep(t.actions);
+	const unstableByStep = countUnstableByStep(t.actions);
+	return `${header}\n\n${steps.map((s) => {
+		const cmds = commandsByStep.get(s.stepId) ?? [];
+		const observations = observationsByStep.get(s.stepId) ?? [];
+		const churn = t.churnByStep.get(s.stepId);
+		const dropped = churn ? churn.recorded - churn.kept : 0;
+		const redundant = churn?.redundant ?? 0;
+		const unstable = unstableByStep.get(s.stepId) ?? 0;
+		return [
+			`### ${s.stepId} — ${oneLineSummary(s.title)} (${s.status})`,
+			...s.detail ? [`- result: ${oneLineSummary(s.detail)}`] : [],
+			...observations.length > 0 ? [`- observations: ${observations.map(oneLineSummary).join(" ; ")}`] : [],
+			...dropped > 0 ? [`- churn: ${churn.recorded} attempts → ${churn.kept} kept (${dropped} dropped)`] : [],
+			...redundant > 0 ? [`- redundant: ${redundant} field(s) entered via 2+ selectors (kept both — record one canonical selector)`] : [],
+			...unstable > 0 ? [`- replay-unstable: ${unstable} kept command(s) marked [unstable] — do NOT record these as canonical; prefer a more stable locator even if it costs one more probe`] : [],
+			...cmds.length > 0 ? [`- kept commands: ${cmds.join(" ; ")}`] : []
+		].join("\n");
+	}).join("\n\n")}`;
 }
-async function collectTargets(specPath, cwd) {
-	const tree = await listFeatureTree(cwd);
-	if (specPath) {
-		const { featureName, specName } = parseSpecPath(specPath);
-		const spec = tree.find((f) => f.featureName === featureName)?.specs.find((s) => s.specName === specName);
-		if (!spec?.hasSpecFile) {
-			error(`spec not found: ${featureName}/${specName} (under ${cwd})`);
-			process.exit(1);
+/**
+* Fold the ordered status lines into one entry per step: STEP_START opens
+* the entry (its detail is the step title); the terminal line sets the
+* outcome. A terminal line for a step that never emitted STEP_START still
+* gets an entry so its outcome isn't silently lost.
+*/
+function collectStepSummaries(lines) {
+	const byId = /* @__PURE__ */ new Map();
+	const ordered = [];
+	const ensure = (stepId, title) => {
+		let entry = byId.get(stepId);
+		if (!entry) {
+			entry = {
+				stepId,
+				title,
+				status: "NO_STATUS"
+			};
+			byId.set(stepId, entry);
+			ordered.push(entry);
 		}
-		return [{
-			featureName,
-			specName,
-			includedBlocks: spec.includedBlocks ?? []
-		}];
-	}
-	const out = [];
-	for (const feature of tree) for (const spec of feature.specs) {
-		if (!spec.hasSpecFile) continue;
-		const t = {
-			featureName: feature.featureName,
-			specName: spec.specName
-		};
-		if (spec.relatedPaths) t.relatedPaths = spec.relatedPaths;
-		if (spec.includedBlocks) t.includedBlocks = spec.includedBlocks;
-		out.push(t);
+		return entry;
+	};
+	for (const line of lines) {
+		if (!line.stepId || line.type === "RUN_COMPLETED") continue;
+		if (line.type === "STEP_START") {
+			ensure(line.stepId, line.detail);
+			continue;
+		}
+		const entry = ensure(line.stepId, "(untitled)");
+		entry.status = line.type === "STEP_DONE" ? "DONE" : line.type === "ASSERTION_FAILED" ? "FAILED" : "SKIPPED";
+		if (line.detail) entry.detail = line.detail;
 	}
-	return out;
+	return ordered;
 }
-function parseFormat(raw) {
-	const v = raw ?? "text";
-	if (v === "text" || v === "json" || v === "github") return v;
-	error(`invalid --format: ${v} (expected text|json|github)`);
-	process.exit(2);
+/** Group each kept action's `action selector` form under its stepId. */
+function groupCommandsByStep(actions) {
+	const byStep = /* @__PURE__ */ new Map();
+	for (const a of actions) {
+		if (!a.stepId) continue;
+		const list = byStep.get(a.stepId) ?? [];
+		list.push(formatRecordedAction(a));
+		byStep.set(a.stepId, list);
+	}
+	return byStep;
 }
-function parseSeverity(raw) {
-	const v = raw ?? "error";
-	if (v === "warn" || v === "error") return v;
-	error(`invalid --severity: ${v} (expected warn|error)`);
-	process.exit(2);
+/**
+* Group per-action observations (snapshot / assert prose) under their stepId
+* — the trace's own record of what it verified at each step.
+*/
+function groupObservationsByStep(actions) {
+	const byStep = /* @__PURE__ */ new Map();
+	for (const a of actions) {
+		if (!a.stepId || !a.observation) continue;
+		const list = byStep.get(a.stepId) ?? [];
+		list.push(a.observation);
+		byStep.set(a.stepId, list);
+	}
+	return byStep;
 }
-function parseConcurrency(raw) {
-	if (raw === void 0) return DEFAULT_CONCURRENCY;
-	const n = Number.parseInt(raw, 10);
-	if (!Number.isFinite(n) || n < 1) {
-		error(`invalid --concurrency: ${raw} (expected positive integer)`);
-		process.exit(2);
+/** Per-step count of kept-but-replay-unstable actions (the flaky selectors). */
+function countUnstableByStep(actions) {
+	const byStep = /* @__PURE__ */ new Map();
+	for (const a of actions) {
+		if (!a.stepId || !a.replayUnstable) continue;
+		byStep.set(a.stepId, (byStep.get(a.stepId) ?? 0) + 1);
 	}
-	return n;
+	return byStep;
+}
+/**
+* One kept action as `action selector` (with the fill value or assert
+* type when present) — the canonical form the record playbook should reuse.
+* Unlike the live summary this keeps selectors verbatim: record learns
+* concrete per-spec selectors, so masking them would defeat the purpose.
+*
+* A replay-unstable action (kept in lenient mode but flagged because its
+* selector wasn't present on a fresh replay) is tagged `[unstable](<reason>)`
+* so the learner does NOT record its selector as canonical — the reason is the
+* teacher signal ("not present within Nms" = timing-fragile, not stable).
+*/
+function formatRecordedAction(a) {
+	const parts = [a.action];
+	if (a.index !== void 0) parts.push(String(a.index));
+	const anchor = a.locator ? formatLocator(a.locator) : a.label;
+	if (anchor) parts.push(anchor);
+	if (a.value) parts.push(`= ${a.value}`);
+	if (a.assert) parts.push(`(${a.assert})`);
+	const line = oneLineSummary(parts.join(" "));
+	return a.replayUnstable ? `${line} [unstable](${oneLineSummary(a.replayReason ?? "no reason")})` : line;
+}
+/** Verbatim locator form: raw selector for css, `by=value` for semantic ones. */
+function formatLocator(locator) {
+	const name = locator.by === "role" && locator.name ? ` name=${locator.name}` : "";
+	return locator.by === "css" ? locator.value : `${locator.by}=${locator.value}${name}`;
+}
+function oneLineSummary(s) {
+	const flat = s.replace(/\s+/g, " ").trim();
+	return flat.length > 240 ? flat.slice(0, 240) + "…" : flat || "(none)";
 }
 //#endregion
-//#region src/cli/init.ts
-const initCommand = new Command("init").description("Create the .ccqa/ spec skeleton (features/, blocks/) in the current directory.").option("--cwd <path>", "Working directory (default: cwd)").action(async (opts) => {
-	const cwd = resolveCwd(opts.cwd);
-	header("init", cwd);
-	await ensureCcqaDir(cwd);
-	info("created  .ccqa/features/, .ccqa/blocks/");
-	blank();
-	hint("set CCQA_HUB_URL / CCQA_HUB_TOKEN to connect to a ccqa hub");
-	hint("edit guidance prompts in the hub UI's Prompts tab");
-	hint("run `ccqa record <feature>/<spec>` to start recording");
-});
-//#endregion
-//#region src/prompts/perspectives.ts
+//#region src/drift/format.ts
 /**
-* Build the system prompt. By default the descriptive fields follow the
-* spec's own language (Japanese specs → Japanese fields). An explicit
-* `--language` is applied by the CLI via `languageDirective`, appended to
-* this prompt, so the language handling lives in one shared place.
+* Render drift results as a string. The CLI commands and the `run` failure
+* hook are the only callers; both want the formatted output returned so
+* they can prefix / interleave / pipe it as needed.
 */
-function buildPerspectivesSystemPrompt() {
-	return `You produce a factual inventory of the E2E test coverage that already exists in a ccqa project.
-
-Think of it as a QA coverage stock-take: for each existing test case, fill in a few short, neutral descriptive fields derived from its steps. Nothing more.
-
-## Hard boundaries (do NOT cross)
-
-- Do NOT assign severity, importance, priority, or risk. Whether a failure hurts the customer is a human + PdM decision; you are not authoring that here.
-- Do NOT do gap analysis. Do NOT list untested areas, missing coverage, or things the code has but the tests lack.
-- Do NOT evaluate whether the feature is good, complete, or correct.
-- Do NOT propose new test cases.
-- Do NOT restate the full step-by-step procedure or the per-step expected results — the spec.yaml is the source of truth for those and the inventory links to it.
-- Do NOT touch status, relatedPaths, feature names, or spec names — the CLI already fixed those.
-
-## Fields to write (per spec)
-
-- \`summary\`: 1–2 sentences, factual and neutral. What the test exercises and what it ultimately asserts, derived from the spec's \`steps\` (\`instruction\` / \`expected\`).
-- \`startScreen\`: the screen/URL the test first lands on after setup (e.g. "Dashboard (/dashboard)"). Derive from the first non-login \`instruction\`. Omit if genuinely unclear.
-- \`testCondition\`: the state/precondition the scenario assumes, phrased as a condition (e.g. "Logged in as an admin", "Unauthenticated user"). Omit if none.
-- \`preconditions\`: array of short setup prerequisites (e.g. which role logs in, required prior state). Derive from \`include: login\` params and the opening steps. Empty/omit if none.
-
-## How to write
-
-- Same language as the spec's title (if titles are Japanese, write these fields in Japanese).
-- Keep each field short. These are index entries, not the test itself.
-- You may use Read/Grep/Glob sparingly to clarify domain vocabulary, but the steps are the primary source. Do not over-explore.
-
-## Output contract (STRICT)
-
-Output exactly ONE fenced \`\`\`json code block, and nothing else outside it. No prose before or after.
-
-Schema:
-
-\`\`\`json
-{
-  "summaries": [
-    {
-      "featureName": "<verbatim from input>",
-      "specName": "<verbatim from input>",
-      "summary": "<1–2 sentence factual description of what this test verifies>",
-      "startScreen": "<opening screen/URL, or omit>",
-      "testCondition": "<assumed state phrased as a condition, or omit>",
-      "preconditions": ["<setup prerequisite>", "..."]
-    }
-  ]
+function renderDrift(results, format, cwd) {
+	if (format === "json") return renderJson(results);
+	if (format === "github") return renderGithub(results, cwd);
+	return renderText(results);
+}
+const HEAVY_RULE = "═".repeat(72);
+function renderText(results) {
+	const out = [];
+	for (const r of results) {
+		out.push("");
+		const heading = `══ ${r.target.featureName}/${r.target.specName} `;
+		const tail = "═".repeat(Math.max(3, 72 - heading.length));
+		out.push(`${heading}${tail}`);
+		if (r.error) {
+			out.push(`  ERROR  ${r.error}`);
+			continue;
+		}
+		const errors = r.issues.filter((i) => i.severity === "ERROR");
+		const warnings = r.issues.filter((i) => i.severity === "WARN");
+		const passed = r.issues.filter((i) => i.severity === "OK");
+		if (errors.length === 0 && warnings.length === 0) {
+			const label = passed.length === 1 ? "check" : "checks";
+			const detail = passed.length > 0 ? `all ${passed.length} ${label} passed` : "no issues";
+			out.push(`  ✓  ${detail}`);
+			continue;
+		}
+		for (const issue of errors) appendFinding(out, "ERROR", issue);
+		for (const issue of warnings) appendFinding(out, "WARN", issue);
+		if (passed.length > 0) {
+			const names = passed.map((i) => DRAFT_CATEGORY_LABEL[i.category]).join(", ");
+			out.push("");
+			out.push(`  ✓  passed (${passed.length}): ${names}`);
+		}
+	}
+	out.push("");
+	out.push(HEAVY_RULE);
+	const totals = summarize(results);
+	out.push(`  specs    ${results.length} (${totals.errored} errored)`);
+	out.push(`  findings ${totals.error} error, ${totals.warn} warn, ${totals.ok} ok`);
+	out.push("");
+	return out.join("\n");
+}
+function appendFinding(out, level, issue) {
+	const stepPart = issue.stepId ? ` ${issue.stepId}` : "";
+	out.push("");
+	out.push(`  ${level}  ${DRAFT_CATEGORY_LABEL[issue.category]}${stepPart}`);
+	out.push(`    ${issue.message}`);
+	if (issue.detail) out.push(`    └ ${issue.detail.replace(/\n/g, "\n      ")}`);
+}
+function renderJson(results) {
+	const payload = { specs: results.map((r) => ({
+		feature: r.target.featureName,
+		spec: r.target.specName,
+		ok: r.ok,
+		...r.error ? { error: r.error } : {},
+		issues: r.issues.map((i) => ({
+			severity: i.severity,
+			category: i.category,
+			stepId: i.stepId,
+			message: i.message,
+			...i.detail ? { detail: i.detail } : {}
+		}))
+	})) };
+	return `${JSON.stringify(payload, null, 2)}\n`;
+}
+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);
+		if (r.error) {
+			lines.push(`::error file=${file}::${escapeGhMessage(r.error)}`);
+			continue;
+		}
+		for (const issue of r.issues) {
+			if (issue.severity === "OK") continue;
+			const level = issue.severity === "ERROR" ? "error" : "warning";
+			const title = `${r.target.featureName}/${r.target.specName} — ${issue.category}${issue.stepId ? ` (${issue.stepId})` : ""}`;
+			const body = issue.detail ? `${issue.message}\n${issue.detail}` : issue.message;
+			lines.push(`::${level} file=${file},title=${escapeGhProp(title)}::${escapeGhMessage(body)}`);
+		}
+	}
+	return lines.length === 0 ? "" : `${lines.join("\n")}\n`;
 }
-\`\`\`
-
-Return one entry per spec given in the input. Echo featureName and specName verbatim so the CLI can match them. \`startScreen\`, \`testCondition\`, and \`preconditions\` are optional — omit a field (or use an empty array for preconditions) when the spec does not express it.
-`;
+function githubRelPath(cwd, repoRoot, featureName, specName) {
+	const abs = resolve(cwd, ".ccqa", "features", featureName, "test-cases", specName, "spec.yaml");
+	const rel = relative(repoRoot, abs);
+	return rel.startsWith("..") ? abs : rel;
 }
-function buildPerspectivesPrompt(specs, instruction) {
-	return `## Existing test cases to summarise
-
-${specs.map((s) => `### ${s.featureName}/${s.specName}
-title: ${s.title}
-
-\`\`\`yaml
-${s.specYaml.trimEnd()}
-\`\`\`
-`).join("\n")}
-${instruction?.trim() ? `## Extra guidance from the user\n\n${instruction.trim()}\n\n` : ""}## Task
-
-For each test case above, write a 1–2 sentence factual \`summary\` of what it verifies, derived from its steps. Return one entry per spec in the JSON contract. Do not assign severity, do gap analysis, or invent new cases.
-`;
+function escapeGhMessage(s) {
+	return s.replace(/%/g, "%25").replace(/\r/g, "%0D").replace(/\n/g, "%0A");
 }
-//#endregion
-//#region src/cli/perspectives.ts
-const perspectivesCommand = addLanguageOption(new Command("perspectives").description("Generate/update .ccqa/perspectives.yaml — a factual inventory of existing test coverage (no severity, no gap analysis)").option("--instruction <text>", "Hint to steer how summaries are written").option("--apply", "Auto-apply without [y/N] confirmation", false).option("-m, --model <name>", "Claude model alias ('sonnet'|'opus'|'haiku') or full ID")).action(async (opts) => {
-	await runPerspectives(opts);
-});
-async function runPerspectives(opts) {
-	header("perspectives", ".ccqa/perspectives.yaml");
-	await ensureCcqaDir();
-	const skeleton = await buildSkeleton(await listFeatureTree());
-	const allSpecs = skeleton.flatMap((f) => f.specs);
-	if (allSpecs.length === 0) {
-		info("no test cases found under .ccqa/features — nothing to inventory.");
-		return;
-	}
-	const existingRaw = await tryReadPerspectives() ?? "";
-	const noteMap = extractNotes(existingRaw);
-	const specBodies = await loadSpecBodies(skeleton);
-	meta("language", opts.language ?? "auto");
-	info(`Summarising ${allSpecs.length} test case(s) across ${skeleton.length} feature(s)...`);
-	const summaries = await requestSummaries(specBodies, opts);
-	if (summaries === null) process.exit(1);
-	const merged = mergePerspectives(skeleton, summaries, noteMap);
-	let validated;
-	try {
-		validated = PerspectivesSchema.parse(merged);
-	} catch (e) {
-		error(`refused to write: assembled perspectives failed validation (${e.message})`);
-		process.exit(1);
-	}
-	const next = stringify(validated, { lineWidth: 0 });
-	if (withoutGeneratedAt(existingRaw) === withoutGeneratedAt(next)) {
-		blank();
-		info("perspectives already up to date — no changes.");
-		return;
-	}
-	blank();
-	info("--- proposed changes (perspectives.yaml) ---");
-	printUnifiedDiff(existingRaw, next);
-	blank();
-	if (!(opts.apply === true || /^y/i.test(await prompt(useJapanesePrompts(opts.language) ? "perspectives.yaml + .md を書き込みますか? [y/N] " : "Write perspectives.yaml + .md? [y/N] ")))) {
-		info("aborted — no changes written.");
-		return;
+function escapeGhProp(s) {
+	return s.replace(/%/g, "%25").replace(/\r/g, "%0D").replace(/\n/g, "%0A").replace(/,/g, "%2C").replace(/:/g, "%3A");
+}
+function summarize(results) {
+	let error = 0;
+	let warn = 0;
+	let ok = 0;
+	let errored = 0;
+	for (const r of results) {
+		if (r.error) errored++;
+		for (const issue of r.issues) if (issue.severity === "ERROR") error++;
+		else if (issue.severity === "WARN") warn++;
+		else ok++;
 	}
-	meta("saved", await savePerspectives(next));
-	const labels = labelsFor(opts.language);
-	meta("saved", await savePerspectivesMarkdown(renderIndexMarkdown(validated, labels)));
-	for (const feature of validated.features) meta("saved", await saveFeaturePerspectivesMarkdown(feature.featureName, renderFeatureMarkdown(feature, labels)));
+	return {
+		error,
+		warn,
+		ok,
+		errored
+	};
 }
+//#endregion
+//#region src/drift/exit-code.ts
 /**
-* Turn the feature tree into the skeleton perspectives features: title +
-* relatedPaths 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.
+* Map drift results to an exit code. Spec-level errors (Claude call failed)
+* always fail; otherwise ERROR severity always fails, WARN fails only when
+* the threshold is `warn`.
 */
-async function buildSkeleton(tree) {
-	return (await Promise.all(tree.map(async (feature) => {
-		const specs = await Promise.all(feature.specs.filter((s) => s.hasSpecFile).map(async (s) => {
-			const spec = await readSpecMeta(feature.featureName, s.specName);
-			const status = await deriveStatus(feature.featureName, s.specName, spec.mode);
-			const entry = {
-				specName: s.specName,
-				title: spec.title,
-				summary: "",
-				status
-			};
-			if (s.relatedPaths) entry.relatedPaths = s.relatedPaths;
-			return entry;
-		}));
-		return {
-			featureName: feature.featureName,
-			specs
-		};
-	}))).filter((f) => f.specs.length > 0).map((f) => ({
-		featureName: f.featureName,
-		specs: [...f.specs].sort((a, b) => a.specName.localeCompare(b.specName))
-	})).sort((a, b) => a.featureName.localeCompare(b.featureName));
+function determineExitCode(results, threshold) {
+	for (const r of results) {
+		if (r.error) return 1;
+		for (const issue of r.issues) {
+			if (issue.severity === "ERROR") return 1;
+			if (threshold === "warn" && issue.severity === "WARN") return 1;
+		}
+	}
+	return 0;
 }
 /**
-* `(featureName, specName)` → human note, parsed from an existing
-* perspectives.yaml. Notes are preserved across regeneration; everything
-* else (title, status, summary) is recomputed. Returns an empty map when the
-* input is empty or unparsable — note preservation is best-effort and never
-* blocks regeneration.
+* Spec-level status under the given threshold, mirroring determineExitCode's
+* per-issue logic (exit-code.ts) but scoped to a single SpecResult.
 */
-function extractNotes(existingRaw) {
-	const map = /* @__PURE__ */ new Map();
-	if (!existingRaw.trim()) return map;
-	let parsed;
-	try {
-		parsed = parse(existingRaw);
-	} catch {
-		return map;
+function specStatus(result, threshold) {
+	if (result.error) return "failed";
+	for (const issue of result.issues) {
+		if (issue.severity === "ERROR") return "failed";
+		if (threshold === "warn" && issue.severity === "WARN") return "failed";
 	}
-	const result = PerspectivesSchema.safeParse(parsed);
-	if (!result.success) return map;
-	for (const feature of result.data.features) for (const spec of feature.specs) if (spec.note !== void 0 && spec.note !== "") map.set(noteKey(feature.featureName, spec.specName), spec.note);
-	return map;
+	return "passed";
 }
 /**
-* Merge the mechanical skeleton with Claude's summaries and the preserved
-* notes into the final perspectives object. Summaries are matched by
-* (featureName, specName); an unmatched spec keeps its empty summary.
+* Adapts `ccqa drift` results into the shared RunReportData shape so they can
+* be pushed to the hub (`ccqa drift --push`) and rendered by the same report
+* UI as `ccqa run`/`ccqa live`. Browser-execution fields (testCounts,
+* evidence, liveRun, ...) don't apply to a drift audit and are always null.
 */
-function mergePerspectives(skeleton, summaries, noteMap) {
-	const summaryMap = /* @__PURE__ */ new Map();
-	for (const s of summaries) summaryMap.set(noteKey(s.featureName, s.specName), s);
-	const features = skeleton.map((feature) => ({
-		featureName: feature.featureName,
-		specs: feature.specs.map((spec) => {
-			const key = noteKey(feature.featureName, spec.specName);
-			const entry = summaryMap.get(key);
-			const merged = {
-				...spec,
-				summary: entry?.summary ?? spec.summary
-			};
-			if (entry?.startScreen) merged.startScreen = entry.startScreen;
-			if (entry?.testCondition) merged.testCondition = entry.testCondition;
-			if (entry?.preconditions && entry.preconditions.length > 0) merged.preconditions = entry.preconditions;
-			const note = noteMap.get(key);
-			if (note !== void 0) merged.note = note;
-			return merged;
-		})
+function driftResultsToReport(results, meta) {
+	const specResults = results.map((result) => ({
+		feature: result.target.featureName,
+		spec: result.target.specName,
+		title: null,
+		status: specStatus(result, meta.threshold),
+		testCounts: null,
+		durationMs: null,
+		assertions: null,
+		analysis: null,
+		analysisSkipped: null,
+		driftIssues: result.issues,
+		failureLogExcerpt: null,
+		diffExcerpt: null,
+		specYaml: null,
+		evidence: null,
+		liveRun: null
 	}));
 	return {
-		generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
-		features
+		schemaVersion: 1,
+		kind: "drift",
+		createdAt: meta.createdAt ?? (/* @__PURE__ */ new Date()).toISOString(),
+		runId: meta.runId ?? null,
+		git: meta.git,
+		model: meta.model ?? null,
+		language: meta.language ?? null,
+		promptVersion: meta.promptVersion ?? "1",
+		customPromptVersion: null,
+		results: specResults
 	};
 }
+//#endregion
+//#region src/drift/route-new-files.ts
 /**
-* Strip the top-level `generatedAt:` line so two serialised perspectives can
-* be compared for substantive equality without the always-fresh timestamp
-* defeating the "already up to date" check. Exported for unit testing.
+* Lightweight Claude call: given a list of new files in the PR and the existing
+* specs (with their relatedPaths globs as a hint), return the spec keys (in
+* "<feature>/<spec>" form) that the new files plausibly affect.
+*
+* Conservative by design — false positives are safer than false negatives,
+* because a missed spec turns into undetected drift in CI. When the router
+* call itself fails, we log a warning rather than fail-close: the surrounding
+* glob match is the primary signal; the router only adds coverage for new
+* paths no glob captures.
 */
-function withoutGeneratedAt(yamlText) {
-	return yamlText.split("\n").filter((line) => !/^generatedAt:/.test(line)).join("\n").trim();
-}
-function noteKey(featureName, specName) {
-	return `${featureName}/${specName}`;
-}
-async function readSpecMeta(featureName, specName) {
-	const raw = await tryReadSpecFile(featureName, specName);
-	if (raw === null) return {
-		title: specName,
-		mode: DEFAULT_SPEC_MODE
-	};
-	try {
-		const parsed = parse(raw);
-		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
-		};
-	} catch {
-		return {
-			title: specName,
-			mode: DEFAULT_SPEC_MODE
-		};
-	}
-}
-async function deriveStatus(featureName, specName, mode) {
-	return {
-		mode,
-		traced: await stat(join(getSpecDir(featureName, specName), "ir.json")).then(() => true).catch(() => false),
-		generated: await getTestScript(featureName, specName) !== null
-	};
-}
-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
-		};
-	})));
-}
-async function requestSummaries(specs, opts) {
-	const toolCounts = {};
-	const startedAt = Date.now();
+async function routeNewFilesToSpecs(input) {
+	const { newFiles, specs, cwd, model } = input;
+	const empty = /* @__PURE__ */ new Set();
+	if (newFiles.length === 0 || specs.length === 0) return empty;
 	const { result, isError } = await invokeClaudeStreaming({
-		prompt: buildPerspectivesPrompt(specs, opts.instruction),
-		systemPrompt: buildPerspectivesSystemPrompt() + languageDirective(opts.language),
+		prompt: buildRouterPrompt(await Promise.all(newFiles.map(async (path) => ({
+			path,
+			head: await readHead(join(cwd, path))
+		}))), specs),
+		systemPrompt: buildRouterSystemPrompt(),
 		allowedTools: [
 			"Read",
 			"Grep",
 			"Glob"
 		],
 		silenceBashLog: true,
-		...opts.model ? { model: opts.model } : {}
-	}, (msg) => {
-		if (msg.type !== "assistant") return;
-		for (const block of msg.message.content ?? []) if (block.type === "tool_use") toolCounts[block.name] = (toolCounts[block.name] ?? 0) + 1;
-	});
-	process.stdout.write(`${formatToolSummary(toolCounts, Date.now() - startedAt)}\n`);
+		cwd,
+		...model ? { model } : {}
+	}, (_msg) => {});
 	if (isError) {
-		error("Claude returned an error result");
-		return null;
+		warn("new-file router: Claude returned an error; skipping router signal");
+		return empty;
 	}
 	const json = extractJsonBlock(result);
 	if (!json) {
-		error("Claude did not return a json block");
-		return null;
+		warn("new-file router: no JSON block in response; skipping router signal");
+		return empty;
 	}
-	return parseSummaries(json);
+	let parsed;
+	try {
+		parsed = JSON.parse(json);
+	} catch (e) {
+		warn(`new-file router: failed to parse JSON (${e.message}); skipping router signal`);
+		return empty;
+	}
+	const out = /* @__PURE__ */ new Set();
+	const validKeys = new Set(specs.map((s) => `${s.featureName}/${s.specName}`));
+	if (typeof parsed === "object" && parsed !== null && "affectedSpecs" in parsed) {
+		const arr = parsed.affectedSpecs;
+		if (Array.isArray(arr)) {
+			for (const item of arr) if (typeof item === "string" && validKeys.has(item)) out.add(item);
+		}
+	}
+	return out;
+}
+async function readHead(absPath) {
+	const content = await readFile(absPath, "utf-8").catch(() => "");
+	if (!content) return "";
+	return content.split("\n").slice(0, 40).join("\n");
+}
+function buildRouterSystemPrompt() {
+	return `You triage which ccqa test specs are potentially affected by NEW source files added in a pull request.
+
+You will receive:
+- A list of new files (path + first ~40 lines of each)
+- A list of existing specs with their declared relatedPaths globs
+
+Your job: return the spec keys (in "<feature>/<spec>" form) whose behaviour might depend on any of the new files.
+
+## Rules
+
+- Be **conservative**: when in doubt, include the spec. A spurious inclusion costs one extra drift check; a missed spec lets real drift slip through CI.
+- Use \`Read\`, \`Grep\`, \`Glob\` if you need to inspect the spec body or related code, but stay focused — this is a triage step, not a full review.
+- Ignore specs whose relatedPaths clearly point to a different area than every new file (e.g. \`src/auth/**\` specs vs new files only under \`src/billing/**\`).
+- Files like tests, generated code, build artifacts, vendor dirs typically do not affect any spec. Skip them.
+
+## Output (STRICT)
+
+Output ONE fenced \`\`\`json block, nothing else:
+
+\`\`\`json
+{
+  "affectedSpecs": ["feature/spec", "feature/spec"]
+}
+\`\`\`
+
+Use exactly the keys you saw in the input ("<feature>/<spec>"). Return an empty array if no spec is affected.
+`;
+}
+function buildRouterPrompt(previews, specs) {
+	return `## New files
+
+${previews.map((p) => {
+		const headBlock = p.head ? `\n\`\`\`\n${p.head}\n\`\`\`` : "\n(empty or unreadable)";
+		return `### ${p.path}${headBlock}`;
+	}).join("\n\n")}
+
+## Existing specs
+
+${specs.map((s) => {
+		const paths = s.relatedPaths.length === 0 ? "  (no relatedPaths declared)" : s.relatedPaths.map((p) => `  - ${p}`).join("\n");
+		return `- ${s.featureName}/${s.specName}\n${paths}`;
+	}).join("\n")}
+
+## Task
+
+Return the spec keys that might be affected by any of the new files. Conservative inclusion is preferred over missing real drift.
+`;
 }
+//#endregion
+//#region src/cli/drift.ts
+const DEFAULT_CONCURRENCY = 3;
+const driftCommand = addLanguageOption(new Command("drift").argument("[feature/spec]", "Optional spec id. If omitted, every spec under .ccqa/features/ is checked.").description("Standalone spec ↔ codebase static audit. Use for PR checks where the browser isn't run. For run-time audit with a structured report, see `ccqa run --report`.").option("--format <fmt>", "Output format: text | json | github", "text").option("--severity <level>", "Exit non-zero on this severity or higher: warn | error", "error").option("--concurrency <n>", `Parallel spec checks (default: ${DEFAULT_CONCURRENCY})`).option("-m, --model <name>", "Claude model alias ('sonnet'|'opus'|'haiku') or full ID. Overrides CCQA_MODEL.").option("--cwd <path>", "Working directory used as both the .ccqa root and the codebase Claude reads. Useful for monorepos. Defaults to process.cwd().").option("--changed", "Restrict drift checks to specs whose relatedPaths intersect the git diff against --base (or, in CI, $GITHUB_BASE_REF, else origin/main). New files are routed to specs via a single lightweight Claude call.").option("--base <ref>", "Base ref to diff against when --changed is set. Defaults to $GITHUB_BASE_REF (CI) or origin/main.").option("--push", "Push the drift result to a ccqa hub as a run (kind: drift).").option("--project <name>", "Logical project name for the pushed run. Defaults to the current directory's name.").option(...hubUrlOption).option(...hubTokenOption).option(...hubHeaderOption)).action(async (specPath, opts) => {
+	const format = parseFormat(opts.format);
+	const threshold = parseSeverity(opts.severity);
+	const concurrency = parseConcurrency(opts.concurrency);
+	const cwd = resolveCwd(opts.cwd);
+	await ensureCcqaDir(cwd);
+	if (opts.changed && specPath) {
+		error("--changed and an explicit spec id cannot be combined; --changed only applies to a full sweep");
+		process.exit(2);
+	}
+	let targets = await collectTargets(specPath, cwd);
+	if (targets.length === 0) exitWithNoSpecs(format, "no test specs found under .ccqa/features/");
+	if (format === "text") {
+		header("drift", specPath ?? `${targets.length} spec${targets.length > 1 ? "s" : ""}`);
+		if (opts.cwd) meta("cwd", cwd);
+	}
+	const baseRef = opts.changed ? resolveBaseRef(opts.base) : null;
+	if (opts.changed) {
+		const total = targets.length;
+		targets = await filterByChanged({
+			targets,
+			cwd,
+			baseOverride: opts.base,
+			format,
+			model: opts.model
+		});
+		if (format === "text") meta("scoped", `${targets.length} of ${total} spec${total > 1 ? "s" : ""}`);
+		if (targets.length === 0) exitWithNoSpecs(format, "no specs intersect the changed file set; nothing to check");
+	}
+	const blocks = await loadAvailableBlocks(cwd);
+	const results = await analyzeDrift({
+		targets,
+		cwd,
+		blocks,
+		concurrency,
+		...opts.model ? { model: opts.model } : {},
+		...opts.language ? { language: opts.language } : {},
+		onSpecStart: (t) => {
+			if (format === "text") info(`checking ${t.featureName}/${t.specName}`);
+		}
+	});
+	process.stdout.write(renderDrift(results, format, cwd));
+	if (opts.push) await pushDriftResults({
+		results,
+		threshold,
+		cwd,
+		opts,
+		format,
+		baseRef
+	});
+	process.exit(determineExitCode(results, threshold));
+});
 /**
-* Parse the `{ summaries: [...] }` JSON contract into typed entries. Returns
-* null and logs when the payload is malformed. Exported for unit testing.
+* Push a finished drift audit to a ccqa hub as a `kind: "drift"` run, so it
+* shows up alongside `ccqa run` runs in the hub UI. Best-effort: a missing
+* hub connection warns and returns rather than failing the command (`--push`
+* never changes drift's own exit code).
+*
+* `resolveHub` is injectable so tests can supply a fake `HubClient` without
+* a real hub connection; it defaults to the real flag/env resolution.
 */
-function parseSummaries(json) {
-	let payload;
+async function pushDriftResults(args, resolveHub = resolveHubClient) {
+	const { results, threshold, cwd, opts, format, baseRef } = args;
+	const hub = resolveHub(opts);
+	if (!hub) {
+		warn("--push requires a hub connection (--hub-url/--hub-token or CCQA_HUB_URL/CCQA_HUB_TOKEN) — skipping push");
+		return;
+	}
 	try {
-		payload = JSON.parse(json);
+		const project = resolveProject({
+			project: opts.project,
+			cwd
+		});
+		const [branch, head] = await Promise.all([detectBranch(cwd), getGitHead(cwd)]);
+		const report = driftResultsToReport(results, {
+			threshold,
+			git: {
+				head,
+				base: baseRef ?? null
+			}
+		});
+		const dir = await mkdtemp(join(tmpdir(), "ccqa-drift-push-"));
+		try {
+			await writeFile(join(dir, "report.json"), JSON.stringify(report, null, 2), "utf8");
+			const archive = await packDirToTarGz(dir);
+			const run = await hub.pushRun(archive, {
+				project,
+				...branch ? { branch } : {},
+				kind: "drift"
+			});
+			if (format === "text") info(`pushed drift result to hub: ${(opts.hubUrl ?? process.env.CCQA_HUB_URL ?? "").replace(/\/+$/, "")}/#/runs/${run.id}`);
+		} finally {
+			await rm(dir, {
+				recursive: true,
+				force: true
+			});
+		}
+	} catch (err) {
+		if (err instanceof HubApiError) {
+			error(`hub request failed (${err.status} ${err.code}): ${err.message}`);
+			process.exit(2);
+		}
+		throw err;
+	}
+}
+function exitWithNoSpecs(format, message) {
+	if (format === "json") process.stdout.write(`${JSON.stringify({ specs: [] }, null, 2)}\n`);
+	else if (format === "text") info(message);
+	process.exit(0);
+}
+async function filterByChanged(input) {
+	const { targets, cwd, baseOverride, format, model } = input;
+	const base = resolveBaseRef(baseOverride);
+	let changed;
+	try {
+		changed = await getChangedFiles(base, cwd);
 	} catch (e) {
-		error(`failed to parse summaries JSON: ${e.message}`);
-		return null;
+		error(`failed to run 'git diff' against ${base}: ${e.message}`);
+		process.exit(2);
 	}
-	if (typeof payload !== "object" || payload === null) {
-		error("summaries payload is not an object");
-		return null;
+	if (format === "text") {
+		meta("changed-base", base);
+		meta("changed-files", changed.length);
+	}
+	if (changed.length === 0) return [];
+	const newFiles = changed.filter((f) => f.status === "added" && !f.outsideCwd);
+	const existingChanges = changed.filter((f) => f.status !== "added" || f.outsideCwd);
+	const affected = /* @__PURE__ */ new Set();
+	const touchedBlockNames = /* @__PURE__ */ new Set();
+	for (const f of changed) {
+		if (f.outsideCwd) continue;
+		const blockName = parseBlockPath(f.path);
+		if (blockName) touchedBlockNames.add(blockName);
+	}
+	for (const t of targets) {
+		if (!t.relatedPaths) {
+			affected.add(specKey(t));
+			continue;
+		}
+		if (existingChanges.some((f) => isPathAffectedBy(f.path, t.relatedPaths)) || newFiles.some((f) => isPathAffectedBy(f.path, t.relatedPaths))) {
+			affected.add(specKey(t));
+			continue;
+		}
+		if (t.includedBlocks?.some((name) => touchedBlockNames.has(name))) affected.add(specKey(t));
+	}
+	if (newFiles.length > 0) {
+		if (format === "text") info(`routing ${newFiles.length} new file(s) to specs via Claude...`);
+		const routed = await routeNewFilesToSpecs({
+			newFiles: newFiles.map((f) => f.path),
+			specs: targets.filter((t) => t.relatedPaths).map((t) => ({
+				featureName: t.featureName,
+				specName: t.specName,
+				relatedPaths: t.relatedPaths
+			})),
+			cwd,
+			model
+		});
+		for (const key of routed) affected.add(key);
 	}
-	const summaries = payload.summaries;
-	if (!Array.isArray(summaries)) {
-		error("summaries payload missing a `summaries` array");
-		return null;
+	return targets.filter((t) => affected.has(specKey(t)));
+}
+async function collectTargets(specPath, cwd) {
+	const tree = await listFeatureTree(cwd);
+	if (specPath) {
+		const { featureName, specName } = parseSpecPath(specPath);
+		const spec = tree.find((f) => f.featureName === featureName)?.specs.find((s) => s.specName === specName);
+		if (!spec?.hasSpecFile) {
+			error(`spec not found: ${featureName}/${specName} (under ${cwd})`);
+			process.exit(1);
+		}
+		return [{
+			featureName,
+			specName,
+			includedBlocks: spec.includedBlocks ?? []
+		}];
 	}
 	const out = [];
-	for (const item of summaries) {
-		const rec = item ?? {};
-		const { featureName, specName, summary } = rec;
-		if (typeof featureName === "string" && typeof specName === "string" && typeof summary === "string") {
-			const entry = {
-				featureName,
-				specName,
-				summary
-			};
-			if (typeof rec.startScreen === "string" && rec.startScreen.length > 0) entry.startScreen = rec.startScreen;
-			if (typeof rec.testCondition === "string" && rec.testCondition.length > 0) entry.testCondition = rec.testCondition;
-			if (Array.isArray(rec.preconditions)) {
-				const pre = rec.preconditions.filter((p) => typeof p === "string" && p.length > 0);
-				if (pre.length > 0) entry.preconditions = pre;
-			}
-			out.push(entry);
-		}
+	for (const feature of tree) for (const spec of feature.specs) {
+		if (!spec.hasSpecFile) continue;
+		const t = {
+			featureName: feature.featureName,
+			specName: spec.specName
+		};
+		if (spec.relatedPaths) t.relatedPaths = spec.relatedPaths;
+		if (spec.includedBlocks) t.includedBlocks = spec.includedBlocks;
+		out.push(t);
 	}
 	return out;
 }
-const LABELS_JA = {
-	indexTitle: "テスト観点インデックス (perspectives)",
-	caseCol: "ケース",
-	itemCol: "項目",
-	valueCol: "内容",
-	modeCol: "モード",
-	statusCol: "状態",
-	modeLabel: "モード",
-	summary: "検証内容",
-	preconditions: "前提条件",
-	startScreen: "開始画面",
-	relatedCode: "関連コード",
-	modeDeterministic: "deterministic",
-	modeLive: "live",
-	notRunnable: "⚠️ 未record",
-	runnable: "✅ 実行可能"
-};
-const LABELS_EN = {
-	indexTitle: "Test Perspectives (perspectives)",
-	caseCol: "Case",
-	itemCol: "Item",
-	valueCol: "Value",
-	modeCol: "Mode",
-	statusCol: "Status",
-	modeLabel: "Mode",
-	summary: "Verifies",
-	preconditions: "Preconditions",
-	startScreen: "Start screen",
-	relatedCode: "Related code",
-	modeDeterministic: "deterministic",
-	modeLive: "live",
-	notRunnable: "⚠️ not recorded",
-	runnable: "✅ runnable"
-};
-/**
-* Pick the label set for a `--language` value. Only an explicit English tag
-* (`en`, `en-US`, …) switches to English labels; `auto`, `ja`, and anything
-* else keep Japanese, matching the source-following default the rest of the
-* command uses.
-*/
-function labelsFor(language) {
-	return /^en\b/i.test(language?.trim() ?? "") ? LABELS_EN : LABELS_JA;
-}
-/**
-* Whether the spec is runnable from the reviewer's perspective. Live specs
-* are always runnable (no codegen step); a deterministic spec is runnable
-* only once `test.spec.ts` exists.
-*/
-function statusLabel(status, labels) {
-	if (status.mode === "live") return labels.runnable;
-	return status.generated ? labels.runnable : labels.notRunnable;
-}
-/** The spec's execution mode (deterministic or live), per spec.yaml. */
-function modeLabel(status, labels) {
-	return status.mode === "live" ? labels.modeLive : labels.modeDeterministic;
-}
-/**
-* Path to a spec.yaml relative to the **root** `.ccqa/perspectives.md`
-* (i.e. relative to the `.ccqa/` dir). Used for the category index links.
-*/
-function specRelPathFromRoot(featureName, specName) {
-	return `features/${featureName}/test-cases/${specName}/spec.yaml`;
-}
-/**
-* Path to a category detail file relative to the **root** `.ccqa/perspectives.md`.
-* The detail file is written to `.ccqa/features/<feature>/perspectives.md`
-* (see `getFeaturePerspectivesMarkdownPath`), so the link must include the
-* `features/` segment — otherwise the category heading link 404s.
-*/
-function featureDetailRelPathFromRoot(featureName) {
-	return `features/${featureName}/perspectives.md`;
+function parseFormat(raw) {
+	const v = raw ?? "text";
+	if (v === "text" || v === "json" || v === "github") return v;
+	error(`invalid --format: ${v} (expected text|json|github)`);
+	process.exit(2);
 }
-/**
-* Path to a spec.yaml relative to the **category** detail file
-* `.ccqa/features/<feature>/perspectives.md`. The spec lives alongside under
-* `test-cases/<spec>/`, so the category file links to it directly — which is
-* what makes the link resolve both on GitHub and in a local editor.
-*/
-function specRelPathFromCategory(specName) {
-	return `test-cases/${specName}/spec.yaml`;
+function parseSeverity(raw) {
+	const v = raw ?? "error";
+	if (v === "warn" || v === "error") return v;
+	error(`invalid --severity: ${v} (expected warn|error)`);
+	process.exit(2);
 }
-/**
-* Render the root `.ccqa/perspectives.md`: a category-grouped index of which
-* cases exist. Each feature is a heading (linking to its own detail
-* `perspectives.md`) followed by a row per case — title, status, and a link
-* to that case's spec.yaml. The per-case *detail* (検証内容, preconditions,
-* note) still lives only in the per-category file; the root stays a scannable
-* "what is tested, and where" overview.
-*
-* Pure and deterministic, so the index rendering is easy to unit-test.
-*/
-function renderIndexMarkdown(perspectives, labels = LABELS_JA) {
-	const lines = [];
-	lines.push(`# ${labels.indexTitle}`);
-	lines.push("");
-	for (const feature of perspectives.features) {
-		const detailLink = featureDetailRelPathFromRoot(feature.featureName);
-		lines.push(`## [${feature.featureName}](${detailLink})`);
-		lines.push("");
-		lines.push(`| ${labels.caseCol} | ${labels.modeCol} | ${labels.statusCol} | spec |`);
-		lines.push("| --- | --- | --- | --- |");
-		for (const spec of feature.specs) {
-			const specLink = specRelPathFromRoot(feature.featureName, spec.specName);
-			const mode = mdCell(modeLabel(spec.status, labels));
-			const status = mdCell(statusLabel(spec.status, labels));
-			lines.push(`| ${mdCell(spec.title)} | ${mode} | ${status} | [spec](${specLink}) |`);
-		}
-		lines.push("");
+function parseConcurrency(raw) {
+	if (raw === void 0) return DEFAULT_CONCURRENCY;
+	const n = Number.parseInt(raw, 10);
+	if (!Number.isFinite(n) || n < 1) {
+		error(`invalid --concurrency: ${raw} (expected positive integer)`);
+		process.exit(2);
 	}
-	return lines.join("\n");
-}
-/**
-* Render one category's `.ccqa/features/<feature>/perspectives.md`: every
-* case in the category as a self-contained vertical table. All columns —
-* including the verification summary (検証内容) and the human note — live
-* inside the table; nothing is emitted outside it. Detailed steps / expected
-* results are still not restated (the spec.yaml is their single home); the
-* table links back to each spec instead.
-*
-* Pure and deterministic, so the per-case rendering is easy to unit-test.
-*/
-function renderFeatureMarkdown(feature, labels = LABELS_JA) {
-	const lines = [];
-	lines.push(`# ${feature.featureName}`);
-	lines.push("");
-	for (const spec of feature.specs) lines.push(...renderSpecMarkdown(spec, labels));
-	return lines.join("\n");
-}
-/**
-* Render one spec as a single vertical (item | content) Markdown table for a
-* category file. Verification summary and preconditions lead. The spec link
-* is relative to this category file so it resolves both on GitHub and in a
-* local editor. Related-code paths stay inline code rather than links: their
-* base (the cwd that hosts `.ccqa/`) is not reliably recoverable here — specs
-* carry a mix of cwd-relative (`src/...`) and repo-root (`pkg/app/src/...`)
-* forms — and many are globs that no link could open anyway. 検証内容
-* (summary) and note are rows inside the table; no prose blocks are emitted
-* around it. Exported for focused unit testing.
-*/
-function renderSpecMarkdown(spec, labels = LABELS_JA) {
-	const lines = [];
-	lines.push(`## ${spec.title}`);
-	lines.push("");
-	lines.push(`| ${labels.itemCol} | ${labels.valueCol} |`);
-	lines.push("| --- | --- |");
-	if (spec.summary) lines.push(`| ${labels.summary} | ${mdCell(spec.summary)} |`);
-	if (spec.preconditions && spec.preconditions.length > 0) lines.push(`| ${labels.preconditions} | ${spec.preconditions.map(mdCell).join("<br>")} |`);
-	if (spec.startScreen) lines.push(`| ${labels.startScreen} | ${mdCell(spec.startScreen)} |`);
-	const specPath = specRelPathFromCategory(spec.specName);
-	lines.push(`| spec | [${specPath}](${specPath}) |`);
-	lines.push(`| ${labels.modeLabel} | ${mdCell(modeLabel(spec.status, labels))} |`);
-	lines.push(`| ${labels.statusCol} | ${mdCell(statusLabel(spec.status, labels))} |`);
-	if (spec.relatedPaths && spec.relatedPaths.length > 0) lines.push(`| ${labels.relatedCode} | ${spec.relatedPaths.map((p) => `\`${p}\``).join("<br>")} |`);
-	if (spec.note) lines.push(`| 📝 note | ${mdCell(spec.note)} |`);
-	lines.push("");
-	return lines;
-}
-/** Escape pipes / newlines so a value stays inside one Markdown table cell. */
-function mdCell(value) {
-	return value.replace(/\|/g, "\\|").replace(/\n/g, " ");
+	return n;
 }
 //#endregion
+//#region src/cli/init.ts
+const initCommand = new Command("init").description("Create the .ccqa/ spec skeleton (features/, blocks/) in the current directory.").option("--cwd <path>", "Working directory (default: cwd)").action(async (opts) => {
+	const cwd = resolveCwd(opts.cwd);
+	header("init", cwd);
+	await ensureCcqaDir(cwd);
+	info("created  .ccqa/features/, .ccqa/blocks/");
+	blank();
+	hint("set CCQA_HUB_URL / CCQA_HUB_TOKEN to connect to a ccqa hub");
+	hint("edit guidance prompts in the hub UI's Prompts tab");
+	hint("run `ccqa record <feature>/<spec>` to start recording");
+});
+//#endregion
 //#region src/cli/session.ts
 const AB = createRequire(import.meta.url).resolve("agent-browser/bin/agent-browser.js");
 /**
@@ -14107,7 +14117,7 @@ function createListProfilesHandler(storage) {
 //#region src/hub/api/handlers/prompts.ts
 const MAX_PROMPT_BODY_BYTES = 256 * 1024;
 /** Validate the `:project` route param (prompts are project-scoped, not per-profile). */
-function requireProject(ctx) {
+function requireProject$1(ctx) {
 	return requireSafeSegment(ctx.params.project, "project");
 }
 /**
@@ -14143,7 +14153,7 @@ function metaFor(name, body) {
 /** PUT /api/v1/projects/:project/prompts/:name — body is Markdown (guidance) or custom prompt JSON. */
 function createPutPromptHandler(config) {
 	return async (ctx) => {
-		const project = requireProject(ctx);
+		const project = requireProject$1(ctx);
 		const name = requirePromptName(ctx);
 		const body = await readBody(ctx.req, MAX_PROMPT_BODY_BYTES);
 		await config.store.put(project, name, new Uint8Array(body), metaFor(name, body));
@@ -14154,7 +14164,7 @@ function createPutPromptHandler(config) {
 /** GET /api/v1/projects/:project/prompts — names + kinds + timestamps (no bodies). */
 function createListPromptsHandler(config) {
 	return async (ctx) => {
-		const project = requireProject(ctx);
+		const project = requireProject$1(ctx);
 		const entries = await config.store.list(project);
 		sendJson(ctx.res, 200, { prompts: entries.map((e) => ({
 			name: e.name,
@@ -14167,7 +14177,7 @@ function createListPromptsHandler(config) {
 /** GET /api/v1/projects/:project/prompts/:name — the raw prompt body, or 404. */
 function createGetPromptHandler(config) {
 	return async (ctx) => {
-		const project = requireProject(ctx);
+		const project = requireProject$1(ctx);
 		const name = requirePromptName(ctx);
 		const stored = await config.store.get(project, name);
 		if (!stored) throw new HttpError(404, "not_found", `prompt "${name}" not found for project "${project}"`);
@@ -14178,7 +14188,7 @@ function createGetPromptHandler(config) {
 /** DELETE /api/v1/projects/:project/prompts/:name */
 function createDeletePromptHandler(config) {
 	return async (ctx) => {
-		const project = requireProject(ctx);
+		const project = requireProject$1(ctx);
 		const name = requirePromptName(ctx);
 		await config.store.delete(project, name);
 		ctx.res.statusCode = 204;
@@ -14186,6 +14196,93 @@ function createDeletePromptHandler(config) {
 	};
 }
 //#endregion
+//#region src/hub/api/handlers/perspectives.ts
+const MAX_PERSPECTIVES_BODY_BYTES = 1024 * 1024;
+/** Validate the `:project` route param (perspectives are project-scoped, one document per project). */
+function requireProject(ctx) {
+	return requireSafeSegment(ctx.params.project, "project");
+}
+/**
+* PUT /api/v1/projects/:project/perspectives — body is the perspectives
+* document as JSON. Schema validation is the CLI's job (it Zod-validates
+* before pushing); the hub only rejects bodies that aren't a JSON object,
+* so the UI can always JSON.parse what it reads back.
+*/
+function createPutPerspectivesHandler(config) {
+	return async (ctx) => {
+		const project = requireProject(ctx);
+		const body = await readBody(ctx.req, MAX_PERSPECTIVES_BODY_BYTES);
+		let parsed;
+		try {
+			parsed = JSON.parse(body.toString("utf8"));
+		} catch {
+			throw new HttpError(400, "invalid_body", "perspectives body must be valid JSON");
+		}
+		if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) throw new HttpError(400, "invalid_body", "perspectives body must be a JSON object");
+		await config.store.put(project, new Uint8Array(body));
+		ctx.res.statusCode = 204;
+		ctx.res.end();
+	};
+}
+/** GET /api/v1/projects/:project/perspectives — the stored document, or 404. */
+function createGetPerspectivesHandler(config) {
+	return async (ctx) => {
+		const project = requireProject(ctx);
+		const stored = await config.store.get(project);
+		if (!stored) throw new HttpError(404, "not_found", `no perspectives stored for project "${project}"`);
+		sendBytes(ctx.res, 200, stored, "application/json; charset=utf-8");
+	};
+}
+/** DELETE /api/v1/projects/:project/perspectives */
+function createDeletePerspectivesHandler(config) {
+	return async (ctx) => {
+		const project = requireProject(ctx);
+		await config.store.delete(project);
+		ctx.res.statusCode = 204;
+		ctx.res.end();
+	};
+}
+const MAX_NOTE_BODY_BYTES = 64 * 1024;
+function parseNotePatch(body) {
+	let parsed;
+	try {
+		parsed = JSON.parse(body.toString("utf8"));
+	} catch {
+		throw new HttpError(400, "invalid_body", "note patch must be valid JSON");
+	}
+	const rec = parsed;
+	if (typeof rec?.feature !== "string" || rec.feature.length === 0 || typeof rec.spec !== "string" || rec.spec.length === 0 || typeof rec.note !== "string") throw new HttpError(400, "invalid_body", "note patch must be { feature, spec, note } with string values");
+	return {
+		feature: rec.feature,
+		spec: rec.spec,
+		note: rec.note
+	};
+}
+/**
+* PATCH /api/v1/projects/:project/perspectives — the hub UI's note editing.
+* Body: `{ feature, spec, note }`; an empty `note` clears the field. The
+* note is the only human-authored field in the document, and this is its
+* only write path now that the document never lives in the consuming repo.
+* Runs as a serialized read-modify-write so an edit can't clobber (or be
+* clobbered by) a concurrent one.
+*/
+function createPatchPerspectivesNoteHandler(config) {
+	return async (ctx) => {
+		const project = requireProject(ctx);
+		const patch = parseNotePatch(await readBody(ctx.req, MAX_NOTE_BODY_BYTES));
+		await config.store.update(project, (current) => {
+			if (current === null) throw new HttpError(404, "not_found", `no perspectives stored for project "${project}"`);
+			const specEntry = current.features?.find((f) => f?.featureName === patch.feature)?.specs?.find((s) => s?.specName === patch.spec);
+			if (!specEntry) throw new HttpError(404, "not_found", `no spec "${patch.feature}/${patch.spec}" in the perspectives document`);
+			if (patch.note === "") delete specEntry.note;
+			else specEntry.note = patch.note;
+			return current;
+		});
+		ctx.res.statusCode = 204;
+		ctx.res.end();
+	};
+}
+//#endregion
 //#region src/hub/api/handlers/learning-jobs.ts
 const MAX_BODY_BYTES = 4 * 1024;
 /** POST /api/v1/projects/:project/learning-jobs — create + enqueue a triage-learning job. */
@@ -14569,6 +14666,7 @@ const HTML_BODY = `
     <div class="nav-group" id="sidebar-project">no project</div>
     <nav class="nav">
       <a href="#/runs" class="nav-runs"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor"><path d="M3 12h4l3 8 4-16 3 8h4"/></svg> <span data-i18n="nav.runs">Runs</span></a>
+      <a href="#/perspectives" class="nav-perspectives"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor"><path d="M8 6h13M8 12h13M8 18h13"/><path d="M3 6h.01M3 12h.01M3 18h.01"/></svg> <span data-i18n="nav.perspectives">Perspectives</span></a>
       <a href="#/secrets" class="nav-secrets"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor"><rect x="3" y="11" width="18" height="10" rx="2"/><path d="M7 11V7a5 5 0 0 1 10 0v4"/></svg> <span data-i18n="nav.secrets">Secrets</span></a>
       <a href="#/prompts" class="nav-prompts"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor"><path d="M4 4h11l5 5v11a1 1 0 0 1-1 1H4a1 1 0 0 1-1-1V5a1 1 0 0 1 1-1z"/><path d="M14 4v6h6"/><path d="M8 13h6M8 17h6"/></svg> <span data-i18n="nav.prompts">Prompts</span></a>
       <a href="#/jobs" class="nav-jobs"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor"><path d="M12 2v4M12 18v4M4.9 4.9l2.8 2.8M16.3 16.3l2.8 2.8M2 12h4M18 12h4M4.9 19.1l2.8-2.8M16.3 7.7l2.8-2.8"/></svg> <span data-i18n="nav.learning">Learning</span></a>
@@ -14617,6 +14715,34 @@ const HTML_BODY = `
       </div>
     </section>
 
+    <!-- ===== PERSPECTIVES ===== -->
+    <section id="view-perspectives" hidden>
+      <div class="page-bar">
+        <h1 data-i18n="perspectives.title">Perspectives</h1>
+        <span class="updated" id="persp-updated"></span>
+        <div class="spacer"></div>
+        <button class="btn ghost sm" id="persp-refresh" data-i18n="common.refresh">Refresh</button>
+      </div>
+      <div class="content">
+        <p id="persp-status" class="empty-note" hidden></p>
+        <div id="persp-body" hidden>
+          <div class="ov" id="persp-ov"></div>
+          <div class="toolbar">
+            <label class="search"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor"><circle cx="11" cy="11" r="7"/><path d="m21 21-4.3-4.3"/></svg><input id="persp-q" type="search" data-i18n-ph="perspectives.search" aria-label="Search cases"></label>
+            <button class="fchip" data-f="all" aria-pressed="true" type="button" data-i18n="perspectives.filter.all">All</button>
+            <button class="fchip" data-f="deterministic" aria-pressed="false" type="button" data-i18n="perspectives.filter.deterministic">Deterministic</button>
+            <button class="fchip" data-f="live" aria-pressed="false" type="button" data-i18n="perspectives.filter.live">Live</button>
+            <button class="fchip" data-f="norec" aria-pressed="false" type="button" data-i18n="perspectives.filter.norec">Not recorded only</button>
+          </div>
+          <div class="tblcard"><div class="table-wrap"><table>
+            <thead><tr><th data-i18n="perspectives.col.case">Case</th><th data-i18n="perspectives.col.mode">Mode</th><th data-i18n="perspectives.col.status">Status</th><th></th></tr></thead>
+            <tbody id="persp-tbody"></tbody>
+          </table></div></div>
+          <p class="empty-note" id="persp-no-hit" hidden data-i18n="perspectives.noHit">No matching cases.</p>
+        </div>
+      </div>
+    </section>
+
     <!-- ===== RUN DETAIL ===== -->
     <section id="view-detail" hidden>
       <div class="page-bar">
@@ -15240,6 +15366,65 @@ const CSS = `
   .prompt-diff pre { margin: 0; padding: 12px 14px; border: 1px solid var(--border); border-radius: var(--radius-sm); background: var(--surface-2);
     font-family: var(--mono); font-size: 11px; line-height: 1.5; color: var(--fg-dim); white-space: pre-wrap; word-break: break-word; max-height: 480px; overflow-y: auto; }
 
+  /* perspectives — coverage strip, filter toolbar, and the one-table-per-project
+     view (feature section rows + expandable case detail rows). Reuses the
+     existing badge/chip primitives above; --pass/--amber cover the "runnable"
+     vs "not recorded" coloring so no new tokens are needed. */
+  .ov { display: flex; align-items: center; gap: 28px; padding: 14px 18px; border: 1px solid var(--border); border-radius: var(--radius); background: var(--surface); margin-bottom: 16px; flex-wrap: wrap; }
+  .ov .num { display: flex; flex-direction: column; }
+  .ov .num b { font-size: 24px; line-height: 1.15; font-weight: 650; font-variant-numeric: tabular-nums; }
+  .ov .num span { font-size: 12px; color: var(--muted); }
+  .ov .sep { width: 1px; align-self: stretch; background: var(--border); }
+  .ov .breakdown { display: flex; gap: 20px; }
+  .covwrap { flex: 1; min-width: 220px; display: flex; flex-direction: column; gap: 6px; }
+  .covbar { height: 8px; border-radius: 999px; overflow: hidden; display: flex; background: var(--surface-3); }
+  .covbar .ok { background: var(--pass); }
+  .covbar .no { background: var(--amber); opacity: 0.75; }
+  .covleg { display: flex; gap: 16px; font-size: 12px; color: var(--muted); }
+  .covleg i { display: inline-block; width: 8px; height: 8px; border-radius: 2px; margin-right: 5px; }
+  .covleg .lg-ok i { background: var(--pass); }
+  .covleg .lg-no i { background: var(--amber); opacity: 0.75; }
+
+  .search { flex: 1; min-width: 200px; max-width: 340px; display: flex; align-items: center; gap: 7px; border: 1px solid var(--border-strong); border-radius: var(--radius-sm); padding: 0 10px; height: 32px; background: var(--surface); }
+  .search svg { width: 15px; height: 15px; flex: none; color: var(--muted-2); }
+  .search input { border: none; outline: none; font: inherit; font-size: 13px; width: 100%; background: transparent; color: var(--fg); }
+  .fchip { border: 1px solid var(--border-strong); background: var(--surface); border-radius: 999px; padding: 5px 12px; font-size: 12.5px; color: var(--muted); }
+  .fchip[aria-pressed="true"] { background: var(--accent); color: var(--accent-fg); border-color: var(--accent); }
+
+  .chip.live { background: var(--info-bg); color: var(--info); border-color: var(--info-border); }
+  .badge.ok { background: var(--pass-bg); color: var(--pass); border-color: var(--pass-border); }
+  .badge.ok .d { background: var(--pass); }
+  .badge.norec { background: var(--amber-bg); color: var(--amber); border-color: var(--amber-border); }
+  .badge.norec .d { background: var(--amber); }
+
+  .tblcard { background: var(--surface); border: 1px solid var(--border); border-radius: var(--radius); overflow: hidden; }
+  /* Feature section rows must read as headings, not as just another data row —
+     larger, darker, extra padding, and a strong top rule marking the break. */
+  tr.grp td { background: var(--surface-2); border-top: 2px solid var(--border-strong); border-bottom: 1px solid var(--border); padding: 12px 12px 10px; font-family: var(--mono); font-size: 15px; font-weight: 700; color: var(--fg); }
+  tr.grp td .gcount { color: var(--muted); font-weight: 500; font-size: 12px; font-family: var(--font); margin-left: 10px; }
+  td.c-title { font-weight: 500; max-width: 460px; }
+  td.c-title .csum { display: block; font-weight: 400; color: var(--muted); font-size: 12.5px; margin-top: 1px; }
+  td.c-chev { width: 28px; color: var(--muted-2); text-align: right; }
+  .chev-i { display: inline-block; transition: transform 0.15s; font-size: 11px; }
+  tr.row[aria-expanded="true"] .chev-i { transform: rotate(90deg); }
+  tr.detail { display: none; }
+  tr.detail.open { display: table-row; }
+  tr.detail > td { background: var(--surface-2); padding: 14px 16px 16px; }
+
+  .d-grid { display: grid; grid-template-columns: 120px 1fr; gap: 7px 14px; font-size: 13px; max-width: 860px; }
+  .d-grid dt { color: var(--muted); font-size: 12px; padding-top: 1px; }
+  .d-grid dd { color: var(--fg-dim); }
+  .d-grid dd ul { list-style: none; display: flex; flex-direction: column; gap: 3px; margin: 0; padding: 0; }
+  .d-grid dd li::before { content: "\\2022 "; color: var(--muted-2); }
+  .d-grid code { font-size: 12px; background: var(--surface); border: 1px solid var(--border); border-radius: 4px; padding: 1px 5px; }
+  .notebox { margin-top: 12px; max-width: 860px; }
+  .notebox .nlabel { font-size: 12px; color: var(--muted); margin-bottom: 4px; }
+  .notebox textarea { width: 100%; min-height: 54px; resize: vertical; font: inherit; font-size: 13px; color: var(--fg-dim); background: var(--surface); border: 1px solid var(--border-strong); border-radius: var(--radius-sm); padding: 8px 10px; }
+  .notebox .nact { margin-top: 6px; display: flex; align-items: center; gap: 8px; }
+  .notebox .nstatus { font-size: 12px; color: var(--muted); }
+  .notebox .nstatus.ok { color: var(--pass); }
+  .notebox .nstatus.err { color: var(--fail); }
+
   @media (max-width: 900px) { .app { grid-template-columns: 1fr; } .sidebar { display: none; } .logo .wm { display: none; } .split { grid-template-columns: 1fr; } .rd-head .meta { margin-left: 0; } }
   @media (max-width: 700px) { .prompt-grid { grid-template-columns: 1fr; } .prompt-diff { grid-template-columns: 1fr; } }
 `;
@@ -15266,7 +15451,7 @@ const CLIENT_JS = `
   // only their display text is localized via FAILURE_LABEL_JA.
   var I18N = {
     en: {
-      "nav.projects": "Projects", "nav.runs": "Runs", "nav.secrets": "Secrets",
+      "nav.projects": "Projects", "nav.runs": "Runs", "nav.perspectives": "Perspectives", "nav.secrets": "Secrets",
       "nav.prompts": "Prompts", "nav.learning": "Learning",
       "app.project": "project", "app.profile": "profile", "app.disconnect": "Disconnect", "app.noProject": "no project",
       "app.newProfile": "New profile",
@@ -15308,6 +15493,27 @@ const CLIENT_JS = `
       "learn.cta.desc": "Learn from what you graded so ccqa classifies failure causes the same way next time.",
       "learn.cta.run": "Learn",
       "secrets.title": "Secrets", "prompts.title": "Prompts", "learning.title": "Learning",
+      "perspectives.title": "Perspectives",
+      "perspectives.search": "Search cases…",
+      "perspectives.filter.all": "All", "perspectives.filter.deterministic": "Deterministic",
+      "perspectives.filter.live": "Live", "perspectives.filter.norec": "Not recorded only",
+      "perspectives.col.case": "Case", "perspectives.col.mode": "Mode", "perspectives.col.status": "Status",
+      "perspectives.noHit": "No matching cases.",
+      "perspectives.updated": "Last updated:",
+      "perspectives.empty": "No perspectives yet. Run ccqa perspectives, or record a test — it's created automatically.",
+      "perspectives.loadFailed": "Loading perspectives failed",
+      "perspectives.mode.deterministic": "deterministic", "perspectives.mode.live": "live",
+      "perspectives.status.runnable": "runnable", "perspectives.status.notRecorded": "not recorded",
+      "perspectives.metric.features": "Features", "perspectives.metric.cases": "Test cases",
+      "perspectives.metric.deterministic": "Deterministic", "perspectives.metric.live": "Live",
+      "perspectives.cov.runnable": "runnable", "perspectives.cov.notRecorded": "not recorded",
+      "perspectives.d.preconditions": "Preconditions", "perspectives.d.startScreen": "Start screen",
+      "perspectives.d.testCondition": "Condition", "perspectives.d.spec": "spec",
+      "perspectives.d.relatedPaths": "Related code",
+      "perspectives.note.label": "Note",
+      "perspectives.note.placeholder": "Notes about this case…",
+      "perspectives.note.saved": "Saved",
+      "perspectives.note.error": "Could not save — retry",
       "prompt.card.record": "Recording browser actions",
       "prompt.card.live": "Live run (AI-driven)",
       "prompt.card.customPrompt": "Failure-cause classification",
@@ -15335,7 +15541,7 @@ const CLIENT_JS = `
       "jobs.failed": "The learning job failed.", "jobs.newCustomPrompt": "New custom prompt:", "jobs.empty": "No learning jobs yet. Grade failing specs on a run, then Learn."
     },
     ja: {
-      "nav.projects": "プロジェクト", "nav.runs": "実行", "nav.secrets": "シークレット",
+      "nav.projects": "プロジェクト", "nav.runs": "実行", "nav.perspectives": "Perspectives", "nav.secrets": "シークレット",
       "nav.prompts": "プロンプト", "nav.learning": "学習",
       "app.project": "プロジェクト", "app.profile": "プロファイル", "app.disconnect": "切断", "app.noProject": "プロジェクト未選択",
       "app.newProfile": "新規プロファイル",
@@ -15377,6 +15583,27 @@ const CLIENT_JS = `
       "learn.cta.desc": "採点した内容をもとに、ccqaが次回から同じように失敗の原因を分類できるよう学習します。",
       "learn.cta.run": "学習",
       "secrets.title": "シークレット", "prompts.title": "プロンプト", "learning.title": "学習",
+      "perspectives.title": "Perspectives",
+      "perspectives.search": "ケースを検索…",
+      "perspectives.filter.all": "すべて", "perspectives.filter.deterministic": "決定的",
+      "perspectives.filter.live": "ライブ", "perspectives.filter.norec": "未recordのみ",
+      "perspectives.col.case": "ケース", "perspectives.col.mode": "モード", "perspectives.col.status": "状態",
+      "perspectives.noHit": "該当するケースがありません。",
+      "perspectives.updated": "最終更新:",
+      "perspectives.empty": "まだperspectivesがありません。ccqa perspectives を実行するか、recordすると自動作成されます。",
+      "perspectives.loadFailed": "perspectivesの読み込みに失敗しました",
+      "perspectives.mode.deterministic": "決定的", "perspectives.mode.live": "ライブ",
+      "perspectives.status.runnable": "実行可能", "perspectives.status.notRecorded": "未record",
+      "perspectives.metric.features": "機能", "perspectives.metric.cases": "テストケース",
+      "perspectives.metric.deterministic": "決定的", "perspectives.metric.live": "ライブ",
+      "perspectives.cov.runnable": "実行可能", "perspectives.cov.notRecorded": "未record",
+      "perspectives.d.preconditions": "前提条件", "perspectives.d.startScreen": "開始画面",
+      "perspectives.d.testCondition": "実行条件", "perspectives.d.spec": "spec",
+      "perspectives.d.relatedPaths": "関連コード",
+      "perspectives.note.label": "note",
+      "perspectives.note.placeholder": "このケースについてのメモ…",
+      "perspectives.note.saved": "保存しました",
+      "perspectives.note.error": "保存に失敗しました — 再試行してください",
       "prompt.card.record": "ブラウザ操作の記録",
       "prompt.card.live": "ライブ実行（AI操作）",
       "prompt.card.customPrompt": "失敗原因の分類",
@@ -15632,8 +15859,8 @@ const CLIENT_JS = `
 
   // ── view routing ────────────────────────────────────────────────────
 
-  var VIEWS = ["projects", "runs", "detail", "secrets", "prompts", "jobs"];
-  var NAV_FOR_VIEW = { projects: ".nav-projects", secrets: ".nav-secrets", prompts: ".nav-prompts", runs: ".nav-runs", detail: ".nav-runs", jobs: ".nav-jobs" };
+  var VIEWS = ["projects", "runs", "detail", "perspectives", "secrets", "prompts", "jobs"];
+  var NAV_FOR_VIEW = { projects: ".nav-projects", secrets: ".nav-secrets", prompts: ".nav-prompts", runs: ".nav-runs", detail: ".nav-runs", jobs: ".nav-jobs", perspectives: ".nav-perspectives" };
   function showView(id) {
     // Any in-flight job poll belongs to the view we're leaving — bump the token
     // so its next tick is a no-op (see pollJob).
@@ -15651,6 +15878,7 @@ const CLIENT_JS = `
   function updateNavGate() {
     var gated = !state.project;
     document.querySelector(".nav-runs").classList.toggle("disabled", gated);
+    document.querySelector(".nav-perspectives").classList.toggle("disabled", gated);
     document.querySelector(".nav-secrets").classList.toggle("disabled", gated);
     document.querySelector(".nav-prompts").classList.toggle("disabled", gated);
     document.querySelector(".nav-jobs").classList.toggle("disabled", gated);
@@ -15666,6 +15894,7 @@ const CLIENT_JS = `
     if (location.hash === "#/projects" || !state.project) { openProjects(); return; }
     var m = location.hash.match(/^#\\/runs\\/(.+)$/);
     if (m) { openRunDetail(decodeURIComponent(m[1])); return; }
+    if (location.hash === "#/perspectives") { openPerspectives(); return; }
     if (location.hash === "#/secrets") { openSecrets(); return; }
     if (location.hash === "#/prompts") { openPrompts(); return; }
     var j = location.hash.match(/^#\\/jobs\\/(.+)$/);
@@ -16922,6 +17151,305 @@ const CLIENT_JS = `
     loadPrompts();
   }
 
+  // ── perspectives ──────────────────────────────────────────────────────
+  // A read-mostly coverage inventory the CLI generates ("ccqa perspectives" /
+  // record); the hub UI's only write path is the per-case note (PATCH). The
+  // whole document is fetched once per view-open and filtered/rendered
+  // client-side — small enough that there is no pagination.
+
+  var perspState = { doc: null, q: "", f: "all" };
+
+  function perspectivesPath() {
+    return "/api/v1/projects/" + encodeURIComponent(state.project) + "/perspectives";
+  }
+
+  // GET the perspectives document. Resolves null on 404 (no document stored
+  // yet — the normal "nothing recorded" state) instead of throwing, so
+  // loadPerspectives can tell that apart from a real fetch/parse failure.
+  function fetchPerspectives() {
+    return fetch(perspectivesPath(), { headers: { Authorization: "Bearer " + state.token } }).then(function (res) {
+      if (res.status === 404) return null;
+      if (!res.ok) throw new Error(res.status + " " + res.statusText);
+      return res.json();
+    }, function () { throw new Error("Network unreachable — check the hub URL and your connection"); });
+  }
+
+  // The execution mode lives inside the mechanically-derived status object
+  // (spec.status.mode), not at the top level of a spec entry.
+  function perspMode(spec) {
+    return spec.status && spec.status.mode === "live" ? "live" : "deterministic";
+  }
+
+  function perspRunnable(spec) {
+    return perspMode(spec) === "live" || (spec.status && spec.status.generated === true);
+  }
+
+  function setPerspStatus(message) {
+    var box = document.getElementById("persp-status");
+    box.hidden = !message;
+    box.textContent = message || "";
+  }
+
+  function perspModeChip(mode) {
+    var span = el("span", "chip" + (mode === "live" ? " live" : ""));
+    span.textContent = t(mode === "live" ? "perspectives.mode.live" : "perspectives.mode.deterministic");
+    return span;
+  }
+
+  function perspStatusBadge(spec) {
+    var ok = perspRunnable(spec);
+    var span = el("span", "badge " + (ok ? "ok" : "norec"));
+    span.appendChild(el("span", "d"));
+    span.appendChild(document.createTextNode(" " + t(ok ? "perspectives.status.runnable" : "perspectives.status.notRecorded")));
+    return span;
+  }
+
+  // Overview strip: feature/case counts, deterministic/live breakdown, and a
+  // runnable-vs-not-recorded coverage bar.
+  function renderPerspOverview(doc) {
+    var host = document.getElementById("persp-ov");
+    clear(host);
+    var allSpecs = doc.features.reduce(function (acc, f) { return acc.concat(f.specs); }, []);
+    var total = allSpecs.length;
+    var ok = allSpecs.filter(perspRunnable).length;
+    var no = total - ok;
+    var det = allSpecs.filter(function (s) { return perspMode(s) === "deterministic"; }).length;
+    var live = total - det;
+
+    function numBlock(value, labelKey) {
+      var box = el("div", "num");
+      box.appendChild(el("b", null, String(value)));
+      box.appendChild(el("span", null, t(labelKey)));
+      return box;
+    }
+
+    host.appendChild(numBlock(doc.features.length, "perspectives.metric.features"));
+    host.appendChild(el("div", "sep"));
+    host.appendChild(numBlock(total, "perspectives.metric.cases"));
+    host.appendChild(el("div", "sep"));
+    var breakdown = el("div", "breakdown");
+    breakdown.appendChild(numBlock(det, "perspectives.metric.deterministic"));
+    breakdown.appendChild(numBlock(live, "perspectives.metric.live"));
+    host.appendChild(breakdown);
+
+    var covwrap = el("div", "covwrap");
+    var covbar = el("div", "covbar");
+    if (total > 0) {
+      var okBar = el("div", "ok");
+      okBar.style.width = (ok / total) * 100 + "%";
+      var noBar = el("div", "no");
+      noBar.style.width = (no / total) * 100 + "%";
+      covbar.appendChild(okBar);
+      covbar.appendChild(noBar);
+    }
+    covwrap.appendChild(covbar);
+    var covleg = el("div", "covleg");
+    var legOk = el("span", "lg-ok");
+    legOk.appendChild(el("i"));
+    legOk.appendChild(document.createTextNode(t("perspectives.cov.runnable") + " " + ok));
+    covleg.appendChild(legOk);
+    if (no > 0) {
+      var legNo = el("span", "lg-no");
+      legNo.appendChild(el("i"));
+      legNo.appendChild(document.createTextNode(t("perspectives.cov.notRecorded") + " " + no));
+      covleg.appendChild(legNo);
+    }
+    covwrap.appendChild(covleg);
+    host.appendChild(covwrap);
+  }
+
+  function perspMatches(spec) {
+    if (perspState.f === "deterministic" && perspMode(spec) !== "deterministic") return false;
+    if (perspState.f === "live" && perspMode(spec) !== "live") return false;
+    if (perspState.f === "norec" && perspRunnable(spec)) return false;
+    if (perspState.q) {
+      var hay = (spec.title + " " + (spec.summary || "") + " " + spec.specName).toLowerCase();
+      if (hay.indexOf(perspState.q) === -1) return false;
+    }
+    return true;
+  }
+
+  // Detail row: a definition list of the case's fields plus the note editor.
+  // Built with createElement/textContent throughout — every field here is
+  // API-derived, so none of it may go through innerHTML.
+  function perspDetailContent(feature, spec) {
+    var frag = document.createDocumentFragment();
+    var dl = el("dl", "d-grid");
+    function row(labelKey, valueNode) {
+      dl.appendChild(el("dt", null, t(labelKey)));
+      var dd = el("dd");
+      if (typeof valueNode === "string") dd.textContent = valueNode;
+      else dd.appendChild(valueNode);
+      dl.appendChild(dd);
+    }
+    if (spec.preconditions && spec.preconditions.length) {
+      var ul = el("ul");
+      spec.preconditions.forEach(function (p) { ul.appendChild(el("li", null, p)); });
+      row("perspectives.d.preconditions", ul);
+    }
+    if (spec.startScreen) row("perspectives.d.startScreen", spec.startScreen);
+    if (spec.testCondition) row("perspectives.d.testCondition", spec.testCondition);
+    var specCode = el("code", null, spec.specName);
+    row("perspectives.d.spec", specCode);
+    if (spec.relatedPaths && spec.relatedPaths.length) {
+      var pathsWrap = el("span");
+      spec.relatedPaths.forEach(function (p, i) {
+        if (i > 0) pathsWrap.appendChild(document.createTextNode(" "));
+        pathsWrap.appendChild(el("code", null, p));
+      });
+      row("perspectives.d.relatedPaths", pathsWrap);
+    }
+    frag.appendChild(dl);
+
+    var notebox = el("div", "notebox");
+    notebox.appendChild(el("div", "nlabel", t("perspectives.note.label")));
+    var ta = el("textarea");
+    ta.placeholder = t("perspectives.note.placeholder");
+    ta.value = spec.note || "";
+    notebox.appendChild(ta);
+    var nact = el("div", "nact");
+    var saveBtn = el("button", "btn primary", t("common.save"));
+    saveBtn.type = "button";
+    var statusEl = el("span", "nstatus");
+    nact.appendChild(saveBtn);
+    nact.appendChild(statusEl);
+    notebox.appendChild(nact);
+    frag.appendChild(notebox);
+
+    saveBtn.addEventListener("click", function () {
+      saveBtn.disabled = true;
+      statusEl.className = "nstatus";
+      statusEl.textContent = "";
+      apiFetch(perspectivesPath(), {
+        method: "PATCH",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ feature: feature.featureName, spec: spec.specName, note: ta.value }),
+      }).then(function () {
+        spec.note = ta.value || undefined;
+        statusEl.className = "nstatus ok";
+        statusEl.textContent = t("perspectives.note.saved");
+      }).catch(function (err) {
+        statusEl.className = "nstatus err";
+        statusEl.textContent = t("perspectives.note.error") + ": " + err.message;
+      }).then(function () { saveBtn.disabled = false; });
+    });
+
+    return frag;
+  }
+
+  function renderPerspTable(doc) {
+    var tbody = document.getElementById("persp-tbody");
+    clear(tbody);
+    var hits = 0;
+    doc.features.forEach(function (feature) {
+      var specs = feature.specs.filter(perspMatches);
+      if (!specs.length) return;
+      hits += specs.length;
+
+      var grpRow = el("tr", "grp");
+      var grpTd = el("td");
+      grpTd.colSpan = 4;
+      grpTd.appendChild(document.createTextNode(feature.featureName));
+      grpTd.appendChild(el("span", "gcount", specs.length + " " + t("perspectives.metric.cases").toLowerCase()));
+      grpRow.appendChild(grpTd);
+      tbody.appendChild(grpRow);
+
+      specs.forEach(function (spec) {
+        var row = el("tr", "row");
+        row.tabIndex = 0;
+        row.setAttribute("aria-expanded", "false");
+
+        var titleTd = el("td", "c-title");
+        titleTd.appendChild(document.createTextNode(spec.title));
+        if (spec.summary) titleTd.appendChild(el("span", "csum", spec.summary));
+        row.appendChild(titleTd);
+
+        var modeTd = el("td");
+        modeTd.appendChild(perspModeChip(perspMode(spec)));
+        row.appendChild(modeTd);
+
+        var statusTd = el("td");
+        statusTd.appendChild(perspStatusBadge(spec));
+        row.appendChild(statusTd);
+
+        var chevTd = el("td", "c-chev");
+        chevTd.appendChild(el("span", "chev-i", "\\u25b6"));
+        row.appendChild(chevTd);
+
+        var detailRow = el("tr", "detail");
+        var detailTd = el("td");
+        detailTd.colSpan = 4;
+        detailRow.appendChild(detailTd);
+        var built = false;
+
+        function toggle() {
+          var open = detailRow.classList.toggle("open");
+          row.setAttribute("aria-expanded", open ? "true" : "false");
+          if (open && !built) {
+            detailTd.appendChild(perspDetailContent(feature, spec));
+            built = true;
+          }
+        }
+        row.addEventListener("click", function (e) {
+          if (e.target.tagName === "TEXTAREA" || e.target.tagName === "BUTTON") return;
+          toggle();
+        });
+        row.addEventListener("keydown", function (e) {
+          if ((e.key === "Enter" || e.key === " ") && e.target === row) { e.preventDefault(); toggle(); }
+        });
+
+        tbody.appendChild(row);
+        tbody.appendChild(detailRow);
+      });
+    });
+    document.getElementById("persp-no-hit").hidden = hits > 0;
+  }
+
+  function renderPerspectives() {
+    var doc = perspState.doc;
+    if (!doc) return;
+    renderPerspOverview(doc);
+    renderPerspTable(doc);
+  }
+
+  function setPerspUpdated(doc) {
+    var span = document.getElementById("persp-updated");
+    if (doc && doc.generatedAt) {
+      span.hidden = false;
+      span.textContent = t("perspectives.updated") + " " + relTime(doc.generatedAt);
+    } else {
+      span.hidden = true;
+      span.textContent = "";
+    }
+  }
+
+  function loadPerspectives() {
+    setPerspStatus("");
+    document.getElementById("persp-body").hidden = true;
+    setPerspUpdated(null);
+    fetchPerspectives()
+      .then(function (doc) {
+        perspState.doc = doc;
+        if (!doc) { setPerspStatus(t("perspectives.empty")); return; }
+        setPerspUpdated(doc);
+        document.getElementById("persp-body").hidden = false;
+        renderPerspectives();
+      })
+      .catch(function (err) {
+        perspState.doc = null;
+        setPerspStatus(t("perspectives.loadFailed") + ": " + err.message);
+      });
+  }
+
+  function openPerspectives() {
+    showView("perspectives");
+    document.getElementById("persp-q").value = perspState.q;
+    document.querySelectorAll("#view-perspectives .fchip").forEach(function (b) {
+      b.setAttribute("aria-pressed", String(b.getAttribute("data-f") === perspState.f));
+    });
+    loadPerspectives();
+  }
+
   // The custom prompt body is JSON (schemaVersion/basePromptVersion/customPromptVersion/
   // generatedAt/guidance); the textarea only ever shows the learned guidance
   // text, never the raw JSON. A parse failure falls back to the raw text so a
@@ -17313,6 +17841,22 @@ const CLIENT_JS = `
   // argument (which would render "[object PointerEvent]" in the status box).
   document.getElementById("sec-load").addEventListener("click", function () { loadSecrets(); });
 
+  // perspectives view
+  document.getElementById("persp-refresh").addEventListener("click", function () { loadPerspectives(); });
+  document.getElementById("persp-q").addEventListener("input", function (e) {
+    perspState.q = e.target.value.trim().toLowerCase();
+    renderPerspectives();
+  });
+  document.querySelectorAll("#view-perspectives .fchip").forEach(function (b) {
+    b.addEventListener("click", function () {
+      perspState.f = b.getAttribute("data-f");
+      document.querySelectorAll("#view-perspectives .fchip").forEach(function (x) {
+        x.setAttribute("aria-pressed", x === b ? "true" : "false");
+      });
+      renderPerspectives();
+    });
+  });
+
   // prompts view
   document.getElementById("pr-load").addEventListener("click", function () { loadPrompts(); });
 
@@ -17717,6 +18261,11 @@ function registerRoutes(router, config, queue) {
 	router.get("/api/v1/projects/:project/prompts", createListPromptsHandler(promptConfig));
 	router.get("/api/v1/projects/:project/prompts/:name", createGetPromptHandler(promptConfig));
 	router.delete("/api/v1/projects/:project/prompts/:name", createDeletePromptHandler(promptConfig));
+	const perspectivesConfig = { store: storage.perspectives };
+	router.put("/api/v1/projects/:project/perspectives", createPutPerspectivesHandler(perspectivesConfig));
+	router.get("/api/v1/projects/:project/perspectives", createGetPerspectivesHandler(perspectivesConfig));
+	router.patch("/api/v1/projects/:project/perspectives", createPatchPerspectivesNoteHandler(perspectivesConfig));
+	router.delete("/api/v1/projects/:project/perspectives", createDeletePerspectivesHandler(perspectivesConfig));
 	router.post("/api/v1/projects/:project/learning-jobs", createCreateLearningJobHandler({
 		storage,
 		queue
@@ -17918,6 +18467,12 @@ function promptBlobPath(root, project, name) {
 function promptMetaPath(root, project, name) {
 	return join(promptProjectDir(root, project), `${name}.meta.json`);
 }
+function perspectivesKindDir(root) {
+	return join(root, "perspectives");
+}
+function perspectivesPath(root, project) {
+	return join(perspectivesKindDir(root), `${project}.json`);
+}
 //#endregion
 //#region src/hub/core/storage/file/artifact-store.ts
 /**
@@ -18005,6 +18560,41 @@ function createFileJobStore(root) {
 	};
 }
 //#endregion
+//#region src/hub/core/storage/file/perspectives-store.ts
+/**
+* Defense-in-depth path validation: the HTTP layer already checks the project
+* segment, but this builds a file path from it, so it re-checks rather than
+* trusting callers. Mirrors the sibling prompt/secret stores.
+*/
+function assertSafeName$2(value, label) {
+	if (value.length === 0 || value.includes("/") || value.includes("\\") || value.split(/[\\/]/).includes("..") || value === ".") throw new Error(`invalid ${label}: must be a bare name without path separators or '..'`);
+}
+/**
+* Perspectives storage: one JSON document per project, plain UTF-8 with no
+* encryption (an inventory of what is tested is not a secret). No meta file —
+* the document's own `generatedAt` is its timestamp.
+*/
+function createFilePerspectivesStore(root) {
+	return {
+		async put(project, blob) {
+			assertSafeName$2(project, "project");
+			await writeBytes(perspectivesPath(root, project), blob);
+		},
+		async get(project) {
+			assertSafeName$2(project, "project");
+			return readBytesOrNull(perspectivesPath(root, project));
+		},
+		async update(project, mutate) {
+			assertSafeName$2(project, "project");
+			await updateJson(perspectivesPath(root, project), mutate);
+		},
+		async delete(project) {
+			assertSafeName$2(project, "project");
+			await removePath(perspectivesPath(root, project));
+		}
+	};
+}
+//#endregion
 //#region src/hub/core/storage/file/prompt-store.ts
 /**
 * Defense-in-depth path validation: the HTTP layer already checks project/name,
@@ -18222,6 +18812,7 @@ function createFileHubStorage(dataDir) {
 		variables: createFileSecretStore(dataDir, "variables"),
 		triage: createFileTriageStore(dataDir),
 		prompts: createFilePromptStore(dataDir),
+		perspectives: createFilePerspectivesStore(dataDir),
 		jobs: createFileJobStore(dataDir)
 	};
 }