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

package/src/internal/profiles.ts

@@ -38,18 +38,18 @@ export const pullRequestReviewerProfile = PullRequestReviewerProfile.make({
 export class FanOutReviewerProfile extends Schema.Class<FanOutReviewerProfile>(
   "@effect-agent/pr-review/FanOutReviewerProfile",
 )({
-  /** Ephemeral runtime: one bounded AgentRuntime.run per invocation. */
+  /** Ephemeral runtime: bounded host-scheduled child runs per invocation. */
   deploymentClass: Schema.Literal("E"),
-  /** Every model-callable tool — parent and child — is a read; none mutate. */
+  /** Every model-callable surface is evidence-only; children expose no tools. */
   readOnlyToolSurface: Schema.Literal(true),
   /** The review is posted by the host AFTER the run settles, never by a tool. */
   publicationOutsideAgentLoop: Schema.Literal(true),
   /** Child findings are untrusted; anchors are validated against the parsed diff. */
   anchorsValidatedBeforePublication: Schema.Literal(true),
-  /** S1 attached ephemeral delegation at depth 1; nested delegation is rejected. */
-  attachedEphemeralDelegation: Schema.Literal(true),
-  /** A failed unit surfaces to the coordinator as a typed failed result, never retried. */
-  failedUnitsReportedNotRetried: Schema.Literal(true),
+  /** Host code schedules every pass from the deterministic plan; no coordinator model. */
+  hostScheduledPasses: Schema.Literal(true),
+  /** A failed pass is retried once, then reported and carried as unreviewed scope. */
+  failedPassesRetriedOnceThenCarried: Schema.Literal(true),
   /** Risk categories and required specialist passes are pure host policy. */
   hostOwnedRiskClassification: Schema.Literal(true),
   /** Every host-classified high-risk unit receives a fresh specialist pass. */
@@ -69,8 +69,8 @@ export const fanOutReviewerProfile = FanOutReviewerProfile.make({
   readOnlyToolSurface: true,
   publicationOutsideAgentLoop: true,
   anchorsValidatedBeforePublication: true,
-  attachedEphemeralDelegation: true,
-  failedUnitsReportedNotRetried: true,
+  hostScheduledPasses: true,
+  failedPassesRetriedOnceThenCarried: true,
   hostOwnedRiskClassification: true,
   redundantHighRiskDiscovery: true,
   independentCandidateVerification: true,

package/src/internal/render.ts

@@ -2,7 +2,7 @@ import { Schema } from "effect";
 
 import { anchorViolation } from "./anchors.ts";
 export { anchorViolation } from "./anchors.ts";
-import type { ReviewAssurance, ReviewCoverage, ReviewInputCoverage } from "./coverage.ts";
+import type { ReviewAssurance, ReviewInputCoverage } from "./coverage.ts";
 import type { ChangedFile } from "./diff.ts";
 import { renderFingerprintMarker } from "./fingerprint.ts";
 import {
@@ -215,27 +215,27 @@ const renderVerdictCallout = (
   options: {
     readonly carriedFindings?: ReadonlyArray<ReviewFinding> | undefined;
     readonly carriedConcerns?: ReadonlyArray<ReviewConcern> | undefined;
-    readonly coverage?: ReviewCoverage | undefined;
     readonly inputCoverage?: ReviewInputCoverage | undefined;
     readonly assurance?: ReviewAssurance | undefined;
+    readonly unreviewedPaths?: ReadonlyArray<string> | undefined;
   },
 ): string => {
   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"}.`;
+  }
+  const carried = options.unreviewedPaths?.length ?? 0;
   if (
     options.inputCoverage?.status === "incomplete" ||
-    (options.inputCoverage === undefined && options.coverage?.status === "incomplete")
+    options.assurance?.status === "incomplete"
   ) {
-    const suffix =
-      counts.blocking > 0 ? ` It also has ${countNoun(counts.blocking, "blocking finding")}.` : "";
-    return `> [!CAUTION]\n> Input coverage is incomplete — the check must not pass.${suffix}`;
-  }
-  if (options.assurance !== undefined && options.assurance.status !== "settled") {
-    const suffix =
-      counts.blocking > 0 ? ` It also has ${countNoun(counts.blocking, "blocking finding")}.` : "";
-    return `> [!CAUTION]\n> Configured review assurance did not settle — the check must not pass.${suffix}`;
-  }
-  if (counts.blocking > 0) {
-    return `> [!CAUTION]\n> ${countNoun(counts.blocking, "blocking finding")} — do not merge before addressing ${counts.blocking === 1 ? "it" : "them"}.`;
+    const carriedNote =
+      carried > 0
+        ? ` ${countNoun(carried, "affected path")} ${carried === 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.`;
   }
   if (counts.important > 0) {
     return `> [!IMPORTANT]\n> ${countNoun(counts.important, "important finding")} to address before merging.`;
@@ -393,22 +393,20 @@ export const planPublication = (
     readonly modelLabel?: string | undefined;
     /** Workflow-run URL rendered into the footer. */
     readonly runUrl?: string | undefined;
-    /** Observed run usage rendered into the footer. */
+    /** Observed whole-run usage rendered into the footer. */
     readonly usage?: { readonly inputTokens: number; readonly outputTokens: number } | undefined;
-    /** What the usage observed: the whole run, or the coordinator only. */
-    readonly usageScope?: "run" | "coordinator" | undefined;
     /**
      * Changeset fingerprint embedded invisibly in the review body so a later
      * run can skip re-reviewing an unchanged changeset.
      */
     readonly fingerprint?: string | undefined;
-    /** Host-owned coverage; incomplete coverage is rendered and fails the check. */
-    readonly coverage?: ReviewCoverage | undefined;
     /** Host-owned path/evidence assignment, separate from review assurance. */
     readonly inputCoverage?: ReviewInputCoverage | undefined;
     /** Host-owned discovery/specialist/verification settlement. */
     readonly assurance?: ReviewAssurance | undefined;
-    /** Unchanged unresolved items carried from the prior settled assurance baseline. */
+    /** Retryable scope this run could not settle; carried to the next run. */
+    readonly unreviewedPaths?: ReadonlyArray<string> | undefined;
+    /** Unchanged unresolved items carried from the prior reviewed baseline. */
     readonly carriedFindings?: ReadonlyArray<ReviewFinding> | undefined;
     readonly carriedConcerns?: ReadonlyArray<ReviewConcern> | undefined;
     /** Selected review scope, made visible whenever orchestration chose it. */
@@ -452,14 +450,8 @@ export const planPublication = (
 
   const footerParts = ["Automated review by @effect-agent/pr-review"];
   if (options.modelLabel !== undefined) footerParts.push(options.modelLabel);
-  // Usage renders only under an EXPLICIT scope: this planner cannot know
-  // whether a budget snapshot observed the whole run or only a fan-out
-  // coordinator, and omitting the number is honest where mislabeling is not.
-  if (options.usage !== undefined && options.usageScope !== undefined) {
-    const scope = options.usageScope === "coordinator" ? " (coordinator)" : "";
-    footerParts.push(
-      `${options.usage.inputTokens} in / ${options.usage.outputTokens} out tokens${scope}`,
-    );
+  if (options.usage !== undefined) {
+    footerParts.push(`${options.usage.inputTokens} in / ${options.usage.outputTokens} out tokens`);
   }
   if (options.runUrl !== undefined) footerParts.push(`[run](${options.runUrl})`);
   footerParts.push(`reviewed at ${options.headSha.slice(0, 7)}`);
@@ -490,9 +482,9 @@ export const planPublication = (
       renderVerdictCallout(review, {
         carriedFindings,
         carriedConcerns,
-        coverage: options.coverage,
         inputCoverage: options.inputCoverage,
         assurance: options.assurance,
+        unreviewedPaths: options.unreviewedPaths,
       }),
     ];
     if (options.reviewMode !== undefined && options.reviewReason !== undefined) {
@@ -513,7 +505,7 @@ export const planPublication = (
     if (options.inputCoverage !== undefined && options.assurance !== undefined) {
       parts.push(
         "",
-        `**Input coverage:** ${options.inputCoverage.status} (${options.inputCoverage.assignedPaths.length}/${options.inputCoverage.requiredPaths.length} paths assigned, ${options.inputCoverage.partialPaths.length} partial) · **Review assurance:** ${options.assurance.status} (${options.assurance.completedGeneralDiscoveryPasses}/${options.assurance.requiredGeneralDiscoveryPasses} general discovery, ${options.assurance.completedSpecialistPasses}/${options.assurance.requiredSpecialistPasses} specialist, ${options.assurance.completedVerificationPasses}/${options.assurance.requiredVerificationPasses} verification; ${options.assurance.confirmedCandidates} confirmed / ${options.assurance.rejectedCandidates} rejected / ${options.assurance.unsettledCandidates} unsettled candidates)`,
+        `**Input coverage:** ${options.inputCoverage.status} (${options.inputCoverage.assignedPaths.length}/${options.inputCoverage.requiredPaths.length} paths assigned, ${options.inputCoverage.partialPaths.length} partial) · **Review assurance:** ${options.assurance.status} (${options.assurance.completedGeneralDiscoveryPasses}/${options.assurance.requiredGeneralDiscoveryPasses} general discovery, ${options.assurance.completedSpecialistPasses}/${options.assurance.requiredSpecialistPasses} specialist, ${options.assurance.completedVerificationPasses}/${options.assurance.requiredVerificationPasses} verification; ${options.assurance.confirmedCandidates} confirmed / ${options.assurance.rejectedCandidates} rejected / ${options.assurance.unsettledCandidates} unsettled${options.assurance.discardedInvalidFindings > 0 ? ` / ${options.assurance.discardedInvalidFindings} discarded` : ""} candidates)`,
       );
     }
     parts.push("", review.summary);
@@ -525,22 +517,17 @@ export const planPublication = (
     if (options.inputCoverage?.status === "incomplete") {
       parts.push(
         "",
-        "### 🛑 Incomplete input coverage",
+        "### ⚠️ Incomplete input coverage",
         "",
         ...options.inputCoverage.reasons.map((reason) => `- ${reason}`),
       );
-    } else if (options.inputCoverage === undefined && options.coverage?.status === "incomplete") {
-      parts.push(
-        "",
-        "### 🛑 Incomplete coverage",
-        "",
-        ...options.coverage.reasons.map((reason) => `- ${reason}`),
-      );
     }
-    if (options.assurance !== undefined && options.assurance.status !== "settled") {
+    if (options.assurance?.status === "incomplete") {
       parts.push(
         "",
-        "### 🛑 Incomplete review assurance",
+        "### ⚠️ Unsettled review passes",
+        "",
+        "The passes below failed on the reviewer's side after a bounded retry. Their paths are carried forward and re-reviewed automatically on the next run — do not change code to satisfy this section.",
         "",
         ...options.assurance.reasons.map((reason) => `- ${reason}`),
       );
@@ -613,14 +600,16 @@ export const planPublication = (
     options.carriedFindings ?? [],
     options.carriedConcerns ?? [],
   );
+  // Machinery gaps (incomplete input or unsettled passes) block APPROVE but
+  // never REQUEST_CHANGES: requesting changes for a reviewer-side fault would
+  // tell the author to edit code nobody reviewed.
+  const unclean =
+    options.inputCoverage?.status === "incomplete" || options.assurance?.status === "incomplete";
   const event: ReviewEvent = !options.applyVerdict
     ? "COMMENT"
-    : options.inputCoverage?.status === "incomplete" ||
-        (options.inputCoverage === undefined && options.coverage?.status === "incomplete") ||
-        (options.assurance !== undefined && options.assurance.status !== "settled") ||
-        counts.blocking > 0
+    : counts.blocking > 0
       ? "REQUEST_CHANGES"
-      : review.verdict === "approve" && counts.important === 0
+      : review.verdict === "approve" && counts.important === 0 && !unclean
         ? "APPROVE"
         : "COMMENT";
 

package/src/internal/retirement.ts

@@ -102,8 +102,10 @@ const findingIdentity = (finding: {
 
 const REVIEW_METADATA_PATTERN = /<!-- effect-agent-pr-review metadata\n[\s\S]*?\n-->/g;
 const FINGERPRINT_PATTERN = /<!-- effect-agent-pr-review fingerprint=sha256:[0-9a-f]{64} -->/g;
+// Version-agnostic on purpose: retirement only RECOGNIZES machine markers to
+// keep them byte-identical through an edit; it never authenticates them.
 const STATE_PATTERN =
-  /<!-- effect-agent-pr-review state-v1:[A-Za-z0-9+/]+={0,2}\.[0-9a-f]{64} -->/g;
+  /<!-- effect-agent-pr-review state-v\d+:[A-Za-z0-9+/]+={0,2}\.[0-9a-f]{64} -->/g;
 const RETIRED_ORIGINAL_PATTERN =
   /<!-- effect-agent-pr-review retired-original:start -->\n([\s\S]*?)\n<!-- effect-agent-pr-review retired-original:end -->/;
 const MACHINE_COMMENT_PATTERN = new RegExp(

package/src/internal/review-agent.ts

@@ -346,7 +346,12 @@ export class ReviewFinding extends Schema.Class<ReviewFinding>(
   title: Schema.NonEmptyString.check(Schema.isMaxLength(120)),
   body: Schema.NonEmptyString.check(Schema.isMaxLength(2_000)),
   /** Replacement for exactly lines startLine..endLine; omit when unsure. */
-  suggestion: Schema.optionalKey(Schema.String.check(Schema.isMaxLength(2_000))),
+  suggestion: Schema.optionalKey(
+    Schema.String.annotate({
+      description:
+        "Committable replacement source code for exactly lines startLine..endLine: the full replacement for every line in the range and nothing else — never prose describing the change, which belongs in body.",
+    }).check(Schema.isMaxLength(2_000)),
+  ),
 }) {}
 
 export const ReviewVerdict = Schema.Literals(["approve", "comment", "request-changes"]);

package/src/internal/review-state.ts

@@ -46,16 +46,22 @@ export class StoredReviewConcern extends Schema.Class<StoredReviewConcern>(
   body: StoredText,
 }) {}
 
+/** The carried-scope bound; a run that cannot fit its leftovers publishes no state. */
+export const MAX_STORED_UNREVIEWED_PATHS = 100;
+
 /**
- * Versioned state embedded only after complete input assignment and settled
- * configured review assurance. The head plus full-scope fingerprint forms an
- * incremental baseline; an absent unresolved item never means the path is
- * defect-free. The `acceptedScopeFingerprint` name is retained for wire
- * compatibility. Storing hundreds of path strings separately would not fit
- * GitHub's bounded review body in the worst case.
+ * Versioned state embedded after EVERY completed run that can be signed. The
+ * head plus full-scope fingerprint forms an incremental baseline; an absent
+ * unresolved item never means the path is defect-free. `unreviewedPaths`
+ * carries retryable review gaps (failed passes) forward so the next
+ * incremental run re-reviews exactly them plus the new delta — the baseline
+ * advances monotonically instead of freezing on one flaky pass and reopening
+ * the whole post-baseline scope. The `acceptedScopeFingerprint` name is
+ * retained for wire compatibility. Storing hundreds of path strings
+ * separately would not fit GitHub's bounded review body in the worst case.
  */
 export class ReviewState extends Schema.Class<ReviewState>("@effect-agent/pr-review/ReviewState")({
-  version: Schema.Literal(1),
+  version: Schema.Literal(2),
   repository: Schema.NonEmptyString.check(Schema.isMaxLength(200)),
   pullRequestNumber: Schema.Int.check(Schema.isGreaterThan(0)),
   baseRef: Schema.NonEmptyString.check(Schema.isMaxLength(300)),
@@ -67,6 +73,14 @@ export class ReviewState extends Schema.Class<ReviewState>("@effect-agent/pr-rev
   reviewedPathCount: Schema.Int.check(Schema.isBetween({ minimum: 0, maximum: 300 })),
   unresolvedFindings: Schema.Array(StoredReviewFinding).check(Schema.isMaxLength(20)),
   unresolvedConcerns: Schema.Array(StoredReviewConcern).check(Schema.isMaxLength(10)),
+  /** Retryable review gaps carried into the next incremental run's scope. */
+  unreviewedPaths: Schema.Array(ChangedPath).check(Schema.isMaxLength(MAX_STORED_UNREVIEWED_PATHS)),
+  /**
+   * True only when the producing run had complete input coverage, no
+   * unsettled pass, and nothing carried. Skip-unchanged authority: an
+   * unchanged patch may skip re-review only over a settled state.
+   */
+  settled: Schema.Boolean,
   lastReviewMode: ReviewScopeMode,
 }) {}
 
@@ -100,15 +114,15 @@ export const toStoredConcern = (concern: ReviewConcern): StoredReviewConcern =>
 export const fromStoredConcern = (concern: StoredReviewConcern): ReviewConcern =>
   ReviewConcern.make({ severity: concern.severity, title: concern.title, body: concern.body });
 
-const STATE_MARKER_PREFIX = "<!-- effect-agent-pr-review state-v1:";
+const STATE_MARKER_PREFIX = "<!-- effect-agent-pr-review state-v2:";
 const STATE_MARKER_SUFFIX = " -->";
 const STATE_MARKER_PATTERN =
-  /(?:^|\n)<!-- effect-agent-pr-review state-v1:([A-Za-z0-9+/]+={0,2})\.([0-9a-f]{64}) -->$/;
-const STATE_SIGNATURE_DOMAIN = "effect-agent-pr-review/state-v1\u0000";
+  /(?:^|\n)<!-- effect-agent-pr-review state-v2:([A-Za-z0-9+/]+={0,2})\.([0-9a-f]{64}) -->$/;
+const STATE_SIGNATURE_DOMAIN = "effect-agent-pr-review/state-v2\u0000";
 export const MAX_REVIEW_STATE_MARKER_CHARS = 24_000;
 export const ReviewStateMarker = Schema.NonEmptyString.check(
   Schema.isMaxLength(MAX_REVIEW_STATE_MARKER_CHARS),
-  Schema.isPattern(/^<!-- effect-agent-pr-review state-v1:[A-Za-z0-9+/]+={0,2}\.[0-9a-f]{64} -->$/),
+  Schema.isPattern(/^<!-- effect-agent-pr-review state-v2:[A-Za-z0-9+/]+={0,2}\.[0-9a-f]{64} -->$/),
 ).pipe(Schema.brand("@effect-agent/pr-review/ReviewStateMarker"));
 export type ReviewStateMarker = typeof ReviewStateMarker.Type;
 
@@ -402,22 +416,32 @@ export const selectReviewRange = (input: {
       selectedByPath.set(file.path, file);
     }
   }
-  if (input.priorState.baseSha !== input.current.baseSha) {
+  // Retryable gaps carried by the prior state re-enter this run's scope; a
+  // carried path reverted out of the pull request has nothing left to review.
+  const carriedPaths = new Set(
+    input.priorState.unreviewedPaths.filter((path) => currentPaths.has(path)),
+  );
+  for (const path of carriedPaths) affectedPaths.add(path);
+  const rescuePaths = input.priorState.baseSha !== input.current.baseSha;
+  if (rescuePaths || carriedPaths.size > 0) {
     for (const file of input.fullFiles) {
-      if (
-        affectedPaths.has(file.path) ||
-        (file.previousPath !== undefined && affectedPaths.has(file.previousPath))
-      ) {
-        selectedByPath.set(file.path, file);
-      }
+      const affected =
+        (rescuePaths &&
+          (affectedPaths.has(file.path) ||
+            (file.previousPath !== undefined && affectedPaths.has(file.previousPath)))) ||
+        carriedPaths.has(file.path) ||
+        (file.previousPath !== undefined && carriedPaths.has(file.previousPath));
+      if (affected) selectedByPath.set(file.path, file);
     }
   }
   const selectedFiles = [...selectedByPath.values()].sort((left, right) =>
     left.path < right.path ? -1 : left.path > right.path ? 1 : 0,
   );
+  const carriedReason =
+    carriedPaths.size === 0 ? "" : `; retrying ${carriedPaths.size} carried unreviewed path(s)`;
   return {
     mode: "incremental",
-    reason: `changes since settled review head ${input.priorState.reviewedHeadSha.slice(0, 7)}${baseReason}`,
+    reason: `changes since reviewed head ${input.priorState.reviewedHeadSha.slice(0, 7)}${baseReason}${carriedReason}`,
     files: selectedFiles,
     affectedPaths: [...affectedPaths].sort(),
     totalFiles: selectedFiles.length,

package/src/internal/review-units.ts

@@ -6,6 +6,7 @@ import {
   fileReviewEvidenceChunks,
   type FindingSeverity,
   MAX_PATCH_CHARS,
+  type ReviewConcern,
   type ReviewFinding,
 } from "./review-agent.ts";
 
@@ -465,3 +466,27 @@ export const rankAndDedupeFindings = (
     })
     .slice(0, MAX_MERGED_FINDINGS);
 };
+
+/**
+ * The concern analogue of `rankAndDedupeFindings`: dedupe by exact content
+ * keeping the most severe duplicate, rank by severity, and cap at the
+ * `CodeReview` concerns bound.
+ */
+export const rankAndDedupeConcerns = (
+  concerns: ReadonlyArray<ReviewConcern>,
+): ReadonlyArray<ReviewConcern> => {
+  const byContent = new Map<string, ReviewConcern>();
+  for (const concern of concerns) {
+    const key = `${concern.title}\u0000${concern.body}`;
+    const previous = byContent.get(key);
+    if (
+      previous === undefined ||
+      severityRank[concern.severity] < severityRank[previous.severity]
+    ) {
+      byContent.set(key, concern);
+    }
+  }
+  return [...byContent.values()]
+    .sort((left, right) => severityRank[left.severity] - severityRank[right.severity])
+    .slice(0, 10);
+};