@llm4ts/flow 2.37.0 → 2.39.0

package/src/Pack.ts

@@ -4,6 +4,7 @@ import * as Schema from "effect/Schema"
 import { Dimension } from "@llm4ts/core/eval/Eval"
 import type { ConsolidateRules } from "./Domains.ts"
 import { PlanParseError } from "./FlowError.ts"
+import { edgeKindsOf, parseGraphRules, type GraphRules } from "./GraphRules.ts"
 import { oracleRulesFrom, type OracleRules } from "./OracleGuard.ts"
 import { Reviewer, parseReviewer } from "./Reviewer.ts"
 import { CoverageRule } from "./SpecChecks.ts"
@@ -37,6 +38,12 @@ export interface Pack {
   readonly judgeDimensions: ReadonlyArray<Dimension>
   readonly coverage: ReadonlyArray<CoverageRule>
   readonly survey: ReadonlyArray<CoverageRule>
+  /**
+   * The graph vocabulary (ADR 0030): `## Node:`, `## Edge:` (with every
+   * `## Survey:` folded in as a file-to-file edge), `## Join:`, `## Probe:`
+   * and the `## Graph` budgets.
+   */
+  readonly graph: GraphRules
   readonly prompts: Readonly<Record<string, string>>
   readonly lenses: ReadonlyArray<Reviewer>
   readonly lessons: string | undefined
@@ -391,16 +398,18 @@ export const loadPack = Effect.fn("@llm4ts/flow/Pack.load")(function* (
           cluster: commaList(consolidateValues.cluster),
           context: commaList(consolidateValues.context)
         }
+  const survey = rules(manifest.sections, "## Survey: ")
+  const graph = yield* parseGraphRules(manifest.sections, survey)
   if (consolidate !== undefined) {
-    const surveyNames = new Set(rules(manifest.sections, "## Survey: ").map((rule) => rule.name))
+    const knownKinds = new Set([...survey.map((rule) => rule.name), ...edgeKindsOf(graph)])
     const unknown = [...consolidate.cluster, ...consolidate.context].filter(
-      (kind) => !surveyNames.has(kind) && !kind.startsWith("llm-") && !kind.endsWith("*")
+      (kind) => !knownKinds.has(kind) && !kind.startsWith("llm-") && !kind.endsWith("*")
     )
     if (unknown.length > 0) {
       return yield* PlanParseError.make({
         message:
-          `pack manifest '## Consolidate' names edge kinds no '## Survey:' rule produces: ${unknown.join(", ")} ` +
-          `(known: ${[...surveyNames].join(", ") || "none"}; 'llm-*' matches refined edges)`
+          `pack manifest '## Consolidate' names edge kinds no '## Survey:', '## Edge:' or '## Join:' rule produces: ${unknown.join(", ")} ` +
+          `(known: ${[...knownKinds].join(", ") || "none"}; 'llm-*' matches refined edges)`
       })
     }
     const both = consolidate.cluster.filter((kind) => consolidate.context.includes(kind))
@@ -438,7 +447,8 @@ export const loadPack = Effect.fn("@llm4ts/flow/Pack.load")(function* (
     }),
     judgeDimensions: dimensions(section(manifest.sections, "Judge")),
     coverage: rules(manifest.sections, "## Coverage: "),
-    survey: rules(manifest.sections, "## Survey: "),
+    survey,
+    graph,
     prompts,
     lenses,
     lessons: lessons === undefined || lessons.length === 0 ? undefined : lessons,

package/src/Review.ts

@@ -735,8 +735,24 @@ export interface ReviewAndFixOptions {
   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
+  /**
+   * When a round settles before `maxRounds` (ADR 0031): "clean" (default)
+   * when it has no findings; "blocking" also when its findings are all
+   * non-blocking. A red gate is always blocking.
+   */
+  readonly settle?: SettleRule
 }
 
+/** When a review round stops sending findings back to the coder (ADR 0031). */
+export type SettleRule = "clean" | "blocking"
+
+/** A finding that must be fixed before the work moves on: Critical (ADR 0031). */
+export const isBlocking = (issue: ReviewIssue): boolean => issue.severity === "Critical"
+
+/** The findings that may wait: everything not blocking (ADR 0031). */
+export const nonBlockingIssues = (result: ReviewResult): ReadonlyArray<ReviewIssue> =>
+  result.issues.filter((issue) => !isBlocking(issue))
+
 export interface ReviewCacheLocation {
   readonly files: PlainFileStoreShape
   readonly dir: string
@@ -881,6 +897,10 @@ export const reviewAndFixLoop = Effect.fn("@llm4ts/flow/Review.reviewAndFixLoop"
   const reported = yield* Ref.make<ReadonlySet<string>>(new Set())
   const oracleNoted = yield* Ref.make(false)
 
+  const settle = options.settle ?? "clean"
+  // A red gate is never settled early, whatever its findings' severities.
+  const gateRed = yield* Ref.make(false)
+
   const reviewOnce = (
     round: number,
     previous: ReviewResult | undefined
@@ -893,6 +913,7 @@ export const reviewAndFixLoop = Effect.fn("@llm4ts/flow/Review.reviewAndFixLoop"
         options.events,
         oracleNoted
       )
+      yield* Ref.set(gateRed, !lint.isClean)
       if (!lint.isClean) {
         return lint
       }
@@ -1017,7 +1038,10 @@ export const reviewAndFixLoop = Effect.fn("@llm4ts/flow/Review.reviewAndFixLoop"
       }
       yield* Ref.set(lastDiff, diffNow)
       const result = yield* reviewOnce(round, previous)
-      const settled = result.isClean || round >= maxRounds
+      const settled =
+        result.isClean ||
+        round >= maxRounds ||
+        (settle === "blocking" && !(yield* Ref.get(gateRed)) && !result.issues.some(isBlocking))
       yield* options.events.publish(
         ReviewFindings.make({
           round,

package/src/Stories.ts

@@ -74,7 +74,9 @@ import {
   ReviewIssue,
   ReviewResult,
   applyTriage,
+  isBlocking,
   loadRepoReviewRules,
+  nonBlockingIssues,
   type FixPromptOptions,
   type GateTriageOptions
 } from "./Review.ts"
@@ -722,6 +724,14 @@ export interface StoriesOptions {
   readonly failFast?: boolean
   readonly reviewers?: ReadonlyArray<Reviewer>
   readonly maxRounds?: number
+  /**
+   * Defer what does not block (ADR 0031): a task's review settles once its
+   * findings are all non-blocking, the judge clears a story whose findings
+   * are all non-blocking, and what is left is written to
+   * `stories/<id>.deferred.md` (`deferredPath`) when the story finishes,
+   * for a follow-up round. Default false: every finding is fixed or fails.
+   */
+  readonly deferNonBlocking?: boolean
   /**
    * 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
@@ -762,6 +772,24 @@ const combined = (first: ReviewResult, second: ReviewResult): ReviewResult =>
         summary: [first.summary, second.summary].filter((part) => part.length > 0).join("; ")
       })
 
+/**
+ * Where a finished story's deferred findings are kept (ADR 0031): one
+ * Markdown list per story under the executor's state directory, absent when
+ * nothing was deferred.
+ */
+export const deferredPath = (stateDir: string, storyId: string): string =>
+  join(stateDir, `stories/${storyId}.deferred.md`)
+
+/** A deferred finding as one Markdown bullet, prefixed with where it was found. */
+export const deferredLine = (source: string, issue: ReviewIssue): string => {
+  const where =
+    issue.file === undefined
+      ? ""
+      : ` (${issue.file}${issue.line === undefined ? "" : `:${issue.line}`})`
+  const detail = issue.description.trim().length === 0 ? "" : `: ${issue.description.trim()}`
+  return `- [${issue.severity}] ${source} — ${issue.title}${where}${detail}`
+}
+
 const issueLines = (result: ReviewResult): string =>
   result.issues.map((issue) => `- ${issue.title}: ${issue.description}`).join("\n")
 
@@ -843,6 +871,7 @@ export const implementStoriesFlow = Effect.fn("@llm4ts/flow/Stories.implement")(
   const epicBranch = options.epicBranch ?? `epic/${plan.epicId}`
   const concurrency = Math.max(1, options.concurrency ?? 3)
   const judgeRounds = Math.max(1, options.judgeRounds ?? 2)
+  const deferring = options.deferNonBlocking === true
   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. */
@@ -1196,6 +1225,8 @@ export const implementStoriesFlow = Effect.fn("@llm4ts/flow/Stories.implement")(
     )
     /** What the coder claimed to have run and did not, task by task, for the judge. */
     const evidenceNotes: Array<string> = []
+    /** Findings left for a follow-up round (ADR 0031), written when the story finishes. */
+    const deferred: Array<string> = []
     const checkEvidence = (
       task: Task,
       trailer: Trailer,
@@ -1513,13 +1544,21 @@ export const implementStoriesFlow = Effect.fn("@llm4ts/flow/Stories.implement")(
       // the story's findings log for people to read.
       reviewCache: { files, dir: reviewCacheDir(story) },
       onReview: (task, round, result, settled) =>
-        appendFindings(
-          story,
-          `review "${task.title}" round ${round} — ${
-            result.isClean ? "clean" : `${result.issues.length} issue(s)`
-          }${settled ? "" : ", fixing"}`,
-          result
-        ),
+        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.
+          const left = settled && deferring ? result.issues : []
+          for (const issue of left) {
+            deferred.push(deferredLine(`review "${task.title}"`, issue))
+          }
+          yield* appendFindings(
+            story,
+            `review "${task.title}" round ${round} — ${
+              result.isClean ? "clean" : `${result.issues.length} issue(s)`
+            }${settled ? (left.length === 0 ? "" : ", deferred") : ", fixing"}`,
+            result
+          )
+        }),
       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.
@@ -1528,7 +1567,8 @@ export const implementStoriesFlow = Effect.fn("@llm4ts/flow/Stories.implement")(
       ...(options.fixer === undefined ? {} : { fixer: options.fixer }),
       ...(options.stall === undefined ? {} : { stall: options.stall }),
       ...(options.reviewers === undefined ? {} : { reviewers: options.reviewers }),
-      ...(options.maxRounds === undefined ? {} : { maxRounds: options.maxRounds })
+      ...(options.maxRounds === undefined ? {} : { maxRounds: options.maxRounds }),
+      ...(deferring ? { settle: "blocking" as const } : {})
     })
     yield* guarded(implementTasks, implementTasks)
 
@@ -1684,11 +1724,17 @@ export const implementStoriesFlow = Effect.fn("@llm4ts/flow/Stories.implement")(
             dimensions: verdict instanceof StoryVerdict ? verdict.dimensions : []
           })
         )
-        if (verdict.isClean) {
+        // 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))) {
+          const waiting = nonBlockingIssues(verdict)
+          for (const issue of waiting) {
+            deferred.push(deferredLine(`judge round ${round}`, issue))
+          }
           inPlace = empty
-          judgeNote = empty
-            ? `verified already in place (round ${round})`
-            : `judge cleared (round ${round})`
+          judgeNote = `${empty ? "verified already in place" : "judge cleared"} (round ${round}${
+            waiting.length === 0 ? "" : `, ${waiting.length} finding(s) deferred`
+          })`
           break
         }
         if (round >= judgeRounds) {
@@ -1709,6 +1755,14 @@ export const implementStoriesFlow = Effect.fn("@llm4ts/flow/Stories.implement")(
 
     const changed = yield* git.changedFilesVsBase(epicBranch)
     yield* enforcePerimeter(changed, story)
+    if (deferring) {
+      yield* deferred.length === 0
+        ? files.remove(deferredPath(options.stateDir, story.id))
+        : files.writeAtomic(
+            deferredPath(options.stateDir, story.id),
+            [`# Deferred from ${story.id}: ${story.title}`, "", ...deferred, ""].join("\n")
+          )
+    }
     const totals = seats.totals === undefined ? undefined : yield* seats.totals
     const history = roster === undefined ? [] : yield* roster.history
     return {