@effect-agent/pr-review 0.1.0-beta.20 → 0.1.0-beta.22

package/src/internal/profiles.ts

@@ -50,6 +50,14 @@ export class FanOutReviewerProfile extends Schema.Class<FanOutReviewerProfile>(
   attachedEphemeralDelegation: Schema.Literal(true),
   /** A failed unit surfaces to the coordinator as a typed failed result, never retried. */
   failedUnitsReportedNotRetried: 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. */
+  redundantHighRiskDiscovery: Schema.Literal(true),
+  /** Only exact candidates confirmed by a fresh verifier child may publish. */
+  independentCandidateVerification: Schema.Literal(true),
+  /** No bounded model pipeline proves that a pull request is defect-free. */
+  defectAbsenceProven: Schema.Literal(false),
   /** The live profile is env-gated out of every ordinary test gate. */
   liveProfileOptIn: Schema.Literal(true),
   /** Never claimed at any phase (DUR-003). */
@@ -63,6 +71,10 @@ export const fanOutReviewerProfile = FanOutReviewerProfile.make({
   anchorsValidatedBeforePublication: true,
   attachedEphemeralDelegation: true,
   failedUnitsReportedNotRetried: true,
+  hostOwnedRiskClassification: true,
+  redundantHighRiskDiscovery: true,
+  independentCandidateVerification: true,
+  defectAbsenceProven: false,
   liveProfileOptIn: true,
   exactlyOnceExternalEffects: false,
 });

package/src/internal/progress.ts

@@ -135,7 +135,7 @@ const settleCallout = (info: ReviewProgressSettle): string => {
     case "blocking":
       return `> 🛑 **Code review posted** — blocking findings; the check fails until they are addressed.`;
     case "incomplete":
-      return `> ⚠️ **Code review posted** — required coverage is incomplete, so the check fails.`;
+      return `> ⚠️ **Code review posted** — input coverage or configured review assurance is incomplete, so the check fails.`;
   }
 };
 

package/src/internal/render.ts

@@ -1,7 +1,9 @@
 import { Schema } from "effect";
 
-import type { ReviewCoverage } from "./coverage.ts";
-import { commentableLines, type ChangedFile } from "./diff.ts";
+import { anchorViolation } from "./anchors.ts";
+export { anchorViolation } from "./anchors.ts";
+import type { ReviewAssurance, ReviewCoverage, ReviewInputCoverage } from "./coverage.ts";
+import type { ChangedFile } from "./diff.ts";
 import { renderFingerprintMarker } from "./fingerprint.ts";
 import {
   ReviewFinding,
@@ -214,13 +216,23 @@ const renderVerdictCallout = (
     readonly carriedFindings?: ReadonlyArray<ReviewFinding> | undefined;
     readonly carriedConcerns?: ReadonlyArray<ReviewConcern> | undefined;
     readonly coverage?: ReviewCoverage | undefined;
+    readonly inputCoverage?: ReviewInputCoverage | undefined;
+    readonly assurance?: ReviewAssurance | undefined;
   },
 ): string => {
   const counts = severityCounts(review, options.carriedFindings, options.carriedConcerns);
-  if (options.coverage?.status === "incomplete") {
+  if (
+    options.inputCoverage?.status === "incomplete" ||
+    (options.inputCoverage === undefined && options.coverage?.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> Review coverage is incomplete — the check must not pass.${suffix}`;
+    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"}.`;
@@ -360,22 +372,6 @@ const renderReviewMetadata = (options: {
  * Why one finding cannot become an inline comment, or undefined when it can.
  * Exported so tests can pin each rule individually.
  */
-export const anchorViolation = (
-  finding: ReviewFinding,
-  files: ReadonlyArray<ChangedFile>,
-): string | undefined => {
-  const file = files.find((candidate) => candidate.path === finding.path);
-  if (file === undefined) return "path is not part of the changeset";
-  if (file.patch === undefined) return "file has no anchorable textual diff";
-  if (finding.endLine < finding.startLine) return "endLine precedes startLine";
-  if (finding.endLine - finding.startLine + 1 > 100) return "range is implausibly large";
-  const anchors = commentableLines(file.patch);
-  for (let line = finding.startLine; line <= finding.endLine; line += 1) {
-    if (!anchors.has(line)) return `line ${line} is not part of the diff`;
-  }
-  return undefined;
-};
-
 /**
  * Turn one validated review into the exact GitHub publication payload.
  * `applyVerdict: false` (the safe default) always posts a COMMENT review;
@@ -408,7 +404,11 @@ export const planPublication = (
     readonly fingerprint?: string | undefined;
     /** Host-owned coverage; incomplete coverage is rendered and fails the check. */
     readonly coverage?: ReviewCoverage | undefined;
-    /** Unchanged unresolved items carried from the prior successfully reviewed head. */
+    /** 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. */
     readonly carriedFindings?: ReadonlyArray<ReviewFinding> | undefined;
     readonly carriedConcerns?: ReadonlyArray<ReviewConcern> | undefined;
     /** Selected review scope, made visible whenever orchestration chose it. */
@@ -491,13 +491,15 @@ export const planPublication = (
         carriedFindings,
         carriedConcerns,
         coverage: options.coverage,
+        inputCoverage: options.inputCoverage,
+        assurance: options.assurance,
       }),
     ];
     if (options.reviewMode !== undefined && options.reviewReason !== undefined) {
       parts.push(
         "",
         options.reviewMode === "incremental"
-          ? `**Incremental scope:** reviewed ${options.reviewFilesVisible ?? files.length} file(s) ${options.reviewReason}. Unchanged accepted scope was preserved and not reopened.`
+          ? `**Incremental scope:** reopened ${options.reviewFilesVisible ?? files.length} affected file(s) ${options.reviewReason}. Unchanged settled scope was preserved and not reopened.`
           : `**Full-diff scope:** ${options.reviewReason}.`,
       );
     }
@@ -508,13 +510,26 @@ export const planPublication = (
       );
     }
     parts.push("", renderReviewStats(files, options.totalChangedFiles, counts));
+    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)`,
+      );
+    }
     parts.push("", review.summary);
     if (walkthroughKept && walkthrough.length > 0) {
       parts.push("", renderWalkthrough(walkthrough));
     } else if (walkthrough.length > 0) {
       parts.push("", "⚠️ Walkthrough omitted — the body exceeded GitHub's review size cap.");
     }
-    if (options.coverage?.status === "incomplete") {
+    if (options.inputCoverage?.status === "incomplete") {
+      parts.push(
+        "",
+        "### 🛑 Incomplete input coverage",
+        "",
+        ...options.inputCoverage.reasons.map((reason) => `- ${reason}`),
+      );
+    } else if (options.inputCoverage === undefined && options.coverage?.status === "incomplete") {
       parts.push(
         "",
         "### 🛑 Incomplete coverage",
@@ -522,6 +537,14 @@ export const planPublication = (
         ...options.coverage.reasons.map((reason) => `- ${reason}`),
       );
     }
+    if (options.assurance !== undefined && options.assurance.status !== "settled") {
+      parts.push(
+        "",
+        "### 🛑 Incomplete review assurance",
+        "",
+        ...options.assurance.reasons.map((reason) => `- ${reason}`),
+      );
+    }
     if (carriedFindings.length > 0) {
       parts.push(
         "",
@@ -543,7 +566,7 @@ export const planPublication = (
     if (files.length < options.totalChangedFiles) {
       parts.push(
         "",
-        `⚠️ Reviewed ${files.length} of ${options.totalChangedFiles} changed files — the changeset exceeded the reviewer's file bound.`,
+        `⚠️ Input exposed ${files.length} of ${options.totalChangedFiles} changed files — the changeset exceeded the reviewer's file bound.`,
       );
     }
     if (demotedKept > 0) {
@@ -592,7 +615,10 @@ export const planPublication = (
   );
   const event: ReviewEvent = !options.applyVerdict
     ? "COMMENT"
-    : options.coverage?.status === "incomplete" || counts.blocking > 0
+    : options.inputCoverage?.status === "incomplete" ||
+        (options.inputCoverage === undefined && options.coverage?.status === "incomplete") ||
+        (options.assurance !== undefined && options.assurance.status !== "settled") ||
+        counts.blocking > 0
       ? "REQUEST_CHANGES"
       : review.verdict === "approve" && counts.important === 0
         ? "APPROVE"

package/src/internal/review-agent.ts

@@ -9,6 +9,7 @@ import {
   hasReviewableContent,
   renderReviewContent,
 } from "./diff.ts";
+import type { ChangedFile } from "./diff.ts";
 import {
   normalizeRepoRelativePath,
   PullRequestSource,
@@ -30,8 +31,8 @@ export const MAX_FINDINGS = 20;
 /** The hard non-anchored-concerns bound carried by the CodeReview schema. */
 export const MAX_CONCERNS = 10;
 
-/** Annotated patches larger than this are truncated with an explicit marker. */
-const MAX_PATCH_CHARS = 60_000;
+/** Maximum characters in one deterministic model-visible evidence chunk. */
+export const MAX_PATCH_CHARS = 60_000;
 
 /** The encoded Tool result must retain one complete bounded content fallback. */
 export const REVIEW_TOOL_RESULT_MAX_BYTES = 2 * 1024 * 1024;
@@ -105,6 +106,67 @@ export class FileDiffView extends Schema.Class<FileDiffView>(
   truncated: Schema.Boolean,
 }) {}
 
+export interface FileReviewEvidenceChunk {
+  readonly reviewMode: "diff" | "content" | "unavailable";
+  readonly annotatedPatch: string;
+}
+
+/**
+ * Split complete model-visible evidence at deterministic line boundaries.
+ * A pathological single line is hard-sliced so every character is still
+ * assigned and every chunk remains within the provider-independent bound.
+ */
+const boundedEvidenceChunks = (evidence: string): ReadonlyArray<string> => {
+  if (evidence.length <= MAX_PATCH_CHARS) return [evidence];
+  const chunks: Array<string> = [];
+  let offset = 0;
+  while (offset < evidence.length) {
+    let end = Math.min(offset + MAX_PATCH_CHARS, evidence.length);
+    if (end < evidence.length) {
+      const boundary = evidence.lastIndexOf("\n", end - 1);
+      if (boundary >= offset) end = boundary + 1;
+    }
+    // No newline exists inside the bound: preserve complete input with a
+    // deterministic hard slice instead of silently truncating the line.
+    if (end === offset) end = Math.min(offset + MAX_PATCH_CHARS, evidence.length);
+    chunks.push(evidence.slice(offset, end));
+    offset = end;
+  }
+  return chunks;
+};
+
+/** Complete bounded evidence chunks used by deterministic fan-out planning. */
+export const fileReviewEvidenceChunks = (
+  file: ChangedFile,
+): ReadonlyArray<FileReviewEvidenceChunk> => {
+  const contentEvidence = renderReviewContent(file);
+  const reviewMode =
+    file.patch !== undefined
+      ? ("diff" as const)
+      : contentEvidence !== undefined
+        ? ("content" as const)
+        : ("unavailable" as const);
+  const annotated = file.patch === undefined ? (contentEvidence ?? "") : annotatePatch(file.patch);
+  return boundedEvidenceChunks(annotated).map((annotatedPatch) => ({
+    reviewMode,
+    annotatedPatch,
+  }));
+};
+
+/** Host-owned rendering of one changed file's bounded review evidence. */
+export const fileDiffView = (file: ChangedFile): FileDiffView => {
+  const chunks = fileReviewEvidenceChunks(file);
+  const first = chunks[0] ?? { reviewMode: "unavailable" as const, annotatedPatch: "" };
+  const truncated = first.reviewMode === "diff" && chunks.length > 1;
+  return FileDiffView.make({
+    path: file.path,
+    status: file.status,
+    reviewMode: first.reviewMode,
+    annotatedPatch: truncated ? `${first.annotatedPatch}\n[diff truncated]` : first.annotatedPatch,
+    truncated,
+  });
+};
+
 // Read failures stay model-visible results ("return"), never run-killers:
 // a model asking for an out-of-changeset path is expected untrusted-input
 // behavior, and the fail-closed answer is a typed refusal it can correct —
@@ -194,25 +256,7 @@ export const readFileDiffHandler = (query: FileDiffQuery) =>
         reason: "Path is not part of this pull request's changeset.",
       });
     }
-    const contentEvidence = renderReviewContent(file);
-    const reviewMode =
-      file.patch !== undefined
-        ? ("diff" as const)
-        : contentEvidence !== undefined
-          ? ("content" as const)
-          : ("unavailable" as const);
-    const annotated =
-      file.patch === undefined ? (contentEvidence ?? "") : annotatePatch(file.patch);
-    const truncated = reviewMode === "diff" && annotated.length > MAX_PATCH_CHARS;
-    return FileDiffView.make({
-      path: file.path,
-      status: file.status,
-      reviewMode,
-      annotatedPatch: truncated
-        ? `${annotated.slice(0, MAX_PATCH_CHARS)}\n[diff truncated]`
-        : annotated,
-      truncated,
-    });
+    return fileDiffView(file);
   });
 
 /**
@@ -302,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"]);
@@ -400,15 +449,15 @@ export const makeReviewInstructions =
         : "The author provided no description.",
       ...resolveGuidance(options.guidance, mission),
       "Work in this order:",
-      "1. Call list_changed_files once to see the changeset. That list is your COMPLETE review scope: in incremental reviews it is deliberately a subset of the pull request's full diff (totalFiles counts the whole pull request), and everything it omits was already reviewed or excluded.",
-      "2. Call read_file_diff for every file you review. 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.",
+      "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.",
       "3. Call read_file when you need surrounding context the diff does not show. ONLY listed files are readable — read_file_diff and read_file both return a failed result for any other path (an import, a neighbor, a file named in the description). Do not request or retry unlisted paths; reason from the visible diffs instead and note the gap honestly in your summary when it matters.",
       "4. Review for real defects first: correctness, security, concurrency, resource leaks, error handling, API misuse. Style nits are least important. Do not praise; do not restate the diff.",
       "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.',
-      `6. Write a walkthrough: for every file you reviewed, 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.`,
+      `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>}.',
       `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.',

package/src/internal/review-state.ts

@@ -47,10 +47,12 @@ export class StoredReviewConcern extends Schema.Class<StoredReviewConcern>(
 }) {}
 
 /**
- * Versioned state embedded in one successfully covered review. The reviewed
- * head plus the full-scope fingerprint means every path not represented by an
- * unresolved item is accepted at that head; storing hundreds of path strings
- * separately would not fit GitHub's bounded review body in the worst case.
+ * 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.
  */
 export class ReviewState extends Schema.Class<ReviewState>("@effect-agent/pr-review/ReviewState")({
   version: Schema.Literal(1),
@@ -415,7 +417,7 @@ export const selectReviewRange = (input: {
   );
   return {
     mode: "incremental",
-    reason: `changes since successfully reviewed head ${input.priorState.reviewedHeadSha.slice(0, 7)}${baseReason}`,
+    reason: `changes since settled review head ${input.priorState.reviewedHeadSha.slice(0, 7)}${baseReason}`,
     files: selectedFiles,
     affectedPaths: [...affectedPaths].sort(),
     totalFiles: selectedFiles.length,