@llm4ts/flow 2.4.2 → 2.6.0

package/src/Review.ts

@@ -8,9 +8,24 @@ import { Capabilities } from "@llm4ts/core/Capability"
 import { guarded } from "./CapabilityGuard.ts"
 import type { Chat } from "./Chat.ts"
 import { FlowLlmError, ProcessError, describeFlowError, type FlowError } from "./FlowError.ts"
-import { Info, type FlowEventsShape } from "./FlowEvents.ts"
+import {
+  Info,
+  JudgmentObserved,
+  publishJudgmentObserved,
+  type FlowEventsShape
+} from "./FlowEvents.ts"
 import { Reviewer } from "./Reviewer.ts"
 import { publishUsage } from "./Usage.ts"
+import type { JudgmentShape } from "@llm4ts/core/judgment/Judgment"
+import { truth, type JudgmentResult, type TruthAnswer } from "@llm4ts/core/judgment/Schemas"
+import {
+  certaintyOf,
+  decide,
+  defaultJudgmentPolicy,
+  type Decision,
+  type JudgmentMode,
+  type JudgmentPolicy
+} from "./Judgment.ts"
 
 export const Severity = Schema.Literals(["Critical", "Warning", "Info"])
 export type Severity = typeof Severity.Type
@@ -67,8 +82,8 @@ export const reviewJsonSchema: JsonSchema = {
   required: ["issues", "summary"]
 }
 
-const reviewer = (name: string, systemPrompt: string, files = ".*"): Reviewer =>
-  Reviewer.make({ name, systemPrompt, files })
+const reviewer = (name: string, systemPrompt: string, screen: string, files = ".*"): Reviewer =>
+  Reviewer.make({ name, systemPrompt, files, screen })
 
 export const correctnessReviewer = reviewer(
   "code-functionality",
@@ -76,7 +91,8 @@ export const correctnessReviewer = reviewer(
     "Review for functional correctness. Check that the change implements the task's intent,",
     "handles obvious edge cases, and does not regress existing behavior. Report only concrete",
     "logic errors, wrong conditions, mishandled error paths, and missing cases. Ignore style."
-  ].join("\n")
+  ].join("\n"),
+  "The diff plausibly contains a logic error, a wrong condition, a mishandled error path, or a missing case."
 )
 
 export const readabilityReviewer = reviewer(
@@ -84,7 +100,8 @@ export const readabilityReviewer = reviewer(
   [
     "Review for readability and clarity. Check names, focused functions, understandable control",
     "flow, and useful comments. Report only concrete, actionable readability problems."
-  ].join("\n")
+  ].join("\n"),
+  "The diff plausibly introduces an unclear name, a tangled function, or confusing control flow."
 )
 
 export const testReviewer = reviewer(
@@ -92,27 +109,32 @@ export const testReviewer = reviewer(
   [
     "Review test coverage and quality. Check that new behavior and important error paths are",
     "covered by tests that assert real outcomes and would fail on regression. Report concrete gaps."
-  ].join("\n")
+  ].join("\n"),
+  "The diff changes behavior that is not covered by a test in the same diff."
 )
 
 export const structureReviewer = reviewer(
   "code-structure",
-  "Review module boundaries, dependency direction, cohesion, and unnecessary coupling. Report concrete structural problems."
+  "Review module boundaries, dependency direction, cohesion, and unnecessary coupling. Report concrete structural problems.",
+  "The diff plausibly crosses a module boundary, reverses a dependency direction, or adds coupling."
 )
 
 export const performanceReviewer = reviewer(
   "performance",
-  "Review for material performance regressions, unbounded work, avoidable repeated I/O, and resource leaks."
+  "Review for material performance regressions, unbounded work, avoidable repeated I/O, and resource leaks.",
+  "The diff plausibly changes performance characteristics: unbounded work, repeated I/O, or a resource leak."
 )
 
 export const securityReviewer = reviewer(
   "security",
-  "Review trust boundaries, input handling, secrets, authorization, injection risks, and unsafe defaults."
+  "Review trust boundaries, input handling, secrets, authorization, injection risks, and unsafe defaults.",
+  "The diff plausibly touches a trust boundary, secret, authorization check, input parser, or unsafe default."
 )
 
 export const effectReviewer = reviewer(
   "effect-ts",
   "Review Effect usage: typed errors, scoped resources, service boundaries, interruption, concurrency, and runtime ownership.",
+  "The diff plausibly misuses Effect: an untyped error, an unscoped resource, a leaked service, or unmanaged concurrency.",
   ".*\\.(ts|tsx|mts|cts)$"
 )
 
@@ -277,9 +299,103 @@ export interface ReviewAndFixOptions {
   readonly lint?: Effect.Effect<ReviewResult, FlowError>
   readonly parallelism?: number
   readonly format?: Effect.Effect<void, FlowError>
+  /**
+   * A judgment pre-screen (ADR 0017): one Truth question per lens over the
+   * diff. Observes by default, keeping every selected lens; only explicit
+   * act mode skips lenses. Omit to disable the judgment entirely.
+   */
+  readonly prescreen?: ReviewPrescreen
+}
+
+export interface ReviewPrescreen {
+  readonly judgment: JudgmentShape
+  readonly policy?: JudgmentPolicy
+  readonly mode?: JudgmentMode
+}
+
+export interface ReviewPrescreenResult {
+  readonly reviewers: ReadonlyArray<Reviewer>
+  readonly observations: ReadonlyArray<{
+    readonly key: string
+    readonly answer: TruthAnswer
+    readonly question: ReturnType<typeof truth>
+    readonly state: { readonly diff: string }
+    readonly judgmentIdentity: string
+    readonly decision: Decision
+  }>
 }
 
-const reviewWith = (
+/**
+ * Selected lenses and their answers for publication after review. In act mode
+ * a lens is skipped only when its screen
+ * answered with `act` certainty that the diff has nothing for it; doubt,
+ * failure, and escalation all run the lens. Never skip on doubt.
+ */
+export const prescreenReviewers = Effect.fn("@llm4ts/flow/Review.prescreen")(function* (
+  prescreen: ReviewPrescreen,
+  events: FlowEventsShape,
+  diff: string,
+  lenses: ReadonlyArray<Reviewer>
+): Effect.fn.Return<ReviewPrescreenResult, FlowError> {
+  if (lenses.length === 0) {
+    return { reviewers: lenses, observations: [] }
+  }
+  const policy = prescreen.policy ?? defaultJudgmentPolicy
+  const state = { diff }
+  const questions = Object.fromEntries(
+    lenses.map((lens) => [lens.name, truth(lens.screeningStatement)])
+  )
+  const result = yield* prescreen.judgment.judge({ state, questions }).pipe(
+    Effect.catch((error) =>
+      events
+        .publish(
+          Info.make({
+            message: `review pre-screen unavailable (${error.message}); running every lens`
+          })
+        )
+        .pipe(Effect.as<JudgmentResult | undefined>(undefined))
+    )
+  )
+  if (result === undefined) {
+    return { reviewers: lenses, observations: [] }
+  }
+  const observations = lenses.flatMap((lens) => {
+    const answer = result.answers[lens.name]
+    return answer?.type === "truth"
+      ? [
+          {
+            key: lens.name,
+            answer,
+            decision: decide(answer, policy),
+            state,
+            question: questions[lens.name],
+            judgmentIdentity: prescreen.judgment.identity
+          }
+        ]
+      : []
+  })
+  const kept =
+    prescreen.mode !== "act"
+      ? lenses
+      : lenses.filter(
+          (lens) =>
+            !observations.some(
+              ({ key, answer, decision }) =>
+                key === lens.name && answer.truth < 0.5 && decision === "act"
+            )
+        )
+  const skipped = lenses.filter((lens) => !kept.includes(lens))
+  if (skipped.length > 0) {
+    yield* events.publish(
+      Info.make({
+        message: `review pre-screen skipped ${skipped.map((lens) => lens.name).join(", ")}`
+      })
+    )
+  }
+  return { reviewers: kept, observations }
+})
+
+export const reviewWith = (
   service: LlmServiceShape,
   events: FlowEventsShape,
   lens: Reviewer,
@@ -339,15 +455,49 @@ export const reviewAndFixLoop = Effect.fn("@llm4ts/flow/Review.reviewAndFixLoop"
       }
       const diff = yield* options.currentDiff
       const files = yield* changedFiles
-      const chosen = yield* selector.select(options.reviewers, files, round, previous)
+      const selected = yield* selector.select(options.reviewers, files, round, previous)
+      const screened =
+        options.prescreen === undefined
+          ? { reviewers: selected, observations: [] }
+          : yield* prescreenReviewers(options.prescreen, options.events, diff, selected)
+      const chosen = screened.reviewers
       const run = (lens: Reviewer) =>
-        reviewWith(options.reviewerService, options.events, lens, options.taskTitle, diff)
+        reviewWith(options.reviewerService, options.events, lens, options.taskTitle, diff).pipe(
+          Effect.map((result) => ({ lens, result }))
+        )
       const parallelism = options.parallelism ?? 0
       const results =
         parallelism > 0
           ? yield* Effect.forEach(chosen, run, { concurrency: parallelism })
           : yield* Effect.forEach(chosen, run, { concurrency: "unbounded" })
-      return mergeReviewResults(results)
+      const mode = options.prescreen?.mode ?? "observe"
+      if (mode !== "act") {
+        for (const { lens, result } of results) {
+          const observation = screened.observations.find(({ key }) => key === lens.name)
+          if (observation === undefined) continue
+          const { key, answer, decision, state, question, judgmentIdentity } = observation
+          const counts = { Critical: 0, Warning: 0, Info: 0 }
+          for (const issue of result.issues) counts[issue.severity] += 1
+          yield* publishJudgmentObserved(
+            options.events,
+            JudgmentObserved.make({
+              consumer: "review-prescreen",
+              state,
+              question,
+              answer,
+              judgmentIdentity,
+              key,
+              decision,
+              certainty: certaintyOf(answer),
+              support: answer.support,
+              origin: answer.origin,
+              outcome: { _tag: "ReviewPrescreen", lens: lens.name, issues: counts },
+              mode
+            })
+          )
+        }
+      }
+      return mergeReviewResults(results.map(({ result }) => result))
     })
 
   const loop = (

package/src/Reviewer.ts

@@ -3,8 +3,22 @@ import * as Schema from "effect/Schema"
 export class Reviewer extends Schema.Class<Reviewer>("Reviewer")({
   name: Schema.String,
   systemPrompt: Schema.String,
-  files: Schema.optionalKey(Schema.String)
+  files: Schema.optionalKey(Schema.String),
+  /**
+   * The yes/no statement a judgment pre-screen evaluates against a diff to
+   * decide whether this lens is worth a full pass (ADR 0017). Absent, one is
+   * derived from the system prompt.
+   */
+  screen: Schema.optionalKey(Schema.String)
 }) {
+  /** The screening statement, explicit or derived. */
+  get screeningStatement(): string {
+    return (
+      this.screen ??
+      `A reviewer following these instructions would report at least one concrete issue in the diff: ${this.systemPrompt}`
+    )
+  }
+
   matches(changedFiles: ReadonlyArray<string>): boolean {
     if (this.files === undefined || changedFiles.length === 0) {
       return true

package/src/TransientRetry.ts

@@ -353,6 +353,7 @@ export const makeTransientRetry = Effect.fn("@llm4ts/flow/TransientRetry.make")(
         options,
         events
       ),
+    scoreLabels: underlying.scoreLabels,
     isAvailable: underlying.isAvailable
   })
 })