@llm4ts/shell 0.13.5 → 0.15.0

package/flows/convert-all.js

@@ -0,0 +1,152 @@
+// Convert the whole legacy estate: walk the survey inventory in wave order, one branch per page, progress board, estimated-cost migration report.
+//
+// Runs rooted at the TARGET repository (`--repo <nextjs>`), with
+// LLM4TS_LEGACY_REPO pointing at the extracted legacy repository:
+//
+//   LLM4TS_LEGACY_REPO=~/estates/demo-bank-legacy \
+//     llm4ts run convert-all --repo ~/estates/demo-bank-nextjs
+//
+// Order comes from the approved docs/modernization/wave-plan.md when present,
+// otherwise every extracted spec alphabetically. The board (a BoardSync port)
+// always writes the local files at .llm4ts/convert/board.{json,md}; when
+// LLM4TS_ADO_ORG_URL and LLM4TS_ADO_PROJECT are set, an Azure DevOps
+// work-item mirror is added via the az CLI (LLM4TS_ADO_REPO defaults to the
+// project; auth belongs to az itself — `az devops login` or
+// AZURE_DEVOPS_EXT_PAT, never an llm4ts variable, per ADR 0011).
+// A failing page is marked failed and the walk continues
+// (LLM4TS_FAIL_FAST=1 stops instead); pages already done on the board are
+// skipped, so re-running resumes. Every token/cost figure — including the
+// closing whole-estate projection in docs/conversion/migration-report.md —
+// is an ESTIMATE, and the report says so.
+import { basename, join } from "node:path";
+import * as Effect from "effect/Effect";
+import { AdoConfig, makeAzureDevOpsTool } from "@llm4ts/flow/AzureDevOpsTool";
+import { BoardItem, composeBoardSync, makeAdoBoardSync, makeLocalBoardSync } from "@llm4ts/flow/BoardSync";
+import { describeFlowError } from "@llm4ts/flow/FlowError";
+import { Info } from "@llm4ts/flow/FlowEvents";
+import { stage } from "@llm4ts/flow/PlanExecution";
+import { asReadOnly, coderFromEnv } 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 { conversionInventory, convertPage, migrationReport, setupConversion } from "./lib/convert.ts";
+const program = Effect.gen(function* () {
+    const input = yield* resolveFlowInput("Convert the legacy estate into the destination SPA");
+    const coder = coderFromEnv(process.env);
+    yield* runNode({
+        workDir: input.workDir,
+        workspace: input.workspace,
+        userPrompt: input.prompt,
+        coder,
+        reasoning: asReadOnly(coder),
+        reviewers: [asReadOnly(coder)],
+        environment: process.env
+    }, (context) => Effect.gen(function* () {
+        const deps = yield* setupConversion(context, input, process.env, import.meta.dirname);
+        const files = nodePlainFileStore;
+        const boardTitle = `Conversion: ${basename(input.workDir)}`;
+        const boards = [
+            makeLocalBoardSync(files, join(input.workDir, ".llm4ts", "convert"), boardTitle)
+        ];
+        const orgUrl = process.env.LLM4TS_ADO_ORG_URL?.trim();
+        const project = process.env.LLM4TS_ADO_PROJECT?.trim();
+        if (orgUrl !== undefined && orgUrl.length > 0 && project !== undefined) {
+            // az CLI owns the credentials (`az devops login` / AZURE_DEVOPS_EXT_PAT);
+            // no PAT ever passes through llm4ts configuration.
+            const ado = makeAzureDevOpsTool(AdoConfig.make({
+                orgUrl,
+                project,
+                repository: process.env.LLM4TS_ADO_REPO?.trim() || project
+            }), nodeProcessExecutor, input.workDir, context.events);
+            boards.push(yield* makeAdoBoardSync(ado, boardTitle));
+            yield* context.events.publish(Info.make({ message: `ADO board mirror enabled: ${orgUrl}/${project}` }));
+        }
+        const board = composeBoardSync(boards);
+        const inventory = yield* stage(context.events, "inventory", conversionInventory(files, deps.legacy, deps.legacyDir, deps.pack));
+        if (inventory.length === 0) {
+            yield* context.events.publish(Info.make({ message: "inventory is empty — extract the legacy estate first" }));
+            return;
+        }
+        // The whole estate lands on the board as planned up front — the
+        // breadth view exists from minute one.
+        yield* stage(context.events, "board", board.plan(inventory.map(({ page, wave }) => BoardItem.make({
+            id: page,
+            title: page,
+            status: "planned",
+            ...(wave === undefined ? {} : { wave })
+        }))));
+        const baseBranch = yield* context.git.currentBranch;
+        const failFast = process.env.LLM4TS_FAIL_FAST === "1";
+        for (const { page } of inventory) {
+            const snapshot = yield* board.snapshot;
+            const known = snapshot.items.find((item) => item.id === page);
+            if (known !== undefined && known.status !== "planned" && known.status !== "failed") {
+                yield* context.events.publish(Info.make({ message: `resume: ${page} is already ${known.status} — skipping` }));
+                continue;
+            }
+            const specPath = join(deps.legacyDir, deps.pack.specsDir, `${page}.md`);
+            if ((yield* files.read(specPath)) === undefined) {
+                yield* board.skip(page, "no extracted spec");
+                continue;
+            }
+            const checkpoint = yield* context.git.checkpoint;
+            yield* board.start(page);
+            const result = yield* Effect.result(convertPage(deps, page));
+            if (result._tag === "Success") {
+                const outcome = result.success;
+                yield* board.complete(page, {
+                    branch: outcome.branch,
+                    reportPath: outcome.reportPath,
+                    ...(outcome.estimatedTokens === undefined
+                        ? {}
+                        : { estimatedTokens: outcome.estimatedTokens }),
+                    ...(outcome.estimatedCostUsd === undefined
+                        ? {}
+                        : { estimatedCostUsd: outcome.estimatedCostUsd })
+                });
+                yield* context.git.checkout(baseBranch);
+            }
+            else {
+                const reason = describeFlowError(result.failure);
+                // A stuck page must not sink the walk: reset the working tree,
+                // mark the failure, keep going (LLM4TS_FAIL_FAST=1 to stop).
+                yield* context.git.rollback(checkpoint);
+                yield* context.git.checkout(baseBranch);
+                yield* board.fail(page, reason);
+                if (failFast) {
+                    return yield* Effect.fromResult(result);
+                }
+                yield* context.events.publish(Info.make({ message: `page ${page} failed — continuing: ${reason}` }));
+            }
+        }
+        const finalBoard = yield* board.snapshot;
+        const rows = finalBoard.items.flatMap((item) => item.status === "done" || item.status === "failed" || item.status === "skipped"
+            ? [
+                {
+                    page: item.id,
+                    outcome: item.status,
+                    ...(item.detail === undefined ? {} : { detail: item.detail }),
+                    ...(item.estimatedTokens === undefined
+                        ? {}
+                        : { estimatedTokens: item.estimatedTokens }),
+                    ...(item.estimatedCostUsd === undefined
+                        ? {}
+                        : { estimatedCostUsd: item.estimatedCostUsd })
+                }
+            ]
+            : []);
+        const remaining = finalBoard.items
+            .filter((item) => item.status === "planned" || item.status === "failed")
+            .map((item) => item.id);
+        yield* stage(context.events, "report", files
+            .writeAtomic(join(input.workDir, "docs", "conversion", "migration-report.md"), migrationReport(rows, remaining))
+            .pipe(Effect.andThen(context.git.commitAll("convert: migration report and board"))));
+        yield* context.events.publish(Info.make({
+            message: `estate walk complete — ${rows.filter((row) => row.outcome === "done").length} ` +
+                `converted, ${remaining.length} remaining; ` +
+                "report: docs/conversion/migration-report.md (all figures estimated)"
+        }));
+    }));
+});
+runFlowMain(program);

package/flows/convert-page.js

@@ -0,0 +1,56 @@
+// Convert ONE legacy J2EE page into the destination Next.js SPA: branch per page, contract-first mocked ACL, judged gates, estimated costs.
+//
+// Runs rooted at the TARGET repository (`--repo <nextjs>`), with
+// LLM4TS_LEGACY_REPO pointing at the extracted legacy repository. The task
+// text is the page name (the program name of its extracted spec):
+//
+//   LLM4TS_LEGACY_REPO=~/estates/demo-bank-legacy \
+//     llm4ts run convert-page --repo ~/estates/demo-bank-nextjs accountOverview
+//
+// Not clean-room (ADR 0012): the coder gets the schema-validated Page Spec as
+// contract plus bounded legacy source evidence, the destination's own pages as
+// style guide, and a deterministically generated OpenAPI anti-corruption
+// contract. Gates: typecheck+lint+test per task, test+build to finish, then a
+// per-page spec-compliance judge with bounded feedback rounds
+// (LLM4TS_JUDGE_ROUNDS). One branch `convert/<page>` per run, no PR — the
+// branch awaits human review; the conversion report is committed with it.
+// Token/cost figures are ESTIMATES (LLM4TS_ESTIMATE_MODEL,
+// LLM4TS_ESTIMATE_CHARS_PER_TOKEN). Pack: LLM4TS_PACK (default
+// packs/j2ee-nextjs-spa).
+import * as Effect from "effect/Effect";
+import { FlowAborted } from "@llm4ts/flow/FlowError";
+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";
+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] ?? "";
+    const coder = coderFromEnv(process.env);
+    yield* runNode({
+        workDir: input.workDir,
+        workspace: input.workspace,
+        userPrompt: input.prompt,
+        coder,
+        reasoning: asReadOnly(coder),
+        reviewers: [asReadOnly(coder)],
+        environment: process.env
+    }, (context) => Effect.gen(function* () {
+        if (page.length === 0) {
+            return yield* FlowAborted.make({
+                message: "pass the page name to convert, e.g.: llm4ts run convert-page accountOverview"
+            });
+        }
+        const deps = yield* setupConversion(context, input, process.env, import.meta.dirname);
+        const outcome = yield* convertPage(deps, page);
+        yield* context.events.publish(Info.make({
+            message: `converted ${outcome.page} on branch ${outcome.branch} — ` +
+                `report at ${outcome.reportPath}` +
+                (outcome.estimatedTokens === undefined
+                    ? ""
+                    : ` (~${outcome.estimatedTokens} tokens estimated)`)
+        }));
+    }));
+});
+runFlowMain(program);

package/flows/modernize-bench.js

@@ -99,7 +99,7 @@ const program = Effect.gen(function* () {
             phases.push(makeBenchPhase(observation, name, Date.now() - began));
             return value;
         });
-        const programs = yield* measured("inventory", matchingFiles(estate, pack.programs ?? pack.sources ?? ".*"));
+        const programs = yield* measured("inventory", matchingFiles(estate, pack.programs ?? pack.sources ?? ".*", pack.exclude));
         if (programs.length === 0) {
             return yield* FlowAborted.make({
                 message: `no source units matched the pack's programs/sources regex under ${input.workDir}`

package/flows/modernize-extract.js

@@ -24,8 +24,13 @@
 // context is bounded by LLM4TS_CONTEXT_BUDGET (chars;
 // LLM4TS_JUDGE_SOURCES_LIMIT is the deprecated alias). The analyst is bounded
 // by LLM4TS_ANALYST_TURNS and LLM4TS_MAX_CLOSURE_FILES.
+// LLM4TS_EXTRACT_CONCURRENCY=<n> extracts and judges n programs at once (default
+// 1): the programs of a wave are independent, each gets a commit scoped to its
+// own files, and a failure lets in-flight programs finish before it surfaces.
 import { join } from "node:path";
 import * as Effect from "effect/Effect";
+import * as Ref from "effect/Ref";
+import * as Semaphore from "effect/Semaphore";
 import { Sample } from "@llm4ts/core/eval/Eval";
 import { judge } from "@llm4ts/core/eval/Judge";
 import { budget, capped, withShrink } from "@llm4ts/flow/Context";
@@ -42,7 +47,7 @@ import { cachedReview } from "@llm4ts/flow/ReviewCache";
 import { coverage, coverageUnits, features, matchingFiles } from "@llm4ts/flow/SpecChecks";
 import { SurveyGraph, closureFor, surveyGraph } from "@llm4ts/flow/Survey";
 import { withDraftApproval, requireApproval } from "@llm4ts/modernize/Approval";
-import { ProgramArtifacts, ProgramUnit, extractProgramsResumably } from "@llm4ts/modernize/Artifacts";
+import { ProgramArtifacts, ProgramUnit, extractProgramsResumably, programArtifactPaths } from "@llm4ts/modernize/Artifacts";
 import { asReadOnly, coderFromEnv, withTurnLimit } from "@llm4ts/runner/Connectors";
 import { resolveFlowInput } from "@llm4ts/runner/FlowArgs";
 import { runFlowMain, runNode } from "@llm4ts/runner/FlowRunner";
@@ -63,6 +68,14 @@ const analystTurns = () => positiveEnvInt("LLM4TS_ANALYST_TURNS", 48);
  * than this gets a bounded, visible subset rather than an unbounded read.
  */
 const maxClosureFiles = () => positiveEnvInt("LLM4TS_MAX_CLOSURE_FILES", 40);
+/**
+ * Programs extracted (and judged) at once. The programs of a wave are
+ * independent — each analyst reads its source and resolved closure, writes
+ * its own four files, and gets its own scoped commit — so this divides wall
+ * time without changing tokens or cost. Default 1 keeps the sequential
+ * narration; the bound is about the coder seat's quota, not correctness.
+ */
+const extractConcurrency = () => positiveEnvInt("LLM4TS_EXTRACT_CONCURRENCY", 1);
 /** `cobol/ACCTXFR.cbl` → `ACCTXFR`: the program name keying every per-program artifact. */
 const programName = (relativePath) => {
     const base = relativePath.slice(relativePath.lastIndexOf("/") + 1);
@@ -203,7 +216,7 @@ const program = Effect.gen(function* () {
         ]
             .filter((part) => part !== undefined)
             .join("\n\n");
-        const all = yield* stage(context.events, "inventory", matchingFiles(repo, pack.programs ?? pack.sources ?? ".*"));
+        const all = yield* stage(context.events, "inventory", matchingFiles(repo, pack.programs ?? pack.sources ?? ".*", pack.exclude));
         const wave = process.env.LLM4TS_WAVE?.trim();
         const programs = wave === undefined || wave.length === 0
             ? all
@@ -239,35 +252,48 @@ const program = Effect.gen(function* () {
                 message: "pack has no '## Survey:' edge regexes — the analyst gets no resolved closure"
             }))
                 .pipe(Effect.as(SurveyGraph.make({ nodes: [], edges: [] })))
-            : surveyGraph(repo, pack.sources ?? ".*", pack.coverage, pack.survey));
+            : surveyGraph(repo, pack.sources ?? ".*", pack.coverage, pack.survey, {
+                ...(pack.exclude === undefined ? {} : { exclude: pack.exclude })
+            }));
         // One structured analyst call per program, resumable per program: a rerun
-        // skips every program whose spec exists, and each program gets its own commit.
+        // skips every program whose spec exists, and each program gets its own
+        // commit scoped to its four files. LLM4TS_EXTRACT_CONCURRENCY runs that
+        // many programs at once; the commit is the one step serialised.
+        const concurrency = extractConcurrency();
         yield* stage(context.events, "extract", Effect.gen(function* () {
-            for (const [index, unit] of units.entries()) {
-                const summary = yield* extractProgramsResumably(files, [unit], (target) => Effect.gen(function* () {
+            const started = yield* Ref.make(0);
+            const commitLock = yield* Semaphore.make(1);
+            if (concurrency > 1) {
+                yield* context.events.publish(Info.make({
+                    message: `extracting up to ${concurrency} program(s) at once (LLM4TS_EXTRACT_CONCURRENCY)`
+                }));
+            }
+            const summary = yield* extractProgramsResumably(files, units, (target) => Effect.gen(function* () {
+                const ordinal = yield* Ref.updateAndGet(started, (count) => count + 1);
+                yield* context.events.publish(Info.make({
+                    message: `extracting ${target.sourcePath} (${ordinal}/${units.length})`
+                }));
+                return yield* structuredAndPublish(context.coder, context.events, `${system}\n\n${programAsk(pack, target.sourcePath, closureFor(graph, target.name, maxClosureFiles()))}`, ProgramArtifacts, programArtifactsJsonSchema, "coder").pipe(
+                // A turn-limit trip is the wedged-agent tail, not a
+                // failure: keep whatever the analyst already produced.
+                Effect.catchIf((error) => error.cause?._tag === "TurnLimitError", (error) => Effect.gen(function* () {
+                    const existing = yield* files.read(join(modDirAbs, "specs", `${target.name}.md`));
+                    if (existing === undefined) {
+                        return yield* Effect.fail(error);
+                    }
                     yield* context.events.publish(Info.make({
-                        message: `extracting ${target.sourcePath} (${index + 1}/${units.length})`
+                        message: `turn limit hit on ${target.sourcePath} after its spec was written — keeping the work`
                     }));
-                    return yield* structuredAndPublish(context.coder, context.events, `${system}\n\n${programAsk(pack, target.sourcePath, closureFor(graph, target.name, maxClosureFiles()))}`, ProgramArtifacts, programArtifactsJsonSchema, "coder").pipe(
-                    // A turn-limit trip is the wedged-agent tail, not a
-                    // failure: keep whatever the analyst already produced.
-                    Effect.catchIf((error) => error.cause?._tag === "TurnLimitError", (error) => Effect.gen(function* () {
-                        const existing = yield* files.read(join(modDirAbs, "specs", `${target.name}.md`));
-                        if (existing === undefined) {
-                            return yield* Effect.fail(error);
-                        }
-                        yield* context.events.publish(Info.make({
-                            message: `turn limit hit on ${target.sourcePath} after its spec was written — keeping the work`
-                        }));
-                        return ProgramArtifacts.make({
-                            spec: existing,
-                            feature: "",
-                            traceability: "",
-                            mapping: ""
-                        });
-                    })));
-                }), modDirAbs);
-                if (summary.created.length > 0) {
+                    return ProgramArtifacts.make({
+                        spec: existing,
+                        feature: "",
+                        traceability: "",
+                        mapping: ""
+                    });
+                })));
+            }), modDirAbs, {
+                concurrency,
+                onCreated: (unit) => Effect.gen(function* () {
                     // Tag the traceability fragment with the cards this program's
                     // source matches — regex-decided, so implementation's playbook
                     // is reproducible.
@@ -278,15 +304,18 @@ const program = Effect.gen(function* () {
                         const fragment = (yield* files.read(fragmentPath)) ?? "";
                         yield* files.writeAtomic(fragmentPath, `${fragment.trimEnd()}\n\nPatterns: ${matched.map((card) => card.id).join(", ")}\n`);
                     }
-                    yield* context.git
-                        .commitAll(`modernize(${pack.name}): spec ${unit.name}`)
-                        .pipe(Effect.asVoid);
-                }
-                else {
-                    yield* context.events.publish(Info.make({
-                        message: `resume: specs/${unit.name}.md exists — skipping ${unit.sourcePath}`
-                    }));
-                }
+                    // Only this program's files, under one permit: a concurrent
+                    // sibling's half-written artifacts must never ride along.
+                    yield* commitLock.withPermit(context.git
+                        .commitPaths(`modernize(${pack.name}): spec ${unit.name}`, programArtifactPaths(unit, ModDir))
+                        .pipe(Effect.asVoid));
+                })
+            });
+            if (summary.skipped.length > 0) {
+                yield* context.events.publish(Info.make({
+                    message: `resume: ${summary.skipped.length} program(s) already have a spec — skipped ` +
+                        summary.skipped.join(", ")
+                }));
             }
         }));
         // traceability.md / mapping.md are regenerated from the fragments — fixes
@@ -377,10 +406,9 @@ const program = Effect.gen(function* () {
             });
             const covered = yield* coverage(repo, pack.coverage, trace);
             const wellFormed = yield* features(repo, join(ModDir, "features"));
-            const judged = [];
-            for (const unit of units) {
-                judged.push(yield* judgeProgram(unit));
-            }
+            // Verdicts are per program and cached per program, so they judge
+            // under the same bound as extraction; the merge is order-stable.
+            const judged = yield* Effect.forEach(units, judgeProgram, { concurrency });
             return mergeReviewResults([covered, wellFormed, docs, ...judged]);
         });
         // One bounded fix turn per sub-bar program (own commit) plus one residual

package/flows/packs/cobol-kafka/prompts/survey-refine.md

@@ -0,0 +1,7 @@
+Regexes miss links in complex COBOL/JCL sources: dynamic CALLs (CALL WS-PROGRAM
+where the target sits in WORKING-STORAGE), JCL symbolic parameters (EXEC
+PGM=&PGM set earlier in the job or in a PROC), PROC expansions, control cards
+and SYSIN members naming programs, and COPY REPLACING variants. Prioritise jobs
+with fewer outgoing edges than steps, programs nothing references, and copybooks
+with degree 0. Calls to system or runtime services (CEE*, DFH*, IGZ*, SQL
+preprocessor stubs) are not estate edges — note them.

package/flows/packs/cobol-kafka/prompts/survey-triage.md

@@ -0,0 +1,8 @@
+Units are COBOL programs, copybooks, and JCL jobs. Copybooks with many callers
+are shared data contracts — migrate them with their first consumer or wrap them.
+Jobs are scheduler entry points: a job nothing calls is still live if a
+scheduler runs it, so it is a "wrap" (keep on the platform, front with an API)
+until every program it steps through has been rewritten, never a "retire" on
+graph evidence alone. Programs with no callers and no job step are the retire
+candidates; give the degree evidence. Batch windows and EOD chains make good
+wave boundaries: keep a job's step programs in the same or an earlier wave.

package/flows/packs/cobol-springboot/prompts/survey-refine.md

@@ -0,0 +1,7 @@
+Regexes miss links in complex COBOL/JCL sources: dynamic CALLs (CALL WS-PROGRAM
+where the target sits in WORKING-STORAGE), JCL symbolic parameters (EXEC
+PGM=&PGM set earlier in the job or in a PROC), PROC expansions, control cards
+and SYSIN members naming programs, and COPY REPLACING variants. Prioritise jobs
+with fewer outgoing edges than steps, programs nothing references, and copybooks
+with degree 0. Calls to system or runtime services (CEE*, DFH*, IGZ*, SQL
+preprocessor stubs) are not estate edges — note them.

package/flows/packs/cobol-springboot/prompts/survey-triage.md

@@ -0,0 +1,8 @@
+Units are COBOL programs, copybooks, and JCL jobs. Copybooks with many callers
+are shared data contracts — migrate them with their first consumer or wrap them.
+Jobs are scheduler entry points: a job nothing calls is still live if a
+scheduler runs it, so it is a "wrap" (keep on the platform, front with an API)
+until every program it steps through has been rewritten, never a "retire" on
+graph evidence alone. Programs with no callers and no job step are the retire
+candidates; give the degree evidence. Batch windows and EOD chains make good
+wave boundaries: keep a job's step programs in the same or an earlier wave.

package/flows/packs/j2ee-nextjs-spa/pack.md

@@ -0,0 +1,48 @@
+# Pack: j2ee-nextjs-spa
+
+source: jsp
+scaffold: ../../fixtures/scaffolds/nextjs-spa
+sources: .*\.(jsp|java|xml)
+programs: .*\.jsp
+specs-dir: docs/modernization/specs
+features-dir: docs/modernization/features
+programFiles: (?:src/app/<NAME>(?:/.*)?|src/services/<NAME>(?:/.*)?|contracts/<NAME>\.openapi\.yaml|tests/<NAME>\..*)
+
+## Gates
+
+- typecheck: pnpm typecheck
+- lint: pnpm lint
+- test: pnpm test
+- build: pnpm build
+
+## Judge
+
+- completeness (0..2): Every screen, servlet mapping (web.xml url-pattern), form field, navigation path, validation rule (client AND server side), user-facing message, session attribute, and API/ESB call in the JSP/servlet source is captured in the spec and BDD scenarios. Score 2 only if nothing material is missing.
+- faithfulness (0..2): Every statement is grounded in the source: validation thresholds, exact message texts, redirect targets, session behaviour, DTO field names, and which ESB service each endpoint wraps match the code, and nothing is invented. Score 2 only if fully source-grounded.
+- testability (0..2): Scenarios are concrete user journeys — specific accounts, amounts, and the exact message or destination screen expected; no vague language ("shows an error", "handled gracefully"). Score 2 only if every scenario is directly encodable as a test.
+- pagespec (0..2): The spec contains exactly one ```json pagespec fenced block; its forms, apiCalls (with esbService), dtos (legacy→domain rename table), navigation, and sessionState agree with the prose and with the source; domain names are business language, never legacy abbreviations. Score 2 only if the block is present, consistent, and complete.
+
+## Coverage: servlet-url
+
+files: .*web\.xml
+unit: <url-pattern>([^<]+)</url-pattern>
+
+## Coverage: jsp-form
+
+files: .*\.jsp
+unit: action="([^"]+)"
+
+## Coverage: jsp-ajax
+
+files: .*\.jsp
+unit: url:\s*['"]([^'"]+)['"]
+
+## Survey: jsp-include
+
+files: .*\.jsp
+unit: <jsp:include page="([^"]+)"
+
+## Survey: servlet-class
+
+files: .*web\.xml
+unit: <servlet-class>[a-z.]*\.([A-Za-z0-9]+)</servlet-class>

package/flows/packs/j2ee-nextjs-spa/patterns/PAT-J2EE-001-jstl-table.md

@@ -0,0 +1,8 @@
+---
+match: <c:forEach|<%[^=]*for\s*\(
+---
+A JSTL/scriptlet row loop becomes the destination DataTable component with
+declarative columns: the loop body's cells map to column render functions, and
+status-code-to-label mappings move into a typed lookup beside the page. The
+data comes from a port call in an effect on mount — never fetched in the
+component body, never re-sorted client-side unless the legacy page sorted.

package/flows/packs/j2ee-nextjs-spa/patterns/PAT-J2EE-002-jquery-validation.md

@@ -0,0 +1,8 @@
+---
+match: \$\(['"]#|validate\.js|onsubmit=
+---
+jQuery/inline validation becomes the house Form component's validation map:
+one entry per spec rule, message text VERBATIM, evaluated in the spec's order
+(first-failure-wins). Where the legacy client and server rules diverged, the
+spec's per-rule enforcedAt says which set is contract — implement the union,
+flag any contradiction as an open question rather than silently choosing.

package/flows/packs/j2ee-nextjs-spa/patterns/PAT-J2EE-003-session-stepper.md

@@ -0,0 +1,9 @@
+---
+match: HttpSession|session\.setAttribute|session\.getAttribute
+---
+An HttpSession-carried multi-step flow becomes explicit client state driven by
+the destination Stepper: one state object typed after the spec's sessionState
+(the legacy draft DTO, domain-renamed), owned by the flow's top-level page,
+passed down per step. Refresh/back semantics are explicit — the legacy app got
+them free from the session; the SPA must decide and the spec's navigation
+section says what to preserve. Never scatter the draft across components.

package/flows/packs/j2ee-nextjs-spa/patterns/PAT-J2EE-004-esb-port.md

@@ -0,0 +1,10 @@
+---
+match: Esb[A-Za-z]+Service|ESB_[A-Z_]+
+---
+Every EsbXxxService wrapper the servlet called becomes one port operation in
+the page's anti-corruption contract: the OpenAPI operation carries the domain
+name, the port interface mirrors it, and the mock adapter returns
+contract-shaped fixtures. The ESB routine name lands in the contract's
+description (the future B4F team's pointer), never in code identifiers. If the
+servlet combined two ESB calls, the port exposes the page's need (one
+operation), and the composition note goes in the contract description.

package/flows/packs/j2ee-nextjs-spa/patterns/PAT-J2EE-005-include-shell.md

@@ -0,0 +1,8 @@
+---
+match: <jsp:include|<%@\s*include
+---
+header/nav/footer jsp:include shells are ALREADY provided by the destination
+app shell (layout + PageLayout) — a converted page never re-renders chrome.
+Map the legacy page body into PageLayout's slots, and turn nav.jsp links into
+the routes of pages that exist (converted or exemplar); links to not-yet-
+converted pages stay out of nav rather than dangling.

package/flows/packs/j2ee-nextjs-spa/prompts/analysis.md

@@ -0,0 +1,27 @@
+You are a legacy-web reverse-engineering analyst on a bank modernization. Extract
+the COMPLETE observable behaviour of one J2EE/JSP page into a Page Spec precise
+enough that a converter who prefers the spec (but may consult the source) can
+rebuild it inside an existing Next.js SPA.
+
+How to read the app:
+
+- Start from WEB-INF/web.xml: every url-pattern is an entry point and must be
+  accounted for.
+- Servlets carry the behaviour: request-parameter validation (exact rules AND
+  exact error message texts), session reads/writes, redirects vs forwards, and
+  every ESB service call behind each endpoint (the EsbXxxService wrappers name
+  the routine — record it; ALL business logic lives behind those services and
+  must NEVER be reimplemented client-side).
+- JSPs carry the screens: what is displayed per row, status-code-to-label
+  mappings, forms (fields, hidden fields, where they submit), links between
+  screens, and every jQuery $.ajax call.
+- Client-side jQuery validation and server-side servlet validation often
+  DIVERGE — record each rule with where it is enforced (client, server, both);
+  the divergences are findings, not noise.
+- Hidden fields and HttpSession attributes are STATE the SPA must own
+  explicitly — document what flows through them.
+- DTO classes use abbreviated legacy names (acctNo, curBal): propose a domain
+  rename for every field — the anti-corruption table.
+
+Never invent behaviour; message texts and thresholds are contract — record them
+verbatim. Genuinely ambiguous behaviour goes in "Open questions", not guesses.

package/flows/packs/j2ee-nextjs-spa/prompts/bdd.md

@@ -0,0 +1,13 @@
+Write Gherkin .feature files encoding the spec as executable user journeys —
+these become the component tests of the converted page.
+
+- One feature per screen/flow.
+- User vocabulary, not servlet vocabulary: "When she submits a transfer of
+  3000.00, Then she is asked to confirm", not "doPost forwards to confirm.jsp".
+- Error messages are asserted VERBATIM — they are contract.
+- Concrete values everywhere: real account numbers, amounts, statuses from the
+  fixture data.
+- Cover: the happy path, EVERY validation rule and its message (noting whether
+  the legacy app enforced it client-side, server-side, or both), threshold
+  boundaries, confirmation flows, and the state that must survive navigation
+  (what the session or hidden fields carried).

package/flows/packs/j2ee-nextjs-spa/prompts/implement.md

@@ -0,0 +1,26 @@
+You convert one legacy J2EE page into an existing client-only Next.js SPA, one
+task at a time. The Page Spec is the contract; the legacy source excerpts you
+are given are evidence for disambiguation — prefer the spec, and when you must
+lean on the source, keep domain names, never legacy abbreviations.
+
+Non-negotiables:
+
+- Read the destination repo's CONTRIBUTING.md and the existing pages under
+  src/app/ FIRST and imitate them: same design-system components, same form
+  handling, same port/adapter shape, same test style. "Code the new like what
+  we have."
+- ALL business logic stays behind the service port — the mock adapter fakes
+  transport, never rules. If the legacy page computed something server-side
+  (fees, limits, validation of business state), that is a port operation, not
+  client code.
+- Components never call fetch; only adapters touch transport. Pages depend on
+  the port through the registry, so the mock swaps for the real gateway later
+  without touching the page.
+- Validation error messages match the spec VERBATIM, in the spec's order.
+- Session attributes and hidden-field flows become explicit client state
+  (the Stepper pattern for multi-step flows) — never re-derive a value the
+  legacy app carried through the session.
+- Legacy DTO names must not appear anywhere in the new code — use the spec's
+  domain renames. Money is exact decimals, never floats.
+- TypeScript strict, no `any`, no type assertions; typecheck, lint, test, and
+  build must all stay green.

package/flows/packs/j2ee-nextjs-spa/prompts/plan.md

@@ -0,0 +1,17 @@
+Derive the conversion task list for ONE page from its Page Spec. The
+destination is an existing Next.js SPA with a design system, an AuthProvider,
+and a port/adapter service convention — imitate it, never fight it.
+
+- Task 1: the anti-corruption service layer — the typed port interface under
+  src/services/<page>/port.ts matching the OpenAPI contract at
+  contracts/<page>.openapi.yaml (domain names only), a mock adapter under
+  src/services/<page>/mock.ts returning contract-shaped fixture data, and the
+  registry wiring. No page code yet.
+- Task 2: the page component(s) under src/app/<page>/ using ONLY the
+  destination design-system components and the port — forms, validation with
+  VERBATIM messages, navigation, and explicit state for anything the legacy
+  app carried in the session or hidden fields.
+- Task 3: component tests under tests/<page>.page.test.tsx in the house test
+  style — spec'd fields render, spec'd validations fire with their exact
+  messages, the port is called with contract-shaped payloads. Nothing else.
+- Each task names the spec rules and scenarios it covers.

package/flows/packs/j2ee-nextjs-spa/prompts/review.md

@@ -0,0 +1,17 @@
+You review a finished conversion increment: a page ported from a J2EE/JSP app
+into an existing Next.js SPA with a design system and a port/adapter service
+convention. Judge the implementation against the Page Spec and the destination
+house rules, not your own taste.
+
+Look specifically for:
+
+- Message drift: validation texts that differ from the spec's verbatim
+  messages, or rules evaluated out of the spec's order.
+- ACL leaks: fetch outside adapters, legacy DTO names in new code, business
+  logic implemented client-side, a mock adapter embedding rules.
+- Contract drift: port methods that do not match the generated OpenAPI
+  contract's operations and shapes.
+- State regressions: session-carried or hidden-field state the legacy app had
+  that the SPA lost (multi-step drafts, confirmation data across steps).
+- House drift: hand-rolled UI where a design-system component exists, ad-hoc
+  styling, tests outside the house style.

package/flows/packs/j2ee-nextjs-spa/prompts/spec.md

@@ -0,0 +1,34 @@
+The spec markdown for a page has two mandatory parts:
+
+1. Prose sections: Screen (layout, displayed data, status label mappings),
+   Forms (each field: name, label, type, required; each validation rule with
+   its VERBATIM message and where it is enforced — client, server, or both),
+   Navigation (inbound links, outbound links/redirects, step order for
+   multi-step flows), API (each endpoint: method, path, request/response
+   fields, and the ESB service it wraps), Session state, Anti-corruption
+   renames (every legacy DTO field → proposed domain name), Open questions.
+
+2. EXACTLY ONE fenced block starting with ```json pagespec containing a JSON
+   object with this shape (all names in domain language where marked):
+
+   {
+     "page": "<program name, e.g. accountOverview>",
+     "route": "<legacy url-pattern>",
+     "title": "<screen title>",
+     "complexity": "low" | "medium" | "high",
+     "forms": [{ "name", "action", "fields": [{ "name", "label", "type",
+       "required", "validations": [{ "rule", "message", "enforcedAt":
+       "client"|"server"|"both" }] }] }],
+     "dtos": [{ "legacyName", "domainName", "fields": [{ "legacyName",
+       "domainName", "type" }] }],
+     "apiCalls": [{ "operation": "<domain verb, e.g. listAccounts>",
+       "method", "path", "esbService", "request": [{ "legacyName",
+       "domainName", "type" }], "response": [{ ... }] }],
+     "navigation": { "inbound": [], "outbound": [], "steps": [] },
+     "sessionState": ["<what the session carries and why>"],
+     "openQuestions": []
+   }
+
+The block is machine-validated downstream: malformed JSON or a missing block
+fails the page. The JSON and the prose must agree — the JSON is the contract,
+the prose is the evidence.

package/flows/packs/j2ee-nextjs-spa/prompts/survey-refine.md

@@ -0,0 +1,22 @@
+This is a J2EE web application: units are JSP pages and fragments, servlets and
+supporting Java classes, and deployment descriptors. Regexes miss most of the
+links such an application establishes indirectly:
+
+- WEB-INF/web.xml: every servlet-mapping ties a url-pattern to a servlet; every
+  servlet-class names a Java unit; welcome-file and error-page entries name
+  JSPs. A JSP form action, link, or redirect that targets a url-pattern is an
+  edge from the JSP to the servlet behind it.
+- Servlets: request.getRequestDispatcher(...).forward/include and
+  response.sendRedirect(...) name the JSP or url-pattern they hand off to;
+  new/injected service and DAO classes are outgoing edges to those units.
+- JSPs: static includes (<%@ include file="…" %>), dynamic includes
+  (<jsp:include page="…">), <jsp:forward>, <a href="…">, <form action="…">,
+  jQuery $.ajax / $.get / $.post url targets, and JSTL <c:import>/<c:url>.
+  Resolve a path to the unit whose file name (without extension) matches.
+- Tag libraries and shared layout fragments (header, footer, navigation) are
+  units only when they are files in the inventory.
+
+Prioritise JSPs with zero incoming edges (are they reached through web.xml or
+a redirect?), servlets nothing maps to, and fragments nothing includes. Calls to
+the ESB, application-server services, and third-party libraries are not estate
+edges — note them.

package/flows/packs/j2ee-nextjs-spa/prompts/survey-triage.md

@@ -0,0 +1,20 @@
+Units are JSP pages, JSP fragments (headers, footers, navigation, included
+partials), servlets, DTO/service classes, and web.xml. Judge them as a web
+estate, not a batch one:
+
+- A page reached through a web.xml url-pattern, a link, a form action, or a
+  redirect is live even when the regex graph shows few callers — check the
+  refine notes before calling it dead. A page nothing reaches and nothing
+  includes is the retire candidate; give the evidence.
+- Fragments with many includers are layout, not business logic: they are
+  migrated with the first page that needs them (same wave) rather than as a
+  wave of their own, and never "retire" while a live page includes them.
+- Servlets and service classes that only front an ESB or backend service are
+  "wrap" candidates: the modernized application keeps calling the same
+  service through a port, and their business rules must not be re-implemented.
+- web.xml and other descriptors are configuration, not migration units:
+  disposition "wrap" with a one-line rationale.
+
+Waves are user journeys: keep a page, the servlet it posts to, and the
+fragments it includes together; simple read-only screens first, then CRUD
+screens, then multi-step session-backed flows last.

package/flows/packs/j2ee-nextjs-spa/reviewers/acl-purity.md

@@ -0,0 +1,12 @@
+You review one conversion increment for anti-corruption discipline. Judge the
+diff against the Page Spec, not your taste. Flag as Critical:
+
+- Any fetch/XMLHttpRequest/axios call outside a service adapter module.
+- Any legacy DTO field name (acctNo-style abbreviations) in page code, port
+  types, or tests — the spec's domain renames are mandatory.
+- Business logic in the client: fee/limit/eligibility calculations, rules the
+  legacy servlet or ESB service owned, or a mock adapter that embeds rules
+  instead of returning contract-shaped data.
+- A page importing a mock adapter directly instead of going through the
+  registry/port seam.
+- Port methods that do not match the OpenAPI contract's operations and shapes.

package/flows/packs/j2ee-nextjs-spa/reviewers/house-style.md

@@ -0,0 +1,13 @@
+You review one conversion increment for destination-repo fidelity — the new
+page must read as if the resident team wrote it. Judge the diff against the
+destination's CONTRIBUTING.md and its existing pages. Flag as Major:
+
+- Hand-rolled UI where a design-system component exists (raw <table> instead
+  of DataTable, raw <input>+<label> instead of Field, ad-hoc wizard state
+  instead of Stepper).
+- Styling outside the token/component classes: inline style objects, new CSS
+  files, hard-coded colors.
+- Form handling that bypasses the house Form component's validation map.
+- Tests that diverge from the house style (different render helpers, missing
+  AuthProvider wrapper, snapshot tests where the exemplars assert behaviour).
+- Auth handled ad hoc instead of through useAuth()/AuthProvider.

package/flows/packs/jsp-bff-nextjs/prompts/survey-refine.md

@@ -0,0 +1,22 @@
+This is a J2EE web application: units are JSP pages and fragments, servlets and
+supporting Java classes, and deployment descriptors. Regexes miss most of the
+links such an application establishes indirectly:
+
+- WEB-INF/web.xml: every servlet-mapping ties a url-pattern to a servlet; every
+  servlet-class names a Java unit; welcome-file and error-page entries name
+  JSPs. A JSP form action, link, or redirect that targets a url-pattern is an
+  edge from the JSP to the servlet behind it.
+- Servlets: request.getRequestDispatcher(...).forward/include and
+  response.sendRedirect(...) name the JSP or url-pattern they hand off to;
+  new/injected service and DAO classes are outgoing edges to those units.
+- JSPs: static includes (<%@ include file="…" %>), dynamic includes
+  (<jsp:include page="…">), <jsp:forward>, <a href="…">, <form action="…">,
+  jQuery $.ajax / $.get / $.post url targets, and JSTL <c:import>/<c:url>.
+  Resolve a path to the unit whose file name (without extension) matches.
+- Tag libraries and shared layout fragments (header, footer, navigation) are
+  units only when they are files in the inventory.
+
+Prioritise JSPs with zero incoming edges (are they reached through web.xml or
+a redirect?), servlets nothing maps to, and fragments nothing includes. Calls to
+the ESB, application-server services, and third-party libraries are not estate
+edges — note them.

package/flows/packs/jsp-bff-nextjs/prompts/survey-triage.md

@@ -0,0 +1,20 @@
+Units are JSP pages, JSP fragments (headers, footers, navigation, included
+partials), servlets, DTO/service classes, and web.xml. Judge them as a web
+estate, not a batch one:
+
+- A page reached through a web.xml url-pattern, a link, a form action, or a
+  redirect is live even when the regex graph shows few callers — check the
+  refine notes before calling it dead. A page nothing reaches and nothing
+  includes is the retire candidate; give the evidence.
+- Fragments with many includers are layout, not business logic: they are
+  migrated with the first page that needs them (same wave) rather than as a
+  wave of their own, and never "retire" while a live page includes them.
+- Servlets and service classes that only front an ESB or backend service are
+  "wrap" candidates: the modernized application keeps calling the same
+  service through a port, and their business rules must not be re-implemented.
+- web.xml and other descriptors are configuration, not migration units:
+  disposition "wrap" with a one-line rationale.
+
+Waves are user journeys: keep a page, the servlet it posts to, and the
+fragments it includes together; simple read-only screens first, then CRUD
+screens, then multi-step session-backed flows last.

package/flows/packs/jsp-nextjs/prompts/survey-refine.md

@@ -0,0 +1,22 @@
+This is a J2EE web application: units are JSP pages and fragments, servlets and
+supporting Java classes, and deployment descriptors. Regexes miss most of the
+links such an application establishes indirectly:
+
+- WEB-INF/web.xml: every servlet-mapping ties a url-pattern to a servlet; every
+  servlet-class names a Java unit; welcome-file and error-page entries name
+  JSPs. A JSP form action, link, or redirect that targets a url-pattern is an
+  edge from the JSP to the servlet behind it.
+- Servlets: request.getRequestDispatcher(...).forward/include and
+  response.sendRedirect(...) name the JSP or url-pattern they hand off to;
+  new/injected service and DAO classes are outgoing edges to those units.
+- JSPs: static includes (<%@ include file="…" %>), dynamic includes
+  (<jsp:include page="…">), <jsp:forward>, <a href="…">, <form action="…">,
+  jQuery $.ajax / $.get / $.post url targets, and JSTL <c:import>/<c:url>.
+  Resolve a path to the unit whose file name (without extension) matches.
+- Tag libraries and shared layout fragments (header, footer, navigation) are
+  units only when they are files in the inventory.
+
+Prioritise JSPs with zero incoming edges (are they reached through web.xml or
+a redirect?), servlets nothing maps to, and fragments nothing includes. Calls to
+the ESB, application-server services, and third-party libraries are not estate
+edges — note them.

package/flows/packs/jsp-nextjs/prompts/survey-triage.md

@@ -0,0 +1,20 @@
+Units are JSP pages, JSP fragments (headers, footers, navigation, included
+partials), servlets, DTO/service classes, and web.xml. Judge them as a web
+estate, not a batch one:
+
+- A page reached through a web.xml url-pattern, a link, a form action, or a
+  redirect is live even when the regex graph shows few callers — check the
+  refine notes before calling it dead. A page nothing reaches and nothing
+  includes is the retire candidate; give the evidence.
+- Fragments with many includers are layout, not business logic: they are
+  migrated with the first page that needs them (same wave) rather than as a
+  wave of their own, and never "retire" while a live page includes them.
+- Servlets and service classes that only front an ESB or backend service are
+  "wrap" candidates: the modernized application keeps calling the same
+  service through a port, and their business rules must not be re-implemented.
+- web.xml and other descriptors are configuration, not migration units:
+  disposition "wrap" with a one-line rationale.
+
+Waves are user journeys: keep a page, the servlet it posts to, and the
+fragments it includes together; simple read-only screens first, then CRUD
+screens, then multi-step session-backed flows last.

package/package.json

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