@llm4ts/flow 2.50.0 → 2.52.0

package/src/Stories.ts

@@ -20,7 +20,7 @@ import type { LlmChunk, TokenUsage } from "@llm4ts/core/Models"
 import type { LlmError } from "@llm4ts/core/Errors"
 import { BoardItem, eventedBoard, type BoardSyncShape } from "./BoardSync.ts"
 import { makeChat } from "./Chat.ts"
-import { implementPlanFlow, type TaskOverrides } from "./Flow.ts"
+import { flowReviewer, implementPlanFlow, type TaskOverrides } from "./Flow.ts"
 import {
   GateBaseline,
   baselineKey,
@@ -77,6 +77,8 @@ import {
   applyTriage,
   isBlocking,
   loadRepoReviewRules,
+  minimalReviewers,
+  reviewAndFixLoop,
   nonBlockingIssues,
   type FixPromptOptions,
   type GateTriageOptions
@@ -87,6 +89,7 @@ import {
   defaultOracleRules,
   parseUnifiedDiff
 } from "./OracleGuard.ts"
+import { ReviewMemory } from "./Recheck.ts"
 import { cachedValue, fingerprintOf } from "./ReviewCache.ts"
 import { withContract, type ContractProfile } from "./AutonomyContract.ts"
 import { fabricatedStatusIssues, unverifiedClaims } from "./Evidence.ts"
@@ -116,8 +119,18 @@ const join = (root: string, path: string): string =>
 
 /** A flow context rooted in a story's worktree, plus that story's own usage totals. */
 /** A story judge's review with the rubric's scores; a plain `ReviewResult` has none. */
+/** A dimension below the bar the story was not held to, with the judge's reasoning (ADR 0045). */
+export const ExcusedDimension = Schema.Struct({
+  id: Schema.String,
+  score: Schema.Number,
+  max: Schema.Number,
+  reasoning: Schema.String
+})
+export type ExcusedDimension = typeof ExcusedDimension.Type
+
 export class StoryVerdict extends ReviewResult.extend<StoryVerdict>("StoryVerdict")({
-  dimensions: Schema.Array(JudgedDimension)
+  dimensions: Schema.Array(JudgedDimension),
+  excused: Schema.optionalKey(Schema.Array(ExcusedDimension))
 }) {}
 
 /** What a judge answers: a scored verdict, or a plain review result. */
@@ -752,6 +765,14 @@ export interface StoriesOptions {
    * story's plan (coder, review, gates, commit). Default 2: one revision.
    */
   readonly judgeRounds?: number
+  /**
+   * Where the review lenses run (ADR 0044): each task (default), or once per
+   * story, beside the judge, with incremental re-checks and one fix turn per
+   * round.
+   */
+  readonly reviewAt?: "task" | "story"
+  /** Story mode: rounds of the merged story review. Default 3. Task mode ignores it. */
+  readonly reviewRounds?: number
   /**
    * When the epic gates are red after a story merges (the merge is undone),
    * the story goes back to its worktree this many times: it catches up with
@@ -809,6 +830,12 @@ export interface StoriesOptions {
    * for a follow-up round. Default false: every finding is fixed or fails.
    */
   readonly deferNonBlocking?: boolean
+  /**
+   * Names the bar the judge holds stories to when it is not the default
+   * (`defer-tests`, ADR 0045). It enters the judge's cache fingerprint, so a
+   * verdict judged under one bar is never reused under another.
+   */
+  readonly judgeBar?: string
   /**
    * Second opinion on a BLOCKED_ON claim the plan cannot settle (a path no
    * story owns, or a parallel story's). `real: false` sends the coder back
@@ -857,6 +884,31 @@ const combined = (first: ReviewResult, second: ReviewResult): ReviewResult =>
 export const deferredPath = (stateDir: string, storyId: string): string =>
   join(stateDir, `stories/${storyId}.deferred.md`)
 
+/** Where a story review keeps its reviewers' memory between rounds and runs (ADR 0044). */
+export const reviewStatePath = (stateDir: string, storyId: string): string =>
+  join(stateDir, `stories/${storyId}.review-state.json`)
+
+/** Where a story's last judge verdict is kept, beside a fingerprint of what it judged. */
+export const judgeVerdictPath = (stateDir: string, storyId: string): string =>
+  join(stateDir, `stories/${storyId}.judge.json`)
+
+/** A story's last judge verdict, when it was a scored one (ADR 0045: what the debt reads). */
+export const lastStoryVerdict = (
+  files: PlainFileStoreShape,
+  stateDir: string,
+  storyId: string
+): Effect.Effect<StoryVerdict | undefined> =>
+  files.read(judgeVerdictPath(stateDir, storyId)).pipe(
+    Effect.flatMap((text) =>
+      text === undefined
+        ? Effect.succeed(undefined)
+        : Schema.decodeUnknownEffect(
+            Schema.fromJsonString(Schema.Struct({ result: StoryVerdict }))
+          )(text).pipe(Effect.map((entry) => entry.result))
+    ),
+    Effect.catch(() => Effect.succeed(undefined))
+  )
+
 /** A deferred finding as one Markdown bullet, prefixed with where it was found. */
 export const deferredLine = (source: string, issue: ReviewIssue): string => {
   const where =
@@ -954,11 +1006,12 @@ export const implementStoriesFlow = Effect.fn("@llm4ts/flow/Stories.implement")(
   // Parallel tasks are opt-in (ADR 0034 amendment): one coder per story unless asked.
   const taskConcurrency = Math.max(1, options.taskConcurrency ?? 1)
   const deferring = options.deferNonBlocking === true
+  const reviewAtStory = options.reviewAt === "story"
+  const reviewRounds = Math.max(1, options.reviewRounds ?? 3)
   const statePath = (story: Story): string => join(options.stateDir, `stories/${story.id}.json`)
   const planPath = (story: Story): string => join(options.stateDir, `stories/${story.id}.plan.md`)
   /** The judge's last verdict beside a fingerprint of what it judged. */
-  const judgePath = (story: Story): string =>
-    join(options.stateDir, `stories/${story.id}.judge.json`)
+  const judgePath = (story: Story): string => judgeVerdictPath(options.stateDir, story.id)
   /** One file per review lens, beside a fingerprint of the task and diff. */
   const reviewCacheDir = (story: Story): string =>
     join(options.stateDir, `stories/${story.id}.review`)
@@ -1900,7 +1953,10 @@ export const implementStoriesFlow = Effect.fn("@llm4ts/flow/Stories.implement")(
       // A lens's answer is kept beside the task and diff it answered, so a
       // rerun over the same change asks nothing; every round is written to
       // the story's findings log for people to read.
-      reviewCache: { files, dir: reviewCacheDir(story) },
+      // Reviewing per story (ADR 0044), a task runs on its gates alone.
+      ...(reviewAtStory
+        ? { reviewers: [] }
+        : { reviewCache: { files, dir: reviewCacheDir(story) } }),
       onReview: (task, round, result, settled) =>
         Effect.gen(function* () {
           // A settled round's leftovers are deferred, not dropped: when the
@@ -1920,15 +1976,17 @@ export const implementStoriesFlow = Effect.fn("@llm4ts/flow/Stories.implement")(
       onTaskReply: (task, _reply, trailer, startedAt) => checkEvidence(task, trailer, startedAt),
       // The repository's own review rules ride along as one extra lens
       // (ADR 0027 decision 9), read from the epic checkout.
-      repoRules: loadRepoReviewRules(files, context.workDir),
+      ...(reviewAtStory ? {} : { repoRules: loadRepoReviewRules(files, context.workDir) }),
       ...(options.votes === undefined ? {} : { votes: options.votes }),
       ...(options.fixer === undefined ? {} : { fixer: options.fixer }),
       ...(options.stall === undefined ? {} : { stall: options.stall }),
-      ...(options.reviewers === undefined ? {} : { reviewers: options.reviewers }),
+      ...(options.reviewers === undefined || reviewAtStory ? {} : { reviewers: options.reviewers }),
       ...(options.maxRounds === undefined ? {} : { maxRounds: options.maxRounds }),
       ...(deferring ? { settle: "blocking" as const } : {})
     })
     if (mergeFailure !== undefined) {
+      // The tasks run again: what the story review remembered no longer holds.
+      yield* files.remove(reviewStatePath(options.stateDir, story.id))
       // The branch already caught up with the epic above: the gates in the
       // worktree now see the combination that was red after the merge.
       yield* appendRevision(
@@ -1986,11 +2044,17 @@ export const implementStoriesFlow = Effect.fn("@llm4ts/flow/Stories.implement")(
         verdict
       )
 
-    let judgeNote: string | undefined
-    let inPlace = false
-    if (options.judge !== undefined) {
-      const judge = options.judge
-      for (let round = 1; round <= judgeRounds; round += 1) {
+    /**
+     * One judge round over the story's branch: the verdict, published on the
+     * lane, logged in the findings and kept beside a fingerprint of what was
+     * judged. `empty` says the branch had no changes, so its owned code was
+     * judged instead.
+     */
+    const judgeOnce = (
+      judge: NonNullable<StoriesOptions["judge"]>,
+      round: number
+    ): Effect.Effect<{ readonly verdict: ReviewResult; readonly empty: boolean }, FlowError> =>
+      Effect.gen(function* () {
         const diff = yield* git.diffVsBase(epicBranch)
         // No changes is not a failure by itself: the story's code may already
         // be on the epic (an earlier story or run put it there). Judge that
@@ -2045,7 +2109,9 @@ export const implementStoriesFlow = Effect.fn("@llm4ts/flow/Stories.implement")(
                       story.id,
                       story.title,
                       story.description,
-                      story.provides.join("\n")
+                      story.provides.join("\n"),
+                      // Absent for the default bar: verdicts stored before 2.52 stay valid.
+                      ...(options.judgeBar === undefined ? [] : [options.judgeBar])
                     ]),
                     withTimedRole(
                       "judge",
@@ -2102,6 +2168,183 @@ export const implementStoriesFlow = Effect.fn("@llm4ts/flow/Stories.implement")(
             dimensions: verdict instanceof StoryVerdict ? verdict.dimensions : []
           })
         )
+        return { verdict, empty }
+      })
+
+    /**
+     * The story review (ADR 0044): every lens and the judge on the story's
+     * diff, one fix turn per round, re-checks after the first. Returns the
+     * judge's note; fails the story when the judge is still not cleared.
+     */
+    const reviewStory = (): Effect.Effect<string | undefined, FlowError> =>
+      Effect.gen(function* () {
+        const statePath = reviewStatePath(options.stateDir, story.id)
+        const repoRules = yield* loadRepoReviewRules(files, context.workDir)
+        const lenses = [
+          ...(options.reviewers ?? minimalReviewers),
+          ...(repoRules === undefined ? [] : [repoRules])
+        ]
+        const judge = options.judge
+        const latest = yield* Ref.make<ReviewResult | undefined>(undefined)
+        const lastStanding = yield* Ref.make<ReviewResult | undefined>(undefined)
+        // The fix turn is a fresh chat: it gets the story and where each finding points.
+        const storyFixPrompt = (prompt: string, standing: ReviewResult | undefined): string => {
+          const located = (standing?.issues ?? []).flatMap((issue) =>
+            issue.file === undefined
+              ? []
+              : [
+                  `- ${issue.title} (${issue.lens ?? "gates"}): ${issue.file}${
+                    issue.line === undefined ? "" : `:${issue.line}`
+                  }`
+                ]
+          )
+          return [
+            `Story ${story.id}: ${story.title}`,
+            story.description,
+            ...(story.acceptance.length === 0
+              ? []
+              : ["Done when:", ...story.acceptance.map((line) => `- ${line}`)]),
+            "",
+            prompt,
+            ...(located.length === 0 ? [] : ["", "Where the findings point:", ...located])
+          ].join("\n")
+        }
+        const judgeRuns = yield* Ref.make(0)
+        const lastRound = yield* Ref.make(0)
+        // A judge that scores `provides` at 0 is owed a piece no fix turn writes.
+        const missingPiece = (verdict: ReviewResult | undefined): verdict is StoryVerdict =>
+          verdict instanceof StoryVerdict &&
+          verdict.dimensions.some((d) => d.id === "provides" && d.score <= 0)
+        const result = yield* reviewAndFixLoop({
+          reviewers: lenses,
+          reviewerService: flowReviewer(storyContext),
+          coder: yield* makeChat(storyContext.coder, { system, events, agent: "coder" }),
+          taskTitle: `story ${story.id}: ${story.title}`,
+          currentDiff: git.diffVsBase(epicBranch),
+          events: storyContext.events,
+          lint: gates,
+          triage,
+          maxRounds: reviewRounds,
+          ...(deferring ? { settle: "blocking" as const } : {}),
+          ...(options.fix === undefined ? {} : { fix: options.fix }),
+          cache: { files, dir: reviewCacheDir(story) },
+          fixWith: (prompt) =>
+            Effect.gen(function* () {
+              const verdict = yield* Ref.get(latest)
+              if (missingPiece(verdict)) {
+                // Used once: a later round's fix answers that round, not this verdict.
+                yield* Ref.set(latest, undefined)
+                yield* addRevision(verdict, false)
+                yield* guarded(implementTasks, implementTasks)
+                yield* catchUp(story, git)
+                yield* repairPerimeter
+                return ""
+              }
+              // A BLOCKED_ON from the fix turn stops the story like a task's would.
+              yield* guarded(
+                coderTurn(storyFixPrompt(prompt, yield* Ref.get(lastStanding))),
+                Effect.void
+              )
+              yield* git.commitAll(`${story.id}: story review fixes`)
+              return ""
+            }),
+          onRound: (round, standing, settled) =>
+            Effect.andThen(
+              Effect.andThen(Ref.set(lastRound, round), Ref.set(lastStanding, standing)),
+              appendFindings(
+                story,
+                `story review round ${round} — ${
+                  standing.isClean ? "clean" : `${standing.issues.length} issue(s)`
+                }${settled ? "" : ", fixing"}`,
+                standing
+              )
+            ),
+          recheck: {
+            extra:
+              judge === undefined
+                ? []
+                : [
+                    {
+                      name: "judge",
+                      review: () =>
+                        Effect.gen(function* () {
+                          const round = yield* Ref.updateAndGet(judgeRuns, (n) => n + 1)
+                          const { verdict } = yield* judgeOnce(judge, round)
+                          yield* Ref.set(latest, verdict)
+                          return verdict
+                        })
+                    }
+                  ],
+            memory: {
+              load: Effect.map(files.read(statePath), (text) => {
+                if (text === undefined) return undefined
+                try {
+                  return Schema.decodeUnknownSync(ReviewMemory)(JSON.parse(text))
+                } catch {
+                  // An unreadable state starts the review over.
+                  return undefined
+                }
+              }),
+              save: (memory) =>
+                files.writeAtomic(
+                  statePath,
+                  JSON.stringify(Schema.encodeSync(ReviewMemory)(memory), null, 2)
+                )
+            }
+          }
+        })
+        const rounds = yield* Ref.get(lastRound)
+        const left = result.issues
+        // Lenses and the judge always name themselves: a finding with no
+        // lens is a gate's (target gates, oracle, perimeter, frozen tests).
+        const gateLeft = left.filter((issue) => issue.lens === undefined)
+        if (gateLeft.length > 0) {
+          return yield* failed(
+            story,
+            `its gates are still red after ${rounds} story review round${rounds === 1 ? "" : "s"}:\n${issueLines(
+              ReviewResult.make({ issues: gateLeft })
+            )}`
+          )
+        }
+        const judgeLeft = left.filter(
+          (issue) => issue.lens === "judge" && (!deferring || isBlocking(issue))
+        )
+        if (judgeLeft.length > 0) {
+          return yield* failed(
+            story,
+            `judge not cleared after ${rounds} story review round${rounds === 1 ? "" : "s"}:\n${issueLines(
+              ReviewResult.make({ issues: judgeLeft })
+            )}`
+          )
+        }
+        const waiting = deferring ? left : []
+        for (const issue of waiting) {
+          deferred.push(deferredLine("story review", issue))
+        }
+        const carried = deferring ? [] : left.filter((issue) => issue.lens !== "judge")
+        if (carried.length > 0) {
+          yield* appendFindings(
+            story,
+            "carried: review rounds ran out",
+            ReviewResult.make({ issues: carried })
+          )
+        }
+        return judge === undefined
+          ? undefined
+          : `judge cleared (story review round ${rounds}${
+              waiting.length === 0 ? "" : `, ${waiting.length} finding(s) deferred`
+            })`
+      })
+
+    let judgeNote: string | undefined
+    let inPlace = false
+    const storyDiff = reviewAtStory ? yield* git.diffVsBase(epicBranch) : ""
+    if (reviewAtStory && storyDiff.trim().length > 0) {
+      judgeNote = yield* stage(laneOf(story), `story ${story.id}: review`, reviewStory())
+    } else if (options.judge !== undefined) {
+      const judge = options.judge
+      for (let round = 1; round <= judgeRounds; round += 1) {
+        const { verdict, empty } = yield* judgeOnce(judge, round)
         // Deferring, a verdict with nothing blocking clears: what it found
         // waits for the follow-up round instead of another revision.
         if (verdict.isClean || (deferring && !verdict.issues.some(isBlocking))) {
@@ -2218,6 +2461,7 @@ export const implementStoriesFlow = Effect.fn("@llm4ts/flow/Stories.implement")(
         ...(last === undefined ? {} : { executor: last })
       })
     )
+    yield* files.remove(reviewStatePath(options.stateDir, story.id))
     const inherited = inheritedByStory.get(story.id)
     return StoryOutcome.make({
       id: story.id,
@@ -2254,11 +2498,19 @@ export const implementStoriesFlow = Effect.fn("@llm4ts/flow/Stories.implement")(
   const attempt = (story: Story): Effect.Effect<Completion> =>
     annotated(
       story,
-      stage(laneOf(story), `story ${story.id}`, runStory(story), {
-        kind: "AGENT",
-        root: true,
-        attributes: storySpanAttributes(story)
-      })
+      stage(
+        laneOf(story),
+        `story ${story.id}`,
+        // A story that ends failed starts its review over next time (ADR 0044).
+        Effect.tapError(runStory(story), () =>
+          Effect.ignore(files.remove(reviewStatePath(options.stateDir, story.id)))
+        ),
+        {
+          kind: "AGENT",
+          root: true,
+          attributes: storySpanAttributes(story)
+        }
+      )
     ).pipe(
       Effect.map((outcome): Completion => ({ story, outcome })),
       Effect.catch((error) =>