@effect-agent/pr-review 0.1.0-beta.23 → 0.1.0-beta.25

package/src/internal/github.ts

@@ -2,6 +2,15 @@ import type { Redacted } from "effect";
 import { Context, DateTime, Effect, Layer, Option, Schema } from "effect";
 import { HttpClient, HttpClientRequest, HttpClientResponse } from "effect/unstable/http";
 
+import {
+  AdjudicableThread,
+  AdjudicationComment,
+  AUTHORIZED_ADJUDICATION_ASSOCIATIONS,
+  MAX_THREAD_ADJUDICATION_COMMANDS,
+  parseThreadAdjudication,
+  ReviewAdjudicationFailure,
+  ReviewAdjudicationHost,
+} from "./adjudication.ts";
 import { ChangedFile } from "./diff.ts";
 import { extractFingerprint } from "./fingerprint.ts";
 import type { ReviewPublicationPlan } from "./render.ts";
@@ -130,8 +139,9 @@ const GitHubReviewCommentWire = Schema.Struct({
   node_id: Schema.String,
   path: Schema.String,
   body: Schema.String,
-  line: Schema.NullOr(Schema.Int),
-  original_line: Schema.NullOr(Schema.Int),
+  // Outdated comments omit `line` entirely instead of sending null.
+  line: Schema.optionalKey(Schema.NullOr(Schema.Int)),
+  original_line: Schema.optionalKey(Schema.NullOr(Schema.Int)),
   start_line: Schema.optionalKey(Schema.NullOr(Schema.Int)),
   original_start_line: Schema.optionalKey(Schema.NullOr(Schema.Int)),
 });
@@ -578,8 +588,11 @@ export const gitHubReviewRetirementHostLayer: Layer.Layer<
         }).pipe(
           Effect.map((comments) =>
             comments.map((comment) => {
-              const endLine = comment.line ?? comment.original_line;
-              const startLine = comment.start_line ?? comment.original_start_line ?? endLine;
+              const positiveLine = (value: number | null | undefined): number | null =>
+                value !== undefined && value !== null && value > 0 ? value : null;
+              const endLine = positiveLine(comment.line ?? comment.original_line);
+              const startLine =
+                positiveLine(comment.start_line ?? comment.original_start_line) ?? endLine;
               return RetirableReviewComment.make({
                 nodeId: comment.node_id,
                 path: comment.path,
@@ -638,6 +651,204 @@ export const gitHubReviewRetirementHostLayer: Layer.Layer<
   }),
 );
 
+// --- Live ReviewAdjudicationHost ----------------------------------------------
+
+const MAX_ADJUDICATION_PAGES = 5;
+
+const GitHubThreadCommentWire = Schema.Struct({
+  id: Schema.Int,
+  in_reply_to_id: Schema.optionalKey(Schema.NullOr(Schema.Int)),
+  path: Schema.String,
+  body: Schema.String,
+  author_association: Schema.optionalKey(Schema.NullOr(Schema.String)),
+  user: Schema.NullOr(Schema.Struct({ login: Schema.String })),
+  created_at: Schema.optionalKey(Schema.NullOr(Schema.String)),
+  line: Schema.optionalKey(Schema.NullOr(Schema.Int)),
+  original_line: Schema.optionalKey(Schema.NullOr(Schema.Int)),
+  start_line: Schema.optionalKey(Schema.NullOr(Schema.Int)),
+  original_start_line: Schema.optionalKey(Schema.NullOr(Schema.Int)),
+});
+const GitHubThreadCommentsPageWire = Schema.Array(GitHubThreadCommentWire);
+
+const GitHubIssueCommentWire = Schema.Struct({
+  body: Schema.optionalKey(Schema.NullOr(Schema.String)),
+  author_association: Schema.optionalKey(Schema.NullOr(Schema.String)),
+  user: Schema.NullOr(Schema.Struct({ login: Schema.String })),
+  created_at: Schema.optionalKey(Schema.NullOr(Schema.String)),
+});
+const GitHubIssueCommentsPageWire = Schema.Array(GitHubIssueCommentWire);
+
+const toAdjudicationComment = (
+  wire: {
+    readonly body?: string | null | undefined;
+    readonly author_association?: string | null | undefined;
+    readonly user: { readonly login: string } | null;
+    readonly created_at?: string | null | undefined;
+  },
+  sourceOrder: number,
+): AdjudicationComment | undefined => {
+  // A comment without an attributable author cannot authorize anything —
+  // skip it fail-closed rather than inventing an actor.
+  const login = wire.user?.login;
+  if (login === undefined || login.length === 0) return undefined;
+  return AdjudicationComment.make({
+    body: (wire.body ?? "").slice(0, 65_536),
+    authorAssociation: (wire.author_association ?? "NONE").slice(0, 40),
+    authorLogin: login.slice(0, 100),
+    createdAt: parseGitHubSubmittedAt(wire.created_at ?? null),
+    sourceOrder,
+  });
+};
+
+/**
+ * GitHub-backed host reads for maintainer adjudication, installed by
+ * `gitHubReviewLayers` in `github-env.ts` at the public composition root: this action's own
+ * inline finding threads (roots authored by the configured review author)
+ * with their replies, and the pull request's top-level conversation comments.
+ * Both listings are creation-ordered.
+ */
+export const gitHubReviewAdjudicationHostLayer: Layer.Layer<
+  ReviewAdjudicationHost,
+  never,
+  GitHubReviewTarget | HttpClient.HttpClient
+> = Layer.effect(ReviewAdjudicationHost)(
+  Effect.gen(function* () {
+    const target = yield* GitHubReviewTarget;
+    const client = yield* HttpClient.HttpClient;
+    const reviewAuthorLogin = (
+      target.reviewAuthorLogin ?? DEFAULT_GITHUB_REVIEW_AUTHOR_LOGIN
+    ).toLowerCase();
+    const asAdjudicationFailure =
+      (operation: string) =>
+      (error: { readonly _tag: string; readonly message?: string }): ReviewAdjudicationFailure =>
+        ReviewAdjudicationFailure.make({
+          operation,
+          reason: `${error._tag}: ${error.message ?? "request failed"}`.slice(0, 2_048),
+        });
+    const decodeAdjudication = <S extends Schema.Top>(schema: S, operation: string) => {
+      const decode = Schema.decodeUnknownEffect(schema);
+      return (response: HttpClientResponse.HttpClientResponse) =>
+        response.json.pipe(
+          Effect.mapError(asAdjudicationFailure(operation)),
+          Effect.flatMap((body) =>
+            decode(body).pipe(Effect.mapError(asAdjudicationFailure(operation))),
+          ),
+        );
+    };
+    const listPaged = <A>(input: {
+      readonly operation: string;
+      readonly url: string;
+      readonly decode: (
+        response: HttpClientResponse.HttpClientResponse,
+      ) => Effect.Effect<ReadonlyArray<A>, ReviewAdjudicationFailure>;
+    }) =>
+      Effect.gen(function* () {
+        const values: Array<A> = [];
+        const perPage = 100;
+        for (let page = 1; page <= MAX_ADJUDICATION_PAGES; page += 1) {
+          const response = yield* client
+            .execute(
+              withCommonHeaders(
+                HttpClientRequest.get(input.url).pipe(
+                  HttpClientRequest.acceptJson,
+                  HttpClientRequest.setUrlParams({
+                    per_page: String(perPage),
+                    page: String(page),
+                    sort: "created",
+                    direction: "asc",
+                  }),
+                ),
+                target.token,
+              ),
+            )
+            .pipe(
+              Effect.flatMap(HttpClientResponse.filterStatusOk),
+              Effect.mapError(asAdjudicationFailure(input.operation)),
+            );
+          const pageValues = yield* input.decode(response);
+          values.push(...pageValues);
+          if (pageValues.length < perPage) return values;
+        }
+        return yield* ReviewAdjudicationFailure.make({
+          operation: input.operation,
+          reason: `history exceeds the bounded ${MAX_ADJUDICATION_PAGES * 100}-item lookup`,
+        });
+      });
+
+    const listFindingThreads = Effect.gen(function* () {
+      const wires = yield* listPaged({
+        operation: "listReviewCommentsForAdjudication",
+        url: `${target.apiUrl}/repos/${target.repository}/pulls/${target.number}/comments`,
+        decode: decodeAdjudication(
+          GitHubThreadCommentsPageWire,
+          "listReviewCommentsForAdjudication",
+        ),
+      });
+      const positiveLine = (value: number | null | undefined): number | null =>
+        value !== undefined && value !== null && value > 0 ? value : null;
+      const threads = new Map<
+        number,
+        { readonly root: (typeof wires)[number]; readonly replies: Array<AdjudicationComment> }
+      >();
+      for (const wire of wires) {
+        if (wire.in_reply_to_id !== undefined && wire.in_reply_to_id !== null) continue;
+        // Only this action's own finding threads can be adjudicated inline.
+        if (wire.user?.login.toLowerCase() !== reviewAuthorLogin) continue;
+        threads.set(wire.id, { root: wire, replies: [] });
+      }
+      for (const [sourceOrder, wire] of wires.entries()) {
+        if (wire.in_reply_to_id === undefined || wire.in_reply_to_id === null) continue;
+        const thread = threads.get(wire.in_reply_to_id);
+        if (thread === undefined) continue;
+        const reply = toAdjudicationComment(wire, sourceOrder);
+        if (reply === undefined) continue;
+        const command = parseThreadAdjudication(reply.body);
+        if (command === undefined) continue;
+        if (!AUTHORIZED_ADJUDICATION_ASSOCIATIONS.has(reply.authorAssociation)) {
+          yield* Effect.logDebug(
+            `Ignored inline adjudication command from @${reply.authorLogin} (${reply.authorAssociation}).`,
+          );
+          continue;
+        }
+        if (thread.replies.length >= MAX_THREAD_ADJUDICATION_COMMANDS) {
+          return yield* ReviewAdjudicationFailure.make({
+            operation: "listReviewCommentsForAdjudication",
+            reason: `inline thread ${wire.in_reply_to_id} exceeds the bounded ${MAX_THREAD_ADJUDICATION_COMMANDS}-command adjudication lookup`,
+          });
+        }
+        thread.replies.push(reply);
+      }
+      return [...threads.values()]
+        .filter((thread) => thread.root.path.length > 0 && thread.root.path.length <= 500)
+        .map(({ root, replies }) => {
+          const endLine = positiveLine(root.line ?? root.original_line);
+          const startLine = positiveLine(root.start_line ?? root.original_start_line) ?? endLine;
+          return AdjudicableThread.make({
+            path: root.path,
+            startLine,
+            endLine,
+            rootBody: root.body.slice(0, 65_536),
+            replies,
+          });
+        });
+    });
+
+    const listIssueComments = Effect.gen(function* () {
+      const wires = yield* listPaged({
+        operation: "listIssueCommentsForAdjudication",
+        url: `${target.apiUrl}/repos/${target.repository}/issues/${target.number}/comments`,
+        decode: decodeAdjudication(GitHubIssueCommentsPageWire, "listIssueCommentsForAdjudication"),
+      });
+      return wires.flatMap((wire, sourceOrder) => {
+        const comment = toAdjudicationComment(wire, sourceOrder);
+        return comment === undefined ? [] : [comment];
+      });
+    });
+
+    return ReviewAdjudicationHost.of({ listFindingThreads, listIssueComments });
+  }),
+);
+
 // --- Prior reviews (fingerprint deduplication) ---------------------------------
 
 /** Reading the pull request's previously posted reviews failed. */
@@ -672,6 +883,15 @@ export class PriorReviews extends Context.Service<
       baseSha: string,
       headSha: string,
     ) => Effect.Effect<ReviewHeadComparison, PriorReviewLookupFailure>;
+    /**
+     * Two-dot tree comparison (`base..head`). Used when the reviewed head is
+     * not a git ancestor so a rebase or amend can still name the paths whose
+     * blob contents actually changed.
+     */
+    readonly compareTrees: (
+      baseSha: string,
+      headSha: string,
+    ) => Effect.Effect<ReviewHeadComparison, PriorReviewLookupFailure>;
   }
 >()("@effect-agent/pr-review/PriorReviews") {}
 
@@ -775,12 +995,12 @@ export const gitHubPriorReviewsLayer: Layer.Layer<
         }
         return { latestFingerprint: latest, latestState };
       }).pipe(Effect.provideService(HttpClient.HttpClient, client));
-    const compareHeads = (baseSha: string, headSha: string) =>
+    const compareCommits = (baseSha: string, headSha: string, separator: "..." | "..") =>
       Effect.gen(function* () {
         const response = yield* HttpClient.execute(
           withCommonHeaders(
             HttpClientRequest.get(
-              `${target.apiUrl}/repos/${target.repository}/compare/${encodeURIComponent(baseSha)}...${encodeURIComponent(headSha)}`,
+              `${target.apiUrl}/repos/${target.repository}/compare/${encodeURIComponent(baseSha)}${separator}${encodeURIComponent(headSha)}`,
             ).pipe(HttpClientRequest.acceptJson),
             target.token,
           ),
@@ -803,6 +1023,21 @@ export const gitHubPriorReviewsLayer: Layer.Layer<
           truncated: files.length >= MAX_CHANGED_FILES,
         });
       }).pipe(Effect.provideService(HttpClient.HttpClient, client));
+    const compareTrees = (baseSha: string, headSha: string) =>
+      compareCommits(baseSha, headSha, "..").pipe(
+        Effect.map((comparison) =>
+          ReviewHeadComparison.make({
+            // This is a content snapshot, not a lineage claim. Selection
+            // intersects these files with the current PR path set.
+            status: comparison.status === "identical" ? "identical" : "ahead",
+            baseSha,
+            headSha,
+            mergeBaseSha: baseSha,
+            files: comparison.files,
+            truncated: comparison.truncated,
+          }),
+        ),
+      );
     return PriorReviews.of({
       latestFingerprint: readMarkers(Option.none()).pipe(
         Effect.map((markers) => markers.latestFingerprint),
@@ -813,7 +1048,8 @@ export const gitHubPriorReviewsLayer: Layer.Layer<
           Effect.map((markers) => markers.latestState),
         );
       }),
-      compareHeads,
+      compareHeads: (baseSha, headSha) => compareCommits(baseSha, headSha, "..."),
+      compareTrees,
     });
   }),
 );

package/src/internal/progress.ts

@@ -133,7 +133,7 @@ const settleCallout = (info: ReviewProgressSettle): string => {
     case "success":
       return `> ✅ **Code review posted** — verdict \`${info.verdict}\`, ${info.inlineComments} inline comment(s), nothing blocking.`;
     case "blocking":
-      return `> 🛑 **Code review posted** — blocking findings; the check fails until they are addressed.`;
+      return `> 🛑 **Code review posted:** blocking review items; the check fails until they are addressed.`;
     case "incomplete":
       return `> ⚠️ **Code review posted** — input coverage or configured review assurance is incomplete, so the check fails.`;
   }

package/src/internal/render.ts

@@ -2,6 +2,7 @@ import { Schema } from "effect";
 
 import { anchorViolation } from "./anchors.ts";
 export { anchorViolation } from "./anchors.ts";
+import { splitCarriedScope } from "./coverage.ts";
 import type { ReviewAssurance, ReviewInputCoverage } from "./coverage.ts";
 import type { ChangedFile } from "./diff.ts";
 import { renderFingerprintMarker } from "./fingerprint.ts";
@@ -11,7 +12,7 @@ import {
   type ReviewConcern,
   type WalkthroughEntry,
 } from "./review-agent.ts";
-import type { ReviewScopeMode, ReviewStateMarker } from "./review-state.ts";
+import type { ReviewScopeMode, ReviewStateMarker, StoredAdjudication } from "./review-state.ts";
 
 // ---------------------------------------------------------------------------
 // Publication planning: pure, deterministic, and fail-closed. Model output is
@@ -185,25 +186,86 @@ const renderDemoted = (finding: ReviewFinding, reason: string): string => {
 const countNoun = (count: number, noun: string): string =>
   `${count} ${noun}${count === 1 ? "" : "s"}`;
 
-/** The validated finding + concern severities, tallied for callout and event. */
+interface SeverityTally {
+  readonly blocking: number;
+  readonly important: number;
+  readonly nit: number;
+  readonly total: number;
+}
+
+interface ReviewItemCounts {
+  readonly findings: SeverityTally;
+  readonly concerns: SeverityTally;
+  readonly carriedFindings: SeverityTally;
+  readonly carriedConcerns: SeverityTally;
+  readonly total: SeverityTally;
+}
+
+const tallySeverities = (
+  items: ReadonlyArray<{ readonly severity: ReviewFinding["severity"] }>,
+): SeverityTally => {
+  const blocking = items.filter((item) => item.severity === "blocking").length;
+  const important = items.filter((item) => item.severity === "important").length;
+  const nit = items.length - blocking - important;
+  return { blocking, important, nit, total: items.length };
+};
+
+/** The validated finding + concern severities, kept separate by provenance. */
 const severityCounts = (
   review: CodeReview,
   carriedFindings: ReadonlyArray<ReviewFinding> = [],
   carriedConcerns: ReadonlyArray<ReviewConcern> = [],
-) => {
-  const severities = [
-    ...review.findings.map((finding) => finding.severity),
-    ...(review.concerns ?? []).map((concern) => concern.severity),
-    ...carriedFindings.map((finding) => finding.severity),
-    ...carriedConcerns.map((concern) => concern.severity),
-  ];
+): ReviewItemCounts => {
+  const findings = tallySeverities(review.findings);
+  const concerns = tallySeverities(review.concerns ?? []);
+  const priorFindings = tallySeverities(carriedFindings);
+  const priorConcerns = tallySeverities(carriedConcerns);
   return {
-    blocking: severities.filter((severity) => severity === "blocking").length,
-    important: severities.filter((severity) => severity === "important").length,
-    total: severities.length,
+    findings,
+    concerns,
+    carriedFindings: priorFindings,
+    carriedConcerns: priorConcerns,
+    total: {
+      blocking:
+        findings.blocking + concerns.blocking + priorFindings.blocking + priorConcerns.blocking,
+      important:
+        findings.important + concerns.important + priorFindings.important + priorConcerns.important,
+      nit: findings.nit + concerns.nit + priorFindings.nit + priorConcerns.nit,
+      total: findings.total + concerns.total + priorFindings.total + priorConcerns.total,
+    },
   };
 };
 
+const joinItemCounts = (items: ReadonlyArray<string>): string =>
+  items.length <= 1
+    ? (items[0] ?? "none")
+    : items.length === 2
+      ? `${items[0]} and ${items[1]}`
+      : `${items.slice(0, -1).join(", ")}, and ${items.at(-1)}`;
+
+const severityItemParts = (
+  counts: ReviewItemCounts,
+  severity: keyof Pick<SeverityTally, "blocking" | "important" | "nit">,
+): ReadonlyArray<string> => [
+  ...(counts.findings[severity] === 0
+    ? []
+    : [countNoun(counts.findings[severity], `${severity} finding`)]),
+  ...(counts.concerns[severity] === 0
+    ? []
+    : [countNoun(counts.concerns[severity], `${severity} concern`)]),
+  ...(counts.carriedFindings[severity] === 0
+    ? []
+    : [countNoun(counts.carriedFindings[severity], `carried ${severity} finding`)]),
+  ...(counts.carriedConcerns[severity] === 0
+    ? []
+    : [countNoun(counts.carriedConcerns[severity], `carried ${severity} concern`)]),
+];
+
+const renderSeverityItems = (
+  counts: ReviewItemCounts,
+  severity: keyof Pick<SeverityTally, "blocking" | "important" | "nit">,
+): string => joinItemCounts(severityItemParts(counts, severity));
+
 /**
  * The opening callout: the review's overall tier, derived HOST-SIDE from the
  * validated severities (never from model prose), described by what GitHub
@@ -223,37 +285,73 @@ const renderVerdictCallout = (
   const counts = severityCounts(review, options.carriedFindings, options.carriedConcerns);
   // Code findings outrank machinery gaps: a blocking finding is the
   // actionable signal, and unsettled reviewer-side work is carried forward.
-  if (counts.blocking > 0) {
-    return `> [!CAUTION]\n> ${countNoun(counts.blocking, "blocking finding")} — do not merge before addressing ${counts.blocking === 1 ? "it" : "them"}.`;
+  if (counts.total.blocking > 0) {
+    return `> [!CAUTION]\n> ${renderSeverityItems(counts, "blocking")}. Do not merge before addressing ${counts.total.blocking === 1 ? "it" : "them"}.`;
   }
-  const carried = options.unreviewedPaths?.length ?? 0;
   if (
     options.inputCoverage?.status === "incomplete" ||
     options.assurance?.status === "incomplete"
   ) {
+    const scope = splitCarriedScope(options);
+    const undiffableCount = scope.undiffablePaths.length;
+    const undiffableNote =
+      undiffableCount > 0
+        ? ` ${countNoun(undiffableCount, "unreviewable file")} (binary or oversized) ${undiffableCount === 1 ? "has" : "have"} no diff a retry could settle — remove ${undiffableCount === 1 ? "it" : "them"} from the pull request or exclude ${undiffableCount === 1 ? "it" : "them"} with ignore globs.`
+        : "";
+    // Undiffable-only gaps are NOT reviewer-side and DO ask for a change (to
+    // the changeset or the ignore configuration), so they get their own
+    // banner instead of the carried-forward retry promise.
+    if (!scope.retryableGap) {
+      return `> [!WARNING]\n>${undiffableNote} The check reports "incomplete" while ${undiffableCount === 1 ? "it remains" : "they remain"} part of the pull request.`;
+    }
+    const retryableCount = scope.retryablePaths.length;
     const carriedNote =
-      carried > 0
-        ? ` ${countNoun(carried, "affected path")} ${carried === 1 ? "is" : "are"} carried forward and retried automatically on the next run.`
+      retryableCount > 0
+        ? ` ${countNoun(retryableCount, "affected path")} ${retryableCount === 1 ? "is" : "are"} carried forward and retried automatically on the next run.`
         : "";
-    return `> [!WARNING]\n> Review infrastructure did not settle — a reviewer-side gap, NOT a request to change code.${carriedNote} The check reports "incomplete" until a run settles.`;
+    return `> [!WARNING]\n> Review infrastructure did not settle. This is a reviewer-side gap, NOT a request to change code.${carriedNote}${undiffableNote} The check reports "incomplete" until a run settles.`;
   }
-  if (counts.important > 0) {
-    return `> [!IMPORTANT]\n> ${countNoun(counts.important, "important finding")} to address before merging.`;
+  if (counts.total.important > 0) {
+    return `> [!IMPORTANT]\n> ${renderSeverityItems(counts, "important")} to address before merging.`;
   }
-  if (counts.total > 0) {
-    return "> ℹ️ Minor suggestions only — mergeable as-is.";
+  if (counts.total.total > 0) {
+    return `> ℹ️ ${renderSeverityItems(counts, "nit")}; mergeable as-is.`;
   }
   return review.verdict === "approve"
     ? "> ✅ No issues found."
-    : "> ℹ️ No findings — see the summary.";
+    : "> ℹ️ No review items. See the summary.";
 };
 
 const renderConcern = (concern: ReviewConcern): string =>
-  [`### ${severityEmoji[concern.severity]} ${concern.title}`, "", concern.body].join("\n");
+  [
+    `### ${severityEmoji[concern.severity]} ${concern.title}`,
+    ...(concern.evidencePaths === undefined
+      ? []
+      : ["", `_Affected paths: ${concern.evidencePaths.map((path) => `\`${path}\``).join(", ")}_`]),
+    "",
+    concern.body,
+  ].join("\n");
 
 const renderCarriedFinding = (finding: ReviewFinding): string =>
   `- \`${finding.path}:${finding.startLine}${finding.endLine === finding.startLine ? "" : `-${finding.endLine}`}\` **[${findingLabel(finding)}] ${finding.title}** — ${finding.body}`;
 
+/**
+ * One adjudicated identity: its location (absent for unanchored concerns),
+ * title, maintainer disposition, actor, and the optional reason. Rendered in
+ * the collapsed adjudicated section so the audit distinguishes fixed,
+ * adjudicated, and still-open items.
+ */
+const renderAdjudicated = (adjudication: StoredAdjudication): string => {
+  const location =
+    adjudication.path !== undefined &&
+    adjudication.startLine !== undefined &&
+    adjudication.endLine !== undefined
+      ? `\`${adjudication.path}:${adjudication.startLine}${adjudication.endLine === adjudication.startLine ? "" : `-${adjudication.endLine}`}\` `
+      : "";
+  const reason = adjudication.reason === undefined ? "" : `: ${adjudication.reason}`;
+  return `- ${location}${adjudication.title} — ${adjudication.disposition} by @${adjudication.actor}${reason}`;
+};
+
 /**
  * Validate the model's walkthrough against the real changeset: entries whose
  * path is not a changed file are dropped (the walkthrough analogue of anchor
@@ -311,7 +409,7 @@ export const estimateReviewEffort = (
 const renderReviewStats = (
   files: ReadonlyArray<ChangedFile>,
   totalChangedFiles: number,
-  counts: { readonly blocking: number; readonly important: number; readonly total: number },
+  counts: ReviewItemCounts,
 ): string => {
   const additions = files.reduce((total, file) => total + file.additions, 0);
   const deletions = files.reduce((total, file) => total + file.deletions, 0);
@@ -319,17 +417,16 @@ const renderReviewStats = (
     files.length < totalChangedFiles
       ? `${files.length} of ${totalChangedFiles} files`
       : countNoun(files.length, "file");
-  const nits = counts.total - counts.blocking - counts.important;
   const tally =
-    counts.total === 0
+    counts.total.total === 0
       ? "none"
-      : [
-          ...(counts.blocking > 0 ? [`${counts.blocking} blocking`] : []),
-          ...(counts.important > 0 ? [`${counts.important} important`] : []),
-          ...(nits > 0 ? [`${nits} nit`] : []),
-        ].join(", ");
+      : joinItemCounts(
+          (["blocking", "important", "nit"] as const).flatMap((severity) =>
+            severityItemParts(counts, severity),
+          ),
+        );
   const effort = estimateReviewEffort(files);
-  return `**Changeset:** ${fileCount} (+${additions} / −${deletions}) · **Findings:** ${tally} · **Review effort:** ${effort.score}/5 (${effort.label})`;
+  return `**Changeset:** ${fileCount} (+${additions} / −${deletions}) · **Review items:** ${tally} · **Review effort:** ${effort.score}/5 (${effort.label})`;
 };
 
 /** HTML comments must not contain `--`; interpolated values are sanitized. */
@@ -409,6 +506,12 @@ export const planPublication = (
     /** Unchanged unresolved items carried from the prior reviewed baseline. */
     readonly carriedFindings?: ReadonlyArray<ReviewFinding> | undefined;
     readonly carriedConcerns?: ReadonlyArray<ReviewConcern> | undefined;
+    /**
+     * Standing maintainer adjudications. The caller excludes their identities
+     * from the review, the carried items, and every severity count; this
+     * planner only renders them as the collapsed adjudicated section.
+     */
+    readonly adjudications?: ReadonlyArray<StoredAdjudication> | undefined;
     /** Selected review scope, made visible whenever orchestration chose it. */
     readonly reviewMode?: ReviewScopeMode | undefined;
     readonly reviewReason?: string | undefined;
@@ -475,6 +578,7 @@ export const planPublication = (
     omitted: number,
     walkthroughKept: boolean,
     promptsKept: boolean,
+    adjudicationsKept: boolean,
   ): string => {
     const carriedFindings = options.carriedFindings ?? [];
     const carriedConcerns = options.carriedConcerns ?? [];
@@ -544,12 +648,33 @@ export const planPublication = (
       );
     }
     if (carriedConcerns.length > 0) {
-      parts.push("", "### Unresolved concerns carried to the final audit");
+      parts.push(
+        "",
+        `### Unresolved concerns from unchanged paths (${carriedConcerns.length})`,
+        "",
+        "These concerns were reported in an earlier review and were not reverified in this incremental pass. They remain active because none of their affected paths changed.",
+      );
       for (const concern of carriedConcerns) parts.push("", renderConcern(concern));
     }
     for (const concern of sortedConcerns.slice(0, concernsKept)) {
       parts.push("", renderConcern(concern));
     }
+    const adjudications = options.adjudications ?? [];
+    if (adjudications.length > 0) {
+      parts.push(
+        "",
+        adjudicationsKept
+          ? [
+              "<details>",
+              `<summary>Adjudicated (${adjudications.length})</summary>`,
+              "",
+              ...adjudications.map(renderAdjudicated),
+              "",
+              "</details>",
+            ].join("\n")
+          : "⚠️ Adjudicated section omitted — the body exceeded GitHub's review size cap.",
+      );
+    }
     if (files.length < options.totalChangedFiles) {
       parts.push(
         "",
@@ -607,9 +732,9 @@ export const planPublication = (
     options.inputCoverage?.status === "incomplete" || options.assurance?.status === "incomplete";
   const event: ReviewEvent = !options.applyVerdict
     ? "COMMENT"
-    : counts.blocking > 0
+    : counts.total.blocking > 0
       ? "REQUEST_CHANGES"
-      : review.verdict === "approve" && counts.important === 0 && !unclean
+      : review.verdict === "approve" && counts.total.important === 0 && !unclean
         ? "APPROVE"
         : "COMMENT";
 
@@ -631,20 +756,30 @@ export const planPublication = (
   const headBudget = 60_000 - tail.length - 1;
 
   // Shed whole trailing items — the derivative consolidated prompt first,
-  // then the informational walkthrough, then demoted bullets (they already
-  // failed validation), then concerns — instead of slicing markdown
-  // mid-block. Every omission is announced, and `plan.demoted` keeps the full
-  // data regardless.
+  // then the informational walkthrough, then the adjudicated record, then
+  // demoted bullets (they already failed validation), then concerns — instead
+  // of slicing markdown mid-block. Every omission is announced, and
+  // `plan.demoted` keeps the full data regardless.
+  const adjudicationCount = options.adjudications?.length ?? 0;
   let concernsKept = sortedConcerns.length;
   let demotedKept = sortedDemoted.length;
   let omitted = 0;
   let walkthroughKept = true;
   let promptsKept = true;
-  let head = renderHead(concernsKept, demotedKept, omitted, walkthroughKept, promptsKept);
+  let adjudicationsKept = true;
+  let head = renderHead(
+    concernsKept,
+    demotedKept,
+    omitted,
+    walkthroughKept,
+    promptsKept,
+    adjudicationsKept,
+  );
   while (
     head.length > headBudget &&
     ((promptsKept && consolidatedPromptWanted) ||
       (walkthroughKept && walkthrough.length > 0) ||
+      (adjudicationsKept && adjudicationCount > 0) ||
       demotedKept > 0 ||
       concernsKept > 0)
   ) {
@@ -652,6 +787,8 @@ export const planPublication = (
       promptsKept = false;
     } else if (walkthroughKept && walkthrough.length > 0) {
       walkthroughKept = false;
+    } else if (adjudicationsKept && adjudicationCount > 0) {
+      adjudicationsKept = false;
     } else if (demotedKept > 0) {
       demotedKept -= 1;
       omitted += 1;
@@ -659,7 +796,14 @@ export const planPublication = (
       concernsKept -= 1;
       omitted += 1;
     }
-    head = renderHead(concernsKept, demotedKept, omitted, walkthroughKept, promptsKept);
+    head = renderHead(
+      concernsKept,
+      demotedKept,
+      omitted,
+      walkthroughKept,
+      promptsKept,
+      adjudicationsKept,
+    );
   }
   // Last resort for a pathological summary; unreachable while the CodeReview
   // schema caps the summary well below the budget.