@llm4ts/flow 2.31.0 → 2.32.0

package/src/Retro.ts

@@ -22,7 +22,7 @@ import { FlowEvent, Info, type FlowEventsShape } from "./FlowEvents.ts"
 import type { TraceLine } from "./FlowRecorder.ts"
 import { Plan, Task, parsePlan } from "./Plan.ts"
 import { loadVersioned, makePlanStore, type PlainFileStoreShape } from "./Persistence.ts"
-import { ReviewResult } from "./Review.ts"
+import { ReviewResult, repoReviewRulesPath } from "./Review.ts"
 import {
   EpicReport,
   EpicReportVersion,
@@ -478,6 +478,7 @@ export const renderRetroDigest = (inputs: RetroInputs): string => {
         break
     }
   }
+  const signatures = signaturesOf(inputs, trace.events)
   const header = [
     `# Retro digest — run ${inputs.runId}, epic ${inputs.plan.epicId}`,
     "",
@@ -492,6 +493,13 @@ export const renderRetroDigest = (inputs: RetroInputs): string => {
           : "present"
     }`,
     ...(retries.length === 0 ? [] : [`- retries across the run: ${countBy(retries)}`]),
+    ...(signatures.length === 0
+      ? []
+      : [
+          "",
+          "## Signatures (patterns across stories: a rule, not a task)",
+          ...signatures.map((line) => `- ${line}`)
+        ]),
     ...(runLines.length === 0
       ? []
       : [
@@ -548,9 +556,33 @@ export const RetroStory = Schema.Struct({
 })
 export type RetroStory = typeof RetroStory.Type
 
+export const RuleEditOp = Schema.Literals(["append-rule", "replace-section"])
+export type RuleEditOp = typeof RuleEditOp.Type
+
+/**
+ * An edit to the loop rather than to a story (ADR 0027 decision 12): a line
+ * appended to a rules file, or a section replaced. Structured, never a
+ * diff; the report renders it as one for the human.
+ */
+export const RuleEdit = Schema.Struct({
+  /** Repo-relative: `.llm4ts/review-rules.md`, a pack's `reviewers/<name>.md`, `pack.md`, `lessons.md`, or a `patterns/pitfalls-*.md` card. */
+  target: Schema.String,
+  op: RuleEditOp,
+  /** `append-rule`: the rule, one line, without a leading dash. */
+  line: Schema.optionalKey(Schema.String),
+  /** `replace-section`: the `## heading` (without the hashes) and its new body. */
+  heading: Schema.optionalKey(Schema.String),
+  body: Schema.optionalKey(Schema.String),
+  /** The signature in the digest this answers. */
+  why: Schema.String
+})
+export type RuleEdit = typeof RuleEdit.Type
+
 export class RetroProposal extends Schema.Class<RetroProposal>("RetroProposal")({
   summary: Schema.String,
   stories: Schema.Array(RetroStory),
+  /** Edits to the rules the next run reviews with; absent in proposals written before ADR 0027. */
+  rules: Schema.optionalKey(Schema.Array(RuleEdit)),
   runAdvice: Schema.Array(Schema.Struct({ finding: Schema.String, evidence: Schema.String })),
   libraryAdvice: Schema.Array(
     Schema.Struct({ title: Schema.String, evidence: Schema.String, suggestion: Schema.String })
@@ -593,6 +625,21 @@ export const retroProposalJsonSchema: JsonSchema = {
         required: ["id", "diagnosis", "kind"]
       }
     },
+    rules: {
+      type: "array",
+      items: {
+        type: "object",
+        properties: {
+          target: { type: "string" },
+          op: { type: "string", enum: ["append-rule", "replace-section"] },
+          line: { type: "string" },
+          heading: { type: "string" },
+          body: { type: "string" },
+          why: { type: "string" }
+        },
+        required: ["target", "op", "why"]
+      }
+    },
     runAdvice: {
       type: "array",
       items: {
@@ -638,6 +685,14 @@ export const retroPrompt = (digest: string, storiesWithPlan: ReadonlyArray<strin
     "  no edit covers). Give the `feedback` text a planner should take.",
     "- `none`: nothing to change (an outage, a dependency that will unblock it). Give `why`.",
     "",
+    "`rules`: when the digest's Signatures section shows a pattern that repeats across stories",
+    "(the same reviewer finding, gaming such as stubs or skipped tests, fabricated status),",
+    "propose an edit to the loop rather than a task: `append-rule` adds one line to a rules",
+    "file, `replace-section` rewrites one `## heading` of it. Targets are repo-relative:",
+    "`.llm4ts/review-rules.md` (every run reads it as a review lens), a pack's",
+    "`reviewers/<name>.md`, `pack.md`, `lessons.md`, or a `patterns/pitfalls-*.md` card. Name",
+    "the signature in `why`. Nothing here is applied unreviewed.",
+    "",
     "`runAdvice`: findings about the environment or configuration (a seat on an old CLI, Node",
     "mismatch, gates missing, transcripts off), each with its evidence line.",
     "`libraryAdvice`: only where the digest shows llm4ts itself — the flow, a seat's harness",
@@ -757,7 +812,96 @@ export const validateRetroProposal = (
         break
     }
   }
-  return { proposal: RetroProposal.make({ ...proposal, stories }), dropped }
+  const rules: Array<RuleEdit> = []
+  for (const edit of proposal.rules ?? []) {
+    if (!allowedRuleTarget(edit.target)) {
+      dropped.push(`rule edit: ${edit.target} is not a rules file a retro may edit`)
+      continue
+    }
+    if (edit.op === "append-rule" && (edit.line ?? "").trim().length === 0) {
+      dropped.push(`rule edit: append-rule to ${edit.target} with no line`)
+      continue
+    }
+    if (
+      edit.op === "replace-section" &&
+      ((edit.heading ?? "").trim().length === 0 || (edit.body ?? "").trim().length === 0)
+    ) {
+      dropped.push(`rule edit: replace-section in ${edit.target} with no heading or body`)
+      continue
+    }
+    rules.push(edit)
+  }
+  return {
+    proposal: RetroProposal.make({
+      ...proposal,
+      stories,
+      ...(rules.length === 0 ? {} : { rules })
+    }),
+    dropped
+  }
+}
+
+/** The files a retro may edit: the repository's review rules, a pack's lenses and rules, a pitfall card. */
+export const allowedRuleTarget = (target: string): boolean =>
+  !badPath(target) &&
+  (target === repoReviewRulesPath ||
+    /(?:^|\/)reviewers\/[^/]+\.md$/u.test(target) ||
+    /(?:^|\/)pack\.md$/u.test(target) ||
+    /(?:^|\/)lessons\.md$/u.test(target) ||
+    /(?:^|\/)patterns\/pitfalls-[^/]+\.md$/u.test(target))
+
+const findingLine = /^- \[(Critical|Warning|Info)\] (.+?)(?: \(| — |: |$)/u
+
+/**
+ * Patterns across stories the digest flags for a rule (ADR 0027 decision 12):
+ * gaming (oracle-guard findings), the same reviewer finding in two or more
+ * stories, fabricated status in two or more stories.
+ */
+export const signaturesOf = (
+  inputs: RetroInputs,
+  events: ReadonlyArray<FlowEvent>
+): ReadonlyArray<string> => {
+  const gaming: Array<string> = []
+  const titles = new Map<string, Set<string>>()
+  for (const entry of inputs.stories) {
+    const text = entry.findings ?? ""
+    if (/^- \[(?:Critical|Warning)\] oracle: /mu.test(text)) {
+      gaming.push(entry.story.id)
+    }
+    for (const raw of text.split(/\r?\n/u)) {
+      const match = findingLine.exec(raw.trim())
+      const title = match?.[2]?.trim().toLowerCase()
+      if (title === undefined || title.startsWith("lint failed") || title.startsWith("oracle:")) {
+        continue
+      }
+      titles.set(title, (titles.get(title) ?? new Set()).add(entry.story.id))
+    }
+  }
+  const fabricated = new Set<string>()
+  for (const event of events) {
+    if (event._tag === "EvidenceChecked" && event.unverified > 0 && event.lane !== undefined) {
+      fabricated.add(event.lane)
+    }
+  }
+  const lines: Array<string> = []
+  if (gaming.length > 0) {
+    lines.push(
+      `gaming: the oracle guard caught deleted or skipped tests in ${gaming.length} stor${gaming.length === 1 ? "y" : "ies"} (${gaming.join(", ")})`
+    )
+  }
+  for (const [title, stories] of titles) {
+    if (stories.size >= 2) {
+      lines.push(
+        `the same reviewer finding in ${stories.size} stories (${[...stories].join(", ")}): "${title}"`
+      )
+    }
+  }
+  if (fabricated.size >= 2) {
+    lines.push(
+      `fabricated status in ${fabricated.size} stories (${[...fabricated].join(", ")}): the coder claimed commands that never ran`
+    )
+  }
+  return lines
 }
 
 // ---- Report ---------------------------------------------------------------------------------
@@ -849,6 +993,25 @@ export const renderRetroReport = (inputs: RetroReportInputs): string => {
       )
     }
   }
+  const rules = proposal.rules ?? []
+  if (rules.length > 0) {
+    lines.push("## Rule edits", "")
+    for (const edit of rules) {
+      lines.push(`### ${edit.target}`, "", `**Why.** ${edit.why.trim()}`, "", "```diff")
+      if (edit.op === "append-rule") {
+        lines.push(`+ - ${(edit.line ?? "").trim()}`)
+      } else {
+        lines.push(
+          `  ## ${(edit.heading ?? "").trim()}`,
+          ...(edit.body ?? "")
+            .trim()
+            .split(/\r?\n/u)
+            .map((row) => `+ ${row}`)
+        )
+      }
+      lines.push("```", "")
+    }
+  }
   if (proposal.runAdvice.length > 0) {
     lines.push(
       "## Run advice",
@@ -865,7 +1028,7 @@ export const renderRetroReport = (inputs: RetroReportInputs): string => {
   )
   const refines = proposal.stories.filter((entry) => entry.kind === "refine")
   lines.push("## Approval", "")
-  if (applies.length === 0) {
+  if (applies.length === 0 && rules.length === 0) {
     lines.push("Nothing here is applied by the next run; the report is for reading.", "")
   } else {
     lines.push(
@@ -876,6 +1039,11 @@ export const renderRetroReport = (inputs: RetroReportInputs): string => {
           ? `- ${entry.id}: append ${entry.tasks?.length ?? 0} task(s) to its plan`
           : `- ${entry.id}: edit its entry and restart it from a fresh worktree`
       ),
+      ...rules.map((edit) =>
+        edit.op === "append-rule"
+          ? `- ${edit.target}: append one rule`
+          : `- ${edit.target}: replace the "${(edit.heading ?? "").trim()}" section`
+      ),
       ""
     )
   }
@@ -963,12 +1131,49 @@ const retroTaskTitle = (runId: string, title: string): string => `Retro ${runId}
  * so the executor's hash check restarts them). Says what it did on the
  * events. Nothing here fails the run: a retro that no longer fits is skipped.
  */
+export interface ApplyRetroOptions {
+  /** The repository root rule edits resolve against; without it they are reported, not applied. */
+  readonly rulesRoot?: string
+}
+
+/** `append-rule`: the file with the rule added once; `replace-section`: with the section rewritten or appended. */
+export const applyRuleEdit = (existing: string | undefined, edit: RuleEdit): string | undefined => {
+  const current = existing ?? ""
+  if (edit.op === "append-rule") {
+    const line = `- ${(edit.line ?? "").trim()}`
+    if (current.split(/\r?\n/u).some((row) => row.trim() === line)) {
+      return undefined
+    }
+    const base =
+      current.trim().length === 0 && edit.target === repoReviewRulesPath
+        ? "# Review rules\n\nRules every review round of this repository applies (ADR 0027).\n\n"
+        : current.length === 0 || current.endsWith("\n")
+          ? current
+          : `${current}\n`
+    return `${base}${line}\n`
+  }
+  const heading = `## ${(edit.heading ?? "").trim()}`
+  const body = (edit.body ?? "").trim()
+  const sections = current.split(/^(?=## )/mu)
+  const index = sections.findIndex((section) => section.split(/\r?\n/u)[0]?.trim() === heading)
+  const replacement = `${heading}\n\n${body}\n`
+  if (index < 0) {
+    const base = current.length === 0 || current.endsWith("\n") ? current : `${current}\n`
+    return `${base}${current.trim().length === 0 ? "" : "\n"}${replacement}`
+  }
+  if (sections[index]?.trim() === replacement.trim()) {
+    return undefined
+  }
+  return [...sections.slice(0, index), replacement, ...sections.slice(index + 1)].join("")
+}
+
 export const applyApprovedRetros = Effect.fn("@llm4ts/flow/Retro.apply")(function* (
   files: PlainFileStoreShape,
   stateDir: string,
   plan: StoryPlan,
   events: FlowEventsShape,
-  now: number
+  now: number,
+  options: ApplyRetroOptions = {}
 ): Effect.fn.Return<AppliedRetros, FlowError> {
   const notes: Array<string> = []
   const say = (message: string): Effect.Effect<void> =>
@@ -1064,6 +1269,26 @@ export const applyApprovedRetros = Effect.fn("@llm4ts/flow/Retro.apply")(functio
           break
       }
     }
+    for (const edit of proposal.rules ?? []) {
+      if (options.rulesRoot === undefined) {
+        yield* say(`${runId}: rule edit to ${edit.target} needs the repository root; not applied`)
+        continue
+      }
+      if (!allowedRuleTarget(edit.target)) {
+        yield* say(`${runId}: rule edit to ${edit.target} is not allowed; skipped`)
+        continue
+      }
+      const path = join(options.rulesRoot, edit.target)
+      const existing = yield* files.read(path).pipe(Effect.catch(() => Effect.succeed(undefined)))
+      const next = applyRuleEdit(existing, edit)
+      if (next === undefined) {
+        continue
+      }
+      yield* files.writeAtomic(path, next)
+      yield* say(
+        `${runId}: ${edit.target} — ${edit.op === "append-rule" ? "one rule appended" : `section "${(edit.heading ?? "").trim()}" replaced`} (${edit.why.trim()})`
+      )
+    }
     if (editedIds.length > 0) {
       const valid: { readonly plan: StoryPlan; readonly problem: string | undefined } =
         yield* validateStoryPlan(edited).pipe(

package/src/Review.ts

@@ -11,7 +11,13 @@ import type { ProcessExecutorShape, ProcessResult } from "@llm4ts/core/ProcessEx
 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 {
+  FlowLlmError,
+  ProcessError,
+  Stalled,
+  describeFlowError,
+  type FlowError
+} from "./FlowError.ts"
 import type { PlainFileStoreShape } from "./Persistence.ts"
 import { GateBaseline, isGateIssue, triageGates } from "./GateTriage.ts"
 import {
@@ -23,6 +29,7 @@ import {
 } from "./OracleGuard.ts"
 import { cachedReview, fingerprintOf } from "./ReviewCache.ts"
 import {
+  ReviewFindingDemoted,
   Info,
   JudgmentObserved,
   ReviewFinding,
@@ -32,7 +39,7 @@ import {
   type FlowEventsShape
 } from "./FlowEvents.ts"
 import { attr, withKindSpan } from "./Spans.ts"
-import { Reviewer } from "./Reviewer.ts"
+import { Reviewer, parseReviewer } 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"
@@ -111,6 +118,40 @@ export const reviewJsonSchema: JsonSchema = {
 const reviewer = (name: string, systemPrompt: string, screen: string, files = ".*"): Reviewer =>
   Reviewer.make({ name, systemPrompt, files, screen })
 
+/**
+ * Rules with teeth (ADR 0027 decision 9), in front of every lens and the
+ * judge rubric: what no reviewer accepts whatever its concern. A pack's
+ * `## Review rules` extends it; `preamble: off` leaves it out.
+ */
+export const reviewRulesPreamble = [
+  "Rules every reviewer applies, whatever its concern:",
+  "- A stubbed body, a placeholder return, a TODO where logic belongs, or a function that only",
+  "  satisfies the type checker is a Critical finding.",
+  "- A skipped, deleted, weakened or hard-coded test is a Critical finding.",
+  "- A layering workaround (a runtime hook where a signature should change, a cast or `any`",
+  "  to silence a type, a duplicated type to avoid an import) is a Critical finding.",
+  "- If the change needs a paragraph-long comment to justify why a workaround is acceptable,",
+  "  the code is wrong, not the comment; report it."
+].join("\n")
+
+/** The one lens whose job is the Bun port's reviewer brief: find why the diff does not work. */
+export const adversarialReviewer = reviewer(
+  "adversarial",
+  [
+    "Your only job is to find reasons this change does not work. Assume the code is wrong and",
+    "look for the evidence: a path that is never taken, an error that is swallowed, a value that",
+    "is wrong at a boundary (empty, zero, negative, unicode, concurrent), a promise or effect that",
+    "is never awaited or yielded, a resource that leaks, a test that passes without exercising the",
+    "change. The diff is the whole subject. Report every concrete way it fails as a finding with",
+    "the file and line; an empty list means you looked and found none, not that it is fine."
+  ].join("\n"),
+  "The diff plausibly contains a defect an adversarial reader would find: a wrong boundary, an unhandled path, a leaked resource, a test that does not exercise the change."
+)
+
+/** The prompt a lens is asked with: the preamble (unless the lens opts out), then its own rules. */
+export const lensPrompt = (lens: Reviewer): string =>
+  lens.preamble === false ? lens.systemPrompt : `${reviewRulesPreamble}\n\n${lens.systemPrompt}`
+
 export const correctnessReviewer = reviewer(
   "code-functionality",
   [
@@ -165,12 +206,14 @@ export const effectReviewer = reviewer(
 )
 
 export const minimalReviewers: ReadonlyArray<Reviewer> = Object.freeze([
+  adversarialReviewer,
   correctnessReviewer,
   readabilityReviewer,
   testReviewer
 ])
 
 export const allReviewers: ReadonlyArray<Reviewer> = Object.freeze([
+  adversarialReviewer,
   correctnessReviewer,
   testReviewer,
   readabilityReviewer,
@@ -532,6 +575,112 @@ export const lintCommand = Effect.fn("@llm4ts/flow/Review.lintCommand")(function
   })
 })
 
+const placeKey = (issue: ReviewIssue): string =>
+  issue.file === undefined
+    ? `title:${issue.title.trim().toLowerCase()}`
+    : `${issue.file}:${issue.line ?? ""}`
+
+/**
+ * Independent votes of one lens merged (ADR 0027 decision 7): any Critical
+ * blocks; Warnings are unioned, one per place; an Info survives only when
+ * more than one vote raised it.
+ */
+export const mergeVotes = (votes: ReadonlyArray<ReviewResult>): ReviewResult => {
+  if (votes.length <= 1) {
+    return votes[0] ?? ReviewResult.make({ issues: [] })
+  }
+  const seen = new Map<string, { issue: ReviewIssue; count: number }>()
+  for (const vote of votes) {
+    for (const issue of vote.issues) {
+      const key = `${issue.severity}|${placeKey(issue)}`
+      const entry = seen.get(key)
+      if (entry === undefined) {
+        seen.set(key, { issue, count: 1 })
+      } else {
+        entry.count += 1
+      }
+    }
+  }
+  const issues = [...seen.values()]
+    .filter(({ issue, count }) => issue.severity !== "Info" || count > 1)
+    .map(({ issue }) => issue)
+  return ReviewResult.make({
+    issues,
+    summary: votes
+      .map((vote) => vote.summary)
+      .filter((summary) => summary.length > 0)
+      .join(" | ")
+  })
+}
+
+const inDiff = (file: string, changed: ReadonlyArray<string>): boolean => {
+  const wanted = file.replace(/^\.\//u, "")
+  return changed.some(
+    (path) => path === wanted || path.endsWith(`/${wanted}`) || wanted.endsWith(`/${path}`)
+  )
+}
+
+/**
+ * Findings that cannot be placed move down (ADR 0027 decision 10): a Critical
+ * without a file becomes a Warning, a finding whose file is not in the diff
+ * becomes an Info. Nothing is dropped; each move is published. With no
+ * changed-file list the result is returned as is.
+ */
+export const demoteUnplaced = Effect.fn("@llm4ts/flow/Review.demoteUnplaced")(function* (
+  lens: Reviewer,
+  result: ReviewResult,
+  changed: ReadonlyArray<string>,
+  events: FlowEventsShape
+): Effect.fn.Return<ReviewResult> {
+  if (changed.length === 0) {
+    return result
+  }
+  const issues: Array<ReviewIssue> = []
+  for (const issue of result.issues) {
+    let to: ReviewIssue["severity"] = issue.severity
+    let reason: string | undefined
+    if (issue.file !== undefined && !inDiff(issue.file, changed)) {
+      to = "Info"
+      reason = `names ${issue.file}, which the diff does not touch`
+    } else if (issue.file === undefined && issue.severity === "Critical") {
+      to = "Warning"
+      reason = "a Critical with no file"
+    }
+    if (reason !== undefined && to !== issue.severity) {
+      yield* events.publish(
+        ReviewFindingDemoted.make({
+          lens: lens.name,
+          title: issue.title,
+          from: issue.severity,
+          to,
+          reason
+        })
+      )
+      issues.push(ReviewIssue.make({ ...issue, severity: to }))
+    } else {
+      issues.push(issue)
+    }
+  }
+  return ReviewResult.make({ issues, summary: result.summary })
+})
+
+/** The repository's own review rules file, loaded as one extra lens; `undefined` when absent. */
+export const repoReviewRulesPath = ".llm4ts/review-rules.md"
+
+export const loadRepoReviewRules = (
+  files: PlainFileStoreShape,
+  workDir: string
+): Effect.Effect<Reviewer | undefined, FlowError> =>
+  files
+    .read(join(workDir, repoReviewRulesPath))
+    .pipe(
+      Effect.map((text) =>
+        text === undefined || text.trim().length === 0
+          ? undefined
+          : parseReviewer("repo-rules", text)
+      )
+    )
+
 export interface ReviewAndFixOptions {
   readonly reviewers: ReadonlyArray<Reviewer>
   readonly reviewerService: LlmServiceShape
@@ -569,6 +718,12 @@ export interface ReviewAndFixOptions {
   readonly fix?: FixPromptOptions
   /** Fail the round when the change deletes or skips tests (ADR 0027 decision 4). */
   readonly oracle?: OracleGateOptions
+  /** Independent votes of the adversarial lens per round (ADR 0027 decision 7). Default 1. */
+  readonly votes?: number
+  /** Applies a fix prompt somewhere other than the implementer's chat (a separate fixer). */
+  readonly fixWith?: (prompt: string) => Effect.Effect<string, FlowError>
+  /** End the task, typed `Stalled`, when a fix round leaves the diff byte-identical (ADR 0027 decision 11). */
+  readonly stallOnIdenticalDiff?: boolean
 }
 
 export interface ReviewCacheLocation {
@@ -671,7 +826,7 @@ export const reviewWith = (
   taskTitle: string,
   diff: string
 ): Effect.Effect<ReviewResult, FlowLlmError> => {
-  const prompt = `${lens.systemPrompt}\n\n${reviewPrompt(taskTitle, diff)}`
+  const prompt = `${lensPrompt(lens)}\n\n${reviewPrompt(taskTitle, diff)}`
   // Usage is published per attempt — a schema retry costs real tokens too.
   const attempt = (text: string): Effect.Effect<ReviewResult, LlmError> =>
     service.executeStructuredWithUsage(text, ReviewResult, reviewJsonSchema).pipe(
@@ -739,16 +894,36 @@ export const reviewAndFixLoop = Effect.fn("@llm4ts/flow/Review.reviewAndFixLoop"
           : yield* prescreenReviewers(options.prescreen, options.events, diff, selected)
       const chosen = screened.reviewers
       const cache = options.cache
-      const review = (lens: Reviewer): Effect.Effect<ReviewResult, FlowError> =>
+      const votes = Math.max(1, options.votes ?? 1)
+      const reviewVote = (lens: Reviewer, vote: number): Effect.Effect<ReviewResult, FlowError> =>
         cache === undefined
           ? reviewWith(options.reviewerService, options.events, lens, options.taskTitle, diff)
           : cachedReview(
               cache.files,
-              join(cache.dir, `${fileSlug(lens.name)}.json`),
-              fingerprintOf([lens.name, lens.systemPrompt, options.taskTitle, diff]),
+              join(cache.dir, `${fileSlug(lens.name)}${vote === 0 ? "" : `-vote${vote}`}.json`),
+              fingerprintOf([lens.name, lensPrompt(lens), String(vote), options.taskTitle, diff]),
               reviewWith(options.reviewerService, options.events, lens, options.taskTitle, diff)
             )
-      const run = (lens: Reviewer) => Effect.map(review(lens), (result) => ({ lens, result }))
+      // Votes multiply only the adversarial lens: its recall is what independent
+      // eyes improve; the concern lenses are cheap scoped questions.
+      const review = (lens: Reviewer): Effect.Effect<ReviewResult, FlowError> =>
+        lens.name === adversarialReviewer.name && votes > 1
+          ? Effect.map(
+              Effect.forEach(
+                Array.from({ length: votes }, (_, index) => index),
+                (vote) => reviewVote(lens, vote),
+                { concurrency: "unbounded" }
+              ),
+              mergeVotes
+            )
+          : reviewVote(lens, 0)
+      const run = (lens: Reviewer) =>
+        Effect.flatMap(review(lens), (result) =>
+          Effect.map(demoteUnplaced(lens, result, files, options.events), (placed) => ({
+            lens,
+            result: placed
+          }))
+        )
       const parallelism = options.parallelism ?? 0
       const results =
         parallelism > 0
@@ -784,12 +959,30 @@ export const reviewAndFixLoop = Effect.fn("@llm4ts/flow/Review.reviewAndFixLoop"
       return mergeReviewResults(results.map(({ result }) => result))
     })
 
+  const lastDiff = yield* Ref.make<string | undefined>(undefined)
   const loop = (
     round: number,
     previous: ReviewResult | undefined
   ): Effect.Effect<ReviewResult, FlowError> =>
     Effect.gen(function* () {
       yield* format
+      // A fix round that changed nothing is a loop going nowhere (ADR 0027
+      // decision 11): the same diff twice in a row ends the task, typed.
+      const diffNow = yield* options.currentDiff
+      const before = yield* Ref.get(lastDiff)
+      if (
+        options.stallOnIdenticalDiff === true &&
+        round > 1 &&
+        before !== undefined &&
+        before === diffNow &&
+        previous !== undefined
+      ) {
+        return yield* Stalled.make({
+          signal: "identical-diff",
+          detail: `review round ${round} found the diff unchanged after the fix for ${previous.issues.length} finding(s)`
+        })
+      }
+      yield* Ref.set(lastDiff, diffNow)
       const result = yield* reviewOnce(round, previous)
       const settled = result.isClean || round >= maxRounds
       yield* options.events.publish(
@@ -812,7 +1005,8 @@ export const reviewAndFixLoop = Effect.fn("@llm4ts/flow/Review.reviewAndFixLoop"
       if (settled) {
         return result
       }
-      yield* options.coder.ask(fixPrompt(result, options.fix))
+      const fix = fixPrompt(result, options.fix)
+      yield* options.fixWith === undefined ? options.coder.ask(fix) : options.fixWith(fix)
       return yield* loop(round + 1, result)
     })
 

package/src/Reviewer.ts

@@ -9,7 +9,9 @@ export class Reviewer extends Schema.Class<Reviewer>("Reviewer")({
    * decide whether this lens is worth a full pass (ADR 0017). Absent, one is
    * derived from the system prompt.
    */
-  screen: Schema.optionalKey(Schema.String)
+  screen: Schema.optionalKey(Schema.String),
+  /** False leaves the shared review-rules preamble (ADR 0027) off this lens; default on. */
+  preamble: Schema.optionalKey(Schema.Boolean)
 }) {
   /** The screening statement, explicit or derived. */
   get screeningStatement(): string {