harnery 0.18.0 → 0.19.1

package/src/commands/supervisor.ts

@@ -617,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"),
@@ -627,6 +628,29 @@ 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,
   };
 }
 
@@ -690,6 +714,11 @@ 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}`);
     }
@@ -747,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`);
@@ -775,6 +812,12 @@ function emitPlan(plan: SupervisorPlanRecord, json: boolean | undefined, emit: E
       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}`);
   emit.text(`${lines.join("\n")}\n`);
@@ -798,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,8 +1,14 @@
 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,
@@ -12,6 +18,13 @@ export {
   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,

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

@@ -1,7 +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,
@@ -9,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}$/;
@@ -24,6 +34,7 @@ const MAX_EVENTS = 100;
 const EVENT_TYPES = new Set<SupervisorPlanEventType>([
   "plan.awaiting_approval",
   "plan.resumed",
+  "plan.reviewed",
   "plan.proposed",
   "plan.applied",
   "plan.completed",
@@ -126,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(
@@ -288,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 ||

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

@@ -1,4 +1,6 @@
 export const SUPERVISOR_PLAN_SCHEMA_VERSION = 1 as const;
+export const MAX_SUPERVISOR_PLAN_REVIEWERS = 5 as const;
+export const MAX_SUPERVISOR_PLAN_REVISION_ROUNDS = 3 as const;
 
 export interface SupervisorPlanTemplate {
   workflow: { path: string; sha256: string };
@@ -13,6 +15,10 @@ export interface SupervisorReplanningPolicy {
   max_work_items_per_plan: number;
   max_total_work_items: number;
   templates: Record<string, SupervisorPlanTemplate>;
+  review?: {
+    reviewer_specialists: string[];
+    max_revision_rounds: number;
+  };
 }
 
 export interface CreateSupervisorPlanTemplateInput {
@@ -28,6 +34,10 @@ export interface CreateSupervisorReplanningInput {
   maxWorkItemsPerPlan?: number;
   maxTotalWorkItems?: number;
   templates: Readonly<Record<string, CreateSupervisorPlanTemplateInput>>;
+  review?: {
+    reviewerSpecialists: readonly string[];
+    maxRevisionRounds: number;
+  };
 }
 
 export interface SupervisorPlanRequest {
@@ -72,6 +82,7 @@ export interface SupervisorPlanProposal {
 export type SupervisorPlanEventType =
   | "plan.awaiting_approval"
   | "plan.resumed"
+  | "plan.reviewed"
   | "plan.proposed"
   | "plan.applied"
   | "plan.completed"
@@ -79,6 +90,49 @@ export type SupervisorPlanEventType =
   | "plan.attention"
   | "plan.failed";
 
+export type SupervisorPlanReviewStatus = "passed" | "revision_exhausted" | "attention" | "failed";
+
+export type SupervisorPlanReviewVerdict = "approve" | "revise" | "attention";
+
+export interface SupervisorPlanReviewFinding {
+  code: string;
+  severity: "blocking" | "advisory";
+  summary: string;
+  recommendation: string;
+}
+
+export interface SupervisorPlanReviewReviewer {
+  specialist: string;
+  verdict: SupervisorPlanReviewVerdict;
+  rationale: string;
+  findings: SupervisorPlanReviewFinding[];
+}
+
+export interface SupervisorPlanReviewRound {
+  round: number;
+  candidate_sha256: string;
+  reviewers: SupervisorPlanReviewReviewer[];
+  outcome: "approved" | "revise" | "attention" | "failed";
+  revision_workflow_run_id?: string;
+}
+
+export interface SupervisorPlanReviewReceipt {
+  schema_version: typeof SUPERVISOR_PLAN_SCHEMA_VERSION;
+  plan_id: string;
+  status: SupervisorPlanReviewStatus;
+  candidate_sha256: string;
+  final_candidate: SupervisorPlanProposal;
+  rounds: SupervisorPlanReviewRound[];
+}
+
+export interface SupervisorPlanReviewSummary {
+  status: SupervisorPlanReviewStatus;
+  candidate_sha256: string;
+  rounds: number;
+  blocking_findings: number;
+  advisory_findings: number;
+}
+
 export interface SupervisorPlanEvent {
   schema_version: typeof SUPERVISOR_PLAN_SCHEMA_VERSION;
   plan_id: string;
@@ -106,6 +160,7 @@ export type SupervisorPlanStatus =
 export interface SupervisorPlanRecord {
   request: SupervisorPlanRequest;
   proposal?: SupervisorPlanProposal;
+  review?: SupervisorPlanReviewSummary;
   events: SupervisorPlanEvent[];
   status: SupervisorPlanStatus;
   approval_id?: string;