ccqa 0.8.3 → 0.9.1

package/README.md

@@ -94,6 +94,7 @@ ccqa run --changed --report                    # only specs whose relatedPaths t
 ## Commands
 
 ```
+ccqa init                          Scaffold .ccqa/prompts/{live,record}.{user,agent}.md templates
 ccqa draft [feature/spec]          Co-author a test spec with Claude
 ccqa perspectives                  Inventory existing test coverage into .ccqa/perspectives.yaml
 ccqa record <feature/spec>         (deterministic specs only) Trace browser actions + generate test.spec.ts
@@ -114,6 +115,7 @@ ccqa drift [feature/spec]          Standalone spec ↔ codebase static audit (fo
 - `--retry <n>` — (live specs only) retry each failing step up to N more times
 - `--format <fmt>` — `text` (default), `json` (report.json), `github` (Actions annotations)
 - `--out <dir>` — (live specs only, single-spec invocations) override the per-run artifact directory
+- `--update-agent-prompt` — (live specs only) after the run, summarise it back to Claude and rewrite `.ccqa/prompts/live.agent.md` so the next run inherits the lessons learned. `ccqa record` ships the same flag, refreshing `record.agent.md` from the trace summary.
 
 All Claude-driven commands accept `-m, --model <name>` (alias `sonnet` | `opus` | `haiku`, or a full model ID). The flag overrides `CCQA_MODEL`; when both are unset, the Claude Code CLI default is used. They also accept `--language <bcp47>` (e.g. `ja`, `en`) to set the language of human-readable output; the default `auto` follows the language of the spec/codebase. `--cwd <path>` works on `record` / `run` / `drift` so you can target a subpackage inside a monorepo from the repo root. Interactive commands authenticate via your local Claude Code login; commands that talk to Claude in CI (`ccqa run --report`, `ccqa drift`) additionally honor `ANTHROPIC_API_KEY`.
 
@@ -125,9 +127,11 @@ All Claude-driven commands accept `-m, --model <name>` (alias `sonnet` | `opus`
 .ccqa/
   perspectives.yaml              # Inventory of existing coverage (machine-readable, canonical)
   perspectives.md                # Category index, regenerated from the YAML
-  prompts/
-    trace.user.md                # Project-specific guidance appended to `ccqa record` (trace phase)
-    run-nd.user.md               # Project-specific guidance appended to `ccqa run` (live specs)
+  prompts/                       # Run `ccqa init` to scaffold these
+    record.user.md               # Human-maintained guidance appended to `ccqa record` (trace phase)
+    record.agent.md              # Auto-updated by `ccqa record --update-agent-prompt`
+    live.user.md                 # Human-maintained guidance appended to `ccqa run` (live specs)
+    live.agent.md                # Auto-updated by `ccqa run --update-agent-prompt`
   blocks/
     login/
       spec.yaml                  # Reusable block (params + steps)
@@ -175,11 +179,16 @@ ccqa run --retry 2 tasks/create-and-complete
 
 Constraints on selectors / `agent-browser` subcommands that apply during `ccqa record` (no `eval`, no `@ref`, no bare-tag positional `find`, no chained agent-browser calls) are **relaxed** for live specs — Claude can use any subcommand and any selector style because there is no replay contract to honour.
 
-### Per-project guidance (`.ccqa/prompts/run-nd.user.md`)
+### Per-project guidance (`.ccqa/prompts/live.user.md` + `live.agent.md`)
 
-ccqa's live-mode system prompt is deliberately product-agnostic. Anything specific to **your** project — staging URLs, login flow quirks, rich-editor types, common access-denied wording — belongs in `.ccqa/prompts/run-nd.user.md`. The file is read once per invocation and appended to the system prompt under a "Project-specific guidance" heading.
+ccqa's live-mode system prompt is deliberately product-agnostic. Anything specific to **your** project — staging URLs, login flow quirks, rich-editor types, common access-denied wording — belongs in two sibling files (run `ccqa init` to scaffold both):
 
-Keep it short. A page or two of focused notes beats a long handbook — Claude has the spec's `expected` text to work from, the file is for the *non-obvious* product knowledge that isn't in any single spec. Examples of what's useful here:
+- `.ccqa/prompts/live.user.md` — human-maintained stable guidance.
+- `.ccqa/prompts/live.agent.md` — auto-updated by `ccqa run --update-agent-prompt` from each run's summary. You can hand-edit it, but the next `--update-agent-prompt` run may rewrite the whole file; durable rules should live in `live.user.md`.
+
+Both files (when present) are read once per invocation and appended to the system prompt under "Project-specific guidance". The `ccqa record` (trace) side has the same split: `record.user.md` + `record.agent.md`, refreshed by `ccqa record --update-agent-prompt`.
+
+Keep them short. A page or two of focused notes beats a long handbook — Claude has the spec's `expected` text to work from, these files are for the *non-obvious* product knowledge that isn't in any single spec. Examples of what's useful here:
 
 - "the rich text editor is `[contenteditable='true']` — use `fill`, not keystrokes"
 - "login redirects through an IDP service-selection screen; you can skip it by opening the destination URL directly"
@@ -189,9 +198,9 @@ Examples of what does **not** belong:
 
 - per-spec details (those belong in the spec's `instruction` / `expected`)
 - restating the STEP_RESULT contract (already in the system prompt)
-- copy-pasted style guidelines from `trace.user.md` (the relaxed-constraint mode doesn't need them)
+- copy-pasted style guidelines from `record.user.md` (the relaxed-constraint mode doesn't need them)
 
-The file is capped at 32 KiB; anything beyond that is truncated with a warning.
+The combined bundle is capped at 32 KiB; anything beyond that is truncated with a warning.
 
 ## License
 

package/dist/bin/ccqa.mjs

@@ -480,50 +480,62 @@ async function loadAvailableBlocks(cwd) {
 		}))
 	}));
 }
-const TRACE_USER_PROMPT_PATH = ".ccqa/prompts/trace.user.md";
-const RUN_ND_USER_PROMPT_PATH = ".ccqa/prompts/run-nd.user.md";
+const RECORD_USER_PROMPT_PATH = ".ccqa/prompts/record.user.md";
+const RECORD_AGENT_PROMPT_PATH = ".ccqa/prompts/record.agent.md";
+const LIVE_USER_PROMPT_PATH = ".ccqa/prompts/live.user.md";
+const LIVE_AGENT_PROMPT_PATH = ".ccqa/prompts/live.agent.md";
 const USER_PROMPT_MAX_BYTES = 32768;
 /**
-* Load project-specific guidance to append to the trace system prompt.
+* Load the prompt bundle appended to the `ccqa record` (trace) system prompt.
 *
-* Returns the file's contents (trimmed) when `.ccqa/prompts/trace.user.md`
-* exists and is non-empty. Missing file, empty file, or read error all
-* resolve to `null` so callers can treat the override as strictly optional.
+* Reads `.ccqa/prompts/record.user.md` (human-maintained, stable project
+* rules) and `.ccqa/prompts/record.agent.md` (auto-rewritten by
+* `ccqa record --update-agent-prompt`). Returns null when both files are
+* missing / empty. The combined text is capped at 32 KiB after concatenation.
 *
-* The file is meant for organisation-specific rules that don't belong in
-* the OSS-default prompt — naming conventions, staging URL hints, repeated
-* UI quirks that recur across specs. Anything that genuinely belongs in
-* one spec should go in that spec's instruction, not here.
-*
-* Size-capped at 32 KiB to keep accidental commits of huge files from
-* blowing up the system prompt; the cap is observable to callers as a
-* truncated warning suffix.
+* Use `ccqa init` to scaffold both files.
 */
-async function loadTraceUserPrompt(cwd) {
-	return loadUserPromptFile(TRACE_USER_PROMPT_PATH, cwd, "trace.user.md");
+async function loadRecordPromptBundle(cwd) {
+	return loadPromptBundle(RECORD_USER_PROMPT_PATH, RECORD_AGENT_PROMPT_PATH, cwd);
 }
 /**
-* Load project-specific guidance to append to the `ccqa run-nd` system prompt.
+* Load the prompt bundle appended to the `ccqa run` (live mode) system prompt.
 *
-* Same shape as `loadTraceUserPrompt`, but reads from
-* `.ccqa/prompts/run-nd.user.md`. The non-deterministic test mode delegates
-* every step to Claude live, so anything that helps Claude do that job for a
-* particular product — domain glossary, staging URL conventions, known
-* "this is fine" warnings, login flow quirks — belongs here. Keeping it in the
+* Reads `.ccqa/prompts/live.user.md` (human-maintained, stable project
+* rules) and `.ccqa/prompts/live.agent.md` (auto-rewritten by
+* `ccqa run --update-agent-prompt`). Same null / cap semantics as
+* `loadRecordPromptBundle`. Keeping product-specific context in the
 * consuming repo (not the ccqa OSS prompt) is the explicit non-contamination
-* boundary: ccqa stays product-agnostic, projects can layer in whatever
-* context they need.
+* boundary.
 */
-async function loadRunNdUserPrompt(cwd) {
-	return loadUserPromptFile(RUN_ND_USER_PROMPT_PATH, cwd, "run-nd.user.md");
+async function loadLivePromptBundle(cwd) {
+	return loadPromptBundle(LIVE_USER_PROMPT_PATH, LIVE_AGENT_PROMPT_PATH, cwd);
+}
+async function loadPromptBundle(userRelPath, agentRelPath, cwd) {
+	const [userText, agentText] = await Promise.all([readPromptFile(userRelPath, cwd), readPromptFile(agentRelPath, cwd)]);
+	if (userText === null && agentText === null) return null;
+	const sections = [];
+	const loaded = [];
+	if (userText !== null) {
+		sections.push(`### Project guidance (human-maintained)\n\n${userText}`);
+		loaded.push(userRelPath);
+	}
+	if (agentText !== null) {
+		sections.push(`### Agent learnings (auto-updated by ccqa --update-agent-prompt)\n\n${agentText}`);
+		loaded.push(agentRelPath);
+	}
+	let text = sections.join("\n\n");
+	if (text.length > USER_PROMPT_MAX_BYTES) text = text.slice(0, USER_PROMPT_MAX_BYTES) + `\n\n[ccqa] (prompt bundle truncated at ${USER_PROMPT_MAX_BYTES} bytes)`;
+	return {
+		text,
+		loaded
+	};
 }
-async function loadUserPromptFile(relPath, cwd, labelForTruncation) {
+async function readPromptFile(relPath, cwd) {
 	const content = await readFile(join(cwd ?? process.cwd(), relPath), "utf-8").catch(() => null);
 	if (content === null) return null;
 	const trimmed = content.trim();
-	if (trimmed.length === 0) return null;
-	if (trimmed.length > USER_PROMPT_MAX_BYTES) return trimmed.slice(0, USER_PROMPT_MAX_BYTES) + `\n\n[ccqa] (${labelForTruncation} truncated at ${USER_PROMPT_MAX_BYTES} bytes)`;
-	return trimmed;
+	return trimmed.length === 0 ? null : trimmed;
 }
 /**
 * Probe for orphaned files left over from earlier ccqa versions inside
@@ -567,9 +579,9 @@ async function getTestScript(featureName, specName, cwd) {
 }
 /**
 * Variant of `listAllSpecs` for callers that care about the spec definition
-* itself (spec.yaml) rather than its compiled vitest script. `ccqa run-nd`
-* uses this because it skips codegen entirely — a freshly drafted spec with
-* no `test.spec.ts` is still a valid target.
+* itself (spec.yaml) rather than its compiled vitest script. `ccqa run` uses
+* this for live-mode specs because they skip codegen entirely — a freshly
+* drafted spec with no `test.spec.ts` is still a valid target.
 */
 async function listAllSpecsWithSpecFile(cwd) {
 	return listAllSpecsFilteredBy(SPEC_FILE, cwd);
@@ -589,10 +601,10 @@ async function listAllSpecsFilteredBy(requiredFilename, cwd) {
 	}))).flat();
 }
 /**
-* Resolve a CLI `<target>` argument into a list of spec refs. Shared between
-* `ccqa run` and `ccqa run-nd`. Callers pass the right enumerator for "no
-* target" (run wants `test.spec.ts`-having specs; run-nd wants `spec.yaml`-
-* having specs).
+* Resolve a CLI `<target>` argument into a list of spec refs. Used by
+* `ccqa run`. Callers pass the right enumerator for "no target" (deterministic
+* specs want `test.spec.ts`-having specs; live specs want `spec.yaml`-having
+* specs).
 */
 async function resolveSpecTargets(target, enumerateAll, cwd) {
 	if (!target) return enumerateAll();
@@ -2324,7 +2336,7 @@ function clamp(n, lo, hi) {
 //#endregion
 //#region src/report/prompt.ts
 function buildFailureAnalysisPrompt(input) {
-	const { script, specYaml, failureLog, ndTranscriptExcerpt, diffPatch, changedFiles, baseRef, driftIssues, outputLanguage = "auto" } = input;
+	const { script, specYaml, failureLog, liveTranscriptExcerpt, diffPatch, changedFiles, baseRef, driftIssues, outputLanguage = "auto" } = input;
 	return `You are analyzing a failing E2E regression test right after a source change landed. Your job is a root-cause CALL, not a fix: decide which of three categories explains the failure, using the source diff as your primary context.
 
 ${outputLanguageBlock(outputLanguage, "`reasoning`, `detail`", "label names (TEST_DRIFT, etc.)")}## The three categories
@@ -2396,7 +2408,7 @@ Evidence rules: TEST_DRIFT and SPEC_CHANGE require at least one concrete \`file\
 ## Test Spec (spec.yaml)
 ${specYaml}
 
-${buildExecutionEvidenceBlock(script, failureLog, ndTranscriptExcerpt)}
+${buildExecutionEvidenceBlock(script, failureLog, liveTranscriptExcerpt)}
 
 ${diffPatch ? `## Source changes since ${baseRef ?? "base"} (git diff, may be truncated)
 
@@ -2432,14 +2444,14 @@ ${driftIssues.map((i) => `- [${i.severity}] (${DRAFT_CATEGORY_LABEL[i.category]}
 * never has to branch on mode — it just sees "here's what was executed
 * and here's how it failed".
 */
-function buildExecutionEvidenceBlock(script, failureLog, ndTranscriptExcerpt) {
+function buildExecutionEvidenceBlock(script, failureLog, liveTranscriptExcerpt) {
 	const sections = [];
 	if (script && script.length > 0) sections.push(`## Test Script (with line numbers)
 ${numberLines(script)}`);
 	if (failureLog && failureLog.length > 0) sections.push(`## Failure Log
 ${failureLog.slice(0, 8e3)}`);
-	if (ndTranscriptExcerpt && ndTranscriptExcerpt.length > 0) sections.push(`## Live Run Transcript (summary of Claude's per-step execution)
-${ndTranscriptExcerpt}`);
+	if (liveTranscriptExcerpt && liveTranscriptExcerpt.length > 0) sections.push(`## Live Run Transcript (summary of Claude's per-step execution)
+${liveTranscriptExcerpt}`);
 	if (sections.length === 0) return `## Execution evidence
 
 (No script, failure log, or live transcript was captured for this run. Classify from spec.yaml + diff only, and be correspondingly more conservative — prefer UNKNOWN over a confident call.)`;
@@ -2535,11 +2547,11 @@ const ReportEvidenceSchema = z.object({
 	failureSummary: z.string().nullable().default(null)
 });
 /**
-* Per-step row for a non-deterministic run (`ccqa run-nd`). Mirrors the
-* structure produced by `src/runtime/nd-executor.ts:NdStepResult` but
+* Per-step row for a live-mode run (spec.yaml `mode: live`). Mirrors the
+* structure produced by `src/runtime/live-executor.ts:LiveStepResult` but
 * encoded against the report schema so the HTML renderer can carry both
-* deterministic (`evidence`) and non-deterministic (`ndRun`) sources of
-* step-boundary screenshots.
+* deterministic (`evidence`) and live (`liveRun`) sources of step-boundary
+* screenshots.
 *
 * `beforePng` / `afterPng` are RELATIVE to the HTML report directory — the
 * caller computes the relative path with `node:path`'s `relative()` so the
@@ -2554,7 +2566,7 @@ const ReportEvidenceSchema = z.object({
 * `models` is the union of model ids the SDK reported using; usually a
 * single element, but the SDK can fan out across models in some modes.
 */
-const NdReportCostSchema = z.object({
+const LiveReportCostSchema = z.object({
 	totalCostUsd: z.number().nullable(),
 	durationApiMs: z.number().nullable(),
 	numTurns: z.number().nullable(),
@@ -2564,7 +2576,7 @@ const NdReportCostSchema = z.object({
 	outputTokens: z.number().nullable(),
 	models: z.array(z.string())
 });
-const NdReportStepSchema = z.object({
+const LiveReportStepSchema = z.object({
 	stepId: z.string(),
 	source: z.string(),
 	instruction: z.string(),
@@ -2578,15 +2590,15 @@ const NdReportStepSchema = z.object({
 	beforePng: z.string().nullable(),
 	afterPng: z.string().nullable(),
 	durationMs: z.number(),
-	cost: NdReportCostSchema
+	cost: LiveReportCostSchema
 });
-const NdReportRunSchema = z.object({
+const LiveReportRunSchema = z.object({
 	runId: z.string(),
 	sessionName: z.string(),
 	startedAt: z.string(),
 	durationMs: z.number(),
-	steps: z.array(NdReportStepSchema),
-	cost: NdReportCostSchema
+	steps: z.array(LiveReportStepSchema),
+	cost: LiveReportCostSchema
 });
 const ReportSpecResultSchema = z.object({
 	feature: z.string(),
@@ -2607,7 +2619,7 @@ const ReportSpecResultSchema = z.object({
 	diffExcerpt: z.string().nullable(),
 	specYaml: z.string().nullable(),
 	evidence: z.array(ReportEvidenceSchema).nullable(),
-	ndRun: NdReportRunSchema.nullable()
+	liveRun: LiveReportRunSchema.nullable()
 });
 z.object({
 	schemaVersion: z.literal(1),
@@ -2846,7 +2858,7 @@ function scopePatchForSpec(patch, relatedPaths, caps = {}) {
 	return parts.join("\n");
 }
 //#endregion
-//#region src/runtime/nd-cost-format.ts
+//#region src/runtime/live-cost-format.ts
 /**
 * Compact one-line cost summary. Format:
 *   "$0.1234 · 4 turns · 42 in / 6,511 out · 2.0M cached · sonnet"
@@ -2856,7 +2868,7 @@ function scopePatchForSpec(patch, relatedPaths, caps = {}) {
 * `model=...` segment. `compact: true` (HTML chip) thousand-separates fresh
 * tokens, abbreviates cache-read with K/M, drops the `model=` prefix.
 */
-function formatNdCost(cost, options) {
+function formatLiveCost(cost, options) {
 	if (cost.totalCostUsd === null) return null;
 	const compact = options.compact;
 	const sep = compact ? " · " : " / ";
@@ -2875,7 +2887,7 @@ function formatNdCost(cost, options) {
 * Sum of per-spec costs for a batch. Used only by the CLI batch summary.
 * Returns null when no spec has cost data.
 */
-function formatNdBatchCost(costs) {
+function formatLiveBatchCost(costs) {
 	let totalUsd = 0;
 	let seen = false;
 	let totalIn = 0;
@@ -3176,7 +3188,7 @@ function renderResult(r, index, s) {
 	const heading = r.title ? `<span class="spec-title">${esc(r.title)}</span><span class="spec-slug">(${esc(id)})</span>` : `<span class="spec-title">${esc(id)}</span>`;
 	const predictionLine = r.status === "failed" && r.analysis ? `<span class="label-text label-${r.analysis.label}">${esc(displayLabel(r.analysis.label, s))} · ${Math.round(r.analysis.confidence * 100)}%</span>` : "";
 	const needsGradingDot = r.status === "failed" && r.analysis ? `<span class="needs-grading-dot" data-case-id="${esc(id)}" title="${esc(s.needsGrading)}"></span>` : "";
-	const modeTag = r.ndRun ? `<span class="mode-tag" title="executed in live mode (Claude drove the browser per step)">LIVE</span>` : `<span class="mode-tag" title="executed in deterministic mode (vitest replayed test.spec.ts)">DETERMINISTIC</span>`;
+	const modeTag = r.liveRun ? `<span class="mode-tag" title="executed in live mode (Claude drove the browser per step)">LIVE</span>` : `<span class="mode-tag" title="executed in deterministic mode (vitest replayed test.spec.ts)">DETERMINISTIC</span>`;
 	return `<details class="spec ${r.status}" data-status="${r.status}" data-case-id="${esc(id)}"${r.status === "failed" ? " open" : ""}>
   <summary>
     ${statusIcon(r.status)}
@@ -3189,7 +3201,7 @@ function renderResult(r, index, s) {
   </summary>
   <div class="spec-body">
     ${renderEvidence(r, s)}
-    ${r.ndRun ? renderNdRun(r.ndRun, s) : ""}
+    ${r.liveRun ? renderLiveRun(r.liveRun, s) : ""}
     ${renderSpecBody(r, index, s)}
     ${collapsible(s.collSpecYaml, s.collSpecYamlHelp, r.specYaml)}
   </div>
@@ -3200,16 +3212,16 @@ function renderSpecBody(r, index, s) {
 	if (r.analysis) return renderAnalysis(r, index, s);
 	return renderSkippedWithSupporting(r, s);
 }
-function renderNdRun(nd, strings) {
-	const stepItems = nd.steps.map((s) => {
+function renderLiveRun(live, strings) {
+	const stepItems = live.steps.map((s) => {
 		const before = s.beforePng ? `<a class="shot" href="${esc(s.beforePng)}" target="_blank" rel="noopener"><img src="${esc(s.beforePng)}" alt="before ${esc(s.stepId)}" loading="lazy"><span>before</span></a>` : "";
 		const after = s.afterPng ? `<a class="shot" href="${esc(s.afterPng)}" target="_blank" rel="noopener"><img src="${esc(s.afterPng)}" alt="after ${esc(s.stepId)}" loading="lazy"><span>after</span></a>` : "";
 		const dur = s.durationMs > 0 ? `<span class="duration">${formatDuration$1(s.durationMs)}</span>` : "";
-		const stepCost = formatNdCostChip(s.cost);
+		const stepCost = formatLiveCostChip(s.cost);
 		const stepModel = formatModelChip(s.cost.models);
-		const sourceBadge = s.source && s.source !== "spec" ? `<span class="nd-source">[${esc(s.source)}]</span>` : "";
-		return `<li class="nd-step ${s.status}">
-        <div class="nd-step-head">
+		const sourceBadge = s.source && s.source !== "spec" ? `<span class="live-source">[${esc(s.source)}]</span>` : "";
+		return `<li class="live-step ${s.status}">
+        <div class="live-step-head">
           ${statusIcon(s.status)}
           <span class="step-name">${esc(s.stepId)}</span>
           ${sourceBadge}
@@ -3218,44 +3230,44 @@ function renderNdRun(nd, strings) {
           ${stepCost}
           ${dur}
         </div>
-        <div class="nd-step-body">
-          <p class="nd-instr"><strong>${esc(strings.stepDoLabel)}:</strong> ${esc(s.instruction)}</p>
-          <p class="nd-instr"><strong>${esc(strings.stepExpectLabel)}:</strong> ${esc(s.expected)}</p>
-          ${s.reasoning ? `<p class="nd-reasoning">${esc(s.reasoning)}</p>` : ""}
-          ${before || after ? `<div class="nd-shots">${before}${after}</div>` : ""}
+        <div class="live-step-body">
+          <p class="live-instr"><strong>${esc(strings.stepDoLabel)}:</strong> ${esc(s.instruction)}</p>
+          <p class="live-instr"><strong>${esc(strings.stepExpectLabel)}:</strong> ${esc(s.expected)}</p>
+          ${s.reasoning ? `<p class="live-reasoning">${esc(s.reasoning)}</p>` : ""}
+          ${before || after ? `<div class="live-shots">${before}${after}</div>` : ""}
         </div>
       </li>`;
 	}).join("\n");
-	const runCost = formatNdCostChip(nd.cost);
-	const runModel = formatModelChip(nd.cost.models);
-	return `<section class="nd-run">
-    <details class="nd-run-meta">
+	const runCost = formatLiveCostChip(live.cost);
+	const runModel = formatModelChip(live.cost.models);
+	return `<section class="live-run">
+    <details class="live-run-meta">
       <summary>${labelWithHelp(esc(strings.collLiveRunMeta), strings.collLiveRunMetaHelp)}</summary>
-      <div class="nd-run-meta-body">
+      <div class="live-run-meta-body">
         <span class="dim">${esc(strings.liveRunIdLabel)}</span>
-        <code>${esc(nd.runId)}</code>
+        <code>${esc(live.runId)}</code>
         <span class="dim">${esc(strings.liveSessionLabel)}</span>
-        <code>${esc(nd.sessionName)}</code>
+        <code>${esc(live.sessionName)}</code>
         ${runModel}
         ${runCost}
-        <span class="duration">${formatDuration$1(nd.durationMs)}</span>
+        <span class="duration">${formatDuration$1(live.durationMs)}</span>
       </div>
     </details>
-    <ol class="nd-steps">${stepItems}</ol>
+    <ol class="live-steps">${stepItems}</ol>
   </section>`;
 }
 /** Compact dot-separated cost chip, e.g. "$0.1234 · 4 turns · 42 in / 6,511 out · 2.0M cached". */
-function formatNdCostChip(cost) {
-	const line = formatNdCost(cost, { compact: true });
+function formatLiveCostChip(cost) {
+	const line = formatLiveCost(cost, { compact: true });
 	if (line === null) return "";
-	return `<span class="nd-cost" title="cost · turns · fresh-input/output tokens · cache-read input">${esc(line)}</span>`;
+	return `<span class="live-cost" title="cost · turns · fresh-input/output tokens · cache-read input">${esc(line)}</span>`;
 }
 function formatModelChip(models) {
 	if (!models || models.length === 0) return "";
-	return `<span class="nd-model" title="Claude model id(s) reported by the SDK">${esc(models.join(", "))}</span>`;
+	return `<span class="live-model" title="Claude model id(s) reported by the SDK">${esc(models.join(", "))}</span>`;
 }
 /**
-* Per-step UI for deterministic runs. Adopts the same `nd-step` card layout
+* Per-step UI for deterministic runs. Adopts the same `live-step` card layout
 * used by live runs so reviewers don't have to context-switch between two
 * visual idioms. We map the evidence entries (which are already keyed by
 * stepId) onto the same shape, leaving live-only fields (before png, cost,
@@ -3263,14 +3275,14 @@ function formatModelChip(models) {
 */
 function renderEvidence(r, s) {
 	if (!r.evidence || r.evidence.length === 0) return "";
-	return `<section class="nd-run">
-    <ol class="nd-steps">${r.evidence.map((e) => renderDetStepCard(e, s)).join("\n")}</ol>
+	return `<section class="live-run">
+    <ol class="live-steps">${r.evidence.map((e) => renderDetStepCard(e, s)).join("\n")}</ol>
   </section>`;
 }
 function renderDetStepCard(e, s) {
 	const status = e.status === "failed" ? "failed" : "passed";
-	const description = e.description ? `<p class="nd-instr"><strong>${esc(s.stepExpectLabel)}:</strong> ${esc(e.description)}</p>` : "";
-	const failureBlock = e.status === "failed" && e.failureSummary ? `<p class="nd-reasoning">${esc(e.failureSummary)}</p>` : "";
+	const description = e.description ? `<p class="live-instr"><strong>${esc(s.stepExpectLabel)}:</strong> ${esc(e.description)}</p>` : "";
+	const failureBlock = e.status === "failed" && e.failureSummary ? `<p class="live-reasoning">${esc(e.failureSummary)}</p>` : "";
 	const metaRows = [];
 	if (e.url) {
 		const shortUrl = shortenUrl(e.url);
@@ -3279,16 +3291,16 @@ function renderDetStepCard(e, s) {
 	if (e.title) metaRows.push(`<div class="evidence-meta-row"><span class="evidence-meta-label">${esc(s.metaPage)}</span><span class="evidence-meta-value">${esc(e.title)}</span></div>`);
 	const meta = metaRows.length > 0 ? `<div class="evidence-meta">${metaRows.join("")}</div>` : "";
 	const after = `<a class="shot" href="${esc(e.pngPath)}" target="_blank" rel="noopener"><img src="${esc(e.pngPath)}" alt="${esc(e.stepId)}" loading="lazy"><span>after</span></a>`;
-	return `<li class="nd-step ${status}">
-    <div class="nd-step-head">
+	return `<li class="live-step ${status}">
+    <div class="live-step-head">
       ${statusIcon(status)}
       <span class="step-name">${esc(e.stepId)}</span>
       <span class="spacer"></span>
     </div>
-    <div class="nd-step-body">
+    <div class="live-step-body">
       ${description}
       ${failureBlock}
-      <div class="nd-shots">${after}</div>
+      <div class="live-shots">${after}</div>
       ${meta}
     </div>
   </li>`;
@@ -3726,54 +3738,54 @@ table.matrix td.miss-nonzero { background: var(--fail-bg); }
 
 /* Per-step block: indented + a thin rail under the test title so the
    hierarchy spec → test → step is visible. */
-.nd-run {
+.live-run {
   padding: 0 0 0 14px;
   margin-left: 6px;
   border-left: 1px solid var(--border-soft);
 }
-.nd-run-meta { margin: 0 0 8px; font-size: 11.5px; }
-.nd-run-meta > summary {
+.live-run-meta { margin: 0 0 8px; font-size: 11.5px; }
+.live-run-meta > summary {
   cursor: pointer; color: var(--text-mute); list-style: none;
   padding: 4px 0;
 }
-.nd-run-meta > summary::-webkit-details-marker { display: none; }
-.nd-run-meta > summary::before {
+.live-run-meta > summary::-webkit-details-marker { display: none; }
+.live-run-meta > summary::before {
   content: "▸"; color: var(--text-dim); font-size: 10px;
   margin-right: 6px; transition: transform 0.12s ease;
   display: inline-block;
 }
-.nd-run-meta[open] > summary::before { transform: rotate(90deg); }
-.nd-run-meta-body {
+.live-run-meta[open] > summary::before { transform: rotate(90deg); }
+.live-run-meta-body {
   display: flex; gap: 12px; align-items: baseline; flex-wrap: wrap;
   color: var(--text-mute); padding: 6px 0 8px 16px;
 }
-.nd-run-meta-body code { background: transparent; padding: 0; font-size: 11.5px; color: var(--text-dim); }
-.nd-run-meta-body .dim { color: var(--text-mute); }
+.live-run-meta-body code { background: transparent; padding: 0; font-size: 11.5px; color: var(--text-dim); }
+.live-run-meta-body .dim { color: var(--text-mute); }
 
 /* Steps: flat list. The separator between steps has to outweigh anything
    *inside* a step (e.g. evidence-meta footer) so the eye finds the
    step boundary at a glance — hence a solid var(--border), not the
    softer hairline used inside the step body. */
-.nd-steps { list-style: none; padding: 0; margin: 0; display: flex; flex-direction: column; gap: 0; }
-.nd-step { border-top: 1px solid var(--border); padding: 16px 0; background: transparent; }
-.nd-step:first-child { border-top: 0; padding-top: 0; }
-.nd-step.skipped { opacity: 0.55; }
-.nd-step-head { display: flex; align-items: baseline; gap: 8px; padding: 0; background: transparent; border-bottom: 0; font-size: 13px; margin-bottom: 6px; }
-.nd-step-body { padding: 0; font-size: 12.5px; line-height: 1.55; }
-.nd-step-body p { margin: 4px 0; }
-.nd-instr strong { color: var(--text-mute); font-weight: 600; margin-right: 4px; font-size: 11px; letter-spacing: 0.04em; text-transform: uppercase; }
+.live-steps { list-style: none; padding: 0; margin: 0; display: flex; flex-direction: column; gap: 0; }
+.live-step { border-top: 1px solid var(--border); padding: 16px 0; background: transparent; }
+.live-step:first-child { border-top: 0; padding-top: 0; }
+.live-step.skipped { opacity: 0.55; }
+.live-step-head { display: flex; align-items: baseline; gap: 8px; padding: 0; background: transparent; border-bottom: 0; font-size: 13px; margin-bottom: 6px; }
+.live-step-body { padding: 0; font-size: 12.5px; line-height: 1.55; }
+.live-step-body p { margin: 4px 0; }
+.live-instr strong { color: var(--text-mute); font-weight: 600; margin-right: 4px; font-size: 11px; letter-spacing: 0.04em; text-transform: uppercase; }
 
 /* Reasoning: left rail, no fill. */
-.nd-reasoning { color: var(--text-dim); font-style: italic; background: transparent; padding: 4px 0 4px 12px; border-left: 2px solid var(--fail); border-radius: 0; margin: 6px 0; }
-.nd-step.passed .nd-reasoning { border-left-color: var(--border); color: var(--text-mute); font-style: normal; }
+.live-reasoning { color: var(--text-dim); font-style: italic; background: transparent; padding: 4px 0 4px 12px; border-left: 2px solid var(--fail); border-radius: 0; margin: 6px 0; }
+.live-step.passed .live-reasoning { border-left-color: var(--border); color: var(--text-mute); font-style: normal; }
 
-.nd-source { font-size: 11px; color: var(--text-mute); }
-.nd-shots { display: flex; gap: 12px; margin-top: 10px; flex-wrap: wrap; }
-.nd-shots .shot { display: flex; flex-direction: column; align-items: center; gap: 4px; text-decoration: none; color: var(--text-mute); font-size: 10px; letter-spacing: 0.08em; }
-.nd-shots .shot img { max-width: 280px; max-height: 180px; border: 1px solid var(--border-soft); border-radius: 3px; object-fit: contain; background: #000; }
+.live-source { font-size: 11px; color: var(--text-mute); }
+.live-shots { display: flex; gap: 12px; margin-top: 10px; flex-wrap: wrap; }
+.live-shots .shot { display: flex; flex-direction: column; align-items: center; gap: 4px; text-decoration: none; color: var(--text-mute); font-size: 10px; letter-spacing: 0.08em; }
+.live-shots .shot img { max-width: 280px; max-height: 180px; border: 1px solid var(--border-soft); border-radius: 3px; object-fit: contain; background: #000; }
 
 /* Cost / model chips: muted text, no fill. */
-.nd-cost, .nd-model {
+.live-cost, .live-model {
   font-size: 11px; padding: 0;
   background: transparent;
   color: var(--text-mute);
@@ -4249,7 +4261,7 @@ function formatAgentBrowserUnavailableMessage() {
 //#region src/cli/preflight.ts
 /**
 * Shared startup steps for every command that drives a real `agent-browser`
-* (currently `ccqa trace` and `ccqa run-nd`):
+* (currently `ccqa record` (trace) and `ccqa run` (live mode)):
 *
 *   1. Verify the peer-installed agent-browser binary is reachable. On
 *      failure print the standard guidance and `process.exit(1)`; on
@@ -4276,14 +4288,14 @@ async function preflightAgentBrowserCommand() {
 	await warnStaleBlockArtifacts();
 }
 //#endregion
-//#region src/report/nd-transcript-excerpt.ts
+//#region src/report/live-transcript-excerpt.ts
 /**
 * Build a compact transcript summary for the failure classifier.
 *
 * Returns `null` when the run has no failed step (every step passed/skipped),
 * since the failure analyzer has nothing to explain in that case.
 */
-async function buildNdTranscriptExcerpt(result, options = {}) {
+async function buildLiveTranscriptExcerpt(result, options = {}) {
 	const failingIndex = result.steps.findIndex((s) => s.status === "failed");
 	if (failingIndex === -1) return null;
 	const failingStep = result.steps[failingIndex];
@@ -4316,7 +4328,7 @@ function oneLine$1(s) {
 	return s.replace(/\s+/g, " ").trim();
 }
 //#endregion
-//#region src/runtime/nd-artifacts.ts
+//#region src/runtime/live-artifacts.ts
 /**
 * Build a sortable run id from the current wall-clock time. ISO8601 with
 * `:` / `.` replaced so it's filename-safe. Caller is expected to mkdir the
@@ -4361,15 +4373,15 @@ function agentBrowserInvokeBase(input) {
 	};
 }
 //#endregion
-//#region src/prompts/run-nd.ts
-function generateRunNdSessionName() {
-	return `ccqa-run-nd-${buildRunId()}`;
+//#region src/prompts/live.ts
+function generateLiveSessionName() {
+	return `ccqa-live-${buildRunId()}`;
 }
 /**
-* Static prefix of the `ccqa run-nd` system prompt. Built once per run and
-* reused across every step's invocation — the only piece that changes per
-* step is the trailing "Your Task: <stepId>" section produced by
-* `buildRunNdSystemPromptStepSection`. Keeping the split here lets the prompt
+* Static prefix of the `ccqa run` (live spec) system prompt. Built once per
+* run and reused across every step's invocation — the only piece that
+* changes per step is the trailing "Your Task: <stepId>" section produced by
+* `buildLiveSystemPromptStepSection`. Keeping the split here lets the prompt
 * cache absorb the shared bulk and keeps each turn's prompt construction down
 * to a small string concat.
 *
@@ -4378,16 +4390,18 @@ function generateRunNdSessionName() {
 * but never names a specific product, URL, account, role, or UI element.
 * Project-specific guidance ("the admin tenant is foo.example", "session
 * times out at X minutes", …) is appended from
-* `.ccqa/prompts/run-nd.user.md` by the caller, so ccqa stays clean of
-* downstream-product context.
+* `.ccqa/prompts/live.user.md` (human-maintained) and
+* `.ccqa/prompts/live.agent.md` (updated by `ccqa run --update-agent-prompt`)
+* by the caller, so ccqa stays clean of downstream-product context.
 *
-* Constraint posture: `ccqa trace` enforces a strict selector whitelist and
-* blocks `eval` / `@ref` / chained agent-browser invocations because those
-* trace outputs need to replay deterministically. `run-nd` has no replay —
-* the model judges the step live — so those guards are off and the model is
-* told it may use any agent-browser subcommand and any selector strategy.
-*/
-function buildRunNdSystemPromptPrefix(input) {
+* Constraint posture: `ccqa record` (trace) enforces a strict selector
+* whitelist and blocks `eval` / `@ref` / chained agent-browser invocations
+* because those trace outputs need to replay deterministically. Live specs
+* have no replay — the model judges the step live — so those guards are off
+* and the model is told it may use any agent-browser subcommand and any
+* selector strategy.
+*/
+function buildLiveSystemPromptPrefix(input) {
 	const stepsText = input.allSteps.map((s) => `### ${s.id} [${s.source}]
 - **Instruction**: ${s.instruction}
 - **Expected**: ${s.expected}`).join("\n\n");
@@ -4456,7 +4470,7 @@ Everything else you write (narrative, tool output summaries, etc.) is fine — o
 `;
 }
 /** Per-step trailer with the current step's instruction / expected. */
-function buildRunNdSystemPromptStepSection(step) {
+function buildLiveSystemPromptStepSection(step) {
 	return `
 ## Your Task: ${step.id}
 
@@ -4467,11 +4481,11 @@ Execute the instruction in the running browser session, then judge whether the e
 `;
 }
 /** Per-turn user message — the system prompt already carries all spec context. */
-function buildRunNdUserPrompt(step) {
+function buildLiveUserPrompt(step) {
 	return `Execute step ${step.id} and emit your STEP_RESULT verdict as instructed in the system prompt.`;
 }
 //#endregion
-//#region src/runtime/nd-result-parse.ts
+//#region src/runtime/live-result-parse.ts
 const MAX_REASON_LEN = 2e3;
 /** Parse a single STEP_RESULT line. Returns null on malformed input. */
 function parseStepResultLine(line) {
@@ -4501,7 +4515,7 @@ function findLastStepResult(text) {
 //#region src/runtime/screenshot.ts
 /**
 * Take a PNG screenshot of the current page in the given agent-browser session
-* and write it to `outPath`. Used by `ccqa run-nd` to capture per-step
+* and write it to `outPath`. Used by `ccqa run` (live mode) to capture per-step
 * artifacts (before / after the step's actions) so the human-readable run
 * report has a visual trail even though no AB_ACTION stream is recorded.
 *
@@ -4530,10 +4544,10 @@ function takeScreenshot(sessionName, outPath, options) {
 	};
 }
 //#endregion
-//#region src/runtime/nd-executor.ts
+//#region src/runtime/live-executor.ts
 /**
-* Run all spec steps once through Claude (non-deterministic mode). Each step
-* is one Claude invocation that:
+* Run all spec steps once through Claude (live mode). Each step is one Claude
+* invocation that:
 *   1. takes a "before" screenshot of the live session
 *   2. lets Claude execute the step's instruction via agent-browser (full
 *      surface, no replay-time selector constraints)
@@ -4544,11 +4558,11 @@ function takeScreenshot(sessionName, outPath, options) {
 * the overall run status flips to `failed`. The Chrome session persists
 * across steps so step N+1 starts on whatever page step N left the browser on.
 */
-async function runNdExecutor(input) {
+async function runLiveExecutor(input) {
 	const startedAt = /* @__PURE__ */ new Date();
 	const stepResults = [];
 	let overallFailed = false;
-	const promptPrefix = buildRunNdSystemPromptPrefix({
+	const promptPrefix = buildLiveSystemPromptPrefix({
 		title: input.spec.title,
 		allSteps: input.steps,
 		sessionName: input.sessionName
@@ -4571,8 +4585,8 @@ async function runNdExecutor(input) {
 		const paths = stepArtifactPaths(input.runDir, step$1.id);
 		await ensureDir(paths.beforePng);
 		const stepStartedAt = Date.now();
-		const systemPrompt = promptPrefix + buildRunNdSystemPromptStepSection(step$1) + suffixBlock + langDirective;
-		const userPrompt = buildRunNdUserPrompt(step$1);
+		const systemPrompt = promptPrefix + buildLiveSystemPromptStepSection(step$1) + suffixBlock + langDirective;
+		const userPrompt = buildLiveUserPrompt(step$1);
 		let attempt = 0;
 		let lastOutcome = null;
 		while (attempt <= retries) {
@@ -4750,24 +4764,24 @@ function truncateForLog$1(s) {
 	return oneLine.length > 100 ? oneLine.slice(0, 100) + "…" : oneLine;
 }
 //#endregion
-//#region src/report/nd-adapter.ts
+//#region src/report/live-adapter.ts
 /**
-* Convert one `run-nd` execution result into the persistence-layer
-* `ReportSpecResult` shape consumed by `renderRunReport`. The conversion
-* does two non-trivial things:
+* Convert one live-mode (`mode: live`) execution result into the
+* persistence-layer `ReportSpecResult` shape consumed by `renderRunReport`.
+* The conversion does two non-trivial things:
 *
 *   - rewrites the executor's absolute `beforePng`/`afterPng` paths as
 *     `reportDir`-relative hrefs so the rendered HTML opens its PNGs
 *     directly when the report dir + the run dir are downloaded together
 *     as a CI artifact bundle
 *   - nulls out every vitest-only field so the report renderer falls
-*     through to its `ndRun` branch
+*     through to its `liveRun` branch
 *
 * Lives in `src/report/` (not the CLI) because the relative-path contract
-* on `NdReportStep.beforePng`/`afterPng` is a report-layer invariant,
+* on `LiveReportStep.beforePng`/`afterPng` is a report-layer invariant,
 * documented next to the schema, and the CLI should not own it.
 */
-function ndRunToReportResult(args) {
+function liveRunToReportResult(args) {
 	const { featureName, specName, specYaml, result, reportDir } = args;
 	const steps = result.steps.map((s) => ({
 		stepId: s.stepId,
@@ -4781,7 +4795,7 @@ function ndRunToReportResult(args) {
 		durationMs: s.durationMs,
 		cost: { ...s.cost }
 	}));
-	const ndRun = {
+	const liveRun = {
 		runId: result.runId,
 		sessionName: result.sessionName,
 		startedAt: result.startedAt,
@@ -4804,16 +4818,16 @@ function ndRunToReportResult(args) {
 		diffExcerpt: null,
 		specYaml,
 		evidence: null,
-		ndRun
+		liveRun
 	};
 }
 function relativeIfPresent(absPath, reportDir) {
 	return absPath === null ? null : relative(reportDir, absPath);
 }
 //#endregion
-//#region src/cli/run-nd.ts
+//#region src/cli/run-live.ts
 /**
-* Run pre-filtered `mode: live` specs through `runNdExecutor` (Claude +
+* Run pre-filtered `mode: live` specs through `runLiveExecutor` (Claude +
 * agent-browser) and, when `reportDir` is set, run drift audit + failure
 * analysis to produce report rows. Sibling of `runDeterministicSpecs`.
 */
@@ -4825,8 +4839,9 @@ async function runLiveSpecs(specs, opts) {
 	const cwd = opts.cwd ?? process.cwd();
 	await preflightAgentBrowserCommand();
 	meta("live-specs", specs.length);
-	const userPromptSuffix = await loadRunNdUserPrompt(cwd);
-	if (userPromptSuffix !== null) meta("user-prompt", ".ccqa/prompts/run-nd.user.md");
+	const userPromptBundle = await loadLivePromptBundle(cwd);
+	if (userPromptBundle !== null) meta("user-prompt", userPromptBundle.loaded.join(" + "));
+	const userPromptSuffix = userPromptBundle?.text ?? null;
 	const runs = [];
 	for (let i = 0; i < specs.length; i++) {
 		const { featureName, specName } = specs[i];
@@ -4859,7 +4874,7 @@ function buildLiveReportResults(runs, driftBySpec, analysisBySpec, reportDir, fa
 		if (r.kind !== "run") return [];
 		const key = `${r.featureName}/${r.specName}`;
 		return [{
-			...ndRunToReportResult({
+			...liveRunToReportResult({
 				featureName: r.featureName,
 				specName: r.specName,
 				specYaml: r.specYaml,
@@ -4889,7 +4904,7 @@ function analysisFieldsFor(a, status, failureAnalysisEnabled) {
 /**
 * Run `analyzeDrift` against every successfully-loaded spec and return a
 * `featureName/specName → driftIssues` map. Drift findings are advisory —
-* they show in the HTML report but do not change the run-nd exit code.
+* they show in the HTML report but do not change the live-run exit code.
 */
 async function runDriftAudit(runs, opts, cwd) {
 	const targets = runs.filter((r) => r.kind === "run").map((r) => ({
@@ -4939,13 +4954,13 @@ async function runOneSpec(args) {
 	meta("steps", expanded.length);
 	const includes = collectIncludedBlockNames(spec);
 	if (includes.length > 0) meta("blocks", includes.join(", "));
-	const sessionName = generateRunNdSessionName();
+	const sessionName = generateLiveSessionName();
 	meta("session", sessionName);
 	const runId = buildRunId();
 	const runDir = opts.out ?? join(specDir, "runs", runId);
 	await mkdir(runDir, { recursive: true });
 	meta("runDir", runDir);
-	const result = await runNdExecutor({
+	const result = await runLiveExecutor({
 		spec: { title: spec.title },
 		steps: expanded,
 		runId,
@@ -4963,7 +4978,7 @@ async function runOneSpec(args) {
 	meta("saved", runJsonPath);
 	meta("status", result.status.toUpperCase());
 	meta("step-summary", `${count(result.steps, "passed")} passed / ${count(result.steps, "failed")} failed / ${count(result.steps, "skipped")} skipped`);
-	const costLine = formatNdCost(result.cost, { compact: false });
+	const costLine = formatLiveCost(result.cost, { compact: false });
 	if (costLine) meta("cost", costLine);
 	return {
 		kind: "run",
@@ -4975,7 +4990,7 @@ async function runOneSpec(args) {
 	};
 }
 function logBatchCost(runs) {
-	const line = formatNdBatchCost(runs.flatMap((r) => r.kind === "run" ? [r.result.cost] : []));
+	const line = formatLiveBatchCost(runs.flatMap((r) => r.kind === "run" ? [r.result.cost] : []));
 	if (line) meta("total-cost", line);
 }
 /**
@@ -5005,7 +5020,7 @@ async function runFailureAnalysisForLiveRuns(runs, driftBySpec, opts, cwd) {
 	for (const r of failed) {
 		const key = `${r.featureName}/${r.specName}`;
 		info(`failure analysis: ${key}`);
-		const excerpt = await buildNdTranscriptExcerpt(r.result);
+		const excerpt = await buildLiveTranscriptExcerpt(r.result);
 		if (excerpt === null) {
 			out.set(key, {
 				analysis: null,
@@ -5016,7 +5031,7 @@ async function runFailureAnalysisForLiveRuns(runs, driftBySpec, opts, cwd) {
 			continue;
 		}
 		const outcome = await analyzeFailure({
-			ndTranscriptExcerpt: excerpt,
+			liveTranscriptExcerpt: excerpt,
 			specYaml: r.specYaml,
 			diffPatch: diff.ok ? diff.diff.patch : null,
 			changedFiles: diff.ok ? diff.diff.nameStatus : null,
@@ -5067,6 +5082,100 @@ function oneLine(s) {
 	return s.replace(/\s+/g, " ").trim();
 }
 //#endregion
+//#region src/prompts/agent-update.ts
+function buildAgentUpdateSystemPrompt(input) {
+	const modeLabel = input.mode === "live" ? "live (Claude drives every step at run time)" : "record (Claude records browser actions for vitest replay)";
+	const userMdLabel = `${input.mode}.user.md`;
+	const agentMdLabel = `${input.mode}.agent.md`;
+	return `You maintain the auto-learned half of ccqa's prompt bundle for ${modeLabel}.
+
+${outputLanguageBlock(input.language ?? "auto", "the bullet text", "headings, agent-browser subcommand names, selector tokens")}## What you are updating
+
+\`.ccqa/prompts/${agentMdLabel}\` is appended to ccqa's system prompt for every ${input.mode === "live" ? "step of every `mode: live` spec" : "trace run of `ccqa record`"}. It is meant to capture **stable lessons learned from past runs** — concrete selectors that worked, login flow quirks the agent kept tripping on, common "this is fine" warnings to ignore.
+
+The sibling file \`${userMdLabel}\` carries human-maintained project guidance (URLs, naming conventions). Rules already well-covered by \`${userMdLabel}\` should NOT be repeated here.
+
+## Output rules
+
+- Emit the COMPLETE replacement contents of \`${agentMdLabel}\`.
+- Concise bullet points. No narrative paragraphs. No preamble. No closing summary.
+- Each bullet is a single declarative sentence (or one bullet → one short selector / command).
+- Group related bullets under \`### …\` subheaders.
+- Skip everything that was already true and well-covered by the previous file or \`${userMdLabel}\`. Only persist new lessons.
+- Keep the whole file under ~3 KB.
+- Output ONLY the new file contents. NO code fences. NO surrounding prose. NO markdown frontmatter.
+- If the run summary contains nothing worth learning from, output the previous file unchanged.
+`;
+}
+function buildAgentUpdateUserPrompt(input) {
+	const agentMdLabel = `${input.mode}.agent.md`;
+	return `## Previous \`${agentMdLabel}\`
+
+${input.currentAgentMd && input.currentAgentMd.trim().length > 0 ? input.currentAgentMd : "(no existing file — this will create one)"}
+
+## Run summary
+
+${input.runSummary}
+
+## Your task
+
+Write the new contents of \`${agentMdLabel}\`. Output ONLY the file contents — no preamble, no fences, no closing note.`;
+}
+//#endregion
+//#region src/cli/update-agent-prompt.ts
+/**
+* Refresh `.ccqa/prompts/<mode>.agent.md` from the latest run.
+*
+* Reads the existing file (if any) and a caller-supplied run summary, sends
+* both to Claude, and writes the response back over the agent prompt file.
+* Degrades gracefully when auth is missing — logs and returns — so the run
+* exit code is unaffected by this opt-in side step.
+*/
+async function updateAgentPrompt(args) {
+	const { mode, runSummary, cwd, model, language } = args;
+	const agentMdPath = join(cwd, ".ccqa", "prompts", `${mode}.agent.md`);
+	const relPath = relative(cwd, agentMdPath);
+	const auth = driftAuthAvailable();
+	if (!auth.ok) {
+		warn(`--update-agent-prompt skipped (${auth.reason})`);
+		return;
+	}
+	const promptInput = {
+		mode,
+		currentAgentMd: await readFile(agentMdPath, "utf-8").catch(() => null),
+		runSummary,
+		...language ? { language } : {}
+	};
+	const systemPrompt = buildAgentUpdateSystemPrompt(promptInput);
+	const userPrompt = buildAgentUpdateUserPrompt(promptInput);
+	info(`--update-agent-prompt: refreshing ${relPath}`);
+	const { result, isError } = await invokeClaudeStreaming({
+		prompt: userPrompt,
+		systemPrompt,
+		allowedTools: [],
+		disableBuiltinTools: true,
+		...model ? { model } : {}
+	}, () => {});
+	if (isError || !result || result.trim().length === 0) {
+		warn(`--update-agent-prompt: Claude returned no usable output${isError ? " (SDK error)" : ""}; leaving ${relPath} unchanged`);
+		return;
+	}
+	const newText = stripCodeFences(result.trim()) + "\n";
+	await mkdir(dirname(agentMdPath), { recursive: true });
+	await writeFile(agentMdPath, newText, "utf-8");
+	info(`--update-agent-prompt: wrote ${relPath} (${newText.length} bytes)`);
+	info(`--update-agent-prompt: review the diff with: git diff -- "${relPath}"`);
+}
+/**
+* Some models still wrap the answer in a ```markdown fence despite the
+* system prompt asking otherwise. Strip a single outer fence when present so
+* the saved file is clean.
+*/
+function stripCodeFences(text) {
+	const m = text.match(/^```[a-zA-Z]*\n([\s\S]*?)\n```\s*$/);
+	return m && m[1] !== void 0 ? m[1] : text;
+}
+//#endregion
 //#region src/cli/changed-specs.ts
 /**
 * Filter specs to those affected by the git diff against the resolved base
@@ -5129,7 +5238,7 @@ const runCommand = addLanguageOption(new Command("run").argument("[target]", "Sp
 	const n = Number(raw);
 	if (!Number.isFinite(n) || n < 0 || Math.floor(n) !== n) throw new Error(`--retry must be a non-negative integer, got "${raw}"`);
 	return n;
-}, 0).option("--out <dir>", "(live only) Override the per-spec artifact directory. Default: <specDir>/runs/<runId>. Ignored when running multiple specs.")).action(async (target, opts) => {
+}, 0).option("--out <dir>", "(live only) Override the per-spec artifact directory. Default: <specDir>/runs/<runId>. Ignored when running multiple specs.").option("--update-agent-prompt", "(live only) After the run finishes, ask Claude to refresh .ccqa/prompts/live.agent.md from a summary of the run.")).action(async (target, opts) => {
 	await runDispatcher(target, opts);
 });
 function resolveReportDir(report, cwd) {
@@ -5163,6 +5272,7 @@ async function runDispatcher(target, opts) {
 	if (liveSpecs.length === 0) {
 		if (typeof opts.retry === "number" && opts.retry > 0) warn("--retry is ignored without any 'mode: live' spec");
 		if (opts.out) warn("--out is ignored without any 'mode: live' spec");
+		if (opts.updateAgentPrompt) warn("--update-agent-prompt is ignored without any 'mode: live' spec");
 	}
 	if (detSpecs.length === 0 && opts.evidence === false) warn("--no-evidence is ignored without any 'mode: deterministic' spec");
 	blank();
@@ -5192,9 +5302,39 @@ async function runDispatcher(target, opts) {
 			opts
 		});
 	}
+	if (opts.updateAgentPrompt && liveSpecs.length > 0) {
+		blank();
+		await updateAgentPrompt({
+			mode: "live",
+			runSummary: buildLiveRunSummary(live.reportResults),
+			cwd,
+			...opts.model ? { model: opts.model } : {},
+			...opts.language ? { language: opts.language } : {}
+		});
+	}
 	process.exit(overallExitCode);
 }
 /**
+* Compact, prompt-friendly summary of one ccqa run for the live agent-prompt
+* update step. One section per spec: header line + per-step verdicts.
+* Kept to a few KB even with many specs/steps so the prompt cache can absorb
+* the bulk.
+*/
+function buildLiveRunSummary(results) {
+	const sections = [];
+	for (const r of results) {
+		if (!r.liveRun) continue;
+		const head = `## ${r.feature}/${r.spec} — ${r.status}`;
+		const steps = r.liveRun.steps.map((s) => `- [${s.status}] ${s.stepId}: ${oneLineSummary$1(s.reasoning)}`).join("\n");
+		sections.push(`${head}\n${steps}`);
+	}
+	return sections.length === 0 ? "(no live runs executed)" : sections.join("\n\n");
+}
+function oneLineSummary$1(s) {
+	const flat = s.replace(/\s+/g, " ").trim();
+	return flat.length > 240 ? flat.slice(0, 240) + "…" : flat || "(no reason given)";
+}
+/**
 * Run pre-filtered deterministic specs under vitest. Empty input is a no-op.
 * Captures step-boundary evidence under `<reportDir>/evidence/<feature>/<spec>/`
 * when enabled.
@@ -5358,7 +5498,7 @@ async function analyzeDeterministicSummaries(summaries, opts, cwd, reportDir) {
 				failureLogExcerpt: null,
 				diffExcerpt: null,
 				specYaml: null,
-				ndRun: null
+				liveRun: null
 			});
 			continue;
 		}
@@ -5408,7 +5548,7 @@ async function analyzeDeterministicSummaries(summaries, opts, cwd, reportDir) {
 			failureLogExcerpt: failureLog.length > 0 ? failureLog : null,
 			diffExcerpt,
 			specYaml,
-			ndRun: null
+			liveRun: null
 		});
 	}
 	return {
@@ -6683,9 +6823,9 @@ async function runTrace(featureName, specName, model, validationMode = "lenient"
 		steps: expanded,
 		sessionName
 	});
-	const userPrompt = await loadTraceUserPrompt();
-	if (userPrompt !== null) meta("user-prompt", ".ccqa/prompts/trace.user.md");
-	const systemPrompt = (userPrompt === null ? baseSystemPrompt : `${baseSystemPrompt}\n## Project-specific guidance\n\n${userPrompt}\n`) + languageDirective(language);
+	const promptBundle = await loadRecordPromptBundle();
+	if (promptBundle !== null) meta("user-prompt", promptBundle.loaded.join(" + "));
+	const systemPrompt = (promptBundle === null ? baseSystemPrompt : `${baseSystemPrompt}\n## Project-specific guidance\n\n${promptBundle.text}\n`) + languageDirective(language);
 	const prompt = buildTracePrompt(spec.title);
 	info("Running agent-browser session...");
 	blank();
@@ -6767,6 +6907,11 @@ async function runTrace(featureName, specName, model, validationMode = "lenient"
 		if (written) meta("relatedPaths", `${relatedPaths.length} path(s) written to ${written}`);
 	} else warn("trace did not emit a RELATED_PATHS block; drift --changed cannot scope this spec");
 	hint(`run 'ccqa generate ${featureName}/${specName}' to generate a test script`);
+	return {
+		route,
+		actionsKept: validatedActions.length,
+		actionsRecorded: traceActions.length
+	};
 }
 /**
 * Strip actions whose recorded fields contain "unstable literal" values
@@ -8342,15 +8487,16 @@ const recordCommand = addLanguageOption(new Command("record").argument("<feature
 }, "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).", (raw) => {
 	if (AUTO_FIX_MODES.includes(raw)) return raw;
 	throw new Error(`--auto-fix must be one of ${AUTO_FIX_MODES.join(" | ")}`);
-}, "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 actions.json").option("--skip-codegen", "Run only the trace step (do not generate test.spec.ts)")).action(async (specPath, opts) => {
+}, "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 actions.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 .ccqa/prompts/record.agent.md from a summary of the run.").option("--cwd <path>", "Working directory containing the .ccqa/ tree (monorepo support). Defaults to the current directory.")).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);
 	}
+	let traceResult = null;
 	if (!opts.skipTrace) {
-		await runTrace(featureName, specName, opts.model, opts.validationMode ?? "lenient", language);
+		traceResult = await runTrace(featureName, specName, opts.model, opts.validationMode ?? "lenient", language);
 		blank();
 	}
 	if (!opts.skipCodegen) {
@@ -8358,7 +8504,37 @@ const recordCommand = addLanguageOption(new Command("record").argument("<feature
 		const useSnapshot = opts.snapshot !== false;
 		await runGenerate(featureName, specName, parseInt(opts.maxRetries ?? "3", 10), fixMode, opts.force ?? false, useSnapshot, language, opts.model);
 	}
+	if (opts.updateAgentPrompt) if (traceResult === null) warn("--update-agent-prompt is ignored when --skip-trace is set (no run summary available)");
+	else {
+		const cwd = resolveCwd(opts.cwd);
+		blank();
+		await updateAgentPrompt({
+			mode: "record",
+			runSummary: buildRecordRunSummary(featureName, specName, traceResult),
+			cwd,
+			...opts.model ? { model: opts.model } : {},
+			...language ? { language } : {}
+		});
+	}
 });
+/**
+* Compact summary of the trace pass for the record agent-prompt refresh:
+* per-step title / action / observation / status. The route steps already
+* carry the assistant's own framing of what happened — perfect input for
+* "what should I remember next time".
+*/
+function buildRecordRunSummary(featureName, specName, t) {
+	return `${`## ${featureName}/${specName} — ${t.route.status}\nActions: ${t.actionsKept} kept / ${t.actionsRecorded} recorded`}\n\n${t.route.steps.length === 0 ? "(no route steps recorded)" : t.route.steps.map((s) => [
+		`### ${s.title} (${s.status})`,
+		`- action: ${oneLineSummary(s.action)}`,
+		`- observation: ${oneLineSummary(s.observation)}`,
+		...s.reason ? [`- reason: ${oneLineSummary(s.reason)}`] : []
+	].join("\n")).join("\n\n")}`;
+}
+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;
@@ -9128,6 +9304,64 @@ function parseConcurrency(raw) {
 	return n;
 }
 //#endregion
+//#region src/cli/init.ts
+const TEMPLATES = [
+	{
+		relPath: ".ccqa/prompts/live.user.md",
+		content: `# Project guidance for live specs
+
+Write stable, hand-maintained context here: staging URLs, naming conventions, known "this is fine" warnings. Lines you add will be appended verbatim to the system prompt of every step in 'mode: live' specs.
+`
+	},
+	{
+		relPath: ".ccqa/prompts/live.agent.md",
+		content: `# Agent learnings for live specs
+
+This file is updated by 'ccqa run --update-agent-prompt'. You can edit it by hand, but the next --update-agent-prompt run may rewrite the whole file. Keep stable rules in live.user.md instead.
+`
+	},
+	{
+		relPath: ".ccqa/prompts/record.user.md",
+		content: `# Project guidance for ccqa record (deterministic trace)
+
+Write stable, hand-maintained context here for the trace phase of 'ccqa record'. Lines you add will be appended verbatim to the trace system prompt.
+`
+	},
+	{
+		relPath: ".ccqa/prompts/record.agent.md",
+		content: `# Agent learnings for ccqa record
+
+This file is updated by 'ccqa record --update-agent-prompt'. Same convention as live.agent.md — stable rules go in record.user.md.
+`
+	}
+];
+const initCommand = new Command("init").description("Create .ccqa/prompts/{live,record}.{user,agent}.md template files (skips existing files unless --force).").option("--cwd <path>", "Working directory (default: cwd)").option("--force", "Overwrite existing files").action(async (opts) => {
+	const cwd = resolveCwd(opts.cwd);
+	header("init", cwd);
+	await mkdir(join(cwd, ".ccqa", "prompts"), { recursive: true });
+	const created = [];
+	const skipped = [];
+	for (const t of TEMPLATES) if (await writeTemplate(join(cwd, t.relPath), t.content, opts.force ?? false)) created.push(t.relPath);
+	else skipped.push(t.relPath);
+	for (const f of created) info(`created  ${f}`);
+	for (const f of skipped) info(`skipped  ${f} (already exists; pass --force to overwrite)`);
+	blank();
+	meta("created", created.length);
+	meta("skipped", skipped.length);
+});
+async function writeTemplate(absPath, content, force) {
+	try {
+		await writeFile(absPath, content, force ? { encoding: "utf-8" } : {
+			encoding: "utf-8",
+			flag: "wx"
+		});
+		return true;
+	} catch (err) {
+		if (typeof err === "object" && err !== null && err.code === "EEXIST") return false;
+		throw err;
+	}
+}
+//#endregion
 //#region src/prompts/perspectives.ts
 /**
 * Build the system prompt. By default the descriptive fields follow the
@@ -9595,8 +9829,6 @@ function renderSpecMarkdown(spec, labels = LABELS_JA) {
 	lines.push("");
 	lines.push(`| ${labels.itemCol} | ${labels.valueCol} |`);
 	lines.push("| --- | --- |");
-	lines.push(`| ${labels.modeLabel} | ${mdCell(modeLabel(spec.status, labels))} |`);
-	lines.push(`| ${labels.statusCol} | ${mdCell(statusLabel(spec.status, labels))} |`);
 	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)} |`);
@@ -9628,6 +9860,7 @@ function resolvePackageJson() {
 const { version } = JSON.parse(readFileSync(resolvePackageJson(), "utf8"));
 const program = new Command();
 program.name("ccqa").description("E2E test CLI using Claude Code + agent-browser").version(version);
+program.addCommand(initCommand);
 program.addCommand(draftCommand);
 program.addCommand(perspectivesCommand);
 program.addCommand(recordCommand);

package/dist/package.json

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

package/package.json

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