harnery 0.17.0 → 0.19.0

package/src/commands/supervisor.ts

@@ -9,6 +9,7 @@ import type { PolicyIsolation } from "../core/policy/index.ts";
 import { loadPolicyFile } from "../core/policy/index.ts";
 import {
   approveSupervisorPlan,
+  type CreateSupervisorMissionInput,
   type CreateSupervisorReplanningInput,
   configureSupervisorService,
   createSupervisor,
@@ -46,6 +47,7 @@ interface CreateOpts {
   resumeApproved?: boolean;
   retryBlocked?: boolean;
   replanning?: string;
+  mission?: string;
   json?: boolean;
 }
 
@@ -75,8 +77,8 @@ export function registerSupervisorCommand(program: Command, emit: EmitContext):
     .description("Run a bounded specialist team over a durable-work dependency graph.");
 
   supervisor
-    .command("create <root-work-id>")
-    .description("Freeze a goal, specialist team, automation policy, and execution limits.")
+    .command("create [root-work-id]")
+    .description("Freeze an existing-root goal or an objective-first bounded mission.")
     .requiredOption("--team <file>", "JSON object mapping specialist ids to profiles")
     .option("--id <goal-id>", "Stable goal id (generated by default)")
     .option("--title <text>", "Goal title (defaults to root work title)")
@@ -90,8 +92,9 @@ export function registerSupervisorCommand(program: Command, emit: EmitContext):
     .option("--no-resume-approved", "Stop after an approval instead of resuming its parked run")
     .option("--retry-blocked", "Allow bounded retry of blocked work")
     .option("--replanning <file>", "Frozen planner policy and allowed workflow-template catalog")
+    .option("--mission <file>", "Frozen objective, acceptance criteria, and milestone bound")
     .option("--json", "Emit the complete supervisor record as JSON")
-    .action((rootWorkId: string, opts: CreateOpts) => {
+    .action((rootWorkId: string | undefined, opts: CreateOpts) => {
       withSupervisorRoot(emit, (coordRoot) => {
         const specialists = readTeamFile(opts.team);
         for (const [id, profile] of Object.entries(specialists)) {
@@ -121,6 +124,7 @@ export function registerSupervisorCommand(program: Command, emit: EmitContext):
               resume_approved: opts.resumeApproved,
               retry_blocked: opts.retryBlocked,
             },
+            mission: opts.mission ? readMissionFile(opts.mission) : undefined,
             replanning: opts.replanning ? readReplanningFile(opts.replanning) : undefined,
           }),
           opts.json,
@@ -613,6 +617,7 @@ function readReplanningFile(path: string): CreateSupervisorReplanningInput {
       ];
     }),
   );
+  const review = readReplanningReview(config.review);
   return {
     plannerSpecialist: config.planner_specialist,
     autoApply: jsonBoolean(config.auto_apply, "replanning auto_apply"),
@@ -623,6 +628,57 @@ function readReplanningFile(path: string): CreateSupervisorReplanningInput {
     ),
     maxTotalWorkItems: jsonInteger(config.max_total_work_items, "replanning max_total_work_items"),
     templates,
+    ...(review ? { review } : {}),
+  };
+}
+
+function readReplanningReview(raw: unknown): CreateSupervisorReplanningInput["review"] | undefined {
+  if (raw === undefined) return undefined;
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+    throw new Error("supervisor replanning review must be a JSON object");
+  }
+  const review = raw as Record<string, unknown>;
+  if (
+    !Array.isArray(review.reviewer_specialists) ||
+    review.reviewer_specialists.some((item) => typeof item !== "string")
+  ) {
+    throw new Error(
+      "supervisor replanning review reviewer_specialists must be an array of strings",
+    );
+  }
+  return {
+    reviewerSpecialists: review.reviewer_specialists as string[],
+    maxRevisionRounds:
+      jsonNonNegativeInteger(review.max_revision_rounds, "replanning review max_revision_rounds") ??
+      0,
+  };
+}
+
+function readMissionFile(path: string): CreateSupervisorMissionInput {
+  const absolute = resolve(path);
+  let value: unknown;
+  try {
+    value = JSON.parse(readFileSync(absolute, "utf8"));
+  } catch (error) {
+    throw new Error(`cannot read supervisor mission at ${absolute}: ${(error as Error).message}`);
+  }
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("supervisor mission must be a JSON object");
+  }
+  const config = value as Record<string, unknown>;
+  if (typeof config.objective !== "string") {
+    throw new Error("supervisor mission objective must be a string");
+  }
+  if (
+    !Array.isArray(config.acceptance) ||
+    config.acceptance.some((item) => typeof item !== "string")
+  ) {
+    throw new Error("supervisor mission acceptance must be an array of strings");
+  }
+  return {
+    objective: config.objective,
+    acceptance: config.acceptance as string[],
+    maxMilestones: jsonInteger(config.max_milestones, "mission max_milestones"),
   };
 }
 
@@ -645,7 +701,7 @@ function emitSupervisor(
   const lines = [
     `${record.intent.id}: ${record.intent.title}`,
     `state: ${projection.state}`,
-    `root: ${projection.root_work_id}`,
+    `root: ${projection.root_materialized ? projection.root_work_id : "pending initial plan"}`,
     `reason: ${projection.reason}`,
     `next: ${projection.next_action}`,
     `work: ${projection.work_ids.length}`,
@@ -658,11 +714,23 @@ function emitSupervisor(
     lines.push(
       `replanning: generation=${projection.plan_generation}, used=${projection.replans_used}/${record.intent.replanning.max_replans}, auto_apply=${record.intent.replanning.auto_apply}`,
     );
+    if (record.intent.replanning.review) {
+      lines.push(
+        `plan review: reviewers=${record.intent.replanning.review.reviewer_specialists.join(", ")}, max_revision_rounds=${record.intent.replanning.review.max_revision_rounds}`,
+      );
+    }
     if (projection.root_work_id !== record.intent.root_work_id) {
       lines.push(`original root: ${record.intent.root_work_id}`);
     }
     if (projection.pending_plan_id) lines.push(`pending plan: ${projection.pending_plan_id}`);
   }
+  if (record.intent.mission) {
+    lines.push(`mission: ${record.intent.mission.objective}`);
+    lines.push(
+      `milestones: ${projection.milestones_completed}/${record.intent.mission.max_milestones}`,
+    );
+    lines.push(`mission acceptance: ${record.intent.mission.acceptance.length}`);
+  }
   if (projection.attention_work.length) {
     lines.push(`attention: ${projection.attention_work.join(", ")}`);
   }
@@ -708,6 +776,14 @@ function jsonInteger(value: unknown, field: string): number | undefined {
   return value as number;
 }
 
+function jsonNonNegativeInteger(value: unknown, field: string): number | undefined {
+  if (value === undefined) return undefined;
+  if (!Number.isSafeInteger(value) || (value as number) < 0) {
+    throw new Error(`${field} must be a non-negative integer`);
+  }
+  return value as number;
+}
+
 function jsonBoolean(value: unknown, field: string): boolean | undefined {
   if (value === undefined) return undefined;
   if (typeof value !== "boolean") throw new Error(`${field} must be boolean`);
@@ -724,6 +800,7 @@ function emitPlan(plan: SupervisorPlanRecord, json: boolean | undefined, emit: E
     `${plan.request.id}: ${plan.status}`,
     `goal: ${plan.request.goal_id}`,
     `sequence: ${plan.request.sequence}`,
+    `trigger: ${plan.request.trigger ?? "recovery"}`,
     `prior root: ${plan.request.prior_root_work_id}`,
     `planner run: ${plan.request.workflow_run_id}`,
   ];
@@ -731,6 +808,15 @@ function emitPlan(plan: SupervisorPlanRecord, json: boolean | undefined, emit: E
     lines.push(`decision: ${plan.proposal.decision}`);
     lines.push(`rationale: ${plan.proposal.rationale}`);
     lines.push(`proposed work: ${plan.proposal.work.length}`);
+    if (plan.proposal.milestone) {
+      lines.push(`milestone: ${plan.proposal.milestone.sequence} ${plan.proposal.milestone.title}`);
+    }
+  }
+  if (plan.review) {
+    lines.push(
+      `review: ${plan.review.status}, rounds=${plan.review.rounds}, blocking=${plan.review.blocking_findings}, advisory=${plan.review.advisory_findings}`,
+    );
+    lines.push(`review candidate: ${plan.review.candidate_sha256}`);
   }
   if (plan.root_work_id) lines.push(`applied root: ${plan.root_work_id}`);
   if (plan.approval_id) lines.push(`approval: ${plan.approval_id}`);
@@ -755,7 +841,8 @@ function emitPlanOutcome(
 }
 
 function renderPlanRow(plan: SupervisorPlanRecord): string {
-  return `${plan.request.id}  ${plan.status.padEnd(18)}  ${plan.request.prior_root_work_id}`;
+  const review = plan.review ? `  review:${plan.review.status}` : "";
+  return `${plan.request.id}  ${plan.status.padEnd(18)}  ${plan.request.prior_root_work_id}${review}`;
 }
 
 function delay(ms: number): Promise<void> {

package/src/core/supervisor/index.ts

@@ -1,16 +1,30 @@
 export { approveSupervisorPlan, rejectSupervisorPlan } from "./plan-api.ts";
-export { readSupervisorPlan, readSupervisorPlans } from "./plan-read.ts";
+export {
+  readSupervisorPlan,
+  readSupervisorPlanReviewReceipt,
+  readSupervisorPlans,
+} from "./plan-read.ts";
 export {
   type CreateSupervisorPlanTemplateInput,
   type CreateSupervisorReplanningInput,
+  MAX_SUPERVISOR_PLAN_REVIEWERS,
+  MAX_SUPERVISOR_PLAN_REVISION_ROUNDS,
   SUPERVISOR_PLAN_SCHEMA_VERSION,
   type SupervisorPlanEvent,
   type SupervisorPlanEventType,
   type SupervisorPlanHistory,
+  type SupervisorPlanMilestone,
   type SupervisorPlanOutcome,
   type SupervisorPlanProposal,
   type SupervisorPlanRecord,
   type SupervisorPlanRequest,
+  type SupervisorPlanReviewFinding,
+  type SupervisorPlanReviewReceipt,
+  type SupervisorPlanReviewReviewer,
+  type SupervisorPlanReviewRound,
+  type SupervisorPlanReviewStatus,
+  type SupervisorPlanReviewSummary,
+  type SupervisorPlanReviewVerdict,
   type SupervisorPlanStatus,
   type SupervisorPlanTemplate,
   type SupervisorPlanWorkSpec,
@@ -53,6 +67,7 @@ export {
 export {
   assertSupervisorId,
   type CreateSupervisorInput,
+  type CreateSupervisorMissionInput,
   collectSupervisorWork,
   createSupervisor,
   listSupervisors,
@@ -62,6 +77,7 @@ export {
   type SupervisorAutomationPolicy,
   type SupervisorIntent,
   type SupervisorLimits,
+  type SupervisorMission,
   type SupervisorNextAction,
   type SupervisorProjection,
   type SupervisorRecord,

package/src/core/supervisor/plan-read.ts

@@ -1,6 +1,10 @@
+import { createHash } from "node:crypto";
 import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { join, resolve } from "node:path";
+import { readWorkItem } from "../work/read.ts";
 import {
+  MAX_SUPERVISOR_PLAN_REVIEWERS,
+  MAX_SUPERVISOR_PLAN_REVISION_ROUNDS,
   SUPERVISOR_PLAN_SCHEMA_VERSION,
   type SupervisorPlanEvent,
   type SupervisorPlanEventType,
@@ -8,6 +12,13 @@ import {
   type SupervisorPlanProposal,
   type SupervisorPlanRecord,
   type SupervisorPlanRequest,
+  type SupervisorPlanReviewFinding,
+  type SupervisorPlanReviewReceipt,
+  type SupervisorPlanReviewReviewer,
+  type SupervisorPlanReviewRound,
+  type SupervisorPlanReviewSummary,
+  type SupervisorPlanReviewVerdict,
+  type SupervisorReplanningPolicy,
 } from "./plan-types.ts";
 
 const PLAN_ID = /^plan-[0-9]{4}-[a-f0-9]{8}$/;
@@ -23,8 +34,10 @@ const MAX_EVENTS = 100;
 const EVENT_TYPES = new Set<SupervisorPlanEventType>([
   "plan.awaiting_approval",
   "plan.resumed",
+  "plan.reviewed",
   "plan.proposed",
   "plan.applied",
+  "plan.completed",
   "plan.rejected",
   "plan.attention",
   "plan.failed",
@@ -46,6 +59,8 @@ export function readSupervisorPlans(
       generation: 0,
       applied_work_ids: [],
       materialized_work_ids: [],
+      milestones_completed: 0,
+      completed: false,
     };
   }
   const entries = readdirSync(root, { withFileTypes: true })
@@ -64,6 +79,8 @@ export function readSupervisorPlans(
   }
   let activeRoot = originalRootWorkId;
   let generation = 0;
+  let milestonesCompleted = 0;
+  let completed = false;
   const appliedWork = new Set<string>();
   const materializedWork = new Set<string>();
   for (const plan of plans) {
@@ -76,14 +93,30 @@ export function readSupervisorPlans(
     if (plan.status !== "applied" || !plan.root_work_id) continue;
     activeRoot = plan.root_work_id;
     generation++;
+    if (
+      plan.proposal?.milestone &&
+      readWorkItem(coordRoot, plan.root_work_id).projection.state === "succeeded"
+    ) {
+      milestonesCompleted++;
+    }
     for (const workId of plan.work_ids) appliedWork.add(workId);
   }
+  const completedPlans = plans.filter((plan) => plan.status === "completed");
+  if (
+    completedPlans.length > 1 ||
+    (completedPlans.length === 1 && completedPlans[0] !== plans.at(-1))
+  ) {
+    throw new Error(`supervisor ${goalId} has invalid completion history`);
+  }
+  completed = completedPlans.length === 1;
   return {
     plans,
     active_root_work_id: activeRoot,
     generation,
     applied_work_ids: [...appliedWork],
     materialized_work_ids: [...materializedWork],
+    milestones_completed: milestonesCompleted,
+    completed,
     latest: plans.at(-1),
   };
 }
@@ -104,9 +137,33 @@ export function readSupervisorPlan(
     ? readJson<SupervisorPlanProposal>(proposalPath, "plan proposal")
     : undefined;
   if (proposal) validateProposalEnvelope(proposal, planId);
+  const review = readSupervisorPlanReviewReceipt(coordRootRaw, goalId, planId);
   const events = readEvents(join(dir, "events.jsonl"), planId);
   const derived = deriveStatus(coordRoot, events, proposal);
-  return { request, proposal, events, ...derived };
+  return {
+    request,
+    proposal,
+    review: review ? summarizeReview(review) : undefined,
+    events,
+    ...derived,
+  };
+}
+
+export function readSupervisorPlanReviewReceipt(
+  coordRootRaw: string,
+  goalId: string,
+  planId: string,
+): SupervisorPlanReviewReceipt | undefined {
+  assertId(goalId, GOAL_ID, "supervisor id");
+  assertId(planId, PLAN_ID, "supervisor plan id");
+  const coordRoot = resolve(coordRootRaw);
+  const path = join(planDir(coordRoot, goalId, planId), "review.json");
+  if (!existsSync(path)) return undefined;
+  const receipt = readJson<SupervisorPlanReviewReceipt>(path, "plan review receipt");
+  validateReviewReceipt(receipt, planId);
+  const reviewPolicy = readFrozenReviewPolicy(coordRoot, goalId);
+  if (reviewPolicy) validateReviewReceiptMatchesPolicy(receipt, planId, reviewPolicy);
+  return receipt;
 }
 
 function deriveStatus(
@@ -115,6 +172,10 @@ function deriveStatus(
   proposal: SupervisorPlanProposal | undefined,
 ): Pick<SupervisorPlanRecord, "status" | "approval_id" | "root_work_id" | "work_ids" | "reason"> {
   const latest = events.at(-1);
+  const completed = [...events].reverse().find((event) => event.event === "plan.completed");
+  if (completed) {
+    return { status: "completed", work_ids: [], reason: completed.reason };
+  }
   const applied = [...events].reverse().find((event) => event.event === "plan.applied");
   if (applied) {
     return {
@@ -180,6 +241,8 @@ function validateRequest(request: SupervisorPlanRequest, goalId: string, planId:
     !Number.isSafeInteger(request.sequence) ||
     request.sequence < 1 ||
     request.sequence > MAX_PLANS ||
+    (request.trigger !== undefined &&
+      !["initial", "recovery", "milestone"].includes(request.trigger)) ||
     typeof request.trigger_fingerprint !== "string" ||
     request.trigger_fingerprint.length < 1 ||
     request.trigger_fingerprint.length > 64_000 ||
@@ -195,7 +258,7 @@ function validateProposalEnvelope(proposal: SupervisorPlanProposal, planId: stri
   if (
     proposal.schema_version !== SUPERVISOR_PLAN_SCHEMA_VERSION ||
     proposal.plan_id !== planId ||
-    !["apply", "attention"].includes(proposal.decision) ||
+    !["apply", "complete", "attention"].includes(proposal.decision) ||
     typeof proposal.rationale !== "string" ||
     proposal.rationale.length < 1 ||
     proposal.rationale.length > 2_000 ||
@@ -207,6 +270,35 @@ function validateProposalEnvelope(proposal: SupervisorPlanProposal, planId: stri
   ) {
     throw new Error(`supervisor plan proposal ${planId} has an unsupported schema`);
   }
+  if (proposal.milestone !== undefined) {
+    const milestone = proposal.milestone;
+    if (
+      !Number.isSafeInteger(milestone.sequence) ||
+      milestone.sequence < 1 ||
+      milestone.sequence > 20 ||
+      typeof milestone.title !== "string" ||
+      milestone.title.length < 1 ||
+      milestone.title.length > 200 ||
+      typeof milestone.objective !== "string" ||
+      milestone.objective.length < 1 ||
+      milestone.objective.length > 4_000 ||
+      !Array.isArray(milestone.acceptance) ||
+      milestone.acceptance.length < 1 ||
+      milestone.acceptance.length > 50 ||
+      milestone.acceptance.some(
+        (criterion) =>
+          typeof criterion !== "string" || criterion.length < 1 || criterion.length > 500,
+      )
+    ) {
+      throw new Error(`supervisor plan proposal ${planId} milestone is invalid`);
+    }
+  }
+  if (
+    (proposal.decision === "attention" || proposal.decision === "complete") &&
+    (proposal.root !== "" || proposal.work.length > 0 || proposal.milestone !== undefined)
+  ) {
+    throw new Error(`supervisor plan proposal ${planId} terminal decision contains work`);
+  }
   for (const [index, spec] of proposal.work.entries()) {
     if (
       !spec ||
@@ -231,6 +323,204 @@ function validateProposalEnvelope(proposal: SupervisorPlanProposal, planId: stri
   }
 }
 
+function validateReviewReceipt(receipt: SupervisorPlanReviewReceipt, planId: string): void {
+  if (
+    !receipt ||
+    typeof receipt !== "object" ||
+    receipt.schema_version !== SUPERVISOR_PLAN_SCHEMA_VERSION ||
+    receipt.plan_id !== planId ||
+    !["passed", "revision_exhausted", "attention", "failed"].includes(receipt.status) ||
+    !/^[a-f0-9]{64}$/.test(receipt.candidate_sha256) ||
+    !Array.isArray(receipt.rounds) ||
+    receipt.rounds.length < 1 ||
+    receipt.rounds.length > MAX_SUPERVISOR_PLAN_REVISION_ROUNDS + 1
+  ) {
+    throw new Error(`supervisor plan review ${planId} has an unsupported schema`);
+  }
+  validateProposalEnvelope(receipt.final_candidate, planId);
+  if (receipt.candidate_sha256 !== candidateDigest(receipt.final_candidate)) {
+    throw new Error(`supervisor plan review ${planId} has invalid candidate digest`);
+  }
+  receipt.rounds.forEach((round, index) => {
+    validateReviewRound(round, planId, index + 1);
+  });
+  const finalRound = receipt.rounds.at(-1);
+  if (finalRound?.candidate_sha256 !== receipt.candidate_sha256) {
+    throw new Error(`supervisor plan review ${planId} final round does not match its candidate`);
+  }
+  if (receipt.status === "passed" && finalRound?.outcome !== "approved") {
+    throw new Error(`supervisor plan review ${planId} passed without approval`);
+  }
+  if (receipt.status === "attention" && finalRound?.outcome === "approved") {
+    throw new Error(`supervisor plan review ${planId} attention conflicts with approval`);
+  }
+}
+
+function readFrozenReviewPolicy(
+  coordRoot: string,
+  goalId: string,
+): SupervisorReplanningPolicy["review"] | undefined {
+  const path = join(coordRoot, ".harnery", "supervisors", goalId, "intent.json");
+  if (!existsSync(path)) return undefined;
+  const intent = readJson<{ replanning?: SupervisorReplanningPolicy }>(path, "supervisor intent");
+  return intent.replanning?.review;
+}
+
+function validateReviewReceiptMatchesPolicy(
+  receipt: SupervisorPlanReviewReceipt,
+  planId: string,
+  review: NonNullable<SupervisorReplanningPolicy["review"]>,
+): void {
+  if (receipt.rounds.length > review.max_revision_rounds + 1) {
+    throw new Error(`supervisor plan review ${planId} exceeds the frozen review policy`);
+  }
+  for (const round of receipt.rounds) {
+    if (round.reviewers.length !== review.reviewer_specialists.length) {
+      throw new Error(`supervisor plan review ${planId} does not match the frozen review policy`);
+    }
+    round.reviewers.forEach((reviewer, index) => {
+      if (reviewer.specialist !== review.reviewer_specialists[index]) {
+        throw new Error(`supervisor plan review ${planId} does not match the frozen review policy`);
+      }
+    });
+    const outcome = aggregateReviewers(round.reviewers);
+    if (round.outcome !== outcome) {
+      throw new Error(`supervisor plan review ${planId} has an invalid reviewer outcome`);
+    }
+  }
+  const finalRound = receipt.rounds.at(-1)!;
+  if (receipt.status === "passed" && finalRound.outcome !== "approved") {
+    throw new Error(`supervisor plan review ${planId} passed without policy approval`);
+  }
+  if (receipt.status === "revision_exhausted" && finalRound.round <= review.max_revision_rounds) {
+    throw new Error(`supervisor plan review ${planId} exhausted before the frozen review limit`);
+  }
+}
+
+function aggregateReviewers(
+  reviewers: readonly SupervisorPlanReviewReviewer[],
+): SupervisorPlanReviewRound["outcome"] {
+  if (reviewers.length < 1) return "failed";
+  if (reviewers.some((reviewer) => reviewer.verdict === "attention")) return "attention";
+  if (
+    reviewers.some(
+      (reviewer) =>
+        reviewer.verdict === "revise" ||
+        reviewer.findings.some((finding) => finding.severity === "blocking"),
+    )
+  ) {
+    return "revise";
+  }
+  return "approved";
+}
+
+function candidateDigest(candidate: SupervisorPlanProposal): string {
+  return createHash("sha256")
+    .update(JSON.stringify(canonicalCandidate(candidate)))
+    .digest("hex");
+}
+
+function canonicalCandidate(candidate: SupervisorPlanProposal): unknown {
+  return {
+    schema_version: candidate.schema_version,
+    plan_id: candidate.plan_id,
+    decision: candidate.decision,
+    rationale: candidate.rationale,
+    root: candidate.root,
+    work: candidate.work,
+    milestone: candidate.milestone,
+  };
+}
+
+function validateReviewRound(
+  round: SupervisorPlanReviewRound,
+  planId: string,
+  sequence: number,
+): void {
+  if (
+    !round ||
+    typeof round !== "object" ||
+    round.round !== sequence ||
+    !/^[a-f0-9]{64}$/.test(round.candidate_sha256) ||
+    !Array.isArray(round.reviewers) ||
+    round.reviewers.length < 1 ||
+    round.reviewers.length > MAX_SUPERVISOR_PLAN_REVIEWERS ||
+    !["approved", "revise", "attention", "failed"].includes(round.outcome) ||
+    (round.revision_workflow_run_id !== undefined &&
+      !/^[A-Za-z0-9][A-Za-z0-9._-]{0,199}$/.test(round.revision_workflow_run_id))
+  ) {
+    throw new Error(`supervisor plan review ${planId} round ${sequence} is invalid`);
+  }
+  round.reviewers.forEach((reviewer, index) => {
+    validateReviewReviewer(reviewer, planId, sequence, index);
+  });
+}
+
+function validateReviewReviewer(
+  reviewer: SupervisorPlanReviewReviewer,
+  planId: string,
+  round: number,
+  index: number,
+): void {
+  if (
+    !reviewer ||
+    typeof reviewer !== "object" ||
+    typeof reviewer.specialist !== "string" ||
+    reviewer.specialist.length < 1 ||
+    reviewer.specialist.length > 100 ||
+    !["approve", "revise", "attention"].includes(reviewer.verdict as SupervisorPlanReviewVerdict) ||
+    typeof reviewer.rationale !== "string" ||
+    reviewer.rationale.length < 1 ||
+    reviewer.rationale.length > 2_000 ||
+    !Array.isArray(reviewer.findings) ||
+    reviewer.findings.length > 50
+  ) {
+    throw new Error(`supervisor plan review ${planId} round ${round} reviewer ${index} is invalid`);
+  }
+  reviewer.findings.forEach((finding, findingIndex) => {
+    validateReviewFinding(finding, planId, round, index, findingIndex);
+  });
+}
+
+function validateReviewFinding(
+  finding: SupervisorPlanReviewFinding,
+  planId: string,
+  round: number,
+  reviewerIndex: number,
+  findingIndex: number,
+): void {
+  if (
+    !finding ||
+    typeof finding !== "object" ||
+    typeof finding.code !== "string" ||
+    !/^[a-z][a-z0-9._-]{0,99}$/.test(finding.code) ||
+    !["blocking", "advisory"].includes(finding.severity) ||
+    typeof finding.summary !== "string" ||
+    finding.summary.length < 1 ||
+    finding.summary.length > 1_000 ||
+    typeof finding.recommendation !== "string" ||
+    finding.recommendation.length < 1 ||
+    finding.recommendation.length > 1_000
+  ) {
+    throw new Error(
+      `supervisor plan review ${planId} round ${round} reviewer ${reviewerIndex} finding ${findingIndex} is invalid`,
+    );
+  }
+}
+
+function summarizeReview(receipt: SupervisorPlanReviewReceipt): SupervisorPlanReviewSummary {
+  const findings = receipt.rounds.flatMap((round) =>
+    round.reviewers.flatMap((reviewer) => reviewer.findings),
+  );
+  return {
+    status: receipt.status,
+    candidate_sha256: receipt.candidate_sha256,
+    rounds: receipt.rounds.length,
+    blocking_findings: findings.filter((finding) => finding.severity === "blocking").length,
+    advisory_findings: findings.filter((finding) => finding.severity === "advisory").length,
+  };
+}
+
 function validateEvent(event: SupervisorPlanEvent, planId: string, sequence: number): void {
   if (
     event.schema_version !== SUPERVISOR_PLAN_SCHEMA_VERSION ||