@effect-agent/pr-review 0.1.0-beta.24 → 0.1.0-beta.26

package/src/internal/adjudication.ts

@@ -0,0 +1,415 @@
+import { Context, DateTime, Effect, Layer, Schema } from "effect";
+
+import { INLINE_FINDING_TITLE_PATTERN } from "./retirement.ts";
+import {
+  adjudicationIdentity,
+  MAX_STORED_ADJUDICATIONS,
+  StoredAdjudication,
+  type AdjudicationDisposition,
+  type StoredReviewFinding,
+} from "./review-state.ts";
+
+// ---------------------------------------------------------------------------
+// Maintainer adjudication. GitHub reads stay behind ReviewAdjudicationHost;
+// this module owns only the deterministic verb grammar, fail-closed
+// authorization, later-wins resolution, and prompt-context rendering. Only an
+// explicit, authorized `/adjudicate` verb adjudicates — free-text rebuttals
+// are deliberately never parsed, because only an explicit verb is auditable
+// and fail-closed (model output and third-party comments are untrusted
+// input, AGENTS.md rule 11).
+// ---------------------------------------------------------------------------
+
+const PositiveLine = Schema.Int.check(Schema.isGreaterThan(0));
+
+/** Maximum authorized command candidates retained for one inline thread. */
+export const MAX_THREAD_ADJUDICATION_COMMANDS = 100;
+
+/** One reply or top-level comment observed through the adjudication host. */
+export class AdjudicationComment extends Schema.Class<AdjudicationComment>(
+  "@effect-agent/pr-review/AdjudicationComment",
+)({
+  body: Schema.String.check(Schema.isMaxLength(65_536)),
+  /** GitHub's author_association for the comment author, verbatim. */
+  authorAssociation: Schema.String.check(Schema.isMaxLength(40)),
+  authorLogin: Schema.NonEmptyString.check(Schema.isMaxLength(100)),
+  /** Creation time; a comment without one loses every later-wins tie. */
+  createdAt: Schema.NullOr(Schema.DateTimeUtc),
+  /** Stable zero-based order in the source listing, before thread grouping. */
+  sourceOrder: Schema.Int.check(Schema.isGreaterThanOrEqualTo(0)),
+}) {}
+
+/** One of the action's own inline finding threads, replies in creation order. */
+export class AdjudicableThread extends Schema.Class<AdjudicableThread>(
+  "@effect-agent/pr-review/AdjudicableThread",
+)({
+  path: Schema.NonEmptyString.check(Schema.isMaxLength(500)),
+  startLine: Schema.NullOr(PositiveLine),
+  endLine: Schema.NullOr(PositiveLine),
+  /** The root comment's body; its first line carries the finding title. */
+  rootBody: Schema.String.check(Schema.isMaxLength(65_536)),
+  replies: Schema.Array(AdjudicationComment).check(
+    Schema.isMaxLength(MAX_THREAD_ADJUDICATION_COMMANDS),
+  ),
+}) {}
+
+/** A GitHub adjudication read failed. */
+export class ReviewAdjudicationFailure extends Schema.TaggedError<ReviewAdjudicationFailure>()(
+  "ReviewAdjudicationFailure",
+  {
+    operation: Schema.String,
+    reason: Schema.String,
+  },
+) {
+  override get message() {
+    return `Review adjudication operation '${this.operation}' failed: ${this.reason}`;
+  }
+}
+
+/**
+ * Host-side GitHub reads used by adjudication. Domain code never reaches into
+ * REST directly, and deterministic tests substitute this port. Both listings
+ * return comments in creation order.
+ */
+export class ReviewAdjudicationHost extends Context.Service<
+  ReviewAdjudicationHost,
+  {
+    /** This action's own inline finding threads with their replies. */
+    readonly listFindingThreads: Effect.Effect<
+      ReadonlyArray<AdjudicableThread>,
+      ReviewAdjudicationFailure
+    >;
+    /** Top-level pull-request conversation comments. */
+    readonly listIssueComments: Effect.Effect<
+      ReadonlyArray<AdjudicationComment>,
+      ReviewAdjudicationFailure
+    >;
+  }
+>()("@effect-agent/pr-review/ReviewAdjudicationHost") {}
+
+/** Explicit program-edge adapter for runs that intentionally perform no host reads. */
+export const noReviewAdjudicationHost = ReviewAdjudicationHost.of({
+  listFindingThreads: Effect.succeed([]),
+  listIssueComments: Effect.succeed([]),
+});
+
+/** Layer form of {@link noReviewAdjudicationHost}. */
+export const noReviewAdjudicationHostLayer =
+  Layer.succeed(ReviewAdjudicationHost)(noReviewAdjudicationHost);
+
+// ---------------------------------------------------------------------------
+// Verb grammar. A body whose first line starts with `/adjudicate` is a
+// command; a command that fails the grammar is malformed and ignored rather
+// than guessed at. Fail-closed authorization: only OWNER, MEMBER, and
+// COLLABORATOR authors may adjudicate.
+// ---------------------------------------------------------------------------
+
+/** author_associations allowed to adjudicate; everything else is ignored. */
+export const AUTHORIZED_ADJUDICATION_ASSOCIATIONS: ReadonlySet<string> = new Set([
+  "OWNER",
+  "MEMBER",
+  "COLLABORATOR",
+]);
+
+const AdjudicationDispositionSchema = Schema.Literals(["accepted-risk", "refuted", "obsolete"]);
+
+const THREAD_COMMAND_PATTERN = /^\/adjudicate[ \t]+([a-z-]+)[ \t]*(?::[ \t]*(.*\S))?[ \t]*$/;
+const ISSUE_COMMAND_PATTERN =
+  /^\/adjudicate[ \t]+([a-z-]+)[ \t]+"([^"\n]+)"[ \t]*(?::[ \t]*(.*\S))?[ \t]*$/;
+
+export interface ParsedAdjudicationCommand {
+  readonly disposition: AdjudicationDisposition;
+  /** Present only for the issue-comment grammar's quoted target title. */
+  readonly title?: string | undefined;
+  readonly reason?: string | undefined;
+}
+
+const firstLine = (body: string): string => (body.split("\n", 1)[0] ?? "").trim();
+
+const boundedReason = (raw: string | undefined): string | undefined => {
+  if (raw === undefined) return undefined;
+  const trimmed = raw.trim().slice(0, 300);
+  return trimmed.length === 0 ? undefined : trimmed;
+};
+
+/**
+ * Parse one inline-thread reply: `/adjudicate <disposition>(: <reason>)?`.
+ * The thread itself names the target identity. Returns undefined for a
+ * non-command body and "malformed" for a command that fails the grammar.
+ */
+export const parseThreadAdjudication = (
+  body: string,
+): ParsedAdjudicationCommand | "malformed" | undefined => {
+  const line = firstLine(body);
+  if (!line.startsWith("/adjudicate")) return undefined;
+  const match = THREAD_COMMAND_PATTERN.exec(line);
+  const disposition = match?.[1];
+  if (disposition === undefined || !Schema.is(AdjudicationDispositionSchema)(disposition)) {
+    return "malformed";
+  }
+  return { disposition, reason: boundedReason(match?.[2]) };
+};
+
+/**
+ * Parse one top-level PR comment:
+ * `/adjudicate <disposition> "<exact title>"(: <reason>)?`. The quoted title
+ * is required because the conversation names no finding thread; it targets
+ * the title-alone identity of an unanchored concern.
+ */
+export const parseIssueAdjudication = (
+  body: string,
+): ParsedAdjudicationCommand | "malformed" | undefined => {
+  const line = firstLine(body);
+  if (!line.startsWith("/adjudicate")) return undefined;
+  const match = ISSUE_COMMAND_PATTERN.exec(line);
+  const disposition = match?.[1];
+  const title = match?.[2];
+  if (
+    disposition === undefined ||
+    !Schema.is(AdjudicationDispositionSchema)(disposition) ||
+    title === undefined ||
+    title.length > 120
+  ) {
+    return "malformed";
+  }
+  return { disposition, title, reason: boundedReason(match?.[3]) };
+};
+
+/** The finding identity an inline thread names, or undefined when unparsable. */
+export const threadFindingTarget = (
+  thread: AdjudicableThread,
+):
+  | {
+      readonly path: string;
+      readonly startLine: number;
+      readonly endLine: number;
+      readonly title: string;
+    }
+  | undefined => {
+  if (thread.startLine === null || thread.endLine === null) return undefined;
+  const title = INLINE_FINDING_TITLE_PATTERN.exec(firstLine(thread.rootBody))?.[1];
+  if (title === undefined || title.length > 120) return undefined;
+  return {
+    path: thread.path,
+    startLine: thread.startLine,
+    endLine: thread.endLine,
+    title,
+  };
+};
+
+// ---------------------------------------------------------------------------
+// Deterministic derivation: authorization, later-wins, bounded storage.
+// ---------------------------------------------------------------------------
+
+interface AdjudicationCandidate {
+  readonly adjudication: StoredAdjudication;
+  readonly epochMillis: number;
+  readonly sourceOrder: number;
+}
+
+export interface DerivedAdjudications {
+  readonly adjudications: ReadonlyArray<StoredAdjudication>;
+  /** Commands ignored fail-closed: unauthorized authors and malformed bodies. */
+  readonly ignored: ReadonlyArray<string>;
+  /** Later-wins winners dropped oldest-first at the storage bound. */
+  readonly droppedOldest: number;
+}
+
+/**
+ * Derive the standing adjudications from the host's listings. Every command
+ * is screened fail-closed (authorization, grammar, a parsable target); later
+ * adjudications of the same identity win by comment creation order; the
+ * result is capped at the ReviewState bound dropping the oldest winners.
+ */
+export const deriveAdjudications = (input: {
+  readonly threads: ReadonlyArray<AdjudicableThread>;
+  readonly issueComments: ReadonlyArray<AdjudicationComment>;
+}): DerivedAdjudications => {
+  const candidates: Array<AdjudicationCandidate> = [];
+  const ignored: Array<string> = [];
+  const admit = (
+    comment: AdjudicationComment,
+    command: ParsedAdjudicationCommand,
+    target: {
+      readonly path?: string | undefined;
+      readonly startLine?: number | undefined;
+      readonly endLine?: number | undefined;
+      readonly title: string;
+    },
+  ): void => {
+    candidates.push({
+      adjudication: StoredAdjudication.make({
+        ...(target.path === undefined ? {} : { path: target.path }),
+        ...(target.startLine === undefined ? {} : { startLine: target.startLine }),
+        ...(target.endLine === undefined ? {} : { endLine: target.endLine }),
+        title: target.title,
+        disposition: command.disposition,
+        ...(command.reason === undefined ? {} : { reason: command.reason }),
+        actor: comment.authorLogin,
+      }),
+      epochMillis: comment.createdAt === null ? -1 : DateTime.toEpochMillis(comment.createdAt),
+      sourceOrder: comment.sourceOrder,
+    });
+  };
+  const authorized = (comment: AdjudicationComment, surface: string): boolean => {
+    if (AUTHORIZED_ADJUDICATION_ASSOCIATIONS.has(comment.authorAssociation)) return true;
+    ignored.push(
+      `${surface}: unauthorized /adjudicate from @${comment.authorLogin} (${comment.authorAssociation})`,
+    );
+    return false;
+  };
+
+  for (const thread of input.threads) {
+    const target = threadFindingTarget(thread);
+    for (const reply of thread.replies) {
+      const command = parseThreadAdjudication(reply.body);
+      if (command === undefined) continue;
+      const surface = `inline thread ${thread.path}`;
+      if (command === "malformed") {
+        ignored.push(`${surface}: malformed /adjudicate command from @${reply.authorLogin}`);
+        continue;
+      }
+      if (!authorized(reply, surface)) continue;
+      if (target === undefined) {
+        ignored.push(`${surface}: thread root names no parsable finding title`);
+        continue;
+      }
+      admit(reply, command, target);
+    }
+  }
+  for (const comment of input.issueComments) {
+    const command = parseIssueAdjudication(comment.body);
+    if (command === undefined) continue;
+    const surface = "pull-request conversation";
+    if (command === "malformed") {
+      ignored.push(`${surface}: malformed /adjudicate command from @${comment.authorLogin}`);
+      continue;
+    }
+    if (!authorized(comment, surface)) continue;
+    if (command.title === undefined) {
+      ignored.push(`${surface}: /adjudicate without a quoted target title`);
+      continue;
+    }
+    admit(comment, command, { title: command.title });
+  }
+
+  const byIdentity = new Map<string, AdjudicationCandidate>();
+  const ordered = [...candidates].sort(
+    (left, right) => left.epochMillis - right.epochMillis || left.sourceOrder - right.sourceOrder,
+  );
+  for (const candidate of ordered) {
+    const identity = adjudicationIdentity(candidate.adjudication);
+    // Delete-then-set so a later adjudication also refreshes its recency for
+    // the oldest-first drop below.
+    byIdentity.delete(identity);
+    byIdentity.set(identity, candidate);
+  }
+  const winners = [...byIdentity.values()];
+  const droppedOldest = Math.max(0, winners.length - MAX_STORED_ADJUDICATIONS);
+  return {
+    adjudications: winners.slice(droppedOldest).map((candidate) => candidate.adjudication),
+    ignored,
+    droppedOldest,
+  };
+};
+
+/** Later-wins merge of stored prior adjudications with freshly derived ones. */
+export const mergeAdjudications = (
+  prior: ReadonlyArray<StoredAdjudication>,
+  fresh: ReadonlyArray<StoredAdjudication>,
+): ReadonlyArray<StoredAdjudication> => {
+  const byIdentity = new Map<string, StoredAdjudication>();
+  for (const adjudication of [...prior, ...fresh]) {
+    const identity = adjudicationIdentity(adjudication);
+    byIdentity.delete(identity);
+    byIdentity.set(identity, adjudication);
+  }
+  const merged = [...byIdentity.values()];
+  return merged.slice(Math.max(0, merged.length - MAX_STORED_ADJUDICATIONS));
+};
+
+/**
+ * Collect the standing maintainer adjudications: freshly derived through the
+ * host, merged later-wins over the prior state's stored set. The host is a
+ * visible Effect requirement; program edges that intentionally perform no
+ * reads provide {@link noReviewAdjudicationHost}. Fail-open — any listing
+ * fault keeps the complete prior set and never fails the review, because NOT
+ * suppressing a finding is the conservative direction.
+ */
+export const collectReviewAdjudications = Effect.fn("collectReviewAdjudications")(function* (
+  prior: ReadonlyArray<StoredAdjudication>,
+) {
+  const host = yield* ReviewAdjudicationHost;
+  const listings = yield* Effect.all({
+    threads: host.listFindingThreads,
+    issueComments: host.listIssueComments,
+  }).pipe(
+    Effect.catch((error) =>
+      Effect.logWarning(
+        `Could not collect adjudications from '${error.operation}': ${error.reason}; retaining stored adjudications unchanged.`,
+      ).pipe(Effect.as(undefined)),
+    ),
+  );
+  if (listings === undefined) return prior;
+  const derived = deriveAdjudications({
+    threads: listings.threads,
+    issueComments: listings.issueComments,
+  });
+  for (const note of derived.ignored) {
+    yield* Effect.logDebug(`Ignored adjudication command — ${note}`);
+  }
+  if (derived.droppedOldest > 0) {
+    yield* Effect.logWarning(
+      `Dropped ${derived.droppedOldest} oldest adjudication(s) over the ${MAX_STORED_ADJUDICATIONS}-entry bound.`,
+    );
+  }
+  return mergeAdjudications(prior, derived.adjudications);
+});
+
+// ---------------------------------------------------------------------------
+// Prompt-context rendering: deterministic bounded lines the reviewer sees.
+// ---------------------------------------------------------------------------
+
+const lineRange = (startLine: number, endLine: number): string =>
+  `${startLine}${endLine === startLine ? "" : `-${endLine}`}`;
+
+/** One adjudication as a bounded reviewer-prompt context line. */
+export const renderAdjudicationContextLine = (adjudication: StoredAdjudication): string => {
+  const location =
+    adjudication.path !== undefined &&
+    adjudication.startLine !== undefined &&
+    adjudication.endLine !== undefined
+      ? `${adjudication.path}:${lineRange(adjudication.startLine, adjudication.endLine)}`
+      : "(unanchored)";
+  const reason = adjudication.reason === undefined ? "" : `: ${adjudication.reason}`;
+  return `${location} "${adjudication.title}" — ${adjudication.disposition} by @${adjudication.actor}${reason}`;
+};
+
+/** One prior-round finding as a bounded reviewer-prompt context line. */
+export const renderPriorFindingContextLine = (finding: StoredReviewFinding): string =>
+  `${finding.path}:${lineRange(finding.startLine, finding.endLine)} [${finding.severity}] "${finding.title}" — ${finding.body.slice(0, 400)}`;
+
+/** Prior-review context threaded into fan-out discovery briefs, per path. */
+export interface PriorReviewContext {
+  /** Adjudicated identities; path-free entries apply to every unit. */
+  readonly adjudicated: ReadonlyArray<{
+    readonly path: string | undefined;
+    readonly line: string;
+  }>;
+  /** Prior-round findings whose paths are being re-reviewed. */
+  readonly priorFindings: ReadonlyArray<{ readonly path: string; readonly line: string }>;
+}
+
+/** Build the fan-out prior-review context from the resolved continuity data. */
+export const buildPriorReviewContext = (
+  adjudications: ReadonlyArray<StoredAdjudication>,
+  priorFindingsOnScope: ReadonlyArray<StoredReviewFinding>,
+): PriorReviewContext => ({
+  adjudicated: adjudications.map((adjudication) => ({
+    path: adjudication.path,
+    line: renderAdjudicationContextLine(adjudication),
+  })),
+  priorFindings: priorFindingsOnScope.map((finding) => ({
+    path: finding.path,
+    line: renderPriorFindingContextLine(finding),
+  })),
+});

package/src/internal/coverage.ts

@@ -19,37 +19,6 @@ import type { ReviewUnitPlan } from "./review-units.ts";
 // results; only the flat reviewer is assessed from its Run event trace here.
 // ---------------------------------------------------------------------------
 
-export class FailedReviewUnit extends Schema.Class<FailedReviewUnit>(
-  "@effect-agent/pr-review/FailedReviewUnit",
-)({
-  unitId: Schema.NonEmptyString.check(Schema.isMaxLength(32)),
-  errorTag: Schema.NonEmptyString.check(Schema.isMaxLength(256)),
-}) {}
-
-/**
- * Compatibility diagnostic retained for callers that consumed the original
- * `coverage` field. New UI and state decisions use ReviewInputCoverage and
- * ReviewAssurance directly.
- */
-export class ReviewCoverage extends Schema.Class<ReviewCoverage>(
-  "@effect-agent/pr-review/ReviewCoverage",
-)({
-  status: Schema.Literals(["complete", "incomplete"]),
-  requiredPaths: Schema.Array(Schema.NonEmptyString.check(Schema.isMaxLength(512))).check(
-    Schema.isMaxLength(300),
-  ),
-  reviewedPaths: Schema.Array(Schema.NonEmptyString.check(Schema.isMaxLength(512))).check(
-    Schema.isMaxLength(300),
-  ),
-  unreviewedPaths: Schema.Array(Schema.NonEmptyString.check(Schema.isMaxLength(512))).check(
-    Schema.isMaxLength(300),
-  ),
-  failedUnits: Schema.Array(FailedReviewUnit).check(Schema.isMaxLength(8)),
-  reasons: Schema.Array(Schema.NonEmptyString.check(Schema.isMaxLength(1_000))).check(
-    Schema.isMaxLength(32),
-  ),
-}) {}
-
 export class ReviewInputCoverage extends Schema.Class<ReviewInputCoverage>(
   "@effect-agent/pr-review/ReviewInputCoverage",
 )({
@@ -159,6 +128,47 @@ export const boundedListReason = (label: string, values: Iterable<string>): stri
   return rendered;
 };
 
+export interface CarriedScope {
+  /** Carried paths a retry can actually settle (failed passes, overflow). */
+  readonly retryablePaths: ReadonlyArray<string>;
+  /** Carried paths no retry can settle (binaries, oversized files). */
+  readonly undiffablePaths: ReadonlyArray<string>;
+  /** Whether any incompleteness beyond the undiffable files exists. */
+  readonly retryableGap: boolean;
+}
+
+/**
+ * Split carried scope into paths a retry can settle and paths it never can.
+ * Undiffable files are a property of the pull request, not a transient
+ * reviewer-side failure: gate reasons and rendered callouts must never promise
+ * they are "retried automatically" — the honest instruction is to remove them
+ * from the pull request or exclude them with ignore globs.
+ */
+export const splitCarriedScope = (input: {
+  readonly inputCoverage?: ReviewInputCoverage | undefined;
+  readonly assurance?: ReviewAssurance | undefined;
+  readonly unreviewedPaths?: ReadonlyArray<string> | undefined;
+}): CarriedScope => {
+  const undiffable = new Set(input.inputCoverage?.undiffablePaths ?? []);
+  const retryablePaths = (input.unreviewedPaths ?? []).filter((path) => !undiffable.has(path));
+  const undiffablePaths = sortedUnique(undiffable);
+  // Every non-undiffable coverage gap (range truncation, capacity overflow,
+  // truncated or missing evidence, anchor surface) contributes its own reason
+  // line, so a lone reason alongside undiffable paths means the undiffable
+  // files are the entire gap.
+  const coverageGapBeyondUndiffable =
+    input.inputCoverage?.status === "incomplete" &&
+    input.inputCoverage.reasons.length > (undiffablePaths.length > 0 ? 1 : 0);
+  return {
+    retryablePaths,
+    undiffablePaths,
+    retryableGap:
+      input.assurance?.status === "incomplete" ||
+      retryablePaths.length > 0 ||
+      coverageGapBeyondUndiffable,
+  };
+};
+
 const anchorSurfaceAdjusted = (
   inputCoverage: ReviewInputCoverage,
   anchorFiles: ReadonlyArray<ChangedFile>,
@@ -345,32 +355,3 @@ export const fanOutInputCoverage = (input: {
     input.totalAnchorFiles,
   );
 };
-
-/** Compatibility aggregate over the two precise claims. */
-export const compatibilityCoverage = (
-  inputCoverage: ReviewInputCoverage,
-  assurance: ReviewAssurance,
-): ReviewCoverage => {
-  const assuranceIncomplete = assurance.status === "incomplete";
-  const failedUnits = new Map<string, FailedReviewUnit>();
-  for (const pass of assurance.failedPasses) {
-    const unitId = pass.workId.slice(0, "unit-000".length);
-    if (!failedUnits.has(unitId)) {
-      failedUnits.set(
-        unitId,
-        FailedReviewUnit.make({ unitId, errorTag: `${pass.stage}:${pass.errorTag}` }),
-      );
-    }
-  }
-  return ReviewCoverage.make({
-    status: inputCoverage.status === "complete" && !assuranceIncomplete ? "complete" : "incomplete",
-    requiredPaths: inputCoverage.requiredPaths,
-    reviewedPaths: inputCoverage.assignedPaths,
-    unreviewedPaths: sortedUnique([
-      ...inputCoverage.partialPaths,
-      ...inputCoverage.unassignedPaths,
-    ]),
-    failedUnits: [...failedUnits.values()].slice(0, 8),
-    reasons: [...inputCoverage.reasons, ...(assuranceIncomplete ? assurance.reasons : [])],
-  });
-};

package/src/internal/fan-out.ts

@@ -11,6 +11,7 @@ import {
 } from "effect-agent";
 import { Toolkit } from "effect/unstable/ai";
 
+import type { PriorReviewContext } from "./adjudication.ts";
 import { anchorViolation } from "./anchors.ts";
 import { boundedListReason, FailedReviewPass, ReviewAssurance } from "./coverage.ts";
 import { ChangedFileStatus, ChangedPath, type ChangedFile } from "./diff.ts";
@@ -174,8 +175,8 @@ export const confirmedFindingForPublication = (
 /**
  * Concern candidates need explicit paths internally to bind the claim to
  * scheduled evidence. The verifier receives the complete bounded unit so it
- * can use neighboring evidence to falsify the claim. The public ReviewConcern
- * remains path-free after the host confirms and projects it.
+ * can use neighboring evidence to falsify the claim. The host copies these
+ * validated paths onto a confirmed public concern for incremental continuity.
  */
 export class DiscoveredConcern extends Schema.Class<DiscoveredConcern>(
   "@effect-agent/pr-review/DiscoveredConcern",
@@ -190,6 +191,11 @@ const UnitPaths = Schema.Array(ChangedPath)
   .check(Schema.isMinLength(1))
   .check(Schema.isMaxLength(MAX_UNIT_FILES));
 
+/** Bounded prior-review context lines injected into discovery instructions. */
+const UnitContextLines = Schema.Array(Schema.String.check(Schema.isMaxLength(1_200))).check(
+  Schema.isMaxLength(20),
+);
+
 const RiskCategories = Schema.Array(ReviewRiskCategory).check(Schema.isMaxLength(6));
 const Candidates = Schema.Array(ReviewCandidate).check(Schema.isMaxLength(MAX_UNIT_CANDIDATES));
 const EvidenceShardIds = Schema.Array(ReviewEvidenceShardId)
@@ -225,6 +231,10 @@ export class FileReviewBrief extends Schema.Class<FileReviewBrief>(
   evidence: Schema.Array(FileReviewEvidence)
     .check(Schema.isMinLength(1))
     .check(Schema.isMaxLength(MAX_UNIT_EVIDENCE_SHARDS)),
+  /** Maintainer-adjudicated identities on this unit; do not re-raise. */
+  adjudicatedContext: Schema.optionalKey(UnitContextLines),
+  /** Prior-round findings on this unit's re-reviewed paths. */
+  priorFindingContext: Schema.optionalKey(UnitContextLines),
 }) {}
 
 /** Child output; phase-inapplicable collections must be empty. */
@@ -297,11 +307,25 @@ export const makeFileReviewerInstructions =
           ? `This is a fresh specialist discovery pass. Concentrate on these host-classified risks without relying on another pass: ${brief.riskCategories.join(", ")}.`
           : "This is a fresh specialist discovery pass. The host found no keyword-classified category, so independently scrutinize authentication/authorization, security boundaries, durability, concurrency, credentials, and external side effects rather than treating classification silence as low risk."
         : "This is the general discovery pass. Review broadly for correctness, security, concurrency, resource, API, and error-handling defects.";
+    const adjudicated = brief.adjudicatedContext ?? [];
+    const priorFindings = brief.priorFindingContext ?? [];
     return [
       ...common,
       focus,
+      ...(adjudicated.length === 0
+        ? []
+        : [
+            "A maintainer has adjudicated these previously raised items on this unit (disposition, reason). Do not re-raise them unless you have materially new evidence, and if you do, say explicitly what changed since the adjudication:",
+            ...adjudicated.map((line) => `- ${line}`),
+          ]),
+      ...(priorFindings.length === 0
+        ? []
+        : [
+            "A previous review round raised these findings on this unit's paths. For each, either confirm it still holds, state that it is fixed, or withdraw it; do not demand the opposite of that prior guidance without explicitly acknowledging the reversal:",
+            ...priorFindings.map((line) => `- ${line}`),
+          ]),
       "The discovery evidence array contains every complete shard in the unit. Review every entry and every shard of a multi-shard path. A later independent verifier, not you, decides which candidates publish.",
-      "When a non-anchored concern depends on one or more unit files, list 1-3 exact evidencePaths to bind the claim to scheduled evidence.",
+      "Every non-anchored concern must list 1-3 exact evidencePaths to bind the claim to scheduled evidence. Report one root concern once; never split it into differently worded restatements.",
       `Return ONLY JSON with phase "discovery", the exact workId/unitId, up to ${MAX_CHILD_FINDINGS} findings, up to ${MAX_CHILD_CONCERNS} concerns shaped as {concern, evidencePaths}, one factual file summary per path (<= ${MAX_WALKTHROUGH_SUMMARY_CHARS} chars), and an empty assessments array. Empty candidate arrays are valid; do not invent defects.`,
       'Each finding is {"path": <a unit file path>, "startLine": <integer, an R-marked new-file line>, "endLine": <integer, >= startLine, same file, R-marked>, "severity": <"blocking" | "important" | "nit">, "category": <OPTIONAL problem-kind label>, "title": <string, <= 120 chars>, "body": <string, why it matters and what to do>, "suggestion": <string, OPTIONAL: replacement source code for exactly lines startLine..endLine, ready to commit>}.',
       'Include "suggestion" only when you are confident the replacement compiles and preserves intent; its text must contain the full replacement source for every line in the range and nothing else — never prose describing the change, which belongs in "body".',
@@ -388,6 +412,12 @@ export interface FanOutPipelineInput {
         readonly stages: ReadonlyArray<FailedReviewPass["stage"]>;
       }
     | undefined;
+  /**
+   * Adjudicated identities and prior-round findings injected as discovery
+   * context on the units whose paths they touch. Context only — they never
+   * enter candidates or publication.
+   */
+  readonly priorContext?: PriorReviewContext | undefined;
 }
 
 const candidateOrdinal = (index: number): string => String(index + 1).padStart(3, "0");
@@ -625,6 +655,19 @@ const reviewUnit = <Provider, ModelProvides, ModelRequires>(
     let turns = 0;
     let completedGeneralPasses = 0;
     let completedSpecialistPasses = 0;
+    // Discovery-only context: adjudicated identities (path-free entries apply
+    // to every unit) and prior-round findings on this unit's paths. The
+    // verifier stays unbiased — it judges only the candidate claims and the
+    // bounded evidence.
+    const unitPaths = new Set(unit.paths);
+    const adjudicatedContext = (input.priorContext?.adjudicated ?? [])
+      .filter((entry) => entry.path === undefined || unitPaths.has(entry.path))
+      .map((entry) => entry.line)
+      .slice(0, 20);
+    const priorFindingContext = (input.priorContext?.priorFindings ?? [])
+      .filter((entry) => unitPaths.has(entry.path))
+      .map((entry) => entry.line)
+      .slice(0, 20);
     for (const pass of passes) {
       const stage = pass.perspective === "risk-specialist" ? "specialist" : "discovery";
       const brief = FileReviewBrief.make({
@@ -637,6 +680,8 @@ const reviewUnit = <Provider, ModelProvides, ModelRequires>(
         riskCategories: pass.riskCategories,
         candidates: [],
         evidence,
+        ...(adjudicatedContext.length === 0 ? {} : { adjudicatedContext }),
+        ...(priorFindingContext.length === 0 ? {} : { priorFindingContext }),
       });
       const outcome = yield* runReviewPass(binding, brief, input.budget);
       if (outcome._tag === "failed") {
@@ -962,7 +1007,14 @@ export const runFanOutReview = <Provider, ModelProvides, ModelRequires>(
     );
     const concerns = rankAndDedupeConcerns(
       confirmed.flatMap(({ candidate }) =>
-        candidate._tag === "ConcernCandidate" ? [candidate.concern] : [],
+        candidate._tag === "ConcernCandidate"
+          ? [
+              ReviewConcern.make({
+                ...candidate.concern,
+                evidencePaths: [...new Set(candidate.evidencePaths)].sort(),
+              }),
+            ]
+          : [],
       ),
     );
     const walkthrough = outcomes.flatMap((outcome) => outcome.walkthrough);