@llm4ts/shell 2.38.0 → 2.40.0

package/flows/lib/epic-stories.js

@@ -38,7 +38,7 @@ import { budget } from "@llm4ts/flow/Context";
 import { makeLocalBoardSync } from "@llm4ts/flow/BoardSync";
 import { estimatedUsageOptionsFromEnv, makeEstimatedUsageMeter } from "@llm4ts/flow/EstimatedUsage";
 import { landEpic } from "@llm4ts/flow/Landing";
-import { implementStoriesFlow } from "@llm4ts/flow/Stories";
+import { deferredPath, implementStoriesFlow } from "@llm4ts/flow/Stories";
 import { validateStoryPlan } from "@llm4ts/flow/StoryPlan";
 import { asReadOnly, nodePlainFileStore, nodeProcessExecutor, resolveFlowInput, runNode, stage, withModel } from "@llm4ts/runner";
 import { claude, coderIds, judgmentConnectorFromEnvironment, pi } from "@llm4ts/runner/Connectors";
@@ -58,6 +58,15 @@ export const epicUsage = [
     "                      A plain rerun finishes an open round; --plan-only stops after planning",
     "  --concurrency <n>   stories implemented at once (default 3)",
     "  --fail-fast         stop the epic at the first failed story",
+    "  --judge-rounds <n>  judge attempts per story (default 2 = one revision); a story the judge",
+    "                      has not cleared after n attempts fails. LLM4TS_JUDGE_ROUNDS sets it too",
+    "  --merge-revisions <n> times a story whose merge turns the epic gates red goes back to",
+    "                      catch up and fix it before failing (default 1; 0 fails at once).",
+    "                      LLM4TS_MERGE_REVISIONS sets it too",
+    "  --defer-findings    lighter review: only Critical findings are fixed in place (reviews",
+    "                      settle, the judge clears without them); the rest are deferred and, once",
+    "                      every story is merged, planned and run as one refine round.",
+    "                      LLM4TS_DEFER_FINDINGS=1 sets it too",
     "Seats: LLM4TS_REASONER (claude|gemini|…, default claude) splits, reviews, judges;",
     "       LLM4TS_CODER (default pi) implements; LLM4TS_REASONING_MODEL / LLM4TS_CODER_MODEL",
     "       pick their models (pi: provider/model); LLM4TS_CODER_FLAGS / LLM4TS_REASONING_FLAGS",
@@ -75,6 +84,9 @@ export const parseEpicArgs = (argv) => Effect.gen(function* () {
     let planOnly = false;
     let failFast = false;
     let concurrency;
+    let judgeRounds;
+    let deferFindings = false;
+    let mergeRevisions;
     let land;
     let keepWorktrees = false;
     let list = false;
@@ -89,6 +101,9 @@ export const parseEpicArgs = (argv) => Effect.gen(function* () {
         else if (argument === "--fail-fast") {
             failFast = true;
         }
+        else if (argument === "--defer-findings") {
+            deferFindings = true;
+        }
         else if (argument === "--keep-worktrees") {
             keepWorktrees = true;
         }
@@ -131,12 +146,95 @@ export const parseEpicArgs = (argv) => Effect.gen(function* () {
             }
             concurrency = parsed;
         }
+        else if (argument === "--merge-revisions" || argument.startsWith("--merge-revisions=")) {
+            const raw = argument.includes("=")
+                ? argument.slice("--merge-revisions=".length)
+                : argv[index + 1];
+            if (!argument.includes("=")) {
+                index += 1;
+            }
+            const parsed = Number.parseInt(raw ?? "", 10);
+            if (!Number.isInteger(parsed) || parsed < 0 || String(parsed) !== (raw ?? "").trim()) {
+                return yield* ScriptUsage.make({
+                    message: `--merge-revisions requires a non-negative integer\n${epicUsage}`
+                });
+            }
+            mergeRevisions = parsed;
+        }
+        else if (argument === "--judge-rounds" || argument.startsWith("--judge-rounds=")) {
+            const raw = argument.includes("=")
+                ? argument.slice("--judge-rounds=".length)
+                : argv[index + 1];
+            if (!argument.includes("=")) {
+                index += 1;
+            }
+            const parsed = Number.parseInt(raw ?? "", 10);
+            if (!Number.isInteger(parsed) || parsed < 1) {
+                return yield* ScriptUsage.make({
+                    message: `--judge-rounds requires a positive integer\n${epicUsage}`
+                });
+            }
+            judgeRounds = parsed;
+        }
         else {
             rest.push(argument);
         }
     }
-    return { planOnly, failFast, concurrency, land, keepWorktrees, list, epic, refine, rest };
+    return {
+        planOnly,
+        failFast,
+        concurrency,
+        judgeRounds,
+        deferFindings,
+        mergeRevisions,
+        land,
+        keepWorktrees,
+        list,
+        epic,
+        refine,
+        rest
+    };
+});
+/**
+ * Merge revisions per story: `--merge-revisions`, else `LLM4TS_MERGE_REVISIONS`,
+ * else the executor's default. An unusable environment value falls back.
+ */
+export const mergeRevisionsOption = (flag, environment) => {
+    if (flag !== undefined) {
+        return { mergeRevisions: flag };
+    }
+    const raw = environment.LLM4TS_MERGE_REVISIONS?.trim() ?? "";
+    return /^\d+$/u.test(raw) ? { mergeRevisions: Number.parseInt(raw, 10) } : {};
+};
+/** `--defer-findings`, or `LLM4TS_DEFER_FINDINGS` set to 1/true/on/yes (ADR 0031). */
+export const deferFindingsEnabled = (flag, environment) => flag || /^(1|true|on|yes)$/i.test(environment.LLM4TS_DEFER_FINDINGS?.trim() ?? "");
+/**
+ * The feedback a follow-up round is planned from (ADR 0031): every story's
+ * deferred findings, in plan order. `undefined` when nothing was deferred.
+ */
+export const deferredFeedback = (files, stateDir, plan) => Effect.map(Effect.forEach(plan.stories, (story) => files.read(deferredPath(stateDir, story.id))), (texts) => {
+    const kept = texts.flatMap((text) => text === undefined || text.trim().length === 0 ? [] : [text.trim()]);
+    return kept.length === 0
+        ? undefined
+        : [
+            "Findings the review and the judge deferred while the epic's stories ran (non-blocking:",
+            "each story was merged with them open). Close the ones that still apply; a finding the",
+            "code already answers, or that would undo a deliberate choice, goes to not-planned.",
+            "",
+            ...kept.flatMap((text) => [text, ""])
+        ].join("\n");
 });
+/**
+ * Judge attempts per story: `--judge-rounds`, else `LLM4TS_JUDGE_ROUNDS`, else
+ * the flow's default. An unusable environment value falls back, never fails.
+ */
+export const judgeRoundsOption = (flag, environment) => {
+    if (flag !== undefined) {
+        return { judgeRounds: flag };
+    }
+    const raw = Number.parseInt(environment.LLM4TS_JUDGE_ROUNDS ?? "", 10);
+    return Number.isInteger(raw) && raw > 0 ? { judgeRounds: raw } : {};
+};
 export const roundDir = (stateDir, round) => join(stateDir, "rounds", String(round));
 const mergedStories = (files, stateDir, plan) => Effect.gen(function* () {
     let merged = 0;
@@ -861,12 +959,18 @@ export const storyDimensions = [
         rubric: "The story ships deterministic tests in the house style covering its screens or contract. 2 = yes; 1 = thin; 0 = none."
     })
 ];
+/**
+ * How much a dimension below the bar blocks (ADR 0031): `provides` short of
+ * full always does, since dependents build on it; any dimension at 0 does;
+ * a partial score elsewhere is a Warning a follow-up round can close.
+ */
+export const judgeSeverity = (name, score) => name === "provides" || score <= 0 ? "Critical" : "Warning";
 const subBar = (scored, story) => ReviewResult.make({
     issues: scored.scores
         .filter((score) => score.score <
         (storyDimensions.find((dimension) => dimension.name === score.name)?.maxScore ?? 2))
         .map((score) => ReviewIssue.make({
-        severity: "Critical",
+        severity: judgeSeverity(score.name, score.score),
         title: `judge[${story.id}]: ${score.name} scored ${score.score}`,
         description: score.reasoning
     })),
@@ -1484,6 +1588,7 @@ export const runEpicStories = (options) => Effect.gen(function* () {
             }));
             return;
         }
+        const deferring = deferFindingsEnabled(flags.deferFindings, process.env);
         // With a roster, the default is every coder slot it has; the flag caps it.
         const concurrency = flags.concurrency ?? context.roster?.slots("coder") ?? 3;
         if (context.roster === undefined && localServer !== undefined && concurrency > 1) {
@@ -1509,13 +1614,14 @@ export const runEpicStories = (options) => Effect.gen(function* () {
         const testCommand = testGateCommand(commands);
         const setupCommand = worktreeSetupCommand(process.env);
         const healthUrl = serverHealthUrl(localServer, process.env);
-        const report = yield* implementStoriesFlow({ ...context, reasoning: reasoningMeter.service }, {
-            plan: unit.plan,
+        // The executor over one unit: the epic's plan or one refine round.
+        const runUnit = (work) => implementStoriesFlow({ ...context, reasoning: reasoningMeter.service }, {
+            plan: work.plan,
             files,
-            stateDir: unit.stateDir,
+            stateDir: work.stateDir,
             epicBranch,
             worktreeRoot: worktreeRootFor(input.workDir, plan.epicId, process.env),
-            board: makeLocalBoardSync(files, unit.stateDir, unit.label),
+            board: makeLocalBoardSync(files, work.stateDir, work.label),
             contextFor: (workDir, contextOptions) => Effect.gen(function* () {
                 const rebound = yield* contextFor(workDir, contextOptions);
                 const coderMeter = yield* makeEstimatedUsageMeter(rebound.coder, estimateOptions);
@@ -1561,14 +1667,14 @@ export const runEpicStories = (options) => Effect.gen(function* () {
             // away from the executor coding it (ADR 0019).
             ...storyContextChars(process.env),
             judge: options.storyJudge({
-                plan: unit.plan,
+                plan: work.plan,
                 budget: contextBudget,
                 reasoning: reasoningMeter.service,
                 events,
                 files,
                 houseRules: guidance
             }),
-            verifyBlocked: (story, need, workDir, seats) => verifyBlockedOn(seats.context.roster?.forRole("verifier") ?? seats.context.reasoning, events, files, unit.plan)(story, need, workDir),
+            verifyBlocked: (story, need, workDir, seats) => verifyBlockedOn(seats.context.roster?.forRole("verifier") ?? seats.context.reasoning, events, files, work.plan)(story, need, workDir),
             // A roster waits for its own executors (the story's next lease
             // does); without one, poll the single coder's engine.
             awaitRecovery: context.roster === undefined
@@ -1582,16 +1688,87 @@ export const runEpicStories = (options) => Effect.gen(function* () {
                 ...appDirNote,
                 ...(orientation === undefined ? [] : ["", orientation])
             ].join("\n")),
+            ...judgeRoundsOption(flags.judgeRounds, process.env),
+            ...mergeRevisionsOption(flags.mergeRevisions, process.env),
             concurrency,
+            ...(deferring ? { deferNonBlocking: true } : {}),
             failFast: flags.failFast
         });
-        yield* events.publish(Info.make({
-            message: `${unit.label.replace("Epic: ", "epic ")}: ${report.count("done")} done, ${report.count("failed")} failed, ${report.count("waiting")} waiting — report at ${join(unit.stateDir, "report.md")} (usage figures estimated)`
+        const summarize = (work, report) => events.publish(Info.make({
+            message: `${work.label.replace("Epic: ", "epic ")}: ${report.count("done")} done, ${report.count("failed")} failed, ${report.count("waiting")} waiting — report at ${join(work.stateDir, "report.md")} (usage figures estimated)`
         }));
+        const report = yield* runUnit(unit);
+        yield* summarize(unit, report);
         const hint = retroHint(report, input.workDir, epicId);
         if (hint !== undefined) {
             yield* events.publish(Info.make({ message: hint }));
         }
+        if (!deferring) {
+            return;
+        }
+        // Deferred findings (ADR 0031) become one refine round once the
+        // epic's own stories are all merged. A round's own deferrals are
+        // listed, never planned again, so the follow-up cannot loop.
+        const feedbackText = yield* deferredFeedback(files, unit.stateDir, unit.plan);
+        if (feedbackText === undefined) {
+            return;
+        }
+        const settledPlan = report.count("failed") === 0 && report.count("waiting") === 0;
+        if (unit.stateDir !== stateDir || !settledPlan) {
+            yield* events.publish(Info.make({
+                message: `${unit.label.replace("Epic: ", "epic ")}: findings deferred in ${join(unit.stateDir, "stories")}/*.deferred.md${unit.stateDir === stateDir
+                    ? "; they become a refine round once every story is merged"
+                    : "; pass them to --refine if they still matter"}`
+            }));
+            return;
+        }
+        const stray = statusPaths(yield* context.git.status);
+        if (stray.length > 0) {
+            yield* events.publish(Info.make({
+                message: `deferred findings not planned: the epic checkout has uncommitted changes (${stray.join(", ")}); commit or discard them, then pass ${join(stateDir, "stories")}/*.deferred.md to --refine`
+            }));
+            return;
+        }
+        yield* stage(events, "epic branch", context.git.checkoutOrCreate(epicBranch));
+        const followUp = rounds.length + 1;
+        const roundBrief = yield* files.read(join(stateDir, "brief.md"));
+        const planned = yield* stage(events, `refine round ${followUp} plan (deferred findings)`, planRound({
+            files,
+            reasoning: reasoningMeter.service,
+            events,
+            stateDir,
+            epicId: plan.epicId,
+            round: followUp,
+            feedback: feedbackText,
+            guidance,
+            plans: [unit.plan],
+            ...(roundBrief === undefined ? {} : { brief: roundBrief }),
+            ...(orientation === undefined ? {} : { orientation }),
+            git: context.git
+        }));
+        for (const left of planned.notPlanned) {
+            yield* events.publish(Info.make({ message: `not planned: ${left.item} — ${left.reason}` }));
+        }
+        if (planned.plan === undefined) {
+            yield* events.publish(Info.make({
+                message: `refine round ${followUp}: no deferred finding needed a story; nothing to run`
+            }));
+            return;
+        }
+        const roundUnit = {
+            plan: planned.plan,
+            stateDir: roundDir(stateDir, followUp),
+            label: `Epic: ${plan.epicId} · round ${followUp}`
+        };
+        yield* events.publish(Info.make({
+            message: `refine round ${followUp}: ${planned.plan.stories.length} follow-up stories from deferred findings at ${join(roundUnit.stateDir, "plan.md")}`
+        }));
+        const roundReport = yield* runUnit(roundUnit);
+        yield* summarize(roundUnit, roundReport);
+        const roundHint = retroHint(roundReport, input.workDir, epicId);
+        if (roundHint !== undefined) {
+            yield* events.publish(Info.make({ message: roundHint }));
+        }
     }));
 });
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llm4ts/shell",
-  "version": "2.38.0",
+  "version": "2.40.0",
   "description": "Interactive shell and CLI for llm4ts: flow discovery, run-a-flow, and view",
   "license": "MIT",
   "type": "module",
@@ -52,9 +52,9 @@
   "dependencies": {
     "@effect/platform-node": "4.0.0",
     "@effect/platform-node-shared": "4.0.0",
-    "@llm4ts/core": "2.38.0",
-    "@llm4ts/runner": "2.38.0",
-    "@llm4ts/flow": "2.38.0"
+    "@llm4ts/core": "2.40.0",
+    "@llm4ts/flow": "2.40.0",
+    "@llm4ts/runner": "2.40.0"
   },
   "peerDependencies": {
     "effect": "4.0.0"