@llm4ts/shell 0.15.1 → 0.16.1

package/flows/convert-all.js

@@ -30,7 +30,7 @@ import { resolveFlowInput } from "@llm4ts/runner/FlowArgs";
 import { runFlowMain, runNode } from "@llm4ts/runner/FlowRunner";
 import { nodePlainFileStore } from "@llm4ts/runner/NodePlainFileStore";
 import { nodeProcessExecutor } from "@llm4ts/runner/NodeProcessExecutor";
-import { conversionInventory, convertPage, migrationReport, setupConversion } from "./lib/convert.ts";
+import { conversionInventory, convertPage, migrationReport, setupConversion } from "./lib/convert.js";
 const program = Effect.gen(function* () {
     const input = yield* resolveFlowInput("Convert the legacy estate into the destination SPA");
     const coder = coderFromEnv(process.env);

package/flows/convert-page.js

@@ -23,7 +23,7 @@ import { Info } from "@llm4ts/flow/FlowEvents";
 import { asReadOnly, coderFromEnv } from "@llm4ts/runner/Connectors";
 import { resolveFlowInput } from "@llm4ts/runner/FlowArgs";
 import { runFlowMain, runNode } from "@llm4ts/runner/FlowRunner";
-import { convertPage, setupConversion } from "./lib/convert.ts";
+import { convertPage, setupConversion } from "./lib/convert.js";
 const program = Effect.gen(function* () {
     const input = yield* resolveFlowInput("Convert one legacy page into the destination SPA");
     const page = input.prompt.trim().split(/\s+/)[0] ?? "";

package/flows/epic-stories.js

@@ -0,0 +1,119 @@
+// Split an epic into stories with a declared dependency graph, approve the plan, then implement the stories with parallel coders in per-story worktrees merged into an epic branch.
+//
+//   llm4ts run epic-stories --repo ~/demo/portal "Add the current account and wire transfers"
+//   llm4ts run epic-stories --repo ~/demo/portal -- --plan-only "…"   # write the plan and stop
+//
+// The reasoning seat (LLM4TS_REASONER, default claude) splits the epic,
+// reviews every task and judges every story; the coder seat (LLM4TS_CODER,
+// default pi) implements; LLM4TS_CODER_MODEL / LLM4TS_REASONING_MODEL pick
+// their models (pi: "provider/model"). The story plan is persisted under
+// .llm4ts/epics/<epic-id>/plan.md BEFORE any coder runs, and an existing
+// file wins over regeneration — editing it is the approval and the re-plan
+// path. Stories run in .llm4ts/worktrees/<story-id> under --concurrency
+// (default 3); a failed story skips its dependents (--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 { budget, cap } from "@llm4ts/flow/Context";
+import { makeLocalBoardSync } from "@llm4ts/flow/BoardSync";
+import { estimatedUsageOptionsFromEnv, makeEstimatedUsageMeter } from "@llm4ts/flow/EstimatedUsage";
+import { FlowAborted } from "@llm4ts/flow/FlowError";
+import { Info } from "@llm4ts/flow/FlowEvents";
+import { stage } from "@llm4ts/flow/PlanExecution";
+import { implementStoriesFlow } from "@llm4ts/flow/Stories";
+import { makeStoryPlanStore, validateStoryPlan } from "@llm4ts/flow/StoryPlan";
+import { asReadOnly, withModel } from "@llm4ts/runner/Connectors";
+import { resolveFlowInput } from "@llm4ts/runner/FlowArgs";
+import { runFlowMain, runNode } from "@llm4ts/runner/FlowRunner";
+import { nodePlainFileStore } from "@llm4ts/runner/NodePlainFileStore";
+import { nodeProcessExecutor } from "@llm4ts/runner/NodeProcessExecutor";
+import { combineTotals, epicIdFor, gateCommands, gatesIn, generateStoryPlan, judgeStory, parseEpicArgs, reasonerFromEnvironment, setupIn, storyCoderFromEnvironment, 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);
+};
+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));
+    const input = yield* resolveFlowInput(defaultEpic, flags.rest);
+    const reasoning = withOptionalModel(yield* reasonerFromEnvironment(process.env), process.env.LLM4TS_REASONING_MODEL);
+    const coder = withOptionalModel(yield* storyCoderFromEnvironment(process.env), process.env.LLM4TS_CODER_MODEL);
+    const files = nodePlainFileStore;
+    const epicId = epicIdFor(input.prompt);
+    const stateDir = join(input.workDir, ".llm4ts", "epics", 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;
+        }
+        const contextFor = context.contextFor;
+        if (contextFor === undefined) {
+            return yield* FlowAborted.make({
+                message: "this runner cannot rebind seats to a worktree (no contextFor)"
+            });
+        }
+        const gates = gatesIn(nodeProcessExecutor, events, gateCommands(process.env));
+        const setupCommand = worktreeSetupCommand(process.env);
+        const report = yield* implementStoriesFlow({ ...context, reasoning: reasoningMeter.service }, {
+            plan,
+            files,
+            stateDir,
+            worktreeRoot: join(input.workDir, ".llm4ts", "worktrees"),
+            board: makeLocalBoardSync(files, stateDir, `Epic: ${plan.epicId}`),
+            contextFor: (workDir) => Effect.gen(function* () {
+                const rebound = yield* contextFor(workDir);
+                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: setupIn(nodeProcessExecutor, events, setupCommand) }),
+            gates,
+            judge: (story, diff) => judgeStory(reasoningMeter.service, story, diff, contextBudget),
+            system: (story) => Effect.succeed([
+                "House rules of the target repository (CONTRIBUTING.md):",
+                guidance,
+                "",
+                `Imitate the exemplar feature before inventing anything. Story id: ${story.id}.`
+            ].join("\n")),
+            ...(flags.concurrency === undefined ? {} : { concurrency: flags.concurrency }),
+            failFast: flags.failFast
+        });
+        yield* events.publish(Info.make({
+            message: `epic ${report.epicId}: ${report.count("done")} done, ${report.count("failed")} failed, ${report.count("skipped")} skipped — report at ${join(stateDir, "report.md")} (usage figures estimated)`
+        }));
+    }));
+});
+runFlowMain(program);

package/flows/fixtures/epic-stories/conto-bonifico.md

@@ -0,0 +1,207 @@
+# Epic: conto-bonifico
+
+Add the retail customer's current account (Conto) with balance and movements, and wire transfers (Bonifico) with beneficiary, review, SCA confirmation, and history.
+
+## Waves
+
+1. accounts-contract, payments-contract, iban-field
+2. conto-overview, conto-movimenti, bonifico-form, bonifici-list
+3. home
+
+## Stories
+
+The expected split of the demo epic against the internet-banking portal fixture (`examples/internet-banking/portal`): two contract stories and one shared-kit story first, four screens under the concurrency cap, then the fan-in that owns the composition point. The block below is the source of truth; the flow's live generator is prompted with the same epic sentence.
+
+## Plan block
+
+```json storyplan
+{
+  "epicId": "conto-bonifico",
+  "epic": "Add the retail customer's current account (Conto) with balance and movements, and wire transfers (Bonifico) with beneficiary, review, SCA confirmation, and history.",
+  "stories": [
+    {
+      "id": "accounts-contract",
+      "title": "Accounts domain contract and fake routes",
+      "description": "Declare the Accounts HttpApi in src/contracts/accounts.ts: list the customer's current accounts (id, IBAN, label, balance in cents, available balance), one account's detail, and its movements as a cursor-paged list (date, description, amount in cents, running balance, category). Implement src/contracts/accounts.fake.ts with deterministic fixture data for customer C-000123 (two accounts, at least 30 movements on the first), a reset function, and the exported accountsDomain. Run pnpm openapi and commit contracts/openapi/accounts.json. Follow src/contracts/profile.ts and profile.fake.ts exactly. Add src/contracts/accounts.test.ts covering the fake routes through the typed client: list, detail, and a page of movements.",
+      "dependsOn": [],
+      "owned": [
+        "src/contracts/accounts.ts",
+        "src/contracts/accounts.fake.ts",
+        "contracts/openapi/accounts.json",
+        "src/contracts/accounts.test.ts"
+      ],
+      "sharedReadOnly": [
+        "src/kit",
+        "src/contracts/profile.ts",
+        "src/contracts/profile.fake.ts",
+        "CONTRIBUTING.md"
+      ],
+      "provides": [
+        "accountsDomain from src/contracts/accounts.fake.ts",
+        "client.accounts.list()",
+        "client.accounts.get({ params: { accountId } })",
+        "client.accounts.movements({ params: { accountId }, urlParams: { cursor } })",
+        "src/contracts/accounts.test.ts"
+      ]
+    },
+    {
+      "id": "payments-contract",
+      "title": "Payments domain contract and stateful fake routes",
+      "description": "Declare the Payments HttpApi in src/contracts/payments.ts: list saved beneficiaries (name, IBAN), create a transfer (from account id, beneficiary name, IBAN, amount in cents, description, execution date) returning a pending transfer with an id, confirm a transfer with a six-digit SCA code (any code confirms except 000000, which is refused as UnprocessableEntity), list transfers newest first with their state (pending, confirmed, refused), and get one transfer. Implement src/contracts/payments.fake.ts with an in-memory store per page session so a created then confirmed transfer appears in the list, a reset function, and the exported paymentsDomain. Run pnpm openapi and commit contracts/openapi/payments.json. Follow src/contracts/profile.ts and profile.fake.ts exactly. Add src/contracts/payments.test.ts covering the fake routes through the typed client: create then confirm then list, and the refused code 000000.",
+      "dependsOn": [],
+      "owned": [
+        "src/contracts/payments.ts",
+        "src/contracts/payments.fake.ts",
+        "contracts/openapi/payments.json",
+        "src/contracts/payments.test.ts"
+      ],
+      "sharedReadOnly": [
+        "src/kit",
+        "src/contracts/profile.ts",
+        "src/contracts/profile.fake.ts",
+        "CONTRIBUTING.md"
+      ],
+      "provides": [
+        "paymentsDomain from src/contracts/payments.fake.ts",
+        "client.payments.beneficiaries()",
+        "client.payments.create({ payload })",
+        "client.payments.confirm({ params: { transferId }, payload: { code } })",
+        "client.payments.list()",
+        "client.payments.get({ params: { transferId } })",
+        "src/contracts/payments.test.ts"
+      ]
+    },
+    {
+      "id": "iban-field",
+      "title": "IBAN input component in the kit",
+      "description": "Add src/kit/iban-field.tsx exporting IbanField (a labelled input that formats the IBAN in groups of four as the customer types, keeps the compact value, and reports validity) and isValidIban (the mod-97 check over the ISO 13616 alphabet). Add src/kit/iban-field.test.tsx covering formatting and valid and invalid IBANs, using the existing Field component and theme classes only.",
+      "dependsOn": [],
+      "owned": [
+        "src/kit/iban-field.tsx",
+        "src/kit/iban-field.test.tsx"
+      ],
+      "sharedReadOnly": [
+        "src/kit/components.tsx",
+        "src/kit/theme.css",
+        "src/kit/i18n.tsx",
+        "src/kit/format.ts",
+        "CONTRIBUTING.md"
+      ],
+      "provides": [
+        "IbanField and isValidIban from src/kit/iban-field.tsx"
+      ]
+    },
+    {
+      "id": "conto-overview",
+      "title": "Conto: account overview screen",
+      "description": "Add the feature src/features/conto/overview/ with messages.ts (English and Italian), route.tsx exporting contoOverviewFeature (id conto), and ContoScreen.tsx: an account picker across the customer's accounts, the balance and available balance as Figures, the IBAN and account details as KeyValues, loaded through accountsDomain. Add ContoScreen.test.tsx in the house style: rows and figures render in both languages against the fake transport.",
+      "dependsOn": [
+        "accounts-contract"
+      ],
+      "owned": [
+        "src/features/conto/overview"
+      ],
+      "sharedReadOnly": [
+        "src/kit",
+        "src/contracts",
+        "src/features/profilo",
+        "CONTRIBUTING.md"
+      ],
+      "provides": [
+        "contoOverviewFeature from src/features/conto/overview/route.tsx",
+        "screen id conto"
+      ]
+    },
+    {
+      "id": "conto-movimenti",
+      "title": "Conto: movements list with filter and CSV export",
+      "description": "Add the feature src/features/conto/movimenti/ with messages.ts (English and Italian), route.tsx exporting contoMovimentiFeature (id movimenti), and MovimentiScreen.tsx: the selected account's movements as a DataTable paged with usePages and LoadMore, a SelectFilter by category, and a CSV export through downloadCsv, loaded through accountsDomain. Add MovimentiScreen.test.tsx in the house style: rows render, the filter narrows them, the next page loads.",
+      "dependsOn": [
+        "accounts-contract"
+      ],
+      "owned": [
+        "src/features/conto/movimenti"
+      ],
+      "sharedReadOnly": [
+        "src/kit",
+        "src/contracts",
+        "src/features/profilo",
+        "CONTRIBUTING.md"
+      ],
+      "provides": [
+        "contoMovimentiFeature from src/features/conto/movimenti/route.tsx",
+        "screen id movimenti"
+      ]
+    },
+    {
+      "id": "bonifico-form",
+      "title": "Bonifico: new transfer with review, SCA confirmation and outcome",
+      "description": "Add the feature src/features/bonifico/nuovo/ with messages.ts (English and Italian), route.tsx exporting bonificoNuovoFeature (id bonifico), and BonificoScreen.tsx: a form (from account, beneficiary picked from saved beneficiaries or typed with IbanField, amount with parseEuro, description, execution date) validated by a pure function, a review step, a six-digit SCA code step calling client.payments.confirm, and an outcome panel for confirmed and refused, all through paymentsDomain and useAction. Add BonificoScreen.test.tsx in the house style: validation blocks a bad submit, a good transfer reaches the fake and is confirmed, code 000000 shows the refusal.",
+      "dependsOn": [
+        "payments-contract",
+        "iban-field"
+      ],
+      "owned": [
+        "src/features/bonifico/nuovo"
+      ],
+      "sharedReadOnly": [
+        "src/kit",
+        "src/contracts",
+        "src/features/profilo",
+        "CONTRIBUTING.md"
+      ],
+      "provides": [
+        "bonificoNuovoFeature from src/features/bonifico/nuovo/route.tsx",
+        "screen id bonifico"
+      ]
+    },
+    {
+      "id": "bonifici-list",
+      "title": "Bonifico: transfer history with state badges and detail",
+      "description": "Add the feature src/features/bonifico/elenco/ with messages.ts (English and Italian), route.tsx exporting bonificiElencoFeature (id bonifici), and BonificiScreen.tsx: the customer's transfers newest first as a DataTable with a StateBadge per state (pending, confirmed, refused mapped to tones) and a detail panel for the selected transfer, through paymentsDomain. Add BonificiScreen.test.tsx in the house style: rows render with translated states in both languages, selecting a row shows its detail.",
+      "dependsOn": [
+        "payments-contract"
+      ],
+      "owned": [
+        "src/features/bonifico/elenco"
+      ],
+      "sharedReadOnly": [
+        "src/kit",
+        "src/contracts",
+        "src/features/profilo",
+        "CONTRIBUTING.md"
+      ],
+      "provides": [
+        "bonificiElencoFeature from src/features/bonifico/elenco/route.tsx",
+        "screen id bonifici"
+      ]
+    },
+    {
+      "id": "home",
+      "title": "Home dashboard and the composition point",
+      "description": "Replace the placeholder src/features/home/ with a dashboard: the first account's balance as a Figure, the last five movements, a quick action navigating to the transfer form with useNavigate, and the three most recent transfers, through accountsDomain and paymentsDomain. Rewrite src/App.tsx so the feature list is home, conto, movimenti, bonifico, bonifici, profilo, in that order. Add HomeScreen.test.tsx in the house style: the figures and lists render, the quick action navigates.",
+      "dependsOn": [
+        "conto-overview",
+        "conto-movimenti",
+        "bonifico-form",
+        "bonifici-list"
+      ],
+      "owned": [
+        "src/features/home",
+        "src/App.tsx"
+      ],
+      "sharedReadOnly": [
+        "src/kit",
+        "src/contracts",
+        "src/features/conto",
+        "src/features/bonifico",
+        "src/features/profilo",
+        "CONTRIBUTING.md"
+      ],
+      "provides": [
+        "the composed application with every screen reachable from the shell"
+      ]
+    }
+  ]
+}
+```

package/flows/lib/convert.js

@@ -0,0 +1,485 @@
+// Shared core of the J2EE→Next.js conversion flows (convert-page,
+// convert-all). One page = one branch = one conversion report. The Page Spec
+// extracted from the legacy repo is the contract; the legacy source is
+// consultable evidence (NOT clean-room — ADR 0012); the destination repo's
+// own pages are the style guide. All token/cost figures are ESTIMATES.
+import { join, resolve } from "node:path";
+import * as Effect from "effect/Effect";
+import { Dimension } from "@llm4ts/core/eval/Eval";
+import { judge } from "@llm4ts/core/eval/Judge";
+import { TokenUsage } from "@llm4ts/core/Models";
+import { makeChat } from "@llm4ts/flow/Chat";
+import { budget, capped } from "@llm4ts/flow/Context";
+import { implementPlanFlow } from "@llm4ts/flow/Flow";
+import { FlowAborted } from "@llm4ts/flow/FlowError";
+import { FlowEvents, Info } from "@llm4ts/flow/FlowEvents";
+import { openApiFor, parsePageSpec, renderPageSpec } from "@llm4ts/flow/PageSpec";
+import { loadPatternCards, matchingPatternCards } from "@llm4ts/flow/Patterns";
+import { makePlanStore } from "@llm4ts/flow/Persistence";
+import { Plan, Task } from "@llm4ts/flow/Plan";
+import { stage } from "@llm4ts/flow/PlanExecution";
+import { judgeAllPrograms } from "@llm4ts/flow/ProgramJudge";
+import { lintCommand, mergeReviewResults, minimalReviewers } from "@llm4ts/flow/Review";
+import { closureFor, surveyGraph } from "@llm4ts/flow/Survey";
+import { estimatedUsageOptionsFromEnv, makeEstimatedUsageMeter } from "@llm4ts/flow/EstimatedUsage";
+import { legacySourceWorkspaceLimits, workspaceLimitsFromEnv } from "@llm4ts/flow/Workspace";
+import { nodePlainFileStore } from "@llm4ts/runner/NodePlainFileStore";
+import { nodeProcessExecutor } from "@llm4ts/runner/NodeProcessExecutor";
+import { makeNodeWorkspace } from "@llm4ts/runner/NodeWorkspace";
+import { loadUniversalPatternCards, openPack } from "@llm4ts/runner/Packs";
+import { reviewFingerprint } from "@llm4ts/runner/ReviewFingerprint";
+export const positiveEnvInt = (environment, name, fallback) => {
+    const raw = Number.parseInt(environment[name] ?? "", 10);
+    return Number.isFinite(raw) && raw > 0 ? raw : fallback;
+};
+/** Sums the coder and reasoning meters into one per-run estimate. */
+export const combineTotals = (first, second) => Effect.gen(function* () {
+    const left = yield* first;
+    const right = yield* second;
+    if (left === undefined) {
+        return right;
+    }
+    if (right === undefined) {
+        return left;
+    }
+    const cached = [left.cached, right.cached].flatMap((value) => value === undefined ? [] : [value]);
+    const cost = [left.costUsd, right.costUsd].flatMap((value) => value === undefined ? [] : [value]);
+    return TokenUsage.make({
+        prompt: left.prompt + right.prompt,
+        completion: left.completion + right.completion,
+        total: left.total + right.total,
+        ...(cached.length === 0 ? {} : { cached: cached.reduce((sum, value) => sum + value, 0) }),
+        ...(cost.length === 0 ? {} : { costUsd: cost.reduce((sum, value) => sum + value, 0) })
+    });
+});
+const conversionDimensions = [
+    Dimension.make({
+        name: "spec-compliance",
+        rubric: "Does the converted page satisfy its Page Spec — every form field present, every " +
+            "validation rule with its VERBATIM message in the spec's order, navigation and " +
+            "multi-step session state owned explicitly, and every apiCall represented as a port " +
+            "operation matching the OpenAPI contract — without weakening any test?"
+    }),
+    Dimension.make({
+        name: "acl-purity",
+        rubric: "Is the anti-corruption layer intact — no fetch outside service adapters, no legacy " +
+            "DTO names anywhere, no business logic implemented client-side, the page depending " +
+            "only on the port through the registry, the mock adapter faking transport rather " +
+            "than rules?"
+    }),
+    Dimension.make({
+        name: "house-fidelity",
+        rubric: "Does the page read as if the destination team wrote it — design-system components " +
+            "instead of hand-rolled UI, the house Form validation map, the house test style, no " +
+            "ad-hoc styling or auth handling?"
+    })
+];
+const conversionPlan = (page, spec, contractPath) => Plan.make({
+    epicId: `convert/${page}`,
+    brief: [
+        `You are converting the legacy page '${page}' into this Next.js SPA.`,
+        "",
+        renderPageSpec(spec).trimEnd(),
+        "",
+        `The OpenAPI anti-corruption contract is ALREADY WRITTEN at ${contractPath} —`,
+        "it is generated from the page spec and is the contract of record. Do not edit it."
+    ].join("\n"),
+    tasks: [
+        Task.make({
+            title: `acl: ${page} service port and mock`,
+            description: [
+                `Implement the anti-corruption service layer for '${page}' from the contract at`,
+                `${contractPath}:`,
+                `- src/services/${page}/port.ts — a typed port interface with one method per`,
+                "  OpenAPI operation, request/response types in the contract's DOMAIN names.",
+                `- src/services/${page}/mock.ts — a mock adapter returning contract-shaped,`,
+                "  deterministic fixture data (transport fake, never business rules).",
+                "- Wire the port into src/services/registry.ts the same way the existing",
+                "  services are wired.",
+                "Imitate the existing services (e.g. src/services/cards/) exactly. No page code",
+                "in this task."
+            ].join("\n")
+        }),
+        Task.make({
+            title: `page: ${page} component`,
+            description: [
+                `Build the converted page under src/app/${page}/ using ONLY the destination`,
+                "design-system components and the port from the previous task:",
+                "- Respect the original form: same fields, same validation rules with their",
+                "  VERBATIM messages in the spec's order, same navigation.",
+                "- Anything the legacy app kept in HttpSession or hidden fields becomes explicit",
+                "  client state (use the Stepper pattern for multi-step flows).",
+                "- No fetch in components; the page obtains its port from the registry.",
+                "- Read CONTRIBUTING.md and the existing pages first and match their style."
+            ].join("\n")
+        }),
+        Task.make({
+            title: `tests: ${page} component tests`,
+            description: [
+                `Write component tests at tests/${page}.page.test.tsx in the house test style`,
+                "(see the existing tests/ files): mock the registry port, render inside",
+                "AuthProvider, and assert EXACTLY three families of behaviour:",
+                "1. every spec'd form field renders,",
+                "2. every spec'd validation fires with its verbatim message,",
+                "3. the port is called with contract-shaped payloads on the happy path.",
+                "No snapshots, no styling assertions, nothing beyond those families."
+            ].join("\n")
+        })
+    ]
+});
+const gateFor = (deps, name) => {
+    const command = deps.pack.gate(name);
+    return command === undefined
+        ? undefined
+        : lintCommand(nodeProcessExecutor, deps.context.events, command, deps.targetDir);
+};
+const allClean = (gates) => Effect.gen(function* () {
+    const results = [];
+    for (const gate of gates) {
+        if (gate !== undefined) {
+            const result = yield* gate;
+            results.push(result);
+            // Fail fast: a broken typecheck makes later gate output noise.
+            if (!result.isClean) {
+                break;
+            }
+        }
+    }
+    return mergeReviewResults(results);
+});
+const issueLines = (result) => result.issues.map((issue) => `- ${issue.title}: ${issue.description}`).join("\n");
+/** The page's legacy source and its bounded include closure, capped to budget. */
+const legacyEvidence = Effect.fn("convert.legacyEvidence")(function* (deps, page) {
+    const matchesPage = yield* deps.legacy
+        .discover(`**/${page}.jsp`)
+        .pipe(Effect.orElseSucceed(() => []));
+    const sourcePath = matchesPage[0];
+    const source = sourcePath === undefined
+        ? ""
+        : yield* deps.legacy.read(sourcePath).pipe(Effect.orElseSucceed(() => ""));
+    const graph = yield* surveyGraph(deps.legacy, deps.pack.sources ?? ".*", deps.pack.coverage, deps.pack.survey);
+    const closure = closureFor(graph, page, positiveEnvInt(deps.environment, "LLM4TS_MAX_CLOSURE_FILES", 12));
+    const parts = [];
+    if (sourcePath !== undefined) {
+        parts.push(`===== ${sourcePath} =====\n${source}`);
+    }
+    for (const path of closure) {
+        const text = yield* deps.legacy.read(path).pipe(Effect.orElseSucceed(() => ""));
+        if (text.trim().length > 0) {
+            parts.push(`===== ${path} =====\n${text}`);
+        }
+    }
+    const evidence = yield* capped(`legacy[${page}]`, parts.join("\n\n"), Math.floor(budget(deps.environment) / 3)).pipe(Effect.provideService(FlowEvents, deps.context.events));
+    return { source, evidence };
+});
+const destinationGuidance = Effect.fn("convert.destinationGuidance")(function* (deps) {
+    const contributing = yield* deps.target
+        .read("CONTRIBUTING.md")
+        .pipe(Effect.orElseSucceed(() => ""));
+    const pages = yield* deps.target
+        .discover("src/app/**/page.tsx")
+        .pipe(Effect.orElseSucceed(() => []));
+    return [
+        "Destination house rules (CONTRIBUTING.md):",
+        contributing.trim(),
+        "",
+        "Existing pages to imitate:",
+        ...pages.map((path) => `- ${path}`)
+    ].join("\n");
+});
+export const convertPage = Effect.fn("convert.page")(function* (deps, page) {
+    const { context, environment, files, pack } = deps;
+    const specPath = join(deps.legacyDir, pack.specsDir, `${page}.md`);
+    const specMarkdown = yield* files.read(specPath);
+    if (specMarkdown === undefined) {
+        return yield* FlowAborted.make({
+            message: `no spec at ${specPath} — run modernize-extract on the legacy repo first`
+        });
+    }
+    // Hard schema validation: a spec without a decodable pagespec block is an
+    // incomplete extraction, not a page to guess at.
+    const spec = yield* parsePageSpec(specMarkdown);
+    const branch = `convert/${page}`;
+    yield* stage(context.events, "branch", context.git.checkoutOrCreate(branch));
+    // The contract is a deterministic projection of the reviewed spec — written
+    // by code before any model runs, committed with the first task.
+    const contractPath = `contracts/${page}.openapi.yaml`;
+    yield* stage(context.events, "contract", files.writeAtomic(join(deps.targetDir, contractPath), openApiFor(spec)));
+    const { source, evidence } = yield* legacyEvidence(deps, page);
+    const playbook = matchingPatternCards(source, deps.cards);
+    const guidance = yield* destinationGuidance(deps);
+    const system = [
+        pack.prompt("implement"),
+        pack.lessons === undefined
+            ? undefined
+            : `Lessons from previous conversion runs — apply them:\n${pack.lessons}`,
+        playbook.length === 0
+            ? undefined
+            : "Pattern cards matched by the legacy source — the translation playbook (advisory, " +
+                "the spec wins):\n\n" +
+                playbook.map((card) => `### ${card.id}\n${card.body}`).join("\n\n"),
+        guidance,
+        evidence.trim().length === 0
+            ? undefined
+            : `Legacy source evidence (for disambiguation only — the Page Spec wins):\n\n${evidence}`
+    ]
+        .filter((part) => part !== undefined)
+        .join("\n\n");
+    const perTaskGate = allClean([
+        gateFor(deps, "typecheck"),
+        gateFor(deps, "lint"),
+        gateFor(deps, "test")
+    ]);
+    yield* implementPlanFlow(context, {
+        store: makePlanStore(files),
+        planPath: join(deps.targetDir, ".llm4ts", "convert", `${page}.plan.md`),
+        plan: Effect.succeed(conversionPlan(page, spec, contractPath)),
+        system,
+        chatPerTask: true,
+        checkoutBranch: false,
+        reviewers: [...minimalReviewers, ...pack.lenses],
+        lint: perTaskGate
+    });
+    const verifyGate = allClean([gateFor(deps, "test"), gateFor(deps, "build")]);
+    yield* stage(context.events, "verify", Effect.gen(function* () {
+        const result = yield* verifyGate;
+        if (!result.isClean) {
+            return yield* FlowAborted.make({
+                message: `verify gate failed for ${page}:\n${issueLines(result)}`
+            });
+        }
+    }));
+    yield* stage(context.events, "judge", Effect.gen(function* () {
+        const complianceJudge = judge(context.reasoning, conversionDimensions);
+        const rounds = positiveEnvInt(environment, "LLM4TS_JUDGE_ROUNDS", 2);
+        for (let round = 1; round <= rounds; round += 1) {
+            const base = yield* context.git.defaultBase;
+            const verdict = yield* judgeAllPrograms({
+                pack,
+                judge: complianceJudge,
+                dimensions: conversionDimensions,
+                git: context.git,
+                files,
+                gateDir: join(deps.targetDir, ".llm4ts", "convert", "gate"),
+                base,
+                programs: [page],
+                specFor: () => Effect.succeed(specMarkdown),
+                query: context.userPrompt,
+                fingerprint: reviewFingerprint
+            });
+            if (verdict.isClean) {
+                return yield* context.events.publish(Info.make({ message: `judge: ${page} cleared the bar` }));
+            }
+            if (round >= rounds) {
+                return yield* FlowAborted.make({
+                    message: `judge not cleared for ${page} after ${rounds} round(s):\n${issueLines(verdict)}`
+                });
+            }
+            const feedback = yield* makeChat(context.coder, {
+                system,
+                events: context.events,
+                agent: "coder"
+            });
+            yield* feedback.ask([
+                `The conversion of '${page}' scored below the bar. Close these gaps without`,
+                "weakening any test, then stop:",
+                issueLines(verdict)
+            ].join("\n"));
+            const regated = yield* verifyGate;
+            if (!regated.isClean) {
+                return yield* FlowAborted.make({
+                    message: `verify gate broke while addressing judge feedback on ${page}`
+                });
+            }
+            yield* context.git.commitAll(`convert/${page}: address judge feedback`);
+        }
+    }).pipe(Effect.provideService(FlowEvents, context.events)));
+    const totals = yield* deps.totals;
+    const reportPath = `docs/conversion/${page}.md`;
+    const base = yield* context.git.defaultBase;
+    const changed = yield* context.git.changedFilesVsBase(base);
+    const report = [
+        `# Conversion report: ${page}`,
+        "",
+        "> Token and cost figures below are ESTIMATES from character counts",
+        "> (see docs/adr/0012): the CLI seats report no usage. They are not",
+        "> measurements.",
+        "",
+        `- Legacy spec: ${specPath}`,
+        `- Branch: \`${branch}\` (awaiting human review — no auto-merge)`,
+        `- Contract: ${contractPath}`,
+        `- Gates: typecheck, lint, test, build — green at report time`,
+        "- Judge: cleared (spec-compliance, acl-purity, house-fidelity)",
+        ...(totals === undefined
+            ? ["- Estimated usage: none recorded"]
+            : [
+                `- Estimated tokens: ~${totals.total} (${totals.prompt} in / ${totals.completion} out)`,
+                ...(totals.costUsd === undefined
+                    ? []
+                    : [`- Estimated cost: ~$${totals.costUsd.toFixed(2)}`])
+            ]),
+        "",
+        "## Files changed",
+        "",
+        ...changed.map((file) => `- ${file}`),
+        ...(spec.openQuestions.length === 0
+            ? []
+            : ["", "## Open questions carried forward", "", ...spec.openQuestions.map((q) => `- ${q}`)])
+    ].join("\n");
+    yield* files.writeAtomic(join(deps.targetDir, reportPath), report + "\n");
+    yield* context.git.commitAll(`convert/${page}: conversion report`);
+    return {
+        page,
+        branch,
+        reportPath,
+        ...(totals === undefined ? {} : { estimatedTokens: totals.total }),
+        ...(totals?.costUsd === undefined ? {} : { estimatedCostUsd: totals.costUsd })
+    };
+});
+/**
+ * The common wiring of both conversion flows: metered seats (estimates-only
+ * accounting), the two workspaces (legacy read-only limits, target default),
+ * the pack (default `packs/j2ee-nextjs-spa`), and the pattern-card deck.
+ */
+export const setupConversion = Effect.fn("convert.setup")(function* (context, input, environment, flowDir) {
+    const legacyRaw = environment.LLM4TS_LEGACY_REPO;
+    if (legacyRaw === undefined || legacyRaw.trim().length === 0) {
+        return yield* FlowAborted.make({
+            message: "set LLM4TS_LEGACY_REPO to the extracted legacy repository path"
+        });
+    }
+    const legacyDir = resolve(input.workspace, legacyRaw.trim());
+    const estimateOptions = estimatedUsageOptionsFromEnv(environment);
+    const coderMeter = yield* makeEstimatedUsageMeter(context.coder, estimateOptions);
+    const reasoningMeter = yield* makeEstimatedUsageMeter(context.reasoning, estimateOptions);
+    const metered = {
+        ...context,
+        coder: coderMeter.service,
+        reasoning: reasoningMeter.service
+    };
+    const legacy = yield* makeNodeWorkspace(legacyDir, workspaceLimitsFromEnv(environment, legacySourceWorkspaceLimits));
+    const target = yield* makeNodeWorkspace(input.workDir);
+    const opened = yield* stage(context.events, "pack", openPack({
+        environment: {
+            ...environment,
+            LLM4TS_PACK: environment.LLM4TS_PACK ?? "packs/j2ee-nextjs-spa"
+        },
+        launchDir: input.workspace,
+        flowDir
+    }));
+    const cards = [
+        ...(yield* loadPatternCards(opened.workspace, `${opened.dir}/patterns`)),
+        ...(yield* loadUniversalPatternCards([input.workspace, flowDir]))
+    ];
+    return {
+        context: metered,
+        files: nodePlainFileStore,
+        pack: opened.pack,
+        cards,
+        legacy,
+        legacyDir,
+        target,
+        targetDir: input.workDir,
+        environment,
+        totals: combineTotals(coderMeter.totals, reasoningMeter.totals)
+    };
+});
+/** `## Wave: <name>` sections with their `- PROG` lines — the survey's plan. */
+export const parseWavePlan = (planText) => {
+    const waves = [];
+    let collecting = false;
+    for (const line of planText.split(/\r?\n/)) {
+        const trimmed = line.trim();
+        const heading = /^## Wave: (.+)$/.exec(trimmed);
+        if (heading?.[1] !== undefined) {
+            waves.push({ wave: heading[1].trim(), pages: [] });
+            collecting = true;
+            continue;
+        }
+        if (trimmed.startsWith("## ") || trimmed.startsWith("# ")) {
+            // Any other section (Triage, notes) ends the current wave's list.
+            collecting = false;
+            continue;
+        }
+        const current = waves.at(-1);
+        if (collecting && current !== undefined && trimmed.startsWith("- ")) {
+            current.pages.push(trimmed.slice(2).trim());
+        }
+    }
+    return waves;
+};
+/**
+ * The ordered page list: the approved wave plan when present, otherwise every
+ * extracted spec. Pages appear in conversion order.
+ */
+export const conversionInventory = Effect.fn("convert.inventory")(function* (files, legacy, legacyDir, pack) {
+    const planText = yield* files.read(join(legacyDir, "docs/modernization/wave-plan.md"));
+    if (planText !== undefined) {
+        const waves = parseWavePlan(planText);
+        if (waves.length > 0) {
+            return waves.flatMap((entry) => entry.pages.map((page) => ({ page, wave: entry.wave })));
+        }
+    }
+    const specs = yield* legacy
+        .discover(`${pack.specsDir}/*.md`)
+        .pipe(Effect.orElseSucceed(() => []));
+    return [...specs]
+        .map((path) => path.split("/").at(-1) ?? path)
+        .filter((name) => name.endsWith(".md") && name !== "README.md")
+        .map((name) => name.slice(0, -".md".length))
+        .sort()
+        .map((page) => ({ page }));
+});
+/**
+ * Whole-estate summary with a deliberately naive projection: average estimated
+ * cost per converted page times the remainder. Every figure is an estimate of
+ * an estimate and the report says so — no pretend precision, rounded hard.
+ */
+export const migrationReport = (rows, remaining) => {
+    const done = rows.filter((row) => row.outcome === "done");
+    const tokenRows = done.flatMap((row) => row.estimatedTokens === undefined ? [] : [row.estimatedTokens]);
+    const costRows = done.flatMap((row) => row.estimatedCostUsd === undefined ? [] : [row.estimatedCostUsd]);
+    const averageTokens = tokenRows.length === 0
+        ? undefined
+        : Math.round(tokenRows.reduce((sum, value) => sum + value, 0) / tokenRows.length);
+    const averageCost = costRows.length === 0
+        ? undefined
+        : costRows.reduce((sum, value) => sum + value, 0) / costRows.length;
+    const lines = [
+        "# Migration report",
+        "",
+        "> EVERY figure in this report is an ESTIMATE derived from character",
+        "> counts (docs/adr/0012) — the CLI seats report no token usage. The",
+        "> projection below is an estimate built on those estimates.",
+        "",
+        `- Pages converted: ${done.length}`,
+        `- Pages failed: ${rows.filter((row) => row.outcome === "failed").length}`,
+        `- Pages skipped: ${rows.filter((row) => row.outcome === "skipped").length}`,
+        `- Pages remaining: ${remaining.length}`,
+        "",
+        "## Per page (estimated)",
+        "",
+        "| Page | Outcome | ~Tokens | ~Cost | Note |",
+        "| --- | --- | --- | --- | --- |",
+        ...rows.map((row) => [
+            `| ${row.page}`,
+            row.outcome,
+            row.estimatedTokens === undefined ? "—" : `~${row.estimatedTokens}`,
+            row.estimatedCostUsd === undefined ? "—" : `~$${row.estimatedCostUsd.toFixed(2)}`,
+            `${row.detail ?? ""} |`
+        ].join(" | "))
+    ];
+    if (remaining.length > 0 && (averageTokens !== undefined || averageCost !== undefined)) {
+        lines.push("", "## Projection for the remaining estate (estimated)", "");
+        if (averageTokens !== undefined) {
+            lines.push(`- ~${averageTokens} tokens/page × ${remaining.length} pages ≈ ` +
+                `~${averageTokens * remaining.length} tokens`);
+        }
+        if (averageCost !== undefined) {
+            lines.push(`- ~$${averageCost.toFixed(2)}/page × ${remaining.length} pages ≈ ` +
+                `~$${(averageCost * remaining.length).toFixed(0)}`);
+        }
+        lines.push("", `Remaining: ${remaining.join(", ")}`);
+    }
+    return lines.join("\n") + "\n";
+};

package/flows/lib/epic-stories.js

@@ -0,0 +1,275 @@
+// Shared core of the epic-stories flow (ADR 0013): the operator flags, the
+// story-plan generator prompt and schema, the story judge, the gate runner,
+// and seat selection. The executor itself is `@llm4ts/flow/Stories`.
+import * as Effect from "effect/Effect";
+import { Dimension, Sample } from "@llm4ts/core/eval/Eval";
+import { judge } from "@llm4ts/core/eval/Judge";
+import { TokenUsage } from "@llm4ts/core/Models";
+import { cap } from "@llm4ts/flow/Context";
+import { structuredAndPublish } from "@llm4ts/flow/Flow";
+import { FlowAborted, FlowLlmError } from "@llm4ts/flow/FlowError";
+import { stableHash } from "@llm4ts/flow/Plan";
+import { lintCommand, mergeReviewResults, ReviewIssue, ReviewResult } from "@llm4ts/flow/Review";
+import { StoryPlan } from "@llm4ts/flow/StoryPlan";
+import { claude, coderFor, coderIds, pi } from "@llm4ts/runner/Connectors";
+import { ScriptUsage } from "@llm4ts/runner/FlowArgs";
+export const epicUsage = [
+    "epic-stories flags:",
+    "  --plan-only         write (or re-validate) the story plan and stop",
+    "  --concurrency <n>   stories implemented at once (default 3)",
+    "  --fail-fast         stop the epic at the first failed story",
+    "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_GATES overrides the gate commands;",
+    "       LLM4TS_WORKTREE_SETUP (default: pnpm install --offline) prepares each worktree."
+].join("\n");
+/** The flow's own flags, taken out before the shared `--repo`/prompt parsing sees the rest. */
+export const parseEpicArgs = (argv) => Effect.gen(function* () {
+    let planOnly = false;
+    let failFast = false;
+    let concurrency;
+    const rest = [];
+    for (let index = 0; index < argv.length; index += 1) {
+        const argument = argv[index] ?? "";
+        if (argument === "--plan-only") {
+            planOnly = true;
+        }
+        else if (argument === "--fail-fast") {
+            failFast = true;
+        }
+        else if (argument === "--concurrency" || argument.startsWith("--concurrency=")) {
+            const raw = argument.includes("=")
+                ? argument.slice("--concurrency=".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: `--concurrency requires a positive integer\n${epicUsage}`
+                });
+            }
+            concurrency = parsed;
+        }
+        else {
+            rest.push(argument);
+        }
+    }
+    return { planOnly, failFast, concurrency, rest };
+});
+// ---- Seats --------------------------------------------------------------------
+/** The reasoning seat: `LLM4TS_REASONER`, any coder id, default claude. Unknown names fail typed. */
+export const reasonerFromEnvironment = (environment) => {
+    const requested = (environment.LLM4TS_REASONER ?? "").trim();
+    if (requested.length === 0) {
+        return Effect.succeed(claude);
+    }
+    const preset = coderFor(requested);
+    return preset === undefined
+        ? ScriptUsage.make({
+            message: `unknown LLM4TS_REASONER '${requested}'; expected ${coderIds.join("|")}`
+        })
+        : Effect.succeed(preset);
+};
+/** The coder seat: `LLM4TS_CODER`, default pi — the cheap local typist under a stronger orchestrator. */
+export const storyCoderFromEnvironment = (environment) => {
+    const requested = (environment.LLM4TS_CODER ?? "").trim();
+    if (requested.length === 0) {
+        return Effect.succeed(pi);
+    }
+    const preset = coderFor(requested);
+    return preset === undefined
+        ? ScriptUsage.make({
+            message: `unknown LLM4TS_CODER '${requested}'; expected ${coderIds.join("|")}`
+        })
+        : Effect.succeed(preset);
+};
+// ---- Story plan generation -----------------------------------------------------
+/** A readable, stable epic id: the first words of the epic plus a content hash. */
+export const epicIdFor = (epic) => {
+    const slug = epic
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .split("-")
+        .filter((part) => part.length > 0)
+        .slice(0, 4)
+        .join("-");
+    return `${slug.length === 0 ? "epic" : slug}-${stableHash(epic).slice(0, 6)}`;
+};
+export const storyPlanJsonSchema = {
+    type: "object",
+    properties: {
+        epicId: { type: "string" },
+        epic: { type: "string" },
+        stories: {
+            type: "array",
+            items: {
+                type: "object",
+                properties: {
+                    id: { type: "string" },
+                    title: { type: "string" },
+                    description: { type: "string" },
+                    dependsOn: { type: "array", items: { type: "string" } },
+                    owned: { type: "array", items: { type: "string" } },
+                    sharedReadOnly: { type: "array", items: { type: "string" } },
+                    provides: { type: "array", items: { type: "string" } }
+                },
+                required: ["id", "title", "description", "dependsOn", "owned", "sharedReadOnly", "provides"]
+            }
+        }
+    },
+    required: ["epicId", "epic", "stories"]
+};
+/** The generator's hard constraints — the perimeter rules the executor will enforce. */
+export const storyPlanInstructions = (epicId, guidance) => [
+    "You are the orchestrator of a parallel implementation. Split the epic below into stories",
+    "that independent coding agents will implement AT THE SAME TIME, each in its own git worktree,",
+    "each confined to the paths it owns. Dependencies are declared here and never discovered later.",
+    "",
+    "Rules (violations are rejected mechanically):",
+    "- Every story has a kebab-case id, a title, a description precise enough to implement alone,",
+    "  `dependsOn` (ids it must wait for), `owned` (repo-relative path prefixes it may create or",
+    "  change), `sharedReadOnly` (prefixes it may read but never change), and `provides` (routes,",
+    "  exports, contracts other stories may rely on).",
+    "- `owned` sets are pairwise DISJOINT: no path prefix appears under two stories.",
+    "- Shared surfaces (the kit, the theme, house rules) are never edited by a feature story. A new",
+    "  shared component is its own story, and every story using it depends on it.",
+    "- Every new service domain is its own contract story (contract + fake routes) that the pages",
+    "  depend on.",
+    "- Exactly ONE story owns the composition point (`src/App.tsx`): the fan-in that depends on",
+    "  every screen story and wires them in.",
+    "- A story fits one agent session: one screen, one contract, or one component.",
+    "- Every story OWNS the test files it must write (the judge asks for tests): list them",
+    "  in `owned` explicitly — a story cannot add a test outside its owned paths.",
+    `- Use exactly this epicId: "${epicId}". Copy the epic text into "epic".`,
+    "",
+    "Respond only with JSON:",
+    '{"epicId":"...","epic":"...","stories":[{"id":"...","title":"...","description":"...",',
+    '"dependsOn":[],"owned":[],"sharedReadOnly":[],"provides":[]}]}',
+    "",
+    "Target repository guidance (house rules and layout — the vocabulary to use):",
+    guidance
+].join("\n");
+export const generateStoryPlan = (reasoning, events, epic, epicId, guidance) => structuredAndPublish(reasoning, events, `${storyPlanInstructions(epicId, guidance)}\n\nEpic:\n${epic}`, StoryPlan, storyPlanJsonSchema).pipe(
+// The id and the epic text are ours, whatever the model echoed back.
+Effect.map((plan) => StoryPlan.make({ ...plan, epicId, epic })));
+// ---- Usage ---------------------------------------------------------------------
+/** Sums two meters into one per-story estimate. */
+export const combineTotals = (first, second) => Effect.map(Effect.all([first, second]), ([left, right]) => {
+    if (left === undefined)
+        return right;
+    if (right === undefined)
+        return left;
+    const cost = [left.costUsd, right.costUsd].flatMap((value) => value === undefined ? [] : [value]);
+    return TokenUsage.make({
+        prompt: left.prompt + right.prompt,
+        completion: left.completion + right.completion,
+        total: left.total + right.total,
+        ...(cost.length === 0 ? {} : { costUsd: cost.reduce((sum, value) => sum + value, 0) })
+    });
+});
+// ---- Judge ---------------------------------------------------------------------
+export const storyDimensions = [
+    Dimension.make({
+        name: "provides",
+        rubric: "Everything the story promised to provide (routes, exports, contracts) exists in the diff and is complete enough for a dependent story to use. 2 = all present and complete; 1 = present but partial; 0 = missing."
+    }),
+    Dimension.make({
+        name: "scope",
+        rubric: "The diff does only what the story describes, inside its owned paths, and does not reimplement what the shared kit already offers. 2 = focused; 1 = minor drift; 0 = unrelated or duplicated work."
+    }),
+    Dimension.make({
+        name: "house-style",
+        rubric: "The code follows the target's house rules: kit components and hooks only, per-feature messages in both languages, contract-first domains, tests beside the feature. 2 = follows them; 1 = mostly; 0 = ignores them."
+    }),
+    Dimension.make({
+        name: "tests",
+        rubric: "The story ships deterministic tests in the house style covering its screens or contract. 2 = yes; 1 = thin; 0 = none."
+    })
+];
+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",
+        title: `judge[${story.id}]: ${score.name} scored ${score.score}`,
+        description: score.reasoning
+    })),
+    summary: `judge:${story.id}`
+});
+/** The story-level judge over the branch diff, bounded by the character budget. */
+export const judgeStory = (reasoning, story, diff, budget) => judge(reasoning, storyDimensions)
+    .evaluate(Sample.make({
+    query: [
+        `Story: ${story.title}`,
+        story.description,
+        "",
+        `Provides: ${story.provides.join(", ") || "(none)"}`,
+        `Owned paths: ${story.owned.join(", ")}`,
+        `Shared read-only: ${story.sharedReadOnly.join(", ") || "(none)"}`
+    ].join("\n"),
+    response: cap(diff, budget).text
+}))
+    .pipe(Effect.mapError(FlowLlmError.from), Effect.map((scored) => subBar(scored, story)));
+// ---- Worktree setup --------------------------------------------------------------
+export const defaultWorktreeSetup = ["pnpm", "install", "--offline"];
+/**
+ * `LLM4TS_WORKTREE_SETUP="pnpm install --offline"` (the default) prepares
+ * each story worktree; an empty value disables the step. Offline by default:
+ * the runbook warms the pnpm store once, and a workshop stage has no network.
+ */
+export const worktreeSetupCommand = (environment) => {
+    const raw = environment.LLM4TS_WORKTREE_SETUP;
+    if (raw === undefined) {
+        return defaultWorktreeSetup;
+    }
+    const parts = raw
+        .trim()
+        .split(/\s+/)
+        .filter((part) => part.length > 0);
+    return parts.length === 0 ? undefined : parts;
+};
+/** Runs the setup command in a worktree; a non-zero exit fails the story with the output. */
+export const setupIn = (process, events, command) => (workDir) => Effect.flatMap(lintCommand(process, events, command, workDir), (result) => result.isClean
+    ? Effect.void
+    : FlowAborted.make({
+        message: `worktree setup failed (${command.join(" ")}):\n${result.issues
+            .map((issue) => issue.description)
+            .join("\n")}`
+    }));
+// ---- Gates ---------------------------------------------------------------------
+export const defaultGateCommands = [
+    ["pnpm", "typecheck"],
+    ["pnpm", "lint"],
+    ["pnpm", "test"],
+    ["pnpm", "build"]
+];
+/** `LLM4TS_GATES="pnpm typecheck;pnpm test"` overrides the four defaults. */
+export const gateCommands = (environment) => {
+    const raw = environment.LLM4TS_GATES?.trim();
+    if (raw === undefined || raw.length === 0) {
+        return defaultGateCommands;
+    }
+    return raw
+        .split(";")
+        .map((command) => command
+        .trim()
+        .split(/\s+/)
+        .filter((part) => part.length > 0))
+        .filter((command) => command.length > 0);
+};
+/** Runs the gates in a directory, stopping at the first red one (later output would be noise). */
+export const gatesIn = (process, events, commands) => (workDir) => Effect.gen(function* () {
+    const results = [];
+    for (const command of commands) {
+        const result = yield* lintCommand(process, events, command, workDir);
+        results.push(result);
+        if (!result.isClean) {
+            break;
+        }
+    }
+    return mergeReviewResults(results);
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llm4ts/shell",
-  "version": "0.15.1",
+  "version": "0.16.1",
   "description": "Interactive shell and CLI for llm4ts: flow discovery, run-a-flow, and view",
   "license": "MIT",
   "type": "module",
@@ -49,10 +49,11 @@
   ],
   "dependencies": {
     "@effect/platform-node": "4.0.0-beta.102",
-    "@llm4ts/modernize": "0.15.1",
-    "@llm4ts/runner": "0.15.1",
-    "@llm4ts/core": "0.15.1",
-    "@llm4ts/flow": "0.15.1"
+    "@effect/platform-node-shared": "4.0.0-beta.102",
+    "@llm4ts/core": "0.16.1",
+    "@llm4ts/modernize": "0.16.1",
+    "@llm4ts/flow": "0.16.1",
+    "@llm4ts/runner": "0.16.1"
   },
   "peerDependencies": {
     "effect": "4.0.0-beta.102"