harnery 0.36.0 → 0.38.0

package/src/commands/qa-record.ts

@@ -0,0 +1,682 @@
+// `qa-record <target>`: record hand-performed page QA as a standard result
+// document. When the matrix runner cannot run — host thrash, a lost bridge, an
+// interaction no runner can drive — an agent does the checks by hand. Today
+// that produces prose, which no consumer can verify. This command turns those
+// hand-performed checks into the SAME artifact qa-run emits, so qa-verify and
+// qa-status work on it identically.
+//
+// One rule is load-bearing and enforced here, not in prose: a manual result
+// can report a defect but can never read `passed`. Every record carries a
+// `validate` blocker naming the reason the runner was unavailable, and the
+// verdict is computed with evidenceSource "manual", which caps at incomplete.
+
+import { execFileSync } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { cpus, freemem, loadavg, totalmem } from "node:os";
+import { basename, dirname, isAbsolute, join, resolve } from "node:path";
+import type { Command } from "commander";
+import type { EmitContext, HarneryProgramContext } from "../commander.ts";
+import { recordQaSignal } from "../core/agents/qa-signal.ts";
+import { createManagedQaOutParent, resolveQaRepoRoot } from "../core/qa-artifacts.ts";
+import {
+  QA_RUN_RESULT_FILENAME,
+  QA_RUN_STATUS_FILENAME,
+  writeLatestPointer,
+} from "../lib/browser/qa-run.ts";
+import {
+  computeJobDigest,
+  computeVerdict,
+  QA_RUN_JOB_SCHEMA_VERSION,
+  QA_RUN_RESULT_SCHEMA_VERSION,
+  QA_RUN_STATUS_SCHEMA_VERSION,
+  type QaRunBlocker,
+  type QaRunCommandOutcome,
+  type QaRunContext,
+  type QaRunHostSample,
+  type QaRunJob,
+  type QaRunResult,
+  type QaRunStatusDocument,
+  validateQaRunJob,
+} from "../lib/browser/qa-run-contracts.ts";
+
+export const QA_RECORD_EVIDENCE_SCHEMA_VERSION = 1 as const;
+
+/** The evidence document is copied into the run directory beside the result:
+ * the run identity's job_digest is taken over it, so without the copy nothing
+ * downstream could re-derive the digest. qa-run writes `job.json` for the same
+ * reason; the manual name keeps the two from being confused. */
+export const QA_RECORD_EVIDENCE_FILENAME = "manual-evidence.json";
+
+/** argv marker for a hand-performed check. The contract types argv as a string
+ * array and consumers print it, so an empty array would render as a command
+ * that ran with no arguments. A single explicit marker reads as "no process
+ * executed" and can never be mistaken for a re-runnable command line. */
+export const QA_RECORD_MANUAL_ARGV = ["<manual>"] as const;
+
+export type QaManualOutcome = "passed" | "failed" | "unknown";
+
+/** One check a human or agent performed by hand. */
+export interface QaManualCheck {
+  /** Context the check was performed in; matches a `contexts[].id` when the
+   * document declares contexts. */
+  context_id: string;
+  /** Stable check identifier. Prefix with `manual:` by convention. */
+  check_id: string;
+  outcome: QaManualOutcome;
+  /** What the recorder observed. Carried into the result's `failures` field. */
+  notes?: string[];
+  /** Files that back the observation. Every path must exist on disk. */
+  artifacts?: { png?: string; html?: string; json?: string };
+  /** Time the check took, when the recorder measured it. */
+  wall_time_ms?: number;
+}
+
+export interface QaManualEvidence {
+  schema_version: typeof QA_RECORD_EVIDENCE_SCHEMA_VERSION;
+  /** Who performed the checks (agent name or operator identity). */
+  recorded_by: string;
+  /** Why the runner could not be used. Required: a hand record with no stated
+   * reason is an assertion, not evidence. */
+  reason: string;
+  checks: QaManualCheck[];
+  /** Declared contexts. Absent: derived from the checks' context IDs. */
+  contexts?: QaRunContext[];
+}
+
+export type QaManualEvidenceValidation =
+  | { ok: true; evidence: QaManualEvidence }
+  | { ok: false; errors: string[] };
+
+const ARTIFACT_KINDS = ["png", "html", "json"] as const;
+
+/** Artifact paths are resolved against the directory holding the evidence
+ * document, not the working directory: an evidence file names the captures
+ * sitting beside it, and that stays true wherever it is recorded from. */
+export function resolveArtifactPath(baseDir: string, path: string): string {
+  return isAbsolute(path) ? path : resolve(baseDir, path);
+}
+
+function isStringArray(value: unknown): value is string[] {
+  return Array.isArray(value) && value.every((item) => typeof item === "string");
+}
+
+/** Reuse the job validator's credential scan rather than duplicating its
+ * patterns: the evidence document is nested under a minimal valid job, so
+ * every error the validator can return for that probe comes from the secret
+ * scan. Paths are rewritten back to the evidence document's own namespace. */
+function scanEvidenceForSecrets(document: unknown): string[] {
+  const probe = {
+    schema_version: QA_RUN_JOB_SCHEMA_VERSION,
+    target: "qa-record",
+    mode: "review",
+    evidence: document,
+  };
+  const validation = validateQaRunJob(probe);
+  if (validation.ok) return [];
+  return validation.errors.map((message) => message.replace(/^job\.evidence/, "evidence"));
+}
+
+/**
+ * Validate an untrusted evidence document. Every structural problem, every
+ * missing artifact, and every secret-bearing field is reported at once, before
+ * anything is written: a caller fixes the document in one pass, and a
+ * half-valid record never reaches disk.
+ */
+export function validateManualEvidence(
+  value: unknown,
+  options: { baseDir: string },
+): QaManualEvidenceValidation {
+  const errors: string[] = [];
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return { ok: false, errors: ["evidence must be a JSON object"] };
+  }
+  const document = value as Record<string, unknown>;
+
+  if (document.schema_version !== QA_RECORD_EVIDENCE_SCHEMA_VERSION) {
+    errors.push(`schema_version must be ${QA_RECORD_EVIDENCE_SCHEMA_VERSION}`);
+  }
+  if (typeof document.recorded_by !== "string" || document.recorded_by.length === 0) {
+    errors.push("recorded_by is required (the agent or operator who performed the checks)");
+  }
+  if (typeof document.reason !== "string" || document.reason.length === 0) {
+    errors.push(
+      "reason is required: name why the runner could not be used — a hand record with " +
+        "no stated reason is an assertion, not evidence",
+    );
+  }
+
+  const declaredContextIds = new Set<string>();
+  if (document.contexts !== undefined) {
+    if (!Array.isArray(document.contexts)) {
+      errors.push("contexts must be an array");
+    } else {
+      document.contexts.forEach((entry, i) => {
+        const context = entry as Record<string, unknown>;
+        if (typeof context?.id !== "string" || context.id.length === 0) {
+          errors.push(`contexts[${i}].id is required`);
+        } else if (declaredContextIds.has(context.id)) {
+          errors.push(`contexts[${i}].id duplicates "${context.id}"`);
+        } else {
+          declaredContextIds.add(context.id);
+        }
+        if (typeof context?.viewport !== "string" || context.viewport.length === 0) {
+          errors.push(`contexts[${i}].viewport is required`);
+        }
+        if (context?.theme !== "light" && context?.theme !== "dark") {
+          errors.push(`contexts[${i}].theme must be "light" or "dark"`);
+        }
+        if (typeof context?.state !== "string" || context.state.length === 0) {
+          errors.push(`contexts[${i}].state is required ("default" for the plain page)`);
+        }
+      });
+    }
+  }
+
+  if (!Array.isArray(document.checks) || document.checks.length === 0) {
+    errors.push(
+      "checks must be a non-empty array: a record with no checks proves nothing about the page",
+    );
+  } else {
+    const seen = new Set<string>();
+    document.checks.forEach((entry, i) => {
+      const check = entry as Record<string, unknown>;
+      const contextId = check?.context_id;
+      if (typeof contextId !== "string" || contextId.length === 0) {
+        errors.push(`checks[${i}].context_id is required`);
+      } else if (declaredContextIds.size > 0 && !declaredContextIds.has(contextId)) {
+        errors.push(`checks[${i}].context_id "${contextId}" is not a declared context`);
+      }
+      const checkId = check?.check_id;
+      if (typeof checkId !== "string" || checkId.length === 0) {
+        errors.push(`checks[${i}].check_id is required`);
+      } else if (typeof contextId === "string") {
+        const key = `${contextId}${checkId}`;
+        if (seen.has(key)) {
+          errors.push(`checks[${i}] duplicates "${checkId}" in context "${contextId}"`);
+        }
+        seen.add(key);
+      }
+      if (
+        check?.outcome !== "passed" &&
+        check?.outcome !== "failed" &&
+        check?.outcome !== "unknown"
+      ) {
+        errors.push(`checks[${i}].outcome must be "passed", "failed", or "unknown"`);
+      }
+      if (check?.notes !== undefined && !isStringArray(check.notes)) {
+        errors.push(`checks[${i}].notes must be an array of strings`);
+      }
+      if (check?.wall_time_ms !== undefined) {
+        const ms = check.wall_time_ms;
+        if (typeof ms !== "number" || !Number.isFinite(ms) || ms < 0) {
+          errors.push(`checks[${i}].wall_time_ms must be a non-negative number of milliseconds`);
+        }
+      }
+      if (check?.artifacts !== undefined) {
+        if (
+          !check.artifacts ||
+          typeof check.artifacts !== "object" ||
+          Array.isArray(check.artifacts)
+        ) {
+          errors.push(`checks[${i}].artifacts must be an object`);
+        } else {
+          for (const [kind, path] of Object.entries(check.artifacts as Record<string, unknown>)) {
+            if (!(ARTIFACT_KINDS as readonly string[]).includes(kind)) {
+              errors.push(
+                `checks[${i}].artifacts.${kind} is not a recognised artifact kind ` +
+                  `(${ARTIFACT_KINDS.join(", ")})`,
+              );
+              continue;
+            }
+            if (typeof path !== "string" || path.length === 0) {
+              errors.push(`checks[${i}].artifacts.${kind} must be a file path`);
+              continue;
+            }
+            // A named artifact that is not on disk is a validation error, not
+            // a warning: an unresolvable path makes the record unverifiable,
+            // which is the failure mode this command exists to remove.
+            const abs = resolveArtifactPath(options.baseDir, path);
+            if (!existsSync(abs)) {
+              errors.push(`checks[${i}].artifacts.${kind} does not exist on disk: ${abs}`);
+            }
+          }
+        }
+      }
+    });
+  }
+
+  errors.push(...scanEvidenceForSecrets(document));
+
+  if (errors.length > 0) return { ok: false, errors };
+  return { ok: true, evidence: value as QaManualEvidence };
+}
+
+/** Contexts the result reports: the document's own declarations when it has
+ * them, otherwise one derived per distinct check context ID. Derivation reads
+ * the runner's `<viewport>-<theme>-<state>` convention when the ID follows it
+ * and records `unknown` rather than guessing when it does not. */
+export function deriveContexts(evidence: QaManualEvidence): QaRunContext[] {
+  if (evidence.contexts && evidence.contexts.length > 0) return evidence.contexts;
+  const contexts: QaRunContext[] = [];
+  const seen = new Set<string>();
+  for (const check of evidence.checks) {
+    if (seen.has(check.context_id)) continue;
+    seen.add(check.context_id);
+    const parts = check.context_id.split("-");
+    const theme = parts[1];
+    if (parts.length >= 3 && (theme === "light" || theme === "dark")) {
+      contexts.push({
+        id: check.context_id,
+        viewport: parts[0] as string,
+        theme,
+        state: parts.slice(2).join("-"),
+      });
+    } else {
+      contexts.push({
+        id: check.context_id,
+        viewport: "unknown",
+        theme: "light",
+        state: "default",
+      });
+    }
+  }
+  return contexts;
+}
+
+function hostSample(): QaRunHostSample {
+  return {
+    captured_at: new Date().toISOString(),
+    loadavg_1m: loadavg()[0] ?? 0,
+    free_mem_bytes: freemem(),
+    total_mem_bytes: totalmem(),
+    cpu_count: cpus().length,
+  };
+}
+
+/** One git probe for the identity block, matching qa-run. Failure is not an
+ * error: work outside any repository legitimately records "unknown". */
+export function probeRevision():
+  | { tested_revision?: string; worktree_dirty?: boolean }
+  | undefined {
+  try {
+    const head = execFileSync("git", ["rev-parse", "HEAD"], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+    const porcelain = execFileSync("git", ["status", "--porcelain"], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    });
+    return { tested_revision: head, worktree_dirty: porcelain.trim().length > 0 };
+  } catch {
+    return undefined;
+  }
+}
+
+export interface BuildManualResultInput {
+  evidence: QaManualEvidence;
+  target: string;
+  mode: "signoff" | "review";
+  /** Parent directory; the result lands in `<outParent>/run-<run_id>/`. */
+  outParent: string;
+  /** Pre-minted run ID (tests); default crypto.randomUUID. */
+  runId?: string;
+  /** Directory the artifact paths resolve against (the evidence file's dir). */
+  baseDir: string;
+  revisionProbe?: { tested_revision?: string; worktree_dirty?: boolean };
+  /** Completion instant (tests); default now. */
+  completedAt?: Date;
+}
+
+/**
+ * Build the QaRunResult for a validated evidence document. Pure apart from the
+ * host sample and the clock, so the shape is testable without touching disk.
+ */
+export function buildManualResult(input: BuildManualResultInput): QaRunResult {
+  const runId = input.runId ?? randomUUID();
+  const outDir = join(resolve(input.outParent), `run-${runId}`);
+
+  const commands: QaRunCommandOutcome[] = input.evidence.checks.map((check) => {
+    const artifacts: QaRunCommandOutcome["artifacts"] = {};
+    for (const kind of ARTIFACT_KINDS) {
+      const path = check.artifacts?.[kind];
+      if (path !== undefined) artifacts[kind] = resolveArtifactPath(input.baseDir, path);
+    }
+    return {
+      context_id: check.context_id,
+      check_id: check.check_id,
+      argv: [...QA_RECORD_MANUAL_ARGV],
+      exit_code: null,
+      outcome: check.outcome,
+      // `failures` is the contract's only free-text field per command, so the
+      // recorder's notes land there whatever the outcome. Dropping the notes
+      // of a passing check would discard the observation that backs it.
+      failures: check.notes ?? [],
+      artifacts,
+      wall_time_ms: check.wall_time_ms ?? 0,
+    };
+  });
+
+  const total = commands.reduce((sum, command) => sum + command.wall_time_ms, 0);
+  const completedAt = input.completedAt ?? new Date();
+  // The identity interval covers the hand-performed work rather than the few
+  // milliseconds this command took: a reader comparing started_at against a
+  // freshness floor should see when the checking happened, not when it was
+  // typed up. Stage buckets stay zero — no runner stage executed.
+  const startedAt = new Date(completedAt.getTime() - total);
+
+  const revision: Pick<
+    QaRunResult["run"],
+    "tested_revision" | "revision_source" | "worktree_dirty"
+  > =
+    input.revisionProbe?.tested_revision !== undefined
+      ? {
+          tested_revision: input.revisionProbe.tested_revision,
+          revision_source: "git",
+          ...(input.revisionProbe.worktree_dirty !== undefined
+            ? { worktree_dirty: input.revisionProbe.worktree_dirty }
+            : {}),
+        }
+      : { revision_source: "unknown" };
+
+  // The digest is taken over the same canonical hashing qa-run uses, with the
+  // evidence document standing in for the job: the record's identity is the
+  // document it was built from.
+  const jobDigest = computeJobDigest({
+    schema_version: QA_RUN_JOB_SCHEMA_VERSION,
+    target: input.target,
+    mode: input.mode,
+    evidence: input.evidence,
+  } as unknown as QaRunJob);
+
+  const blockers: QaRunBlocker[] = [
+    {
+      stage: "validate",
+      reason:
+        `evidence was recorded by hand (${input.evidence.reason}); no re-executable ` +
+        "proof exists, so this result cannot read passed",
+    },
+  ];
+
+  const start = hostSample();
+  return {
+    schema_version: QA_RUN_RESULT_SCHEMA_VERSION,
+    evidence_source: "manual",
+    run: {
+      run_id: runId,
+      started_at: startedAt.toISOString(),
+      completed_at: completedAt.toISOString(),
+      ...revision,
+      job_digest: jobDigest,
+      out_dir: outDir,
+    },
+    host: { start, finish: hostSample() },
+    last_completed_stage: null,
+    target: input.target,
+    ...(revision.tested_revision !== undefined
+      ? { tested_revision: revision.tested_revision }
+      : {}),
+    mode: input.mode,
+    qa_plan: null,
+    contexts: deriveContexts(input.evidence),
+    commands,
+    critique: [],
+    snapshot: { saved: false },
+    wall_time_ms: {
+      plan: 0,
+      gates: 0,
+      interactions: 0,
+      capture: 0,
+      critique: 0,
+      snapshot: 0,
+      total,
+    },
+    blockers,
+    verdict: computeVerdict({
+      mode: input.mode,
+      blockers,
+      commands,
+      critique: [],
+      snapshotSaved: false,
+      evidenceSource: "manual",
+    }),
+  };
+}
+
+export interface QaRecordWritePaths {
+  runDir: string;
+  resultPath: string;
+  evidencePath: string;
+  statusPath: string;
+  latestPath: string;
+}
+
+/**
+ * Write the run directory exactly the way the runner does: the result, the
+ * source document, a terminal status document, and the parent's latest.json
+ * pointer written temp-then-rename so a reader never sees a torn write.
+ */
+export function writeManualRun(
+  result: QaRunResult,
+  evidence: QaManualEvidence,
+): QaRecordWritePaths {
+  const runDir = result.run.out_dir;
+  const outParent = dirname(runDir);
+  mkdirSync(runDir, { recursive: true });
+
+  const evidencePath = join(runDir, QA_RECORD_EVIDENCE_FILENAME);
+  writeFileSync(evidencePath, `${JSON.stringify(evidence, null, 2)}\n`);
+  const resultPath = join(runDir, QA_RUN_RESULT_FILENAME);
+  writeFileSync(resultPath, `${JSON.stringify(result, null, 2)}\n`);
+
+  const status: QaRunStatusDocument = {
+    schema_version: QA_RUN_STATUS_SCHEMA_VERSION,
+    run_id: result.run.run_id,
+    pid: process.pid,
+    state: "completed",
+    stage: null,
+    started_at: result.run.started_at,
+    updated_at: result.run.completed_at,
+    verdict: result.verdict,
+  };
+  const statusPath = join(runDir, QA_RUN_STATUS_FILENAME);
+  const statusTmp = join(runDir, `.${QA_RUN_STATUS_FILENAME}.tmp`);
+  writeFileSync(statusTmp, `${JSON.stringify(status, null, 2)}\n`);
+  renameSync(statusTmp, statusPath);
+
+  const latestPath = writeLatestPointer(outParent, {
+    run_id: result.run.run_id,
+    dir: basename(runDir),
+    completed_at: result.run.completed_at,
+    verdict: result.verdict,
+  });
+
+  return { runDir, resultPath, evidencePath, statusPath, latestPath };
+}
+
+export interface QaRecordOutcome {
+  /** 1 usage or validation error · 2 verdict failed · 4 verdict incomplete.
+   * Never 0: a hand-recorded result cannot report a pass. */
+  exit: 1 | 2 | 4;
+  result?: QaRunResult;
+  paths?: QaRecordWritePaths;
+  error?: string;
+  /** Individual validation errors, all of them, when the document was bad. */
+  evidenceErrors?: string[];
+}
+
+export interface QaRecordInput {
+  target: string;
+  evidencePath: string;
+  mode?: string;
+  outDir?: string;
+  /** Lazy default so invalid evidence does not create an empty artifact workspace. */
+  defaultOutDir?: () => string;
+  runId?: string;
+  completedAt?: Date;
+  /** Injectable for tests; default: the real git probe. */
+  revisionProbe?: () => { tested_revision?: string; worktree_dirty?: boolean } | undefined;
+}
+
+/**
+ * Pure core of qa-record: read the evidence document, validate it completely,
+ * build the result, and write the run directory. The commander action is a
+ * thin wrapper over this so the whole path tests without a CLI harness.
+ */
+export function recordManualQa(input: QaRecordInput): QaRecordOutcome {
+  const mode = input.mode ?? "review";
+  if (mode !== "signoff" && mode !== "review") {
+    return { exit: 1, error: '--mode must be "signoff" or "review"' };
+  }
+  const evidenceAbs = resolve(input.evidencePath);
+  let raw: string;
+  try {
+    raw = readFileSync(evidenceAbs, "utf8");
+  } catch (err: unknown) {
+    return {
+      exit: 1,
+      error: `cannot read --evidence file ${evidenceAbs}: ${err instanceof Error ? err.message : String(err)}`,
+    };
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err: unknown) {
+    return {
+      exit: 1,
+      error: `--evidence file ${evidenceAbs} is not valid JSON: ${err instanceof Error ? err.message : String(err)}`,
+    };
+  }
+
+  const baseDir = dirname(evidenceAbs);
+  const validation = validateManualEvidence(parsed, { baseDir });
+  if (!validation.ok) {
+    return {
+      exit: 1,
+      error: `evidence validation failed with ${validation.errors.length} error${validation.errors.length === 1 ? "" : "s"}`,
+      evidenceErrors: validation.errors,
+    };
+  }
+
+  const probe = (input.revisionProbe ?? probeRevision)();
+  let outParent = input.outDir;
+  if (!outParent && input.defaultOutDir) {
+    try {
+      outParent = input.defaultOutDir();
+    } catch (err: unknown) {
+      return {
+        exit: 1,
+        error: `cannot create managed QA output: ${err instanceof Error ? err.message : String(err)}`,
+      };
+    }
+  }
+  if (!outParent) {
+    return { exit: 1, error: "qa-record requires outDir or defaultOutDir" };
+  }
+
+  const result = buildManualResult({
+    evidence: validation.evidence,
+    target: input.target,
+    mode,
+    outParent,
+    baseDir,
+    ...(input.runId !== undefined ? { runId: input.runId } : {}),
+    ...(probe ? { revisionProbe: probe } : {}),
+    ...(input.completedAt !== undefined ? { completedAt: input.completedAt } : {}),
+  });
+  const paths = writeManualRun(result, validation.evidence);
+  return { exit: result.verdict === "failed" ? 2 : 4, result, paths };
+}
+
+interface QaRecordOpts {
+  evidence?: string;
+  mode: string;
+  outDir?: string;
+  json?: boolean;
+}
+
+export function registerQaRecordCommand(
+  program: Command,
+  emit: EmitContext,
+  context?: HarneryProgramContext,
+): void {
+  program
+    .command("qa-record <target>")
+    .description(
+      "Record hand-performed page QA as a standard result document. Writes the " +
+        "same page-qa-result.json shape, run identity, and timing block the matrix " +
+        "runner writes, marked evidence_source manual, so qa-verify and qa-status " +
+        "treat it like any other result. A manual record can report a defect but " +
+        "never a pass.",
+    )
+    .option(
+      "--evidence <file>",
+      "Evidence document (JSON) describing the checks that were performed by hand, " +
+        "who performed them, and why the runner could not be used. Required.",
+    )
+    .option(
+      "--mode <mode>",
+      "signoff or review. A manual record never saves a QA snapshot either way.",
+      "review",
+    )
+    .option(
+      "--out-dir <dir>",
+      "PARENT output directory (default: a managed .harnery/artifacts workspace). The " +
+        "record lands in its own run-<run_id>/ beneath it and updates the parent's " +
+        "latest.json pointer, exactly like a runner invocation.",
+    )
+    .option("--json", "Print the full result JSON to stdout.")
+    .addHelpText(
+      "after",
+      "\nReach for this only when the matrix runner cannot run: host thrash, a lost " +
+        "bridge, or an interaction no runner can drive. Artifact paths in the evidence " +
+        "document must exist on disk, and secret-bearing fields are refused." +
+        "\n\nExit codes: 1 usage or evidence-validation error · 2 verdict failed · " +
+        "4 verdict incomplete. Never 0 — hand-recorded evidence can prove a defect " +
+        "but never its absence, so the verdict caps at incomplete.",
+    )
+    .action((target: string, opts: QaRecordOpts) => {
+      if (!opts.evidence) {
+        emit.error({
+          code: "qa_record_missing_evidence",
+          message: "--evidence <file> is required: the record IS the evidence document",
+        });
+        process.exitCode = 1;
+        return;
+      }
+      const outcome = recordManualQa({
+        target,
+        evidencePath: opts.evidence,
+        mode: opts.mode,
+        ...(opts.outDir !== undefined ? { outDir: opts.outDir } : {}),
+        defaultOutDir: () => createManagedQaOutParent(resolveQaRepoRoot(context), "qa-record"),
+      });
+      if (outcome.exit === 1 || !outcome.result || !outcome.paths) {
+        for (const message of outcome.evidenceErrors ?? [])
+          emit.log(`evidence: ${message}`, "error");
+        emit.error({
+          code: "qa_record_invalid_evidence",
+          message: outcome.error ?? "qa-record could not write the result",
+        });
+        process.exitCode = 1;
+        return;
+      }
+      const { result, paths } = outcome;
+      // Same status surface as a runner result: an operator should see that
+      // the latest evidence was hand-recorded, not silently see nothing.
+      recordQaSignal(result);
+      if (opts.json) emit.data(result);
+      for (const blocker of result.blockers) {
+        emit.log(`blocker [${blocker.stage}]: ${blocker.reason}`, "warn");
+      }
+      emit.log(
+        `verdict: ${result.verdict} — manual record ${result.run.run_id}, ` +
+          `${result.contexts.length} context${result.contexts.length === 1 ? "" : "s"}, ` +
+          `${result.commands.length} check${result.commands.length === 1 ? "" : "s"}; ` +
+          `result: ${paths.resultPath}`,
+        "warn",
+      );
+      process.exitCode = outcome.exit;
+    });
+}