@llm4ts/flow 2.50.0 → 2.51.0

package/dist/Stories.js

@@ -16,7 +16,7 @@ import * as Stream from "effect/Stream";
 import { cap } from "./Context.js";
 import { BoardItem, eventedBoard } from "./BoardSync.js";
 import { makeChat } from "./Chat.js";
-import { implementPlanFlow } from "./Flow.js";
+import { flowReviewer, implementPlanFlow } from "./Flow.js";
 import { GateBaseline, baselineKey, ensureBaseline as ensureStoredBaseline, failingLinesOf, storyGateLogDir, mergeGateLogDir, writeBaseline } from "./Gates.js";
 import { describeFlowError, rosterExhaustedPrefix, EpicCheckoutDirty, MissingDependency, PerimeterViolation, StoryFailed } from "./FlowError.js";
 import { Began, EvidenceChecked, Info, JudgedDimension, StoryJudged, Timed, withLane } from "./FlowEvents.js";
@@ -27,8 +27,9 @@ import { loadVersioned, makePlanStore, saveVersioned } from "./Persistence.js";
 import { Plan, Task } from "./Plan.js";
 import { stage } from "./PlanExecution.js";
 import { planFrom } from "./Planner.js";
-import { ReviewIssue, ReviewResult, applyTriage, isBlocking, loadRepoReviewRules, nonBlockingIssues } from "./Review.js";
+import { ReviewIssue, ReviewResult, applyTriage, isBlocking, loadRepoReviewRules, minimalReviewers, reviewAndFixLoop, nonBlockingIssues } from "./Review.js";
 import { checkOracle, defaultOracleRules, parseUnifiedDiff } from "./OracleGuard.js";
+import { ReviewMemory } from "./Recheck.js";
 import { cachedValue, fingerprintOf } from "./ReviewCache.js";
 import { withContract } from "./AutonomyContract.js";
 import { fabricatedStatusIssues, unverifiedClaims } from "./Evidence.js";
@@ -451,6 +452,8 @@ const combined = (first, second) => first.isClean && second.isClean
  * nothing was deferred.
  */
 export const deferredPath = (stateDir, storyId) => join(stateDir, `stories/${storyId}.deferred.md`);
+/** Where a story review keeps its reviewers' memory between rounds and runs (ADR 0044). */
+export const reviewStatePath = (stateDir, storyId) => join(stateDir, `stories/${storyId}.review-state.json`);
 /** A deferred finding as one Markdown bullet, prefixed with where it was found. */
 export const deferredLine = (source, issue) => {
     const where = issue.file === undefined
@@ -516,6 +519,8 @@ 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) => join(options.stateDir, `stories/${story.id}.json`);
     const planPath = (story) => join(options.stateDir, `stories/${story.id}.plan.md`);
     /** The judge's last verdict beside a fingerprint of what it judged. */
@@ -1155,7 +1160,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
                 // rounds ran out, blocking ones too, since the task commits anyway.
@@ -1168,15 +1176,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" } : {})
         });
         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("make the epic gates green after merging", [
@@ -1211,94 +1221,230 @@ export const implementStoriesFlow = Effect.fn("@llm4ts/flow/Stories.implement")(
         const addRevision = (verdict, empty) => appendRevision("close the judge's findings", empty
             ? `The story "${story.title}" has no changes yet, and what it must provide is not all in place on the epic branch.`
             : `The story "${story.title}" was judged short of done.`, verdict);
-        let judgeNote;
-        let inPlace = false;
-        if (options.judge !== undefined) {
+        /**
+         * 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, round) => 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
+            // code instead: the owned paths against the empty tree.
+            const empty = diff.trim().length === 0;
+            const judgedCode = empty ? yield* git.diffVsBaseScoped(emptyTree, story.owned, false) : diff;
+            // What the coder claimed and could not show travels with the subject
+            // (ADR 0027 decision 6): the judge weighs the code knowing the
+            // story's own account of its testing is not evidence.
+            const subject = evidenceNotes.length === 0
+                ? judgedCode
+                : [
+                    "Evidence notes from the run (not part of the diff):",
+                    ...evidenceNotes.map((note) => `- ${note}`),
+                    "",
+                    judgedCode
+                ].join("\n");
+            // The verdict is kept beside a fingerprint of what was judged: a
+            // rerun that finds the same diff gets the same answer without a
+            // model call, and the last verdict is on disk to read. Only the
+            // first round reuses it; a later round follows a revision and asks.
+            // The round is an EVALUATOR span (ADR 0026): the verdict's scores and
+            // findings land on it, so a trace shows why a story was sent back.
+            const judged = yield* withKindSpan(`story ${story.id}: judge ${round}`, { kind: "EVALUATOR" }, Effect.gen(function* () {
+                const outcome = empty && subject.trim().length === 0
+                    ? // Nothing to judge is decided here, not asked of a model.
+                        {
+                            value: ReviewResult.make({
+                                issues: [
+                                    ReviewIssue.make({
+                                        severity: "Critical",
+                                        title: `nothing exists yet under ${story.owned.join(", ")}`,
+                                        description: "The story's owned paths are empty on the epic branch."
+                                    })
+                                ],
+                                summary: `judge:${story.id}`
+                            }),
+                            reused: false
+                        }
+                    : yield* cachedValue(files, judgePath(story), Verdict, fingerprintOf([
+                        empty ? "code" : "diff",
+                        subject,
+                        story.id,
+                        story.title,
+                        story.description,
+                        story.provides.join("\n")
+                    ]), withTimedRole("judge", judge(story, subject, watchedSeats, empty ? "code" : "diff")), { reuse: round === 1 });
+                const scored = outcome.value instanceof StoryVerdict ? outcome.value.dimensions : [];
+                yield* Effect.annotateCurrentSpan({
+                    "llm4ts.judge.cleared": outcome.value.isClean,
+                    "llm4ts.judge.reused": outcome.reused,
+                    ...Object.fromEntries(scored.map((d) => [`llm4ts.judge.${d.id}`, d.score]))
+                });
+                const now = yield* Clock.currentTimeNanos;
+                yield* Effect.option(Effect.currentSpan).pipe(Effect.map((span) => {
+                    if (span._tag === "Some") {
+                        for (const issue of outcome.value.issues) {
+                            span.value.event("judge finding", now, {
+                                title: issue.title,
+                                severity: issue.severity
+                            });
+                        }
+                    }
+                }));
+                return outcome;
+            }));
+            const verdict = judged.value;
+            if (judged.reused) {
+                yield* laneOf(story).publish(Info.make({
+                    lane: story.id,
+                    message: `judge round ${round}: reused the verdict for an unchanged ${empty ? "code" : "diff"}`
+                }));
+            }
+            yield* appendFindings(story, `judge round ${round} — ${verdict.isClean ? "cleared" : "not cleared"}${verdict instanceof StoryVerdict
+                ? ` (${verdict.dimensions.map((d) => `${d.id} ${d.score}/${d.max}`).join(", ")})`
+                : ""}${judged.reused ? ", reused" : ""}`, verdict);
+            yield* laneOf(story).publish(StoryJudged.make({
+                lane: story.id,
+                round,
+                cleared: verdict.isClean,
+                issues: verdict.issues.length,
+                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.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;
-            for (let round = 1; round <= judgeRounds; round += 1) {
-                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
-                // code instead: the owned paths against the empty tree.
-                const empty = diff.trim().length === 0;
-                const judgedCode = empty ? yield* git.diffVsBaseScoped(emptyTree, story.owned, false) : diff;
-                // What the coder claimed and could not show travels with the subject
-                // (ADR 0027 decision 6): the judge weighs the code knowing the
-                // story's own account of its testing is not evidence.
-                const subject = evidenceNotes.length === 0
-                    ? judgedCode
+            const latest = yield* Ref.make(undefined);
+            const lastStanding = yield* Ref.make(undefined);
+            // The fix turn is a fresh chat: it gets the story and where each finding points.
+            const storyFixPrompt = (prompt, standing) => {
+                const located = (standing?.issues ?? []).flatMap((issue) => issue.file === undefined
+                    ? []
                     : [
-                        "Evidence notes from the run (not part of the diff):",
-                        ...evidenceNotes.map((note) => `- ${note}`),
-                        "",
-                        judgedCode
-                    ].join("\n");
-                // The verdict is kept beside a fingerprint of what was judged: a
-                // rerun that finds the same diff gets the same answer without a
-                // model call, and the last verdict is on disk to read. Only the
-                // first round reuses it; a later round follows a revision and asks.
-                // The round is an EVALUATOR span (ADR 0026): the verdict's scores and
-                // findings land on it, so a trace shows why a story was sent back.
-                const judged = yield* withKindSpan(`story ${story.id}: judge ${round}`, { kind: "EVALUATOR" }, Effect.gen(function* () {
-                    const outcome = empty && subject.trim().length === 0
-                        ? // Nothing to judge is decided here, not asked of a model.
+                        `- ${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) => 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" } : {}),
+                ...(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
+                        ? []
+                        : [
                             {
-                                value: ReviewResult.make({
-                                    issues: [
-                                        ReviewIssue.make({
-                                            severity: "Critical",
-                                            title: `nothing exists yet under ${story.owned.join(", ")}`,
-                                            description: "The story's owned paths are empty on the epic branch."
-                                        })
-                                    ],
-                                    summary: `judge:${story.id}`
-                                }),
-                                reused: false
+                                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;
+                                })
                             }
-                        : yield* cachedValue(files, judgePath(story), Verdict, fingerprintOf([
-                            empty ? "code" : "diff",
-                            subject,
-                            story.id,
-                            story.title,
-                            story.description,
-                            story.provides.join("\n")
-                        ]), withTimedRole("judge", judge(story, subject, watchedSeats, empty ? "code" : "diff")), { reuse: round === 1 });
-                    const scored = outcome.value instanceof StoryVerdict ? outcome.value.dimensions : [];
-                    yield* Effect.annotateCurrentSpan({
-                        "llm4ts.judge.cleared": outcome.value.isClean,
-                        "llm4ts.judge.reused": outcome.reused,
-                        ...Object.fromEntries(scored.map((d) => [`llm4ts.judge.${d.id}`, d.score]))
-                    });
-                    const now = yield* Clock.currentTimeNanos;
-                    yield* Effect.option(Effect.currentSpan).pipe(Effect.map((span) => {
-                        if (span._tag === "Some") {
-                            for (const issue of outcome.value.issues) {
-                                span.value.event("judge finding", now, {
-                                    title: issue.title,
-                                    severity: issue.severity
-                                });
+                        ],
+                    memory: {
+                        load: Effect.map(files.read(statePath), (text) => {
+                            if (text === undefined)
+                                return undefined;
+                            try {
+                                return Schema.decodeUnknownSync(ReviewMemory)(JSON.parse(text));
                             }
-                        }
-                    }));
-                    return outcome;
-                }));
-                const verdict = judged.value;
-                if (judged.reused) {
-                    yield* laneOf(story).publish(Info.make({
-                        lane: story.id,
-                        message: `judge round ${round}: reused the verdict for an unchanged ${empty ? "code" : "diff"}`
-                    }));
+                            catch {
+                                // An unreadable state starts the review over.
+                                return undefined;
+                            }
+                        }),
+                        save: (memory) => files.writeAtomic(statePath, JSON.stringify(Schema.encodeSync(ReviewMemory)(memory), null, 2))
+                    }
                 }
-                yield* appendFindings(story, `judge round ${round} — ${verdict.isClean ? "cleared" : "not cleared"}${verdict instanceof StoryVerdict
-                    ? ` (${verdict.dimensions.map((d) => `${d.id} ${d.score}/${d.max}`).join(", ")})`
-                    : ""}${judged.reused ? ", reused" : ""}`, verdict);
-                yield* laneOf(story).publish(StoryJudged.make({
-                    lane: story.id,
-                    round,
-                    cleared: verdict.isClean,
-                    issues: verdict.issues.length,
-                    dimensions: verdict instanceof StoryVerdict ? verdict.dimensions : []
-                }));
+            });
+            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;
+        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))) {
@@ -1384,6 +1530,7 @@ export const implementStoriesFlow = Effect.fn("@llm4ts/flow/Stories.implement")(
             status: "merged",
             ...(last === undefined ? {} : { executor: last })
         }));
+        yield* files.remove(reviewStatePath(options.stateDir, story.id));
         const inherited = inheritedByStory.get(story.id);
         return StoryOutcome.make({
             id: story.id,
@@ -1409,7 +1556,9 @@ export const implementStoriesFlow = Effect.fn("@llm4ts/flow/Stories.implement")(
             : { [attr.session]: context.trace.runId, [attr.run]: context.trace.runId })
     });
     const annotated = (story, effect) => Object.entries(storySpanAttributes(story)).reduce((acc, [key, value]) => Effect.annotateSpans(key, value)(acc), effect);
-    const attempt = (story) => annotated(story, stage(laneOf(story), `story ${story.id}`, runStory(story), {
+    const attempt = (story) => annotated(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)