@llm4ts/shell 2.14.0 → 2.16.0

package/flows/epic-stories-board.js

@@ -0,0 +1,18 @@
+// A fork of epic-stories that judges each story with a blackboard ruleset (ADR 0020): the four story dimensions are scored by the Judgment service, decided by the run's judgment policy, and a company-editable bar in flows/lib/story-board.ts says whether the story merges. Same flags and environment as epic-stories.
+//
+//   llm4ts run epic-stories-board --repo ~/demo/portal "Add the current account and wire transfers"
+//   llm4ts run epic-stories-board --repo ~/demo/portal -- --plan-only "…"
+//
+// The judgment seat is LLM4TS_JUDGMENT_PROVIDER / LLM4TS_JUDGMENT_MODEL (ADR
+// 0017), or one derived from the reasoning seat. Each round's run lands in
+// the trace as a BlackboardRun event and each answer in
+// .llm4ts/judgments/story-board.jsonl. Until this judge is approved,
+// epic-stories keeps the rubric judge.
+import { runFlowMain } from "@llm4ts/runner";
+import { runEpicStories } from "./lib/epic-stories.js";
+import { boardJudgeFactory } from "./lib/story-board.js";
+runFlowMain(runEpicStories({
+    storyJudge: boardJudgeFactory,
+    judgmentFromEnvironment: true,
+    judgmentLog: true
+}));

package/flows/epic-stories.js

@@ -18,182 +18,6 @@
 // (--fail-fast stops instead). The epic branch is left in place; the board
 // and the report under .llm4ts/epics/<epic-id>/ carry ESTIMATED usage
 // figures (ADR 0013).
-import { join } from "node:path";
-import * as Effect from "effect/Effect";
-import { CliConnectorConfig } from "@llm4ts/core/ConnectorConfig";
-import { budget, cap } from "@llm4ts/flow/Context";
-import { makeLocalBoardSync } from "@llm4ts/flow/BoardSync";
-import { estimatedUsageOptionsFromEnv, makeEstimatedUsageMeter } from "@llm4ts/flow/EstimatedUsage";
-import { FlowAborted, Info, asReadOnly, nodePlainFileStore, nodeProcessExecutor, resolveFlowInput, runFlowMain, runNode, stage, withModel } from "@llm4ts/runner";
-import { landEpic } from "@llm4ts/flow/Landing";
-import { implementStoriesFlow } from "@llm4ts/flow/Stories";
-import { makeStoryPlanStore, validateStoryPlan } from "@llm4ts/flow/StoryPlan";
-import * as Console from "effect/Console";
-import { awaitServer, chooseEpic, epicsDir, listEpics, renderEpicList, combineTotals, epicIdFor, flagsFromEnvironment, appDirFor, appScripts, gateCommands, gatesIn, inAppDir, generateStoryPlan, httpProbe, judgeStory, localCoderServer, parseEpicArgs, reasonerFromEnvironment, serverHealthUrl, setupAgentEnabled, setupIn, storyCoderFromEnvironment, verifyBlockedOn, worktreeRootFor, worktreeSetupCommand } from "./lib/epic-stories.js";
-/** `LLM4TS_CODER_MODEL` / `LLM4TS_REASONING_MODEL`: pi takes `provider/model` (e.g. `openai-codex/gpt-5.5`). */
-const withOptionalModel = (config, model) => {
-    const trimmed = model?.trim();
-    return trimmed === undefined || trimmed.length === 0 ? config : withModel(config, trimmed);
-};
-/** Extra CLI flags on top of a preset's own (`LLM4TS_CODER_FLAGS`). */
-const withExtraFlags = (config, flags) => Object.keys(flags).length === 0
-    ? config
-    : CliConnectorConfig.make({ ...config, flags: { ...config.flags, ...flags } });
-const defaultEpic = "Add the retail customer's current account (Conto) with balance and movements, and wire " +
-    "transfers (Bonifico) with beneficiary, review, SCA confirmation, and history.";
-const program = Effect.gen(function* () {
-    const flags = yield* parseEpicArgs(process.argv.slice(2));
-    // The epic is chosen before any seat is resolved: the text given, `--epic`,
-    // or the one epic not landed yet (`chooseEpic`); `--list` only lists.
-    const given = yield* resolveFlowInput("", flags.rest);
-    const files = nodePlainFileStore;
-    const epics = yield* listEpics(files, given.workDir);
-    if (flags.list) {
-        yield* Console.log(renderEpicList(epics));
-        return;
-    }
-    const choice = yield* chooseEpic({
-        text: given.prompt,
-        epic: flags.epic,
-        epics,
-        defaultEpic
-    });
-    const input = {
-        ...given,
-        prompt: choice._tag === "Existing" ? choice.epic.epic : choice.prompt
-    };
-    const coderFlags = flagsFromEnvironment(process.env.LLM4TS_CODER_FLAGS);
-    const reasoning = withExtraFlags(withOptionalModel(yield* reasonerFromEnvironment(process.env), process.env.LLM4TS_REASONING_MODEL), flagsFromEnvironment(process.env.LLM4TS_REASONING_FLAGS));
-    const coder = withExtraFlags(withOptionalModel(yield* storyCoderFromEnvironment(process.env), process.env.LLM4TS_CODER_MODEL), coderFlags);
-    const localServer = localCoderServer(process.env.LLM4TS_CODER_MODEL, coderFlags, process.env);
-    // A new epic's id (and state folder) is derived from its text; an existing
-    // one keeps its folder, whatever text is on the command line.
-    const epicId = choice._tag === "Existing" ? choice.epic.dir : epicIdFor(input.prompt);
-    const stateDir = join(epicsDir(input.workDir), epicId);
-    const planPath = join(stateDir, "plan.md");
-    const estimateOptions = estimatedUsageOptionsFromEnv(process.env);
-    const contextBudget = budget(process.env);
-    yield* runNode({
-        workDir: input.workDir,
-        workspace: input.workspace,
-        userPrompt: input.prompt,
-        coder,
-        reasoning,
-        reviewers: [asReadOnly(reasoning)],
-        environment: process.env
-    }, (context) => Effect.gen(function* () {
-        const events = context.events;
-        const reasoningMeter = yield* makeEstimatedUsageMeter(context.reasoning, estimateOptions);
-        const guidance = yield* Effect.map(files.read(join(input.workDir, "CONTRIBUTING.md")), (text) => cap(text ?? "(no CONTRIBUTING.md in the target repository)", 24_000).text);
-        const store = makeStoryPlanStore(files);
-        const plan = yield* stage(events, "story plan", store
-            .recoverOrCreate(planPath, generateStoryPlan(reasoningMeter.service, events, input.prompt, epicId, guidance))
-            .pipe(Effect.flatMap(validateStoryPlan)));
-        yield* events.publish(Info.make({
-            message: `story plan: ${plan.stories.length} stories at ${planPath} (edit and rerun to re-plan)`
-        }));
-        if (flags.planOnly) {
-            return;
-        }
-        // Setup and gates run where the application is, in every checkout.
-        const appDir = yield* appDirFor(input.workDir, process.env);
-        if (appDir !== ".") {
-            yield* events.publish(Info.make({ message: `app dir: ${appDir} (setup and gates run there; LLM4TS_APP_DIR)` }));
-        }
-        const commands = gateCommands(process.env, yield* appScripts(files, join(input.workDir, appDir)));
-        yield* events.publish(Info.make({
-            message: commands.length === 0
-                ? "gates: none (the app defines none of typecheck, lint, test, build; set LLM4TS_GATES)"
-                : `gates: ${commands.map((command) => command.join(" ")).join(" · ")}`
-        }));
-        if (flags.land !== undefined) {
-            const landed = yield* landEpic(context, {
-                plan,
-                files,
-                stateDir,
-                target: flags.land,
-                keepWorktrees: flags.keepWorktrees,
-                gates: inAppDir(appDir, gatesIn(nodeProcessExecutor, events, commands)),
-                system: ["House rules of the target repository (CONTRIBUTING.md):", guidance].join("\n")
-            });
-            yield* events.publish(Info.make({
-                message: `epic ${plan.epicId}: landed on ${landed.target}${landed.conflicts.length === 0 ? "" : ` (${landed.conflicts.length} conflicted file(s) resolved in ${landed.rounds} round(s))`}`
-            }));
-            return;
-        }
-        // 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) {
-            yield* events.publish(Info.make({
-                message: `⚠ the coder is served by a local single-model server (${localServer}): it generates one ` +
-                    `reply at a time, so ${concurrency} parallel coders queue behind each other and a queued ` +
-                    'request is cut off after a few minutes ("terminated"). Prefer --concurrency 1, or give ' +
-                    "the server parallel slots."
-            }));
-        }
-        const contextFor = context.contextFor;
-        if (contextFor === undefined) {
-            return yield* FlowAborted.make({
-                message: "this runner cannot rebind seats to a worktree (no contextFor)"
-            });
-        }
-        const appDirNote = appDir === "."
-            ? []
-            : [
-                `The application lives in ${appDir}/ — its package.json, sources and tests; the gates run there.`
-            ];
-        const gates = inAppDir(appDir, gatesIn(nodeProcessExecutor, events, commands));
-        const setupCommand = worktreeSetupCommand(process.env);
-        const healthUrl = serverHealthUrl(localServer, process.env);
-        const report = yield* implementStoriesFlow({ ...context, reasoning: reasoningMeter.service }, {
-            plan,
-            files,
-            stateDir,
-            worktreeRoot: worktreeRootFor(input.workDir, plan.epicId, process.env),
-            board: makeLocalBoardSync(files, stateDir, `Epic: ${plan.epicId}`),
-            contextFor: (workDir, contextOptions) => Effect.gen(function* () {
-                const rebound = yield* contextFor(workDir, contextOptions);
-                const coderMeter = yield* makeEstimatedUsageMeter(rebound.coder, estimateOptions);
-                const reviewMeter = yield* makeEstimatedUsageMeter(rebound.reasoning, estimateOptions);
-                const seats = {
-                    context: {
-                        ...rebound,
-                        coder: coderMeter.service,
-                        reasoning: reviewMeter.service
-                    },
-                    totals: combineTotals(coderMeter.totals, reviewMeter.totals)
-                };
-                return seats;
-            }),
-            ...(setupCommand === undefined
-                ? {}
-                : {
-                    setup: inAppDir(appDir, setupIn(nodeProcessExecutor, events, setupCommand)),
-                    setupAgent: setupAgentEnabled(process.env)
-                }),
-            gates,
-            // With a roster, the judge and the verifier are leased per story,
-            // away from the executor coding it (ADR 0019).
-            judge: (story, diff, seats) => judgeStory(seats.context.roster?.forRole("judge") ?? reasoningMeter.service, story, diff, contextBudget, plan),
-            verifyBlocked: (story, need, workDir, seats) => verifyBlockedOn(seats.context.roster?.forRole("verifier") ?? reasoningMeter.service, events, files, 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
-                ? awaitServer(healthUrl === undefined ? undefined : httpProbe(healthUrl), events)
-                : () => Effect.void,
-            system: (story) => Effect.succeed([
-                "House rules of the target repository (CONTRIBUTING.md):",
-                guidance,
-                "",
-                `Imitate the exemplar feature before inventing anything. Story id: ${story.id}.`,
-                ...appDirNote
-            ].join("\n")),
-            concurrency,
-            failFast: flags.failFast
-        });
-        yield* events.publish(Info.make({
-            message: `epic ${report.epicId}: ${report.count("done")} done, ${report.count("failed")} failed, ${report.count("waiting")} waiting — report at ${join(stateDir, "report.md")} (usage figures estimated)`
-        }));
-    }));
-});
-runFlowMain(program);
+import { runFlowMain } from "@llm4ts/runner";
+import { rubricStoryJudge, runEpicStories } from "./lib/epic-stories.js";
+runFlowMain(runEpicStories({ storyJudge: rubricStoryJudge }));

package/flows/lib/epic-stories.js

@@ -18,7 +18,16 @@ import { BlockedVerdict, StoryState, StoryStateVersion } from "@llm4ts/flow/Stor
 import { stableHash } from "@llm4ts/flow/Plan";
 import { ReviewIssue } from "@llm4ts/flow/Review";
 import { StoryPlan, dependenciesOf, makeStoryPlanStore, pathsNamedIn } from "@llm4ts/flow/StoryPlan";
-import { claude, coderIds, pi } from "@llm4ts/runner/Connectors";
+import * as Console from "effect/Console";
+import { CliConnectorConfig } from "@llm4ts/core/ConnectorConfig";
+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 { 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";
 import { FlowAborted, FlowLlmError, ReviewResult, ScriptUsage, coderFor, lintCommand, mergeReviewResults } from "@llm4ts/runner";
 export const epicUsage = [
     "epic-stories flags:",
@@ -307,7 +316,8 @@ export const serverHealthUrl = (server, environment) => {
     }
 };
 /** Whether `url` answers 2xx within five seconds (the roster's health check). */
-export { httpProbe } from "@llm4ts/runner/ExecutorRoster";
+import { httpProbe } from "@llm4ts/runner/ExecutorRoster";
+export { httpProbe };
 export const defaultRecoveryTiming = {
     interval: "15 seconds",
     attempts: 60,
@@ -671,3 +681,192 @@ export const gatesIn = (process, events, commands) => (workDir) => Effect.gen(fu
     }
     return mergeReviewResults(results);
 });
+/** Today's story judge: the rubric judge over the four dimensions. */
+export const rubricStoryJudge = (context) => (story, diff, seats) => judgeStory(seats.context.roster?.forRole("judge") ?? context.reasoning, story, diff, context.budget, context.plan);
+/** The runner options the two flags above add; empty when neither is set. */
+export const epicRunnerOptions = Effect.fn("epic-stories.runnerOptions")(function* (options, environment) {
+    const judgment = options.judgmentFromEnvironment === true
+        ? yield* judgmentConnectorFromEnvironment(environment)
+        : undefined;
+    return {
+        ...(judgment === undefined ? {} : { judgment }),
+        ...(options.judgmentLog === true ? { judgmentLog: true } : {})
+    };
+});
+/** `LLM4TS_CODER_MODEL` / `LLM4TS_REASONING_MODEL`: pi takes `provider/model` (e.g. `openai-codex/gpt-5.5`). */
+const withOptionalModel = (config, model) => {
+    const trimmed = model?.trim();
+    return trimmed === undefined || trimmed.length === 0 ? config : withModel(config, trimmed);
+};
+/** Extra CLI flags on top of a preset's own (`LLM4TS_CODER_FLAGS`). */
+const withExtraFlags = (config, flags) => Object.keys(flags).length === 0
+    ? config
+    : CliConnectorConfig.make({ ...config, flags: { ...config.flags, ...flags } });
+const defaultEpic = "Add the retail customer's current account (Conto) with balance and movements, and wire " +
+    "transfers (Bonifico) with beneficiary, review, SCA confirmation, and history.";
+export const runEpicStories = (options) => Effect.gen(function* () {
+    const flags = yield* parseEpicArgs(process.argv.slice(2));
+    // The epic is chosen before any seat is resolved: the text given, `--epic`,
+    // or the one epic not landed yet (`chooseEpic`); `--list` only lists.
+    const given = yield* resolveFlowInput("", flags.rest);
+    const files = nodePlainFileStore;
+    const epics = yield* listEpics(files, given.workDir);
+    if (flags.list) {
+        yield* Console.log(renderEpicList(epics));
+        return;
+    }
+    const choice = yield* chooseEpic({
+        text: given.prompt,
+        epic: flags.epic,
+        epics,
+        defaultEpic
+    });
+    const input = {
+        ...given,
+        prompt: choice._tag === "Existing" ? choice.epic.epic : choice.prompt
+    };
+    const coderFlags = flagsFromEnvironment(process.env.LLM4TS_CODER_FLAGS);
+    const reasoning = withExtraFlags(withOptionalModel(yield* reasonerFromEnvironment(process.env), process.env.LLM4TS_REASONING_MODEL), flagsFromEnvironment(process.env.LLM4TS_REASONING_FLAGS));
+    const coder = withExtraFlags(withOptionalModel(yield* storyCoderFromEnvironment(process.env), process.env.LLM4TS_CODER_MODEL), coderFlags);
+    const localServer = localCoderServer(process.env.LLM4TS_CODER_MODEL, coderFlags, process.env);
+    // A new epic's id (and state folder) is derived from its text; an existing
+    // one keeps its folder, whatever text is on the command line.
+    const epicId = choice._tag === "Existing" ? choice.epic.dir : epicIdFor(input.prompt);
+    const stateDir = join(epicsDir(input.workDir), epicId);
+    const planPath = join(stateDir, "plan.md");
+    const estimateOptions = estimatedUsageOptionsFromEnv(process.env);
+    const contextBudget = budget(process.env);
+    const runnerOptions = yield* epicRunnerOptions(options, process.env);
+    yield* runNode({
+        workDir: input.workDir,
+        workspace: input.workspace,
+        userPrompt: input.prompt,
+        coder,
+        reasoning,
+        reviewers: [asReadOnly(reasoning)],
+        environment: process.env,
+        ...runnerOptions
+    }, (context) => Effect.gen(function* () {
+        const events = context.events;
+        const reasoningMeter = yield* makeEstimatedUsageMeter(context.reasoning, estimateOptions);
+        const guidance = yield* Effect.map(files.read(join(input.workDir, "CONTRIBUTING.md")), (text) => cap(text ?? "(no CONTRIBUTING.md in the target repository)", 24_000).text);
+        const store = makeStoryPlanStore(files);
+        const plan = yield* stage(events, "story plan", store
+            .recoverOrCreate(planPath, generateStoryPlan(reasoningMeter.service, events, input.prompt, epicId, guidance))
+            .pipe(Effect.flatMap(validateStoryPlan)));
+        yield* events.publish(Info.make({
+            message: `story plan: ${plan.stories.length} stories at ${planPath} (edit and rerun to re-plan)`
+        }));
+        if (flags.planOnly) {
+            return;
+        }
+        // Setup and gates run where the application is, in every checkout.
+        const appDir = yield* appDirFor(input.workDir, process.env);
+        if (appDir !== ".") {
+            yield* events.publish(Info.make({
+                message: `app dir: ${appDir} (setup and gates run there; LLM4TS_APP_DIR)`
+            }));
+        }
+        const commands = gateCommands(process.env, yield* appScripts(files, join(input.workDir, appDir)));
+        yield* events.publish(Info.make({
+            message: commands.length === 0
+                ? "gates: none (the app defines none of typecheck, lint, test, build; set LLM4TS_GATES)"
+                : `gates: ${commands.map((command) => command.join(" ")).join(" · ")}`
+        }));
+        if (flags.land !== undefined) {
+            const landed = yield* landEpic(context, {
+                plan,
+                files,
+                stateDir,
+                target: flags.land,
+                keepWorktrees: flags.keepWorktrees,
+                gates: inAppDir(appDir, gatesIn(nodeProcessExecutor, events, commands)),
+                system: ["House rules of the target repository (CONTRIBUTING.md):", guidance].join("\n")
+            });
+            yield* events.publish(Info.make({
+                message: `epic ${plan.epicId}: landed on ${landed.target}${landed.conflicts.length === 0 ? "" : ` (${landed.conflicts.length} conflicted file(s) resolved in ${landed.rounds} round(s))`}`
+            }));
+            return;
+        }
+        // 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) {
+            yield* events.publish(Info.make({
+                message: `⚠ the coder is served by a local single-model server (${localServer}): it generates one ` +
+                    `reply at a time, so ${concurrency} parallel coders queue behind each other and a queued ` +
+                    'request is cut off after a few minutes ("terminated"). Prefer --concurrency 1, or give ' +
+                    "the server parallel slots."
+            }));
+        }
+        const contextFor = context.contextFor;
+        if (contextFor === undefined) {
+            return yield* FlowAborted.make({
+                message: "this runner cannot rebind seats to a worktree (no contextFor)"
+            });
+        }
+        const appDirNote = appDir === "."
+            ? []
+            : [
+                `The application lives in ${appDir}/ — its package.json, sources and tests; the gates run there.`
+            ];
+        const gates = inAppDir(appDir, gatesIn(nodeProcessExecutor, events, commands));
+        const setupCommand = worktreeSetupCommand(process.env);
+        const healthUrl = serverHealthUrl(localServer, process.env);
+        const report = yield* implementStoriesFlow({ ...context, reasoning: reasoningMeter.service }, {
+            plan,
+            files,
+            stateDir,
+            worktreeRoot: worktreeRootFor(input.workDir, plan.epicId, process.env),
+            board: makeLocalBoardSync(files, stateDir, `Epic: ${plan.epicId}`),
+            contextFor: (workDir, contextOptions) => Effect.gen(function* () {
+                const rebound = yield* contextFor(workDir, contextOptions);
+                const coderMeter = yield* makeEstimatedUsageMeter(rebound.coder, estimateOptions);
+                const reviewMeter = yield* makeEstimatedUsageMeter(rebound.reasoning, estimateOptions);
+                const seats = {
+                    context: {
+                        ...rebound,
+                        coder: coderMeter.service,
+                        reasoning: reviewMeter.service
+                    },
+                    totals: combineTotals(coderMeter.totals, reviewMeter.totals)
+                };
+                return seats;
+            }),
+            ...(setupCommand === undefined
+                ? {}
+                : {
+                    setup: inAppDir(appDir, setupIn(nodeProcessExecutor, events, setupCommand)),
+                    setupAgent: setupAgentEnabled(process.env)
+                }),
+            gates,
+            // With a roster, the judge and the verifier are leased per story,
+            // away from the executor coding it (ADR 0019).
+            judge: options.storyJudge({
+                plan,
+                budget: contextBudget,
+                reasoning: reasoningMeter.service,
+                events,
+                files,
+                houseRules: guidance
+            }),
+            verifyBlocked: (story, need, workDir, seats) => verifyBlockedOn(seats.context.roster?.forRole("verifier") ?? reasoningMeter.service, events, files, 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
+                ? awaitServer(healthUrl === undefined ? undefined : httpProbe(healthUrl), events)
+                : () => Effect.void,
+            system: (story) => Effect.succeed([
+                "House rules of the target repository (CONTRIBUTING.md):",
+                guidance,
+                "",
+                `Imitate the exemplar feature before inventing anything. Story id: ${story.id}.`,
+                ...appDirNote
+            ].join("\n")),
+            concurrency,
+            failFast: flags.failFast
+        });
+        yield* events.publish(Info.make({
+            message: `epic ${report.epicId}: ${report.count("done")} done, ${report.count("failed")} failed, ${report.count("waiting")} waiting — report at ${join(stateDir, "report.md")} (usage figures estimated)`
+        }));
+    }));
+});

package/flows/lib/story-board.js

@@ -0,0 +1,232 @@
+// The per-story "mergeable" decision as a blackboard ruleset (ADR 0020):
+// a judge rule scores the four story dimensions with the Judgment service,
+// decideRule turns each answer into act|caution|hold, and `bar` — the rule a
+// company edits — posts whether the story may merge and the issues the coder
+// gets back. Plugged into implementStoriesFlow's judge seam by boardStoryJudge.
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Schema from "effect/Schema";
+import { makeKey } from "@llm4ts/core/blackboard/Fact";
+import { all, derive, judge } from "@llm4ts/core/blackboard/Rule";
+import { runRuleset } from "@llm4ts/core/blackboard/Run";
+import { makeRuleset } from "@llm4ts/core/blackboard/Ruleset";
+import { ProviderError } from "@llm4ts/core/Errors";
+import { dimensionQuestion } from "@llm4ts/core/eval/Judge";
+import { Judgment } from "@llm4ts/core/judgment/Judgment";
+import { answerKey, decideRule, decisionKey, publishBlackboardRun, runErrorToFlowError } from "@llm4ts/flow/Blackboard";
+import { cap } from "@llm4ts/flow/Context";
+import { FlowLlmError } from "@llm4ts/flow/FlowError";
+import { JudgmentObserved, publishJudgmentObserved } from "@llm4ts/flow/FlowEvents";
+import { certaintyOf, decide, judgmentOf } from "@llm4ts/flow/Judgment";
+import { ReviewIssue, ReviewResult } from "@llm4ts/flow/Review";
+import { dependenciesOf } from "@llm4ts/flow/StoryPlan";
+import { storyDimensions } from "./epic-stories.js";
+export class StoryBrief extends Schema.Class("StoryBrief")({
+    id: Schema.String,
+    title: Schema.String,
+    description: Schema.String,
+    provides: Schema.Array(Schema.String),
+    owned: Schema.Array(Schema.String),
+    sharedReadOnly: Schema.Array(Schema.String),
+    dependencies: Schema.Array(Schema.Struct({ id: Schema.String, provides: Schema.Array(Schema.String) }))
+}) {
+}
+export const storyBriefOf = (story, plan) => StoryBrief.make({
+    id: story.id,
+    title: story.title,
+    description: story.description,
+    provides: story.provides,
+    owned: story.owned,
+    sharedReadOnly: story.sharedReadOnly,
+    dependencies: plan === undefined
+        ? []
+        : dependenciesOf(plan, story.id).flatMap((id) => {
+            const dependency = plan.story(id);
+            return dependency === undefined ? [] : [{ id, provides: dependency.provides }];
+        })
+});
+// ---- Facts ------------------------------------------------------------------
+export const storyBrief = makeKey("story.brief", StoryBrief);
+export const storyDiff = makeKey("story.diff", Schema.String);
+export const houseRules = makeKey("story.houseRules", Schema.String);
+export const mergeable = makeKey("story.mergeable", Schema.Boolean);
+export const issues = makeKey("story.issues", Schema.Array(ReviewIssue));
+/** One judged answer and one decision per story dimension, keyed by the dimension's name. */
+const judged = (name) => answerKey(`judge.${name}`);
+const decided = (name) => decisionKey(`decision.${name}`);
+const [provides, scope, houseStyle, tests] = storyDimensions.map((dimension) => ({
+    dimension,
+    answer: judged(dimension.name),
+    decision: decided(dimension.name)
+}));
+if (provides === undefined ||
+    scope === undefined ||
+    houseStyle === undefined ||
+    tests === undefined) {
+    throw new Error("story board: storyDimensions must have four entries");
+}
+const dimensions = [provides, scope, houseStyle, tests];
+export const dimensionNames = dimensions.map((d) => d.dimension.name);
+/** Expected level (of 2) a dimension must reach; the company's bar. */
+export const passingScore = 1.5;
+/** The State the judge reads: the same words as the rubric judge, brief then diff. */
+export const stateOf = (brief, diff, rules) => [
+    `Story: ${brief.title}`,
+    brief.description,
+    "",
+    `Provides: ${brief.provides.join(", ") || "(none)"}`,
+    `Owned paths: ${brief.owned.join(", ")}`,
+    `Shared read-only: ${brief.sharedReadOnly.join(", ") || "(none)"}`,
+    ...(brief.dependencies.length === 0
+        ? []
+        : [
+            "",
+            "Already merged, from the stories this one depends on (their declared interface):",
+            ...brief.dependencies.map((d) => `- ${d.id}: ${d.provides.join("; ") || "(nothing declared)"}`),
+            "Using these exactly as declared (the same module, the same export) is correct and is",
+            "never a house-style or scope problem, even where the module is a fake transport."
+        ]),
+    "",
+    "House rules:",
+    rules,
+    "",
+    "Diff:",
+    diff
+].join("\n");
+const levelDescription = (answer) => {
+    const rounded = String(Math.max(0, Math.min(2, Math.round(answer.score))));
+    const legend = answer.legend[rounded];
+    return typeof legend === "string" ? legend : JSON.stringify(legend ?? "");
+};
+// ---- The ruleset ------------------------------------------------------------
+export const makeStoryBoard = (policy) => {
+    const storyJudge = judge({
+        name: "story-judge",
+        condition: all(storyBrief, storyDiff, houseRules),
+        produces: dimensions.map((d) => d.answer),
+        ask: ([brief, diff, rules]) => ({
+            state: stateOf(brief, diff, rules),
+            questions: Object.fromEntries(dimensions.map((d) => [d.dimension.name, dimensionQuestion(d.dimension)]))
+        }),
+        post: (result) => dimensions.flatMap((d) => {
+            const answer = result.answers[d.dimension.name];
+            return answer?.type === "score" ? [d.answer.of(answer)] : [];
+        })
+    });
+    const decisions = dimensions.map((d) => decideRule({
+        name: `decide-${d.dimension.name}`,
+        answer: d.answer,
+        decision: d.decision,
+        ...(policy === undefined ? {} : { policy })
+    }));
+    const bar = derive({
+        name: "bar",
+        condition: all(provides.answer, scope.answer, houseStyle.answer, tests.answer, provides.decision, scope.decision, houseStyle.decision, tests.decision),
+        produces: [mergeable, issues],
+        derive: ([a1, a2, a3, a4, v1, v2, v3, v4]) => {
+            const found = [];
+            const answers = [a1, a2, a3, a4];
+            const verdicts = [v1, v2, v3, v4];
+            dimensions.forEach((d, index) => {
+                const answer = answers[index];
+                const verdict = verdicts[index];
+                if (answer === undefined || verdict === undefined || answer.type !== "score")
+                    return;
+                if (answer.score < passingScore) {
+                    found.push(ReviewIssue.make({
+                        severity: "Critical",
+                        title: `${d.dimension.name} scored ${answer.score.toFixed(1)}`,
+                        description: levelDescription(answer)
+                    }));
+                }
+                else if (verdict !== "act") {
+                    found.push(ReviewIssue.make({
+                        severity: "Critical",
+                        title: `unsure about ${d.dimension.name}`,
+                        description: `the judge's ${verdict} decision (certainty ${certaintyOf(answer).toFixed(2)}, support ${answer.support.toFixed(2)}) is below the bar for acting on it`
+                    }));
+                }
+            });
+            return [mergeable.of(found.length === 0), issues.of(found)];
+        }
+    });
+    return makeRuleset({
+        name: "story-board",
+        imports: [storyBrief, storyDiff, houseRules],
+        exports: [mergeable, issues],
+        rules: [storyJudge, ...decisions, bar]
+    });
+};
+/**
+ * The round's error when the bar never fired: which dimensions went unscored
+ * and, when the backend itself failed, its message — the story loop reads an
+ * outage off that message and waits for recovery instead of failing the story.
+ */
+const unscored = (story, error) => {
+    const names = [
+        ...new Set(error.missing
+            .flatMap((m) => m.waitingRules.flatMap((w) => w.missingKeys))
+            .filter((key) => key.startsWith("judge."))
+            .map((key) => key.slice("judge.".length)))
+    ];
+    const because = error.failures.map((failure) => `${failure.tag}: ${failure.message}`);
+    return FlowLlmError.from(ProviderError.make({
+        message: `story-board: the judge could not score ${names.join(", ")} for ${story}${because.length === 0 ? "" : ` (${because.join("; ")})`}`
+    }));
+};
+/** The seam implementation: the ruleset built once, run per judge round. */
+export const boardStoryJudge = (context) => Effect.map(makeStoryBoard(context.policy).pipe(Effect.mapError(runErrorToFlowError)), (board) => (story, diff, seats) => Effect.gen(function* () {
+    const judgment = seats.context.judgment ?? context.judgment;
+    const brief = storyBriefOf(story, context.plan);
+    const capped = cap(diff, context.budget).text;
+    const result = yield* runRuleset(board, [
+        storyBrief.of(brief),
+        storyDiff.of(capped),
+        houseRules.of(context.houseRules)
+    ]).pipe(Effect.provide(Layer.succeed(Judgment, judgment)), Effect.mapError((error) => error._tag === "ExportsMissing"
+        ? unscored(story.id, error)
+        : runErrorToFlowError(error)));
+    yield* publishBlackboardRun(context.events, "story-board", result);
+    const isMergeable = yield* result.board.get(mergeable).pipe(Effect.orDie);
+    const found = yield* result.board.get(issues).pipe(Effect.orDie);
+    const state = stateOf(brief, capped, context.houseRules);
+    for (const d of dimensions) {
+        yield* observe(context, judgment, d.dimension, state, result, isMergeable, d.answer);
+    }
+    return ReviewResult.make({
+        issues: found.map((issue) => ReviewIssue.make({ ...issue, title: `judge[${story.id}]: ${issue.title}` })),
+        summary: `story-board:${story.id}`
+    });
+}));
+const observe = (context, judgment, dimension, state, result, isMergeable, key) => Effect.gen(function* () {
+    // The bar read every answer, so a missing one after a successful run is a defect.
+    const answer = yield* result.board.get(key).pipe(Effect.orDie);
+    if (answer.type !== "score")
+        return;
+    yield* publishJudgmentObserved(context.events, JudgmentObserved.make({
+        consumer: "story-board",
+        key: dimension.name,
+        state,
+        question: dimensionQuestion(dimension),
+        answer,
+        judgmentIdentity: judgment.identity,
+        decision: decide(answer, context.policy),
+        certainty: certaintyOf(answer),
+        support: answer.support,
+        origin: answer.origin,
+        outcome: {
+            _tag: "StoryBoard",
+            dimension: dimension.name,
+            score: answer.score,
+            mergeable: isMergeable
+        },
+        mode: "act"
+    }));
+});
+/**
+ * The judge `epic-stories-board` passes to runEpicStories: the run's judgment
+ * seat (LLM4TS_JUDGMENT_PROVIDER, or one derived from the reasoning seat),
+ * the default policy. Validating six rules is microseconds, so the ruleset
+ * is built per call and the factory keeps the plain StoryJudge type.
+ */
+export const boardJudgeFactory = (context) => (story, diff, seats) => Effect.flatMap(boardStoryJudge({ ...context, judgment: judgmentOf(seats.context) }), (judge) => judge(story, diff, seats));