ccqa 1.30.0 → 1.31.0

package/dist/bin/ccqa.mjs

@@ -7537,6 +7537,7 @@ z.object({
 const SpecDriftEntrySchema = z.object({
 	label: DriftLabelSchema.nullable(),
 	surface: DriftSurfaceSchema.optional(),
+	subDiagnosis: DriftSubDiagnosisSchema.optional(),
 	specChangeKind: SpecChangeKindSchema.optional(),
 	confidence: z.number().optional(),
 	headline: z.string().optional(),
@@ -13844,8 +13845,12 @@ function createRunTeardown() {
 * A command must install at most one: a second handler that also exits would
 * race this one and could terminate mid-finalizer. A second signal while
 * tearing down hard-exits immediately rather than waiting.
+*
+* `onSignal` runs synchronously before the teardown starts, so a finalizer
+* can already see which signal is ending the process (e.g. `ccqa record`
+* seals its hub run with a "terminated by signal" note).
 */
-function installTeardownSignalHandlers(teardown) {
+function installTeardownSignalHandlers(teardown, onSignal) {
 	let handling = false;
 	const handler = (sig) => {
 		const code = sig === "SIGINT" ? 130 : 143;
@@ -13854,6 +13859,7 @@ function installTeardownSignalHandlers(teardown) {
 			return;
 		}
 		handling = true;
+		onSignal?.(sig);
 		teardown.run().finally(() => process.exit(code));
 	};
 	const onInt = () => handler("SIGINT");
@@ -14018,6 +14024,16 @@ function generateSessionName() {
 */
 function buildTraceSystemPrompt(input) {
 	const sessionName = input.sessionName ?? generateSessionName();
+	const callerGuidance = input.instruction ? `## Caller Guidance
+
+The caller provided extra guidance for this recording — for example, a drift
+audit's finding about what a previous recording of this spec got wrong. Treat
+it as advice on what to avoid or verify while recording; the spec's steps
+above remain the contract for what to do.
+
+${input.instruction}
+
+` : "";
 	const stepsText = input.steps.map((step) => `### ${step.id} [${step.source}]
 - **Instruction**: ${step.instruction}
 - **Expected**: ${step.expected}`).join("\n\n");
@@ -14405,7 +14421,7 @@ RUN_COMPLETED|passed|<summary>
 RUN_COMPLETED|failed|<summary>
 \`\`\`
 
-## Start
+${callerGuidance}## Start
 
 Begin by clearing cookies, then proceed straight to the first step's instruction.
 
@@ -14881,7 +14897,8 @@ async function runTrace(featureName, specName, model, validationMode = "lenient"
 	const baseSystemPrompt = buildTraceSystemPrompt({
 		title: spec.title,
 		steps: expanded,
-		sessionName
+		sessionName,
+		...opts.instruction ? { instruction: opts.instruction } : {}
 	});
 	const promptBundle = await loadPromptBundleFromHub(opts.hubContext ?? null, "record");
 	if (promptBundle !== null) meta("prompt", promptBundle.loaded.join(" + "));
@@ -14892,7 +14909,7 @@ async function runTrace(featureName, specName, model, validationMode = "lenient"
 	const statusLines = [];
 	let overallStatus = "passed";
 	const traceActions = [];
-	const stepTracker = createStepTracker();
+	const stepTracker = createStepTracker(opts.onStep);
 	const withStepId = (action, stepId) => {
 		if (!action) return null;
 		return stepId ? {
@@ -15234,15 +15251,18 @@ function groupCountByStep(actions) {
 	}
 	return counts;
 }
-function createStepTracker() {
+function createStepTracker(onChange) {
 	let currentStepId;
+	const advance = (stepId) => {
+		if (stepId === currentStepId) return;
+		currentStepId = stepId;
+		onChange?.(stepId);
+	};
 	return {
 		current: () => currentStepId,
-		fromStepStartLine: (stepId) => {
-			currentStepId = stepId;
-		},
+		fromStepStartLine: advance,
 		fromCommand: (stepId) => {
-			if (stepId) currentStepId = stepId;
+			if (stepId) advance(stepId);
 			return currentStepId;
 		}
 	};
@@ -15500,7 +15520,7 @@ async function runGenerateCli(specPath, opts) {
 //#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 test from a spec: run agent-browser to collect actions (trace), then compile them into runnable code via the spec's target (generate) — a vitest test.spec.ts for agent-browser, a @playwright/test spec for the playwright target. Recording-backed targets only; spec-input targets like runn have no trace step (use `ccqa generate`), and agent-browser live specs need no recording.").optionsGroup("How to record:").option("-m, --model <name>", "Claude model alias ('sonnet'|'opus'|'haiku') or full ID. Overrides CCQA_MODEL.").option("--trace-validation <mode>", "What to do with actions that fail post-trace validation: 'lenient' (default) tags them; 'strict' drops them.", (raw) => {
+const recordCommand = addHubOptions(addProfileOption(addLanguageOption(new Command("record").argument("<feature/spec>", "Spec id in '<feature>/<spec>' form (resolves to .ccqa/features/<feature>/test-cases/<spec>/)").description("Record a test from a spec: run agent-browser to collect actions (trace), then compile them into runnable code via the spec's target (generate) — a vitest test.spec.ts for agent-browser, a @playwright/test spec for the playwright target. Recording-backed targets only; spec-input targets like runn have no trace step (use `ccqa generate`), and agent-browser live specs need no recording.").optionsGroup("How to record:").option("-m, --model <name>", "Claude model alias ('sonnet'|'opus'|'haiku') or full ID. Overrides CCQA_MODEL.").option("--instruction <text>", "Extra guidance for the recording agent — e.g. the drift audit's finding when re-recording a drifted spec.").option("--trace-validation <mode>", "What to do with actions that fail post-trace validation: 'lenient' (default) tags them; 'strict' drops them.", (raw) => {
 	if (VALIDATION_MODES.includes(raw)) return raw;
 	throw new Error(`--trace-validation must be one of ${VALIDATION_MODES.join(" | ")}`);
 }, "lenient").option("--auto-fix <mode>", "Auto-fix behaviour during script generation: 'interactive' (default, prompt y/N; declines on non-TTY), 'auto' (apply without prompt, for CI), 'skip' (agent-browser: apply only high-confidence fixes; external targets like playwright/runn: no fix pass at all).", parseAutoFixFlag, "interactive").option("--auto-fix-max-retries <n>", "Maximum number of auto-fix retries", "3").option("--trace-only", "Stop after the trace step; do not generate test code").option("--no-session-pin", "Don't pin AGENT_BROWSER_SESSION / capture page snapshots after a failure (debug toggle)").optionsGroup("What to do with the result:").option("--overwrite", "Replace an existing test.spec.ts without warning").option("--report-to-hub", "Leave a run (kind: record) on the hub saying this spec was recorded and what the recording spent on Claude, so a budget summed over the hub's runs sees it. It advances no ledger: a recording verifies nothing.").optionsGroup("Learning:").option("--learn-hub-trace-prompt", "After the trace finishes, ask Claude to refresh the \"record.agent\" prompt on the hub from a summary of the run. Requires a hub connection.").optionsGroup("Environment and connection:").option("--cwd <path>", "Working directory containing the .ccqa/ tree (monorepo support). Defaults to the current directory.").option("--project <name>", "Project name for the hub. Defaults to the current directory's name.")))).action(withUsageErrors(async (specPath, opts) => {
@@ -15557,19 +15577,30 @@ async function runRecord(specPath, opts) {
 	if (push) info(`hub: record run opened (${push.runId})`);
 	let recorded = false;
 	let sealed = true;
+	let tracingStep;
+	let killedBy;
 	const teardown = createRunTeardown();
 	teardown.onFinalize(async () => {
-		if (push) sealed = await sealRecordPush(push, featureName, specName, recorded);
+		if (!push) return;
+		const note = killedBy ? `terminated by signal (${killedBy})${tracingStep ? ` during ${tracingStep}` : ""}` : void 0;
+		sealed = await sealRecordPush(push, featureName, specName, recorded, note);
+	});
+	const disposeSignalHandlers = installTeardownSignalHandlers(teardown, (sig) => {
+		killedBy = sig;
 	});
-	const disposeSignalHandlers = installTeardownSignalHandlers(teardown);
 	try {
 		let traceResult = null;
 		let generated = true;
 		try {
 			traceResult = await runTrace(featureName, specName, opts.model, opts.traceValidation ?? "lenient", language, {
 				cwd: cwdForProfile,
-				hubContext
+				hubContext,
+				...opts.instruction ? { instruction: opts.instruction } : {},
+				onStep: (stepId) => {
+					tracingStep = stepId;
+				}
 			});
+			tracingStep = void 0;
 			blank();
 			if (!opts.traceOnly) generated = (await runGenerate(featureName, specName, {
 				maxRetries: parseInt(opts.autoFixMaxRetries ?? "3", 10),
@@ -15608,15 +15639,23 @@ async function runRecord(specPath, opts) {
 * Close the record run with the one row this command produced, answering
 * whether it closed. One spec is recorded per invocation, so one row is the
 * whole run — enough for the runs list to say what the money bought.
+*
+* `failureNote` (e.g. "terminated by signal (SIGTERM) during step-03") rides
+* in the row's `failureLogExcerpt` — the field a failed `ccqa run` row already
+* uses for its failure text — so the hub says why a recording died instead of
+* a bare status:"failed". Ignored on a successful recording.
 */
-async function sealRecordPush(push, featureName, specName, recorded) {
+async function sealRecordPush(push, featureName, specName, recorded, failureNote) {
 	return sealHubRun(push, {
-		rows: [emptySpecRow({
-			feature: featureName,
-			spec: specName,
-			title: null,
-			status: recorded ? "passed" : "failed"
-		})],
+		rows: [{
+			...emptySpecRow({
+				feature: featureName,
+				spec: specName,
+				title: null,
+				status: recorded ? "passed" : "failed"
+			}),
+			...!recorded && failureNote ? { failureLogExcerpt: failureNote } : {}
+		}],
 		reportMeta: {
 			git: {
 				head: push.gitHead,
@@ -17457,6 +17496,7 @@ function gradedDriftEntry(ledger, key, runId, label) {
 	};
 	if (label === null) {
 		delete graded.surface;
+		delete graded.subDiagnosis;
 		delete graded.headline;
 		delete graded.confidence;
 	}
@@ -17821,9 +17861,11 @@ async function updateDriftLedger(storage, run, results) {
 		if (row.status === "skipped") continue;
 		const key = `${row.feature}/${row.spec}`;
 		const diagnosis = row.analysis ? normalizeDiagnosis(row.analysis) : null;
+		const subDiagnosis = DriftSubDiagnosisSchema.safeParse(diagnosis?.subDiagnosis);
 		ledger.specs[key] = {
 			label: diagnosis ? diagnosis.label : null,
 			surface: diagnosis?.surface,
+			subDiagnosis: subDiagnosis.success ? subDiagnosis.data : void 0,
 			specChangeKind: diagnosis?.specChangeKind,
 			confidence: diagnosis?.confidence,
 			headline: diagnosis?.headline,

package/dist/hub-client/index.d.mts

@@ -383,6 +383,11 @@ declare const DriftLedgerResponseSchema: z.ZodObject<{
       spec: "spec";
       generated: "generated";
     }>>;
+    subDiagnosis: z.ZodOptional<z.ZodEnum<{
+      OVER_ASSERTION: "OVER_ASSERTION";
+      SELECTOR_DRIFT: "SELECTOR_DRIFT";
+      NONE: "NONE";
+    }>>;
     specChangeKind: z.ZodOptional<z.ZodEnum<{
       FEATURE_REMOVED: "FEATURE_REMOVED";
       BEHAVIOUR_CHANGED: "BEHAVIOUR_CHANGED";

package/dist/package.json

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

package/package.json

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