@effect-agent/pr-review 0.1.0-beta.24 → 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");

package/src/internal/review-state.ts

@@ -37,15 +37,94 @@ export class StoredReviewFinding extends Schema.Class<StoredReviewFinding>(
   body: StoredText,
 }) {}
 
-/** A compact unresolved non-anchored concern carried until a final audit. */
+/** A compact unresolved non-anchored concern with its invalidation paths. */
 export class StoredReviewConcern extends Schema.Class<StoredReviewConcern>(
   "@effect-agent/pr-review/StoredReviewConcern",
 )({
+  /** Absent only on legacy state written before concern path binding. */
+  evidencePaths: Schema.optionalKey(
+    Schema.Array(ChangedPath).check(Schema.isMinLength(1)).check(Schema.isMaxLength(3)),
+  ),
   severity: FindingSeverity,
   title: Schema.NonEmptyString.check(Schema.isMaxLength(120)),
   body: StoredText,
 }) {}
 
+/** How a maintainer settled a previously raised finding or concern. */
+export const AdjudicationDisposition = Schema.Literals(["accepted-risk", "refuted", "obsolete"]);
+export type AdjudicationDisposition = typeof AdjudicationDisposition.Type;
+
+/** The adjudications bound carried by the ReviewState schema. */
+export const MAX_STORED_ADJUDICATIONS = 20;
+
+/**
+ * One maintainer adjudication of a finding or concern identity. Anchored
+ * findings carry their full location identity; unanchored concerns are
+ * identified by title alone, so the location fields stay absent.
+ */
+const StoredAdjudicationFields = Schema.Struct({
+  path: Schema.optionalKey(ChangedPath),
+  startLine: Schema.optionalKey(Schema.Int.check(Schema.isGreaterThan(0))),
+  endLine: Schema.optionalKey(Schema.Int.check(Schema.isGreaterThan(0))),
+  title: Schema.NonEmptyString.check(Schema.isMaxLength(120)),
+  disposition: AdjudicationDisposition,
+  reason: Schema.optionalKey(Schema.NonEmptyString.check(Schema.isMaxLength(300))),
+  /** GitHub login of the maintainer whose comment adjudicated the identity. */
+  actor: Schema.NonEmptyString.check(Schema.isMaxLength(100)),
+}).check(
+  Schema.makeFilter(
+    (adjudication) => {
+      const locationParts = [
+        adjudication.path,
+        adjudication.startLine,
+        adjudication.endLine,
+      ].filter((part) => part !== undefined).length;
+      return locationParts === 0 || locationParts === 3
+        ? undefined
+        : "path, startLine, and endLine must be either all present or all absent";
+    },
+    { title: "adjudication locations are complete or unanchored" },
+  ),
+);
+
+export class StoredAdjudication extends Schema.Class<StoredAdjudication>(
+  "@effect-agent/pr-review/StoredAdjudication",
+)(StoredAdjudicationFields) {}
+
+/**
+ * The one finding-identity composition shared by retirement, adjudication,
+ * and settlement. A tagged JSON tuple keeps anchored findings in a namespace
+ * disjoint from title-only concerns and remains unambiguous even when
+ * untrusted path or title text contains delimiter characters.
+ */
+export const findingIdentity = (finding: {
+  readonly path: string;
+  readonly startLine: number;
+  readonly endLine: number;
+  readonly title: string;
+}): string =>
+  JSON.stringify(["finding", finding.path, finding.startLine, finding.endLine, finding.title]);
+
+/** The disjoint title-only identity namespace for unanchored concerns. */
+export const concernIdentity = (concern: { readonly title: string }): string =>
+  JSON.stringify(["concern", concern.title]);
+
+/**
+ * An adjudication's identity: the shared finding identity when anchored, the
+ * disjoint concern identity when unanchored.
+ */
+export const adjudicationIdentity = (adjudication: StoredAdjudication): string =>
+  adjudication.path !== undefined &&
+  adjudication.startLine !== undefined &&
+  adjudication.endLine !== undefined
+    ? findingIdentity({
+        path: adjudication.path,
+        startLine: adjudication.startLine,
+        endLine: adjudication.endLine,
+        title: adjudication.title,
+      })
+    : concernIdentity(adjudication);
+
 /** The carried-scope bound; a run that cannot fit its leftovers publishes no state. */
 export const MAX_STORED_UNREVIEWED_PATHS = 100;
 
@@ -71,12 +150,11 @@ export class StoredUnreviewedPass extends Schema.Class<StoredUnreviewedPass>(
  * 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.
+ * the whole post-baseline scope. 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(2),
+  version: Schema.Literal(1),
   repository: Schema.NonEmptyString.check(Schema.isMaxLength(200)),
   pullRequestNumber: Schema.Int.check(Schema.isGreaterThan(0)),
   baseRef: Schema.NonEmptyString.check(Schema.isMaxLength(300)),
@@ -84,19 +162,15 @@ export class ReviewState extends Schema.Class<ReviewState>("@effect-agent/pr-rev
   headRef: Schema.NonEmptyString.check(Schema.isMaxLength(300)),
   reviewedHeadSha: GitCommitSha,
   profileFingerprint: Fingerprint,
-  acceptedScopeFingerprint: Fingerprint,
+  settledScopeFingerprint: Fingerprint,
   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)),
-  /**
-   * Which failed pass produced those leftovers. Absent on state-v2 markers
-   * written before this field existed; those leftovers still re-enter scope
-   * but cannot skip rediscovery. Present (including empty) on new markers.
-   */
-  unreviewedPasses: Schema.optionalKey(
-    Schema.Array(StoredUnreviewedPass).check(Schema.isMaxLength(MAX_STORED_UNREVIEWED_PASSES)),
+  /** Which failed pass produced those leftovers. */
+  unreviewedPasses: Schema.Array(StoredUnreviewedPass).check(
+    Schema.isMaxLength(MAX_STORED_UNREVIEWED_PASSES),
   ),
   /**
    * True only when the producing run had complete input coverage, no
@@ -105,6 +179,13 @@ export class ReviewState extends Schema.Class<ReviewState>("@effect-agent/pr-rev
    */
   settled: Schema.Boolean,
   lastReviewMode: ReviewScopeMode,
+  /**
+   * Maintainer adjudications standing against this pull request. optionalKey
+   * so state markers signed before the field existed still decode.
+   */
+  adjudications: Schema.optionalKey(
+    Schema.Array(StoredAdjudication).check(Schema.isMaxLength(MAX_STORED_ADJUDICATIONS)),
+  ),
 }) {}
 
 export const toStoredFinding = (finding: ReviewFinding): StoredReviewFinding =>
@@ -129,23 +210,29 @@ export const fromStoredFinding = (finding: StoredReviewFinding): ReviewFinding =
 
 export const toStoredConcern = (concern: ReviewConcern): StoredReviewConcern =>
   StoredReviewConcern.make({
+    ...(concern.evidencePaths === undefined ? {} : { evidencePaths: concern.evidencePaths }),
     severity: concern.severity,
     title: concern.title,
     body: concern.body.slice(0, 800),
   });
 
 export const fromStoredConcern = (concern: StoredReviewConcern): ReviewConcern =>
-  ReviewConcern.make({ severity: concern.severity, title: concern.title, body: concern.body });
+  ReviewConcern.make({
+    ...(concern.evidencePaths === undefined ? {} : { evidencePaths: concern.evidencePaths }),
+    severity: concern.severity,
+    title: concern.title,
+    body: concern.body,
+  });
 
-const STATE_MARKER_PREFIX = "<!-- effect-agent-pr-review state-v2:";
+const STATE_MARKER_PREFIX = "<!-- effect-agent-pr-review state-v1:";
 const STATE_MARKER_SUFFIX = " -->";
 const STATE_MARKER_PATTERN =
-  /(?:^|\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";
+  /(?:^|\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";
 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-v2:[A-Za-z0-9+/]+={0,2}\.[0-9a-f]{64} -->$/),
+  Schema.isPattern(/^<!-- effect-agent-pr-review state-v1:[A-Za-z0-9+/]+={0,2}\.[0-9a-f]{64} -->$/),
 ).pipe(Schema.brand("@effect-agent/pr-review/ReviewStateMarker"));
 export type ReviewStateMarker = typeof ReviewStateMarker.Type;
 
@@ -324,16 +411,17 @@ export interface ReviewSelection {
   readonly totalFiles: number;
   readonly baselineSha: string | undefined;
   readonly priorState: ReviewState | undefined;
-  readonly profileFingerprint: string;
+  /** Absent only for an explicit full review with no continuity profile. */
+  readonly profileFingerprint: string | undefined;
   /** Action-owned authentication capability, constructed at the composition root. */
   readonly stateAuthenticator?: ReviewStateAuthenticator["Service"] | undefined;
 }
 
-const fullSelection = (input: {
+export const fullReviewSelection = (input: {
   readonly reason: string;
   readonly files: ReadonlyArray<ChangedFile>;
   readonly totalFiles: number;
-  readonly profileFingerprint: string;
+  readonly profileFingerprint?: string | undefined;
 }): ReviewSelection => ({
   mode: "full",
   reason: input.reason,
@@ -380,6 +468,9 @@ export const validateReviewState = (
   if (state.profileFingerprint !== profileFingerprint) {
     return "the reviewer profile or model configuration changed";
   }
+  if (state.unresolvedConcerns.some((concern) => concern.evidencePaths === undefined)) {
+    return "stored concerns predate affected-path tracking";
+  }
   return undefined;
 };
 
@@ -400,6 +491,23 @@ const incrementalFromDelta = (input: {
     ...input.deltaFiles.flatMap(filePaths),
     ...(input.extraAffectedPaths ?? []),
   ]);
+  const initialAffectedCount = affectedPaths.size;
+  // Reopen every current path needed to reassess a concern touched by this
+  // delta. Repeat to a fixed point because two concerns may overlap on a path.
+  let expanded = true;
+  while (expanded) {
+    expanded = false;
+    for (const concern of input.priorState.unresolvedConcerns) {
+      const paths = concern.evidencePaths ?? [];
+      if (!paths.some((path) => affectedPaths.has(path))) continue;
+      for (const path of paths) {
+        if (!affectedPaths.has(path)) {
+          affectedPaths.add(path);
+          expanded = true;
+        }
+      }
+    }
+  }
   const selectedByPath = new Map<string, ChangedFile>();
   for (const file of input.deltaFiles) {
     if (
@@ -410,22 +518,16 @@ const incrementalFromDelta = (input: {
     }
   }
   const carriedPaths = input.priorState.unreviewedPaths.filter((path) => currentPaths.has(path));
-  const surgical = input.priorState.unreviewedPasses !== undefined;
   const retryOnly = new Set<string>();
   const retryStages = new Set<UnreviewedStage>();
   for (const path of carriedPaths) {
     if (affectedPaths.has(path)) continue;
     retryOnly.add(path);
-    if (surgical) {
-      for (const pass of input.priorState.unreviewedPasses ?? []) {
-        if (pass.paths.includes(path)) retryStages.add(pass.stage);
-      }
-    } else {
-      affectedPaths.add(path);
+    for (const pass of input.priorState.unreviewedPasses) {
+      if (pass.paths.includes(path)) retryStages.add(pass.stage);
     }
   }
   if (
-    surgical &&
     retryStages.has("verification") &&
     !retryStages.has("discovery") &&
     !retryStages.has("specialist")
@@ -433,35 +535,38 @@ const incrementalFromDelta = (input: {
     retryStages.add("discovery");
     retryStages.add("specialist");
   }
-  if (surgical && retryOnly.size > 0 && retryStages.size === 0) {
+  if (retryOnly.size > 0 && retryStages.size === 0) {
     for (const path of retryOnly) affectedPaths.add(path);
     retryStages.add("discovery");
     retryStages.add("specialist");
     retryStages.add("verification");
   }
-  if (carriedPaths.length > 0 || (input.extraAffectedPaths?.length ?? 0) > 0) {
-    for (const file of input.fullFiles) {
-      const needed =
-        affectedPaths.has(file.path) ||
-        (file.previousPath !== undefined && affectedPaths.has(file.previousPath)) ||
-        retryOnly.has(file.path) ||
-        (file.previousPath !== undefined && retryOnly.has(file.previousPath));
-      if (needed) selectedByPath.set(file.path, file);
-    }
+  for (const file of input.fullFiles) {
+    const needed =
+      affectedPaths.has(file.path) ||
+      (file.previousPath !== undefined && affectedPaths.has(file.previousPath)) ||
+      retryOnly.has(file.path) ||
+      (file.previousPath !== undefined && retryOnly.has(file.previousPath));
+    if (needed) selectedByPath.set(file.path, file);
   }
   const selectedFiles = [...selectedByPath.values()].sort((left, right) =>
     left.path < right.path ? -1 : left.path > right.path ? 1 : 0,
   );
   const leftoverCount = [...retryOnly].filter((path) => !affectedPaths.has(path)).length;
   const carriedReason =
-    leftoverCount > 0 && surgical
+    leftoverCount > 0
       ? `; retrying ${leftoverCount} unchanged leftover path(s) without rediscovery`
       : carriedPaths.length > 0
         ? `; retrying ${carriedPaths.length} carried unreviewed path(s)`
         : "";
+  const concernPathCount = affectedPaths.size - initialAffectedCount;
+  const concernReason =
+    concernPathCount === 0
+      ? ""
+      : `; reopening ${concernPathCount} related concern path(s) for context`;
   return {
     mode: "incremental",
-    reason: `${input.reason}${carriedReason}`,
+    reason: `${input.reason}${carriedReason}${concernReason}`,
     files: selectedFiles,
     affectedPaths: [...affectedPaths].sort(),
     retryPaths: [...retryOnly].filter((path) => !affectedPaths.has(path)).sort(),
@@ -491,7 +596,7 @@ export const selectReviewRange = (input: {
   readonly lookupFailure?: string | undefined;
 }): ReviewSelection => {
   const full = (reason: string) =>
-    fullSelection({
+    fullReviewSelection({
       reason,
       files: input.fullFiles,
       totalFiles: input.current.totalChangedFiles,
@@ -560,6 +665,20 @@ export class ReviewExecutionContext extends Context.Service<
   ReviewSelection
 >()("@effect-agent/pr-review/ReviewExecutionContext") {}
 
+/**
+ * Explicit direct-run adapter for callers that intentionally review the full
+ * source without authenticated incremental continuity.
+ */
+export const fullReviewExecutionContextLayer = (reason: string) =>
+  Layer.effect(
+    ReviewExecutionContext,
+    Effect.gen(function* () {
+      const source = yield* PullRequestSource;
+      const [metadata, files] = yield* Effect.all([source.metadata, source.changedFiles]);
+      return fullReviewSelection({ reason, files, totalFiles: metadata.totalChangedFiles });
+    }),
+  );
+
 /**
  * Decorate the full source with the selected review range. Full anchor files
  * remain available to host-side publication validation; model tools see only

package/src/internal/review-units.ts

@@ -24,9 +24,6 @@ export const MAX_REVIEW_UNITS = 8;
 /** A unit never carries more files than this, regardless of their size. */
 export const MAX_UNIT_FILES = 12;
 
-/** Compatibility export; complete evidence chars now own unit packing. */
-export const UNIT_CHANGED_LINE_BUDGET = 800;
-
 /**
  * Bound the complete model-visible evidence assigned to one child. This is a
  * character bound rather than a token estimate because it is deterministic,
@@ -45,9 +42,6 @@ export const MAX_UNIT_EVIDENCE_SHARDS = 12;
  */
 export const MAX_REPORTED_UNASSIGNED_EVIDENCE_SHARDS = MAX_REVIEW_UNITS * MAX_UNIT_EVIDENCE_SHARDS;
 
-/** @deprecated Use `MAX_PATCH_CHARS`; this is now the per-shard bound. */
-export const MAX_FILE_EVIDENCE_CHARS = MAX_PATCH_CHARS;
-
 /** The merged review never exceeds the `CodeReview` findings bound. */
 export const MAX_MERGED_FINDINGS = 20;
 
@@ -468,8 +462,15 @@ export const rankAndDedupeFindings = (
 };
 
 /**
- * The concern analogue of `rankAndDedupeFindings`: dedupe by exact content
- * keeping the most severe duplicate, rank by severity, and cap at the
+ * Stable identity for one concern. The paths are part of the claim: identical
+ * prose about two independent files must not collapse into one item.
+ */
+export const reviewConcernKey = (concern: ReviewConcern): string =>
+  `${(concern.evidencePaths ?? []).join("\u0000")}\u0001${concern.title}\u0000${concern.body}`;
+
+/**
+ * The concern analogue of `rankAndDedupeFindings`: dedupe by exact scoped
+ * content keeping the most severe duplicate, rank by severity, and cap at the
  * `CodeReview` concerns bound.
  */
 export const rankAndDedupeConcerns = (
@@ -477,7 +478,7 @@ export const rankAndDedupeConcerns = (
 ): ReadonlyArray<ReviewConcern> => {
   const byContent = new Map<string, ReviewConcern>();
   for (const concern of concerns) {
-    const key = `${concern.title}\u0000${concern.body}`;
+    const key = reviewConcernKey(concern);
     const previous = byContent.get(key);
     if (
       previous === undefined ||