@starlove/orbit 1.1.2 → 1.2.0

package/src/cli/orbit.js

@@ -43,6 +43,7 @@ Options (dispatch):
   --worktree-path <dir> Worktree path when --worktree is used
   --branch <name>       Branch name for the preserved worktree
   --hermes-bin <cmd>    Hermes executable (default: hermes)
+  --verify-command <cmd> Declare an expected verification command (repeatable)
   --no-spawn            Prepare card/worktree/run record but do not start Hermes or move In Progress
   --no-yolo             Do not pass --yolo to Hermes (default dispatch passes --yolo)
   --foreground          Attach spawned Hermes process to this terminal
@@ -157,6 +158,13 @@ function resetBusyError(error, projectRoot) {
   return wrapped;
 }
 
+function invalidArgs(args, message) {
+  console.error(message);
+  args.command = "help";
+  args.invalid = true;
+  return args;
+}
+
 function parseArgs(argv) {
   const args = {
     command: null,
@@ -180,6 +188,7 @@ function parseArgs(argv) {
     worktreePath: null,
     branch: null,
     hermesBin: "hermes",
+    verifyCommands: [],
     noSpawn: false,
     yolo: true,
     keepHandoffFile: false,
@@ -254,6 +263,18 @@ function parseArgs(argv) {
       args.hermesBin = rest[++i];
     } else if (a.startsWith("--hermes-bin=")) {
       args.hermesBin = a.slice("--hermes-bin=".length);
+    } else if (a === "--verify-command") {
+      const value = rest[i + 1];
+      if (!value || value.startsWith("--")) {
+        return invalidArgs(args, "--verify-command requires a non-empty value. Use --verify-command=<cmd> for values that start with --.");
+      }
+      args.verifyCommands.push(rest[++i]);
+    } else if (a.startsWith("--verify-command=")) {
+      const value = a.slice("--verify-command=".length);
+      if (!value) {
+        return invalidArgs(args, "--verify-command requires a non-empty value.");
+      }
+      args.verifyCommands.push(value);
     } else if (a === "--no-spawn") {
       args.noSpawn = true;
     } else if (a === "--no-yolo") {
@@ -560,6 +581,7 @@ async function runDispatch(options) {
   console.log(`Policy: ${result.policy}`);
   console.log(`Worktree: ${result.worktree_path}`);
   if (result.branch) console.log(`Branch: ${result.branch}`);
+  if (result.run_record_path) console.log(`Run record: ${result.run_record_path}`);
   if (result.pid) console.log(`PID: ${result.pid}`);
   console.log("AI Written-Plan updated with the generated handoff.");
   console.log("Run record comment added to the ticket.");

package/src/core/board.js

@@ -132,6 +132,7 @@ export {
   boardManual
 } from "./boards.js";
 export { archiveTicket, createComment, createTicket, deleteTicket, restoreTicket, updateTicket } from "./tickets.js";
+export { createReviewVerdict, getReviewVerdict, listReviewVerdicts } from "./review-verdicts.js";
 export { archivedTicketsForBoard } from "./queries.js";
 export { getTicketBlockers, getTicketRelations } from "./relations.js";
 export { checkpointTicket, claimNext, completeTicket, getAgentDispatchPacket, getContextPack, getContextPackFull, readComments, readTicket } from "./agent.js";

package/src/core/css-bundle.js

@@ -0,0 +1,29 @@
+// CSS bundling seam for Starscape UI package imports.
+//
+// public/styles.css remains Orbit's editable source of truth, but it can now
+// import @starlove/ui component CSS. Static builds and source dev serving both
+// pass that source through esbuild so browsers never have to resolve package
+// specifiers from raw CSS.
+
+const CURSOR_ASSET_LOADERS = {
+  ".cur": "file"
+};
+
+export async function bundleCss({ entryPoint, outfile, minify = false }) {
+  const { build } = await import("esbuild");
+  const result = await build({
+    entryPoints: [entryPoint],
+    bundle: true,
+    target: "es2022",
+    minify,
+    sourcemap: false,
+    write: false,
+    outfile,
+    assetNames: "cursors/[name]",
+    loader: CURSOR_ASSET_LOADERS,
+    legalComments: "none"
+  });
+  const cssFile = result.outputFiles.find((file) => file.path.endsWith(".css"));
+  if (!cssFile) throw new Error("CSS bundle did not produce a stylesheet");
+  return { cssFile, outputFiles: result.outputFiles };
+}

package/src/core/db.js

@@ -179,6 +179,22 @@ export function createBoardSchema(db) {
       created_at TEXT NOT NULL
     );
 
+    CREATE TABLE IF NOT EXISTS review_verdicts (
+      id TEXT PRIMARY KEY,
+      ticket_id TEXT NOT NULL REFERENCES tickets(id) ON DELETE CASCADE,
+      verdict TEXT NOT NULL CHECK (verdict IN ('PASS', 'BLOCK', 'QUESTION')),
+      blocking_findings_json TEXT NOT NULL DEFAULT '[]',
+      optional_findings_json TEXT NOT NULL DEFAULT '[]',
+      evidence_commands_json TEXT NOT NULL DEFAULT '[]',
+      reviewer_profile TEXT NOT NULL DEFAULT '',
+      reviewer_session_id TEXT NOT NULL DEFAULT '',
+      reviewed_commit_sha TEXT NOT NULL DEFAULT '',
+      dispatch_run_id TEXT NOT NULL DEFAULT '',
+      supersedes_prior_review_id TEXT REFERENCES review_verdicts(id) ON DELETE SET NULL,
+      created_by TEXT NOT NULL DEFAULT 'human',
+      created_at TEXT NOT NULL
+    );
+
     CREATE TABLE IF NOT EXISTS ticket_attachments (
       id TEXT PRIMARY KEY,
       ticket_id TEXT NOT NULL REFERENCES tickets(id) ON DELETE CASCADE,
@@ -251,6 +267,8 @@ export function createBoardSchema(db) {
     CREATE INDEX IF NOT EXISTS idx_tickets_archived ON tickets(board_id, archived_at);
     CREATE INDEX IF NOT EXISTS idx_tickets_parent ON tickets(parent_ticket_id);
     CREATE INDEX IF NOT EXISTS idx_comments_ticket ON comments(ticket_id, created_at);
+    CREATE INDEX IF NOT EXISTS idx_review_verdicts_ticket ON review_verdicts(ticket_id, created_at);
+    CREATE INDEX IF NOT EXISTS idx_review_verdicts_supersedes ON review_verdicts(supersedes_prior_review_id);
     CREATE INDEX IF NOT EXISTS idx_ticket_attachments_ticket ON ticket_attachments(ticket_id, created_at);
     CREATE INDEX IF NOT EXISTS idx_ticket_attachments_board ON ticket_attachments(board_id, created_at);
     CREATE INDEX IF NOT EXISTS idx_board_entries_board ON board_entries(board_id, type, created_at);
@@ -266,6 +284,7 @@ export function resetBoard(db) {
     DELETE FROM ticket_labels;
     DELETE FROM relations;
     DELETE FROM comments;
+    DELETE FROM review_verdicts;
     DELETE FROM ticket_attachments;
     DELETE FROM board_entries;
     DELETE FROM events;

package/src/core/dispatch.js

@@ -11,6 +11,13 @@ import { createComment, updateTicket } from "./tickets.js";
 import { id, normalizePath, slugify } from "./util.js";
 
 const DEFAULT_POLICY = "agent-safe";
+const DEFAULT_VERIFICATION_COMMANDS = [
+  "npm test",
+  "npm run build (when public/ or browser bundle assets change)",
+  "node src/cli/orbit.js dispatch --help",
+  "git diff --check",
+  "git diff --cached --check before commit"
+];
 
 function shortId() {
   return id().replace(/-/g, "").slice(0, 10);
@@ -111,7 +118,8 @@ function resolveRepoRoot(options, boardRow) {
 }
 
 function commandOutput(command, args, options = {}) {
-  const result = spawnSync(command, args, { encoding: "utf8", ...options });
+  const executable = command === "git" ? findExecutable("git") || command : command;
+  const result = spawnSync(executable, args, { encoding: "utf8", ...options });
   if (result.error) throw result.error;
   if (result.status !== 0) {
     const detail = [result.stdout, result.stderr].filter(Boolean).join("\n").trim();
@@ -120,8 +128,101 @@ function commandOutput(command, args, options = {}) {
   return String(result.stdout || "").trim();
 }
 
+function optionalCommandOutput(command, args, options = {}) {
+  try {
+    return commandOutput(command, args, options);
+  } catch {
+    return "";
+  }
+}
+
+function normalizeVerificationCommands(commands) {
+  const values = Array.isArray(commands) ? commands : commands ? [commands] : [];
+  const cleaned = values.map((value) => String(value || "").trim()).filter(Boolean);
+  return cleaned.length ? cleaned : [...DEFAULT_VERIFICATION_COMMANDS];
+}
+
+const REDACTED_URL_PRESENT = "[redacted-url-present]";
+const URL_ENV_KEYS = new Set(["ORBIT_API_URL", "ORBIT_SERVER_URL"]);
+
+function sanitizeUrlBearingValue(value) {
+  if (value === undefined || value === null || value === "") return "";
+  return REDACTED_URL_PRESENT;
+}
+
+function sanitizeEnvironmentValue(key, value) {
+  if (URL_ENV_KEYS.has(key)) return sanitizeUrlBearingValue(value);
+  return value;
+}
+
+function collectEnvironmentVariance() {
+  const envKeys = ["HOME", "PROJECT_ROOT", "DATA_DIR", "ORBIT_MODE", "ORBIT_API_URL", "ORBIT_DEFAULT_BOARD", "ORBIT_SERVER_URL"];
+  const env = {};
+  for (const key of envKeys) {
+    if (process.env[key] !== undefined) env[key] = sanitizeEnvironmentValue(key, process.env[key]);
+  }
+  return {
+    platform: process.platform,
+    node: process.version,
+    cwd: process.cwd(),
+    path_format: process.platform === "win32" ? "windows" : "posix",
+    env
+  };
+}
+
+function buildRunRecordJson({
+  runId,
+  status,
+  boardRow,
+  ticket,
+  profile,
+  policyName,
+  repoRoot,
+  worktreePath,
+  branchName,
+  baseCommit,
+  handoffPath,
+  policyBin,
+  child,
+  hermesArgs,
+  verificationCommands,
+  options,
+  serverUrl,
+  environmentVariance
+}) {
+  return {
+    schema: "orbit.dispatch.run.v1",
+    run_id: runId,
+    ticket_id: ticket.id,
+    ticket_number: ticket.number,
+    board_id: boardRow.id,
+    board_slug: boardRow.slug,
+    profile,
+    prompt_path: handoffPath,
+    worktree: worktreePath || repoRoot,
+    repo_root: repoRoot,
+    branch: branchName || optionalCommandOutput("git", ["-C", repoRoot, "branch", "--show-current"]),
+    base_commit: baseCommit,
+    process_id: child?.pid || null,
+    policy: policyName || "none",
+    status,
+    verification_commands: verificationCommands,
+    commit_shas: [],
+    residual_risks: [],
+    server_url: sanitizeUrlBearingValue(serverUrl),
+    mode: options.noSpawn ? "prepare-only" : "spawn",
+    command: `${options.hermesBin || "hermes"} ${hermesArgs.map((arg) => (arg.includes(" ") ? q(arg) : arg)).join(" ")}`,
+    created_at: new Date().toISOString(),
+    environment_variance: environmentVariance
+  };
+}
+
 function findExecutable(name) {
-  const result = spawnSync("sh", ["-lc", `command -v ${name}`], { encoding: "utf8" });
+  const filteredPath = String(process.env.PATH || "")
+    .split(process.platform === "win32" ? ";" : ":")
+    .filter((entry) => entry && !/(^|[/\\])policy-bin$/i.test(entry))
+    .join(process.platform === "win32" ? ";" : ":");
+  const result = spawnSync("sh", ["-lc", `command -v ${name}`], { encoding: "utf8", env: { ...process.env, PATH: filteredPath } });
   return result.status === 0 ? result.stdout.trim() : "";
 }
 
@@ -264,7 +365,7 @@ exec ${q(realRm)} "$@"
   return binDir;
 }
 
-function buildHandoff({ boardRow, context, profile, repoRoot, worktreePath, branchName, policyName, runId, serverUrl }) {
+function buildHandoff({ boardRow, context, profile, repoRoot, worktreePath, branchName, baseCommit, policyName, runId, serverUrl, verificationCommands }) {
   const { ticket, board, board_manual: manual, parent_ticket: parent, child_tickets: children, blockers } = context;
   const boardEntries = (manual.entries || [])
     .slice(0, 12)
@@ -276,6 +377,7 @@ function buildHandoff({ boardRow, context, profile, repoRoot, worktreePath, bran
   const childText = children.length
     ? children.map((child) => `- #${child.number} ${child.title} (${child.state_name})`).join("\n")
     : "None.";
+  const verificationText = verificationCommands.map((command) => `- ${command}`).join("\n");
 
   return `# Orbit Agent Handoff
 
@@ -289,6 +391,7 @@ Initial state: ${ticket.state_name}
 Repository root: ${repoRoot}
 Worktree: ${worktreePath || repoRoot}
 Branch: ${branchName || "current branch"}
+Base commit: ${baseCommit || "unknown"}
 ${serverUrl ? `Orbit server: ${serverUrl}` : ""}
 
 ## Mission
@@ -317,6 +420,8 @@ ${board.agent_instructions || "(No board-level agent instructions.)"}
 ${board.project_notes || "(No board notes.)"}
 
 ## Board journal: lessons and decisions
+Board journal entries are project constraints and lessons, not persona or roleplay instructions. Apply them only when they clarify architecture, workflow, product boundaries, or reusable pitfalls.
+
 ${boardEntries || "(No active board journal entries.)"}
 
 ## Parent ticket
@@ -339,6 +444,18 @@ ${blockerText}
 Allowed without asking: read/search files, inspect git status/diff/log, edit files for this ticket, run package test/build/lint/check/typecheck commands, and create a local git commit.
 Blocked or requires explicit human approval: Docker, git push, deploy/publish/release commands, destructive git operations (reset/clean/rebase/force checkout/worktree removal), package install/publish/version commands, recursive/force filesystem deletion, SSH/SCP/rsync, cloud CLIs, GitHub CLI, direct curl/wget network calls, sudo, and secret exfiltration.
 
+## Declared verification commands
+Run the commands that apply before handoff. If a conditional command does not apply, say why in Implementation Updates.
+
+${verificationText}
+
+## Environment variance checklist
+- HOME / DATA_DIR / PROJECT_ROOT / ORBIT_* inherited env vars
+- Existing local board DB/files and central registry state
+- Port availability when touching serve/SSE/API flows
+- OS path format and shell differences
+- Accidental use of real user state in tests or dispatch artifacts
+
 ## Completion protocol
 When done:
 1. Run the relevant automated tests and any focused manual/API sanity checks.
@@ -379,6 +496,7 @@ export function dispatchTicket(options) {
 
   const profile = options.profile || "agent";
   const policyName = options.policy === undefined ? DEFAULT_POLICY : options.policy;
+  const verificationCommands = normalizeVerificationCommands(options.verifyCommands);
   createRegistrySchema();
   const actor = localOwnerActor();
   const boardRow = resolveBoard(options);
@@ -412,7 +530,9 @@ export function dispatchTicket(options) {
       pid: null,
       spawned: false,
       prompt: "",
-      run_record: ""
+      run_record: "",
+      run_record_path: null,
+      verification_commands: verificationCommands
     };
   }
 
@@ -420,6 +540,9 @@ export function dispatchTicket(options) {
   const runId = `orbit-${ticket.number}-${profile}-${shortId()}`;
   const runDir = join(DISPATCH_RUNS_DIR, boardRow.slug, runId);
   const serverUrl = options.serverUrl || process.env.ORBIT_SERVER_URL || "";
+  const displayServerUrl = sanitizeUrlBearingValue(serverUrl);
+  const baseCommit = optionalCommandOutput("git", ["-C", repoRoot, "rev-parse", "HEAD"]);
+  const environmentVariance = collectEnvironmentVariance();
   let branchName = options.branch || "";
   let worktreePath = "";
 
@@ -446,14 +569,52 @@ export function dispatchTicket(options) {
     repoRoot,
     worktreePath,
     branchName,
+    baseCommit,
     policyName,
     runId,
-    serverUrl
+    serverUrl: displayServerUrl,
+    verificationCommands
   });
-  const prompt = buildShortPrompt({ boardRow, ticket, profile, serverUrl });
+  const prompt = buildShortPrompt({ boardRow, ticket, profile, serverUrl: displayServerUrl });
   const handoffPath = join(runDir, "handoff.md");
   writeFileSync(handoffPath, handoff, "utf8");
 
+  const hermesArgs = [];
+  if (profile) hermesArgs.push("-p", profile);
+  if (options.yolo) hermesArgs.push("--yolo");
+  hermesArgs.push("chat", "-q", prompt);
+  const runRecordPath = join(runDir, "run-record.json");
+  const writeRunRecordFile = options.writeRunRecordFile || ((path, runRecordJson) => {
+    writeFileSync(path, `${JSON.stringify(runRecordJson, null, 2)}\n`, "utf8");
+  });
+  const writeRunRecordJson = (status, childProcess = null) => {
+    const runRecordJson = buildRunRecordJson({
+      runId,
+      status,
+      boardRow,
+      ticket,
+      profile,
+      policyName,
+      repoRoot,
+      worktreePath,
+      branchName,
+      baseCommit,
+      handoffPath,
+      policyBin,
+      child: childProcess,
+      hermesArgs,
+      verificationCommands,
+      options,
+      serverUrl,
+      environmentVariance
+    });
+    writeRunRecordFile(runRecordPath, runRecordJson);
+    return runRecordJson;
+  };
+
+  let status = "prepared";
+  writeRunRecordJson(status, null);
+
   touchBoardActive(boardRow.id);
   if (options.noSpawn) {
     updateTicket(ticket.id, { ai_plan: handoff }, ctx);
@@ -461,10 +622,6 @@ export function dispatchTicket(options) {
     updateTicket(ticket.id, { ai_plan: handoff, state_id: inProgress.id }, ctx);
   }
 
-  const hermesArgs = [];
-  if (profile) hermesArgs.push("-p", profile);
-  if (options.yolo) hermesArgs.push("--yolo");
-  hermesArgs.push("chat", "-q", prompt);
   const cwd = worktreePath || repoRoot;
   const env = {
     ...process.env,
@@ -486,19 +643,25 @@ export function dispatchTicket(options) {
       stdio: options.foreground ? "inherit" : "ignore"
     });
     if (!options.foreground) child.unref();
+    status = "launched";
+    writeRunRecordJson(status, child);
   }
 
   const runRecord = [
     `Orbit dispatch run ${options.noSpawn ? "prepared" : "started"}.`,
     `- run_id: ${runId}`,
     `- profile: ${profile}`,
+    `- status: ${status}`,
     `- policy: ${policyName || "none"}`,
     `- ticket: #${ticket.number} ${ticket.title}`,
     `- branch: ${branchName || "current branch"}`,
+    `- base_commit: ${baseCommit || "unknown"}`,
     `- worktree: ${worktreePath || repoRoot}`,
     `- handoff: AI Written-Plan field${options.keepHandoffFile ? ` and ${handoffPath}` : ""}`,
+    `- run_record_json: ${runRecordPath}`,
     `- policy_bin: ${policyBin || "none"}`,
     `- pid: ${child?.pid || "not spawned"}`,
+    `- verification_commands: ${verificationCommands.join("; ")}`,
     `- command: ${options.hermesBin || "hermes"} ${hermesArgs.map((arg) => (arg.includes(" ") ? q(arg) : arg)).join(" ")}`,
     options.noSpawn ? "- mode: prepare-only; no agent spawned and ticket state left unchanged" : "- mode: spawned; ticket moved to In Progress"
   ].join("\n");
@@ -527,6 +690,8 @@ export function dispatchTicket(options) {
     pid: child?.pid || null,
     spawned: Boolean(child),
     prompt,
-    run_record: runRecord
+    run_record: runRecord,
+    run_record_path: runRecordPath,
+    verification_commands: verificationCommands
   };
 }

package/src/core/http.js

@@ -1,7 +1,8 @@
 import { readFile } from "node:fs/promises";
 import { createReadStream } from "node:fs";
-import { extname, resolve as resolvePath } from "node:path";
-import { PUBLIC_DIR } from "./paths.js";
+import { extname, join, resolve as resolvePath } from "node:path";
+import { bundleCss } from "./css-bundle.js";
+import { PUBLIC_DIR, ROOT_DIR } from "./paths.js";
 import { httpError } from "./util.js";
 
 export function setCors(res) {
@@ -70,6 +71,10 @@ function contentType(filePath) {
   return types[extname(filePath)] || "application/octet-stream";
 }
 
+function shouldBundleSourceStyles(pathname, filePath) {
+  return pathname === "/styles.css" && filePath === join(ROOT_DIR, "public", "styles.css");
+}
+
 export async function serveStatic(req, res, pathname) {
   if (req.method !== "GET" && req.method !== "HEAD") {
     sendEmpty(res, 405);
@@ -84,7 +89,9 @@ export async function serveStatic(req, res, pathname) {
   }
 
   try {
-    const data = await readFile(filePath);
+    const data = shouldBundleSourceStyles(pathname, filePath)
+      ? Buffer.from((await bundleCss({ entryPoint: filePath, outfile: filePath })).cssFile.contents)
+      : await readFile(filePath);
     res.writeHead(200, {
       "Content-Type": contentType(filePath),
       "Cache-Control": "no-store"

package/src/core/registry.js

@@ -27,7 +27,7 @@ export function getBoardByRepoPath(repoPathNorm) {
     .prepare(
       `SELECT * FROM boards
        WHERE repo_path = ?
-       ORDER BY (last_active_at IS NULL) ASC, last_active_at DESC
+       ORDER BY (last_active_at IS NULL) ASC, last_active_at DESC, rowid DESC
        LIMIT 1`
     )
     .get(repoPathNorm);
@@ -39,7 +39,7 @@ export function pickDefaultBoard() {
   return getRegistry()
     .prepare(
       `SELECT * FROM boards
-       ORDER BY (last_active_at IS NULL) ASC, last_active_at DESC, created_at ASC
+       ORDER BY (last_active_at IS NULL) ASC, last_active_at DESC, rowid DESC
        LIMIT 1`
     )
     .get();

package/src/core/review-verdicts.js

@@ -0,0 +1,138 @@
+import { boardById, ticketById } from "./queries.js";
+import { requireBoardAccess, requirePermission } from "./auth.js";
+import { tx } from "./db.js";
+import { recordEvent } from "./events.js";
+import { bumpTicketUpdatedAt } from "./tickets.js";
+import { httpError, id, now, requiredString } from "./util.js";
+
+const VERDICTS = new Set(["PASS", "BLOCK", "QUESTION"]);
+const JSON_ARRAY_FIELDS = ["blocking_findings", "optional_findings", "evidence_commands"];
+
+export function normalizeReviewVerdict(value) {
+  const verdict = String(value || "").trim().toUpperCase();
+  if (!VERDICTS.has(verdict)) throw httpError(400, "invalid_review_verdict");
+  return verdict;
+}
+
+function normalizeJsonArray(value, field) {
+  if (value === undefined || value === null) return [];
+  if (!Array.isArray(value)) throw httpError(400, `invalid_${field}`);
+  return value;
+}
+
+function optionalString(value) {
+  if (value === undefined || value === null) return "";
+  return String(value).trim();
+}
+
+function hydrateReviewVerdict(row) {
+  if (!row) return null;
+  const hydrated = { ...row };
+  for (const field of JSON_ARRAY_FIELDS) {
+    const jsonField = `${field}_json`;
+    hydrated[field] = JSON.parse(row[jsonField] || "[]");
+    delete hydrated[jsonField];
+  }
+  hydrated.supersedes_prior_review_id = hydrated.supersedes_prior_review_id || null;
+  return hydrated;
+}
+
+function reviewVerdictById(db, reviewId) {
+  return hydrateReviewVerdict(db.prepare("SELECT * FROM review_verdicts WHERE id = ?").get(reviewId));
+}
+
+function requireTicketForReview(ticketId, ctx) {
+  const { db, board, actor } = ctx;
+  const ticket = ticketById(db, ticketId);
+  if (!ticket || ticket.board_id !== board.id) throw httpError(404, "ticket_not_found");
+  requireBoardAccess(actor, boardById(db, ticket.board_id));
+  return ticket;
+}
+
+export function createReviewVerdict(ticketId, body = {}, ctx) {
+  const { db, actor } = ctx;
+  const ticket = requireTicketForReview(ticketId, ctx);
+  requirePermission(actor, "write");
+
+  const verdict = normalizeReviewVerdict(requiredString(body.verdict, "verdict"));
+  const blockingFindings = normalizeJsonArray(body.blocking_findings, "blocking_findings");
+  const optionalFindings = normalizeJsonArray(body.optional_findings, "optional_findings");
+  const evidenceCommands = normalizeJsonArray(body.evidence_commands, "evidence_commands");
+  const supersedesPriorReviewId = optionalString(body.supersedes_prior_review_id) || null;
+
+  if (supersedesPriorReviewId) {
+    const prior = reviewVerdictById(db, supersedesPriorReviewId);
+    if (!prior) throw httpError(400, "invalid_supersedes_prior_review_id");
+    if (prior.ticket_id !== ticket.id) throw httpError(400, "superseded_review_ticket_mismatch");
+  }
+
+  const reviewId = id();
+  return tx(db, () => {
+    const time = now();
+    db.prepare(
+      `INSERT INTO review_verdicts
+       (id, ticket_id, verdict, blocking_findings_json, optional_findings_json,
+        evidence_commands_json, reviewer_profile, reviewer_session_id,
+        reviewed_commit_sha, dispatch_run_id, supersedes_prior_review_id,
+        created_by, created_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`
+    ).run(
+      reviewId,
+      ticket.id,
+      verdict,
+      JSON.stringify(blockingFindings),
+      JSON.stringify(optionalFindings),
+      JSON.stringify(evidenceCommands),
+      optionalString(body.reviewer_profile),
+      optionalString(body.reviewer_session_id),
+      optionalString(body.reviewed_commit_sha),
+      optionalString(body.dispatch_run_id),
+      supersedesPriorReviewId,
+      actor.name,
+      time
+    );
+    db.prepare("UPDATE tickets SET updated_at = ? WHERE id = ?").run(time, ticket.id);
+    recordEvent(db, ticket.board_id, "review_verdict_created", ticket.id, actor.name, {
+      review_id: reviewId,
+      verdict,
+      supersedes_prior_review_id: supersedesPriorReviewId,
+      reviewed_commit_sha: optionalString(body.reviewed_commit_sha),
+      dispatch_run_id: optionalString(body.dispatch_run_id),
+      actor_type: actor.type,
+      actor_id: actor.id
+    });
+    bumpTicketUpdatedAt(db, ticket.parent_ticket_id, time);
+    return getReviewVerdict(reviewId, ctx);
+  });
+}
+
+export function getReviewVerdict(reviewId, ctx) {
+  const { db, board, actor } = ctx;
+  const review = reviewVerdictById(db, reviewId);
+  if (!review) throw httpError(404, "review_verdict_not_found");
+  const ticket = ticketById(db, review.ticket_id);
+  if (!ticket || ticket.board_id !== board.id) throw httpError(404, "review_verdict_not_found");
+  requireBoardAccess(actor, boardById(db, ticket.board_id));
+  return review;
+}
+
+export function listReviewVerdicts(ticketId, ctx, options = {}) {
+  const { db } = ctx;
+  const ticket = requireTicketForReview(ticketId, ctx);
+  const limit = normalizeLimit(options.limit);
+  return db
+    .prepare(
+      `SELECT * FROM review_verdicts
+       WHERE ticket_id = ?
+       ORDER BY created_at DESC, rowid DESC
+       LIMIT ?`
+    )
+    .all(ticket.id, limit)
+    .map(hydrateReviewVerdict);
+}
+
+function normalizeLimit(value) {
+  const n = Number(value ?? 50);
+  if (!Number.isInteger(n) || n <= 0) return 50;
+  return Math.min(n, 200);
+}