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

package/src/internal/retirement.ts

@@ -1,6 +1,8 @@
 import { Context, DateTime, Effect, Option, Schema } from "effect";
 
 import {
+  adjudicationIdentity,
+  findingIdentity,
   ReviewStateAuthenticator,
   type ReviewState,
   type StoredReviewFinding,
@@ -92,20 +94,10 @@ export interface ReviewRetirementDecision {
   readonly priorFindingCount: number;
 }
 
-const findingIdentity = (finding: {
-  readonly path: string;
-  readonly startLine: number;
-  readonly endLine: number;
-  readonly title: string;
-}): string =>
-  `${finding.path}\u0000${finding.startLine}\u0000${finding.endLine}\u0000${finding.title}`;
-
 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-v\d+:[A-Za-z0-9+/]+={0,2}\.[0-9a-f]{64} -->/g;
+  /<!-- effect-agent-pr-review state-v1:[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(
@@ -114,11 +106,12 @@ const MACHINE_COMMENT_PATTERN = new RegExp(
 );
 const VERDICT_CALLOUT_PATTERN =
   /^(?:> \[!(?:CAUTION|IMPORTANT)\]\n> [^\n]*(?:\n> [^\n]*)*|> (?:ℹ️|✅)[^\n]*)\n*/;
-// Accepts both the pre-category first line (`**[⚠️ important] Title**`) and
-// the current one carrying an optional category chip (`… · security]`), so
-// retirement keeps matching inline comments posted by older package versions.
-const INLINE_FINDING_TITLE_PATTERN =
-  /^\*\*\[(?:🛑 blocking|⚠️ important|💅 nit)(?: · [a-z-]+)?\] ([^\n]+)\*\*$/;
+/**
+ * The first line of every inline finding comment this package posts. Shared
+ * with adjudication so both parse the identical title shape.
+ */
+export const INLINE_FINDING_TITLE_PATTERN =
+  /^\*\*\[(?:🛑 blocking|⚠️ important|💅 nit) · [a-z-]+\] ([^\n]+)\*\*$/;
 const MAX_REVIEW_BODY_CHARS = 60_000;
 
 /** The host-authored metadata marker is the authority gate for any edit. */
@@ -191,8 +184,14 @@ export const decideReviewRetirement = (input: {
   readonly currentReviewUrl: string;
 }): ReviewRetirementDecision => {
   const current = new Set(input.currentState.unresolvedFindings.map(findingIdentity));
+  // Adjudicated identities are distinct from resolved: a maintainer verdict
+  // is not a fix, so retirement neither strikes nor minimizes them.
+  const adjudicated = new Set(
+    (input.currentState.adjudications ?? []).map((entry) => adjudicationIdentity(entry)),
+  );
   const resolvedFindings = input.priorState.unresolvedFindings.filter(
-    (finding) => !current.has(findingIdentity(finding)),
+    (finding) =>
+      !current.has(findingIdentity(finding)) && !adjudicated.has(findingIdentity(finding)),
   );
   return {
     body: renderRetiredBody({ ...input, resolvedFindings }),

package/src/internal/review-agent.ts

@@ -300,6 +300,11 @@ export const ReviewToolkitLayer = ReviewToolkit.toLayer({
 // Mission input and review output contracts.
 // ---------------------------------------------------------------------------
 
+/** Bounded prior-review context lines injected into reviewer instructions. */
+const ReviewContextLines = Schema.Array(Schema.String.check(Schema.isMaxLength(1_200))).check(
+  Schema.isMaxLength(20),
+);
+
 export class ReviewMission extends Schema.Class<ReviewMission>(
   "@effect-agent/pr-review/ReviewMission",
 )({
@@ -310,6 +315,18 @@ export class ReviewMission extends Schema.Class<ReviewMission>(
   baseRef: Schema.NonEmptyString.check(Schema.isMaxLength(300)),
   headRef: Schema.NonEmptyString.check(Schema.isMaxLength(300)),
   changedFileCount: Schema.Int.check(Schema.isGreaterThanOrEqualTo(0)),
+  /**
+   * Maintainer-adjudicated identities rendered as bounded context lines; the
+   * reviewer must not re-raise them without materially new evidence. Absent
+   * from fingerprint missions so an adjudication never invalidates the
+   * skip-unchanged authority.
+   */
+  adjudicatedContext: Schema.optionalKey(ReviewContextLines),
+  /**
+   * Prior-round findings on re-reviewed scope, rendered as bounded context
+   * lines; each must be confirmed, declared fixed, or explicitly withdrawn.
+   */
+  priorFindingContext: Schema.optionalKey(ReviewContextLines),
 }) {}
 
 export const FindingSeverity = Schema.Literals(["blocking", "important", "nit"]);
@@ -361,12 +378,18 @@ export type ReviewVerdict = typeof ReviewVerdict.Type;
  * A concern with no diff line to anchor to: a missing deletion or cleanup,
  * rollout or migration sequencing, a coverage gap the diff implies but does
  * not add, or a scope question only the author can answer. Rendered as a
- * review-body section — never as an inline comment, so it needs no anchor and
- * is never demoted.
+ * review-body section instead of an inline comment. `evidencePaths` binds the
+ * concern to changed files so a later incremental review can invalidate and
+ * recheck it when any supporting path changes. It remains optional only for
+ * decoding review output and continuity state written before path binding was
+ * introduced; a pathless concern cannot authorize incremental continuity.
  */
 export class ReviewConcern extends Schema.Class<ReviewConcern>(
   "@effect-agent/pr-review/ReviewConcern",
 )({
+  evidencePaths: Schema.optionalKey(
+    Schema.Array(ChangedPath).check(Schema.isMinLength(1)).check(Schema.isMaxLength(3)),
+  ),
   severity: FindingSeverity,
   title: Schema.NonEmptyString.check(Schema.isMaxLength(120)),
   body: Schema.NonEmptyString.check(Schema.isMaxLength(2_000)),
@@ -448,6 +471,18 @@ export const makeReviewInstructions =
         ? `Author description:\n${mission.body}`
         : "The author provided no description.",
       ...resolveGuidance(options.guidance, mission),
+      ...(mission.adjudicatedContext === undefined || mission.adjudicatedContext.length === 0
+        ? []
+        : [
+            "A maintainer has adjudicated these previously raised review items (disposition, reason). Do not re-raise them unless you have materially new evidence, and if you do, say explicitly what changed since the adjudication:",
+            ...mission.adjudicatedContext.map((line) => `- ${line}`),
+          ]),
+      ...(mission.priorFindingContext === undefined || mission.priorFindingContext.length === 0
+        ? []
+        : [
+            "Your previous review raised these findings on the scope you are re-reviewing. For each, either confirm it still holds, state that it is fixed, or withdraw it; do not demand the opposite of your own prior guidance without explicitly acknowledging the reversal:",
+            ...mission.priorFindingContext.map((line) => `- ${line}`),
+          ]),
       "Work in this order:",
       "1. Call list_changed_files once to see the selected input scope. In incremental reviews it is deliberately a subset of the pull request's full diff (totalFiles counts the whole pull request); omitted paths belong to settled prior scope or explicit host exclusions, not to this run.",
       "2. Call read_file_diff for every listed file. A normal diff marks new-version anchors as R<number>; only those numbers are valid startLine/endLine values. When GitHub omitted a diff, the tool may return bounded base/head content marked B/H instead. Review that content, but report its defects as non-anchored concerns because B/H lines cannot anchor GitHub comments. Never anchor a finding to a removed (-), B, or H line.",
@@ -456,9 +491,9 @@ export const makeReviewInstructions =
       "When the diff adds or changes a test, check that it can actually fail: a test that would still pass with the bug present is theatre, not coverage. The usual tell is a loose assertion standing where an exact one belongs — >= or a truthiness check over an expected value, or a snapshot that absorbs whatever it is handed.",
       "Go shallow only when the diff has no behavioral surface at all: doc typos, formatting, lockfile or generated-code regeneration, a mechanical rename. Line count is not the signal — a one-line change to auth, money, SQL, a comparison operator, or a config default is not trivial.",
       "Drop bloat-shaped findings before reporting: defensive checks for cases that cannot happen, abstractions used once, comments restating obvious code, tests asserting tautologies, just-in-case guards. A finding must be sound, correct, and worth acting on; prefer an explicit keep over an invented finding.",
-      '5. After collecting anchored findings, deliberately scan for concerns with NO line to point at: deletion or cleanup plans for code the diff replaces, rollout or migration sequencing, coverage gaps the diff implies but does not add, scope questions only the author can answer. Report each as a "concern", never as a finding with an invented anchor; report none when none exist.',
+      '5. After collecting anchored findings, deliberately scan for concerns with NO line to point at: deletion or cleanup plans for code the diff replaces, rollout or migration sequencing, coverage gaps the diff implies but does not add, scope questions only the author can answer. Report each as a "concern", never as a finding with an invented anchor. Every concern must list 1-3 exact changed evidencePaths that support it so later incremental reviews can recheck it when those files change. Report none when none exist, and never split one root concern into differently worded restatements.',
       `6. Write a walkthrough: for every file whose evidence you examined, one factual sentence (<= ${MAX_WALKTHROUGH_SUMMARY_CHARS} chars) describing what changed in that file — written for a reader scanning the pull request, never restating the diff line by line. Use only paths from list_changed_files; invented paths are dropped.`,
-      '7. Then return ONLY a JSON object — no Markdown fences, no prose before or after — exactly this shape: {"summary": <string, 1-3 paragraphs of overall assessment>, "verdict": <"approve" | "comment" | "request-changes">, "findings": [{"path": <string, a changed file path>, "startLine": <integer, an R-marked new-file line>, "endLine": <integer, >= startLine, same file, R-marked>, "severity": <"blocking" | "important" | "nit">, "category": <OPTIONAL: "correctness" | "security" | "concurrency" | "performance" | "resources" | "error-handling" | "testing" | "maintainability" | "style" | "docs">, "title": <string, <= 120 chars>, "body": <string, why it matters and what to do>, "suggestion": <string, OPTIONAL: replacement text for exactly lines startLine..endLine, ready to commit>}], "concerns": <array, OPTIONAL: [{"severity": <"blocking" | "important" | "nit">, "title": <string, <= 120 chars>, "body": <string>}], only for step-5 concerns with no valid anchor — never duplicate a finding here>, "walkthrough": <array, OPTIONAL: [{"path": <string, a changed file path>, "summary": <string, the step-6 sentence>}], one entry per reviewed file>}.',
+      '7. Then return ONLY a JSON object — no Markdown fences, no prose before or after — exactly this shape: {"summary": <string, 1-3 paragraphs of overall assessment>, "verdict": <"approve" | "comment" | "request-changes">, "findings": [{"path": <string, a changed file path>, "startLine": <integer, an R-marked new-file line>, "endLine": <integer, >= startLine, same file, R-marked>, "severity": <"blocking" | "important" | "nit">, "category": <OPTIONAL: "correctness" | "security" | "concurrency" | "performance" | "resources" | "error-handling" | "testing" | "maintainability" | "style" | "docs">, "title": <string, <= 120 chars>, "body": <string, why it matters and what to do>, "suggestion": <string, OPTIONAL: replacement text for exactly lines startLine..endLine, ready to commit>}], "concerns": <array, OPTIONAL: [{"evidencePaths": <array of 1-3 exact changed file paths>, "severity": <"blocking" | "important" | "nit">, "title": <string, <= 120 chars>, "body": <string>}], only for step-5 concerns with no valid anchor — never duplicate a finding here>, "walkthrough": <array, OPTIONAL: [{"path": <string, a changed file path>, "summary": <string, the step-6 sentence>}], one entry per reviewed file>}.',
       `Report at most ${maxFindings} findings and at most ${MAX_CONCERNS} concerns; prefer the most important ones. An empty findings array with verdict "approve" is a valid review. Include "suggestion" only when you are confident the replacement compiles and preserves intent; its text must contain the full replacement for every line in the range and nothing else.`,
       'Use verdict "request-changes" only when at least one finding or concern is "blocking". Line anchors you invent will be discarded, so copy R-numbers from read_file_diff output.',
     ].join("\n");