@llm4ts/shell 0.16.2 → 0.18.0

package/flows/modernize-pack-check.js

@@ -0,0 +1,159 @@
+// Legacy modernization phase -1: load a pack and match its rules against an estate; no LLM.
+//
+// The pack equivalent of the mock provider: a deterministic first success
+// before any paid phase. The pack is loaded exactly as survey and extract load
+// it, then the flow reports what it found and how each rule matches the
+// estate at `--repo`:
+//
+//   1. manifest — name, source, scaffold, specs/features dirs, gates, replay,
+//      equivalence policy, judge dimensions, prompt and reviewer sidecars.
+//   2. estate — the files `sources:` selects (minus `exclude:`), the files
+//      `programs:` selects, and for every `## Coverage:` and `## Survey:` rule
+//      the units it captures, with a sample of each so a regex typo is
+//      visible at a glance.
+//   3. verdict — hard failures (the pack does not load, `sources:` or
+//      `programs:` match nothing) abort with exit code 1; likely mistakes (a
+//      rule capturing no unit, a missing phase prompt, a scaffold path that
+//      does not exist, no reviewer lens, no judge dimension) are listed as
+//      warnings and the flow exits 0.
+//
+// Run: LLM4TS_PACK=packs/my-pack modernize-pack-check --repo ~/estates/legacy
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import * as Effect from "effect/Effect";
+import { FlowAborted, Info, makeNodeWorkspace, mock, openPack, resolveFlowInput, runFlowMain, runNode, stage } from "@llm4ts/runner";
+import { coverageUnits, matchingFiles } from "@llm4ts/flow/SpecChecks";
+import { legacySourceWorkspaceLimits, workspaceLimitsFromEnv } from "@llm4ts/flow/Workspace";
+/** Prompt sidecars the modernization phases read, with the phase that reads each. */
+const phasePrompts = [
+    ["analysis", "extract"],
+    ["spec", "extract"],
+    ["bdd", "extract"],
+    ["plan", "extract"],
+    ["implement", "implement"],
+    ["review", "review"],
+    ["vectors", "verify"]
+];
+const sampleSize = 5;
+const sample = (units) => units.length === 0
+    ? "(none)"
+    : units.slice(0, sampleSize).join(", ") +
+        (units.length > sampleSize ? ` … +${units.length - sampleSize} more` : "");
+const plural = (count, noun, many = `${noun}s`) => `${count} ${count === 1 ? noun : many}`;
+const program = Effect.gen(function* () {
+    const input = yield* resolveFlowInput("Check the pack against the estate");
+    yield* runNode({
+        workDir: input.workDir,
+        workspace: input.workspace,
+        userPrompt: input.prompt,
+        // This phase makes no model call; the mock seat satisfies the one
+        // context shape the runner composes for every flow.
+        coder: mock,
+        environment: process.env
+    }, (context) => Effect.gen(function* () {
+        const say = (message) => context.events.publish(Info.make({ message }));
+        const warnings = [];
+        const failures = [];
+        const opened = yield* stage(context.events, "pack", openPack({
+            environment: process.env,
+            launchDir: input.workspace,
+            flowDir: import.meta.dirname
+        }));
+        const pack = opened.pack;
+        const packRoot = join(opened.workspace.root, opened.dir);
+        yield* stage(context.events, "manifest", Effect.gen(function* () {
+            yield* say(`pack '${pack.name}' (source: ${pack.source}) at ${packRoot}`);
+            yield* say(`specs-dir: ${pack.specsDir} · features-dir: ${pack.featuresDir}`);
+            if (pack.scaffold === undefined) {
+                yield* say("scaffold: (none — seed needs a non-empty target)");
+            }
+            else {
+                const scaffoldRoot = join(packRoot, pack.scaffold);
+                yield* say(`scaffold: ${pack.scaffold}`);
+                if (!existsSync(scaffoldRoot)) {
+                    warnings.push(`scaffold '${pack.scaffold}' does not exist at ${scaffoldRoot}`);
+                }
+            }
+            const gates = Object.entries(pack.gates);
+            yield* say(gates.length === 0
+                ? "gates: (none)"
+                : `gates: ${gates.map(([name, command]) => `${name} → ${command.join(" ")}`).join(" · ")}`);
+            if (gates.length === 0) {
+                warnings.push("## Gates is empty — implement and verify have nothing to enforce");
+            }
+            yield* say(pack.replay === undefined
+                ? "replay: (none — verify cannot run equivalence vectors)"
+                : `replay: ${pack.replay.join(" ")} (${pack.equivalence.ordering.toLowerCase()} comparison)`);
+            yield* say(`judge: ${plural(pack.judgeDimensions.length, "dimension")}` +
+                (pack.judgeDimensions.length === 0
+                    ? ""
+                    : ` — ${pack.judgeDimensions.map((d) => `${d.name} (0..${d.maxScore})`).join(", ")}`));
+            if (pack.judgeDimensions.length === 0) {
+                warnings.push("## Judge has no dimensions — extract's gate cannot score a spec");
+            }
+            const present = phasePrompts.filter(([name]) => pack.prompt(name) !== undefined);
+            const missing = phasePrompts.filter(([name]) => pack.prompt(name) === undefined);
+            yield* say(`prompts: ${present.length}/${phasePrompts.length} phase sidecars` +
+                (present.length === 0 ? "" : ` — ${present.map(([name]) => name).join(", ")}`));
+            for (const [name, phase] of missing) {
+                warnings.push(`prompts/${name}.md not found (read by ${phase})`);
+            }
+            yield* say(`reviewers: ${plural(pack.lenses.length, "lens", "lenses")}` +
+                (pack.lenses.length === 0 ? "" : ` — ${pack.lenses.map((l) => l.name).join(", ")}`));
+            if (pack.lenses.length === 0) {
+                warnings.push("no reviewers/*.md sidecar — review runs without pack lenses");
+            }
+            yield* say(`lessons: ${pack.lessons === undefined ? "(none yet)" : "present"}`);
+        }));
+        yield* stage(context.events, "estate", Effect.gen(function* () {
+            const repo = yield* makeNodeWorkspace(input.workDir, workspaceLimitsFromEnv(process.env, legacySourceWorkspaceLimits));
+            const sourcesRegex = pack.sources ?? ".*";
+            const sources = yield* matchingFiles(repo, sourcesRegex, pack.exclude);
+            yield* say(`sources: ${plural(sources.length, "file")} match '${sourcesRegex}'` +
+                (pack.exclude === undefined ? "" : ` minus '${pack.exclude}'`) +
+                ` — ${sample(sources)}`);
+            if (sources.length === 0) {
+                failures.push(`sources '${sourcesRegex}' matched no file under ${input.workDir}`);
+            }
+            if (pack.programs === undefined) {
+                yield* say("programs: (not set — every source file is a program)");
+            }
+            else {
+                const programs = yield* matchingFiles(repo, pack.programs, pack.exclude);
+                yield* say(`programs: ${plural(programs.length, "file")} match '${pack.programs}' — ${sample(programs)}`);
+                if (programs.length === 0) {
+                    failures.push(`programs '${pack.programs}' matched no file under ${input.workDir}`);
+                }
+            }
+            const report = Effect.fn("modernize-pack-check.rules")(function* (kind, rules) {
+                if (rules.length === 0) {
+                    yield* say(`${kind}: (no rules)`);
+                    return;
+                }
+                const units = yield* coverageUnits(repo, rules);
+                for (const rule of rules) {
+                    const found = units[rule.name] ?? [];
+                    yield* say(`${kind} '${rule.name}': ${plural(found.length, "unit")} — ${sample(found)}`);
+                    if (found.length === 0) {
+                        warnings.push(`${kind} rule '${rule.name}' captured no unit: files '${rule.files}', unit '${rule.unit}'`);
+                    }
+                }
+            });
+            yield* report("coverage", pack.coverage);
+            yield* report("survey", pack.survey);
+        }));
+        yield* stage(context.events, "verdict", Effect.gen(function* () {
+            for (const warning of warnings) {
+                yield* say(`warning: ${warning}`);
+            }
+            if (failures.length > 0) {
+                return yield* FlowAborted.make({
+                    message: `pack '${pack.name}' failed the check: ${failures.join("; ")}`
+                });
+            }
+            yield* say(`pack '${pack.name}' check passed with ${plural(warnings.length, "warning")} — ` +
+                `next: LLM4TS_PACK=${process.env.LLM4TS_PACK ?? opened.dir} modernize-survey --repo ${input.workDir}`);
+        }));
+    }));
+});
+runFlowMain(program);

package/flows/modernize-review.js

@@ -20,24 +20,15 @@ import * as Schema from "effect/Schema";
 import { Dimension } from "@llm4ts/core/eval/Eval";
 import { judge } from "@llm4ts/core/eval/Judge";
 import { capped, renderTruncation, truncations, withShrink } from "@llm4ts/flow/Context";
-import { FlowAborted } from "@llm4ts/flow/FlowError";
+import { FlowAborted, Info, Plan, ReviewResult, asReadOnly, coderFromEnv, makeNodeWorkspace, makePlanStore, mergeReviewResults, nodePlainFileStore, openPack, resolveFlowInput, reviewFingerprint, runFlowMain, runNode, stage } from "@llm4ts/runner";
 import { structuredAndPublish } from "@llm4ts/flow/Flow";
-import { FlowEvents, Info } from "@llm4ts/flow/FlowEvents";
+import { FlowEvents } from "@llm4ts/flow/FlowEvents";
 import { judgeAllPrograms } from "@llm4ts/flow/ProgramJudge";
 import { Provenance, makeProvenanceStore } from "@llm4ts/flow/Provenance";
 import { appendPackLesson } from "@llm4ts/flow/Pack";
-import { makePlanStore } from "@llm4ts/flow/Persistence";
-import { Plan, Task } from "@llm4ts/flow/Plan";
-import { stage } from "@llm4ts/flow/PlanExecution";
-import { allReviewers, mergeReviewResults, reviewJsonSchema, reviewPrompt, ReviewResult } from "@llm4ts/flow/Review";
+import { Task } from "@llm4ts/flow/Plan";
+import { allReviewers, reviewJsonSchema, reviewPrompt } from "@llm4ts/flow/Review";
 import { checkWall, wallBreachMessage } from "@llm4ts/flow/Wall";
-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 { makeNodeWorkspace } from "@llm4ts/runner/NodeWorkspace";
-import { openPack } from "@llm4ts/runner/Packs";
-import { reviewFingerprint } from "@llm4ts/runner/ReviewFingerprint";
 const ModDir = "docs/modernization";
 class FixSpec extends Schema.Class("FixSpec")({
     title: Schema.String,

package/flows/modernize-seed.js

@@ -21,20 +21,12 @@
 import { join } from "node:path";
 import * as Effect from "effect/Effect";
 import * as Schema from "effect/Schema";
-import { FlowAborted, PersistenceError } from "@llm4ts/flow/FlowError";
-import { Info } from "@llm4ts/flow/FlowEvents";
+import { PersistenceError } from "@llm4ts/flow/FlowError";
+import { FlowAborted, Info, coderFromEnv, makeNodeWorkspace, nodePlainFileStore, openPack, parsePlan, resolveFlowInput, runFlowMain, runNode, stage } from "@llm4ts/runner";
 import { packageVersion } from "@llm4ts/flow/Package";
-import { parsePlan } from "@llm4ts/flow/Plan";
-import { stage } from "@llm4ts/flow/PlanExecution";
 import { Provenance, makeProvenanceStore } from "@llm4ts/flow/Provenance";
 import { matchingFiles } from "@llm4ts/flow/SpecChecks";
-import { requireApproval } from "@llm4ts/modernize/Approval";
-import { 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 { makeNodeWorkspace } from "@llm4ts/runner/NodeWorkspace";
-import { openPack } from "@llm4ts/runner/Packs";
+import { requireApproval } from "@llm4ts/flow/Approval";
 const ModDir = "docs/modernization";
 const skipped = new Set([".git", "target", "node_modules", "dist"]);
 const Seats = Schema.Record(Schema.String, Schema.String);

package/flows/modernize-verify.js

@@ -23,23 +23,15 @@ import * as Schema from "effect/Schema";
 import { CurrentEquivSchema, EquivVector, Observations, canonicaliseFieldMap, readEquivVectors, replayEquivVector, diffObservations, writeEquivVectors } from "@llm4ts/flow/Equiv";
 import { capped, renderTruncation, truncations, withShrink } from "@llm4ts/flow/Context";
 import { renderEquivReport, VectorVerdict } from "@llm4ts/flow/EquivReport";
-import { FlowAborted, PlanParseError } from "@llm4ts/flow/FlowError";
+import { PlanParseError } from "@llm4ts/flow/FlowError";
 import { structuredAndPublish } from "@llm4ts/flow/Flow";
-import { FlowEvents, Info } from "@llm4ts/flow/FlowEvents";
-import { makePlanStore } from "@llm4ts/flow/Persistence";
-import { stage } from "@llm4ts/flow/PlanExecution";
-import { Plan, Task } from "@llm4ts/flow/Plan";
+import { FlowEvents } from "@llm4ts/flow/FlowEvents";
+import { FlowAborted, Info, Plan, asReadOnly, coderFromEnv, makeNodeWorkspace, makePlanStore, nodePlainFileStore, nodeProcessExecutor, openPack, resolveFlowInput, runFlowMain, runNode, stage } from "@llm4ts/runner";
+import { Task } from "@llm4ts/flow/Plan";
 import { Provenance, makeProvenanceStore } from "@llm4ts/flow/Provenance";
 import { matchingFiles } from "@llm4ts/flow/SpecChecks";
 import { checkWall, wallBreachMessage } from "@llm4ts/flow/Wall";
-import { generateVectorsResumably } from "@llm4ts/modernize/Artifacts";
-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 { makeNodeWorkspace } from "@llm4ts/runner/NodeWorkspace";
-import { openPack } from "@llm4ts/runner/Packs";
+import { generateVectorsResumably } from "@llm4ts/flow/Artifacts";
 const ModDir = "docs/modernization";
 /**
  * The model-facing vector shape: flat maps only, so structured output stays

package/flows/sdd.js

@@ -1,18 +1,8 @@
 // Spec-driven development: write a specification, encode it as red tests, implement to green.
 import { join } from "node:path";
 import * as Effect from "effect/Effect";
-import { makeChat } from "@llm4ts/flow/Chat";
-import { FlowAborted } from "@llm4ts/flow/FlowError";
-import { Plan, defaultPlanPath } from "@llm4ts/flow/Plan";
-import { implementTaskLoop, stage } from "@llm4ts/flow/PlanExecution";
-import { defaultPlanInstructions, planFrom, writeBrief } from "@llm4ts/flow/Planner";
-import { makePlanStore } from "@llm4ts/flow/Persistence";
-import { lintCommand, minimalReviewers, reviewAndFixLoop } from "@llm4ts/flow/Review";
-import { asReadOnly, coderFromEnv, gemini, 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 { FlowAborted, Plan, asReadOnly, coderFromEnv, defaultPlanInstructions, defaultPlanPath, implementTaskLoop, lintCommand, makeChat, makePlanStore, minimalReviewers, nodePlainFileStore, nodeProcessExecutor, planFrom, resolveFlowInput, reviewAndFixLoop, runFlowMain, runNode, stage, withModel, writeBrief } from "@llm4ts/runner";
+import { gemini } from "@llm4ts/runner/Connectors";
 const proModel = process.env.LLM4TS_REASONING_MODEL ?? "gemini-3-pro-preview";
 const flashModel = process.env.LLM4TS_CODER_MODEL ?? "gemini-2.5-flash";
 const specInstructions = [

package/kits/j2ee-nextjs/README.md

@@ -0,0 +1,29 @@
+# Kit: j2ee-nextjs
+
+JSP/servlet estates to Next.js, as a SPA over a mocked anti-corruption layer or behind a Spring BFF.
+
+A kit bundles everything the engine's `modernize-*` flows need to know about
+one legacy source and one target stack (ADR 0014). This one ships three
+packs, the two scaffolds they seed an empty target from, the `convert-page`
+and `convert-all` flows that drive the non-clean-room page conversion of
+ADR 0012, and the demo-bank fixture (a legacy J2EE estate and its Next.js
+target) the [workshop runbook](fixtures/demo-bank/RUNBOOK.md) rehearses on.
+
+| Pack                                               | Legacy → target                  | Scaffold     | Replay |
+| -------------------------------------------------- | -------------------------------- | ------------ | ------ |
+| [`j2ee-nextjs-spa`](packs/j2ee-nextjs-spa/pack.md) | JSP/servlets → Next.js SPA + ACL | `nextjs-spa` | no     |
+| [`jsp-nextjs`](packs/jsp-nextjs/pack.md)           | JSP/Java → Next.js SPA           | `nextjs-spa` | no     |
+| [`jsp-bff-nextjs`](packs/jsp-bff-nextjs/pack.md)   | JSP/Java → Spring BFF + Next.js  | `spring-bff` | no     |
+
+| Flow           | What it does                                                           |
+| -------------- | ---------------------------------------------------------------------- |
+| `convert-page` | Convert ONE extracted page into the Next.js target on its own branch   |
+| `convert-all`  | Walk the survey inventory in wave order, one branch per page, a report |
+
+```sh
+llm4ts run modernize-pack-check --pack j2ee-nextjs-spa --repo /path/to/legacy-estate
+LLM4TS_LEGACY_REPO=/path/to/legacy-estate llm4ts run convert-page --pack j2ee-nextjs-spa --repo /path/to/nextjs accountOverview
+```
+
+The convert flows default to `j2ee-nextjs-spa`; `kits/test/packs.test.ts`
+shows what the flows require of a manifest.

package/kits/j2ee-nextjs/fixtures/demo-bank/RUNBOOK.md

@@ -0,0 +1,156 @@
+# DemoBank workshop runbook
+
+Half/full-day live workshop: the whole J2EE → Next.js conversion pipeline runs
+in front of the client, with discussion between phases. There are no recorded
+fallbacks by design — every phase is checkpointed (plan files, per-page
+extraction resume, judge/review caches, the conversion board), so the recovery
+move for ANY failure is: rerun the same command and watch it resume. That
+recovery is itself a selling point; demonstrate it deliberately if a failure
+hands you the chance.
+
+Say out loud, at least once per act: **all token and cost figures are
+estimates** (character-count heuristics — the CLI seats report no usage).
+
+## Act 0 — before the audience arrives
+
+```bash
+node kits/j2ee-nextjs/fixtures/demo-bank/preflight.mjs
+```
+
+Preflight seeds both fixtures into a temp dir, runs their smoke checks, and
+verifies git, pnpm, and the `claude` CLI are present. Fix anything red before
+continuing. Then materialize the demo estate (pick a short path you can type
+on stage):
+
+```bash
+node kits/j2ee-nextjs/fixtures/demo-bank/reset-demo.mjs ~/demo
+```
+
+This creates `~/demo/legacy-j2ee` and `~/demo/nextjs` as fresh git repos and
+warms the target's node_modules from the pnpm store (documented offline
+strategy: the lockfile is committed; run it once on hotel wifi, never on
+stage). Finally: `cd ~/demo/nextjs && pnpm test` must be green.
+
+Timing bounds for the day (set in the environment you run flows from):
+
+```bash
+export LLM4TS_PACK=j2ee-nextjs-spa
+export LLM4TS_LEGACY_REPO=~/demo/legacy-j2ee
+export LLM4TS_JUDGE_ROUNDS=1        # bound judge feedback to one round on stage
+export LLM4TS_MAX_CLOSURE_FILES=8   # bound legacy evidence per page
+export LLM4TS_EXTRACT_CONCURRENCY=3 # pages extracted and judged at once (measure in rehearsal)
+```
+
+`LLM4TS_PACK` is the one that matters for Act 1: it is what makes the survey
+reason in J2EE terms (web.xml mappings, includes, forwards, ajax targets)
+instead of the default COBOL pack's. Discovery needs nothing extra for the
+fixture or for a typical client estate — only files the pack's `sources:`
+regex matches count, and `.git`, `node_modules`, `target`, `build`, `dist`
+are never entered. Keep these two in your back pocket for a real estate with
+an unusual layout, never set them on stage without a reason:
+
+```bash
+export LLM4TS_EXCLUDE_DIRS=.git,node_modules,target,generated   # replaces the pruned list
+export LLM4TS_MAX_DISCOVER_RESULTS=50000                         # default 20000 for estates
+```
+
+## Act 1 — breadth: survey and extract (~duration: measure in rehearsal)
+
+```bash
+llm4ts run modernize-survey --repo ~/demo/legacy-j2ee
+```
+
+Talk track while it runs: 18 pages inventoried, dead pages and fragments
+triaged out, waves proposed. Three beats, in the order the artifacts land:
+
+1. `docs/modernization/inventory.md` — the deterministic graph, no model
+   involved yet. Point at the `In` column: `header` and `footer` carry one
+   incoming edge per page that includes them, `web` (web.xml) fans out to
+   every servlet, and the genuinely dead pages are the ones flagged
+   `unreferenced — retire candidate?`. That column is what the model is
+   asked to trust.
+2. `docs/modernization/graph-refine.md` — the edges the regexes could not
+   see (form actions and redirects to url-patterns, ajax targets), each with
+   the file and line that establishes it. No evidence, no edge.
+3. `docs/modernization/wave-plan.md` — fragments travel with the first page
+   that includes them, the ESB wrappers come out `wrap` (the port story for
+   Act 2), and the waves are user journeys: read-only screens, then CRUD,
+   then the session-backed transfer stepper last.
+
+Say once that the prompts behind beats 2 and 3 are the pack's
+(`kits/j2ee-nextjs/packs/j2ee-nextjs-spa/prompts/survey-*.md`), not the tool's: a client with
+a different stack edits two markdown files, not the pipeline. Review the plan
+WITH the audience, flip `- [x] Approved` (the human gate is the point — banks
+like this beat).
+
+```bash
+LLM4TS_WAVE=wave-1 llm4ts run modernize-extract --repo ~/demo/legacy-j2ee
+```
+
+Extraction runs three pages at once (`LLM4TS_EXTRACT_CONCURRENCY=3` from Act
+0): the pages of a wave are independent, each lands in its own commit holding
+only its four files, and the log interleaves — say so before it starts, then
+point at `git log --oneline` filling up out of page order. Two lines to say
+aloud: concurrency divides the wall clock, not the cost (the estimates in
+Act 3 are identical at 1 or 3), and if a quota death hits mid-batch the pages
+already in flight still finish and land — the rerun resumes only what is
+missing. If the client's plan rate-limits at 3, drop to 1 and narrate the
+same resume. Show one finished spec: the prose, then the `json pagespec`
+block, then the judge gate verdicts under `docs/modernization/gate/`.
+
+## Act 2 — depth: convert (order: accountOverview → beneficiaryList → transferStep1)
+
+```bash
+llm4ts run convert-all --repo ~/demo/nextjs
+```
+
+Beats to show while pages convert:
+
+1. `.llm4ts/convert/board.md` in the target — the whole estate planned from
+   minute one, pages moving planned → active → done.
+2. `contracts/<page>.openapi.yaml` — generated before any model wrote code;
+   this file is the future B4F team's requirements document.
+3. A finished branch: `git log convert/accountOverview`, the page diff, the
+   port/mock pair, the component tests.
+4. `docs/conversion/<page>.md` — the per-page report with the estimated
+   tokens/cost line.
+5. The dev server (`pnpm dev`) showing the converted page next to an original
+   JSP screenshot: same form, new house style, mock data flowing through the
+   port.
+
+## Act 3 — money and governance
+
+Open `docs/conversion/migration-report.md`: per-page estimates, the remaining
+estate, and the projection — then scale the projection aloud to the client's
+real page count. Close on governance: branches await human review (no
+auto-merge), every page has a spec, a contract, a judge verdict, and a report.
+
+Optional ADO mirror (decide before the workshop, never set it up live):
+
+```bash
+export LLM4TS_ADO_ORG_URL=https://dev.azure.com/<org>
+export LLM4TS_ADO_PROJECT=<project>
+# Auth belongs to the az CLI itself: `az devops login` beforehand (or
+# AZURE_DEVOPS_EXT_PAT in the shell) — llm4ts never sees the PAT.
+```
+
+## Recovery drills (rehearse each one)
+
+| Failure | Move |
+| --- | --- |
+| Rate limit / quota death mid-extract | Rerun the same command; per-page resume skips finished specs. Narrate it. |
+| Rate limit mid-convert | Rerun `convert-all`; the board skips done pages, the plan file resumes the interrupted one. |
+| A page's tests refuse to go green | Let `convert-all` mark it failed and keep walking (default); return to it in discussion. `LLM4TS_FAIL_FAST=1` exists but stays OFF on stage. |
+| Machine sleep / network blip | Same as rate limit: rerun. |
+| Judge keeps rejecting | `LLM4TS_JUDGE_ROUNDS=1` already bounds it; the failure lands on the board with its reason — governance beat, not a crash. |
+| `⟳ flaky … (fresh retry)` lines scrolling past — Gemini CLI's `Loop detected` / `A potential loop was detected`, an empty response, a malformed tool call | Nothing to do: the seat restarts the turn in a fresh process, up to 6 times, and the flow carries on. Say it out loud: the turn was lost, the quota and the prompt were not. Only if all 6 fail does the stage abort — rerun, it resumes. |
+| `⟳ structured output (repair retry)` lines — `Failed to parse response as structured output` | Nothing to do: the model gets its own parse failure quoted back and is asked for the JSON alone, up to 2 more times. If the third reply still does not parse the stage aborts with the reason — rerun resumes; a schema the model can never satisfy is a pack bug, not a stage bug. |
+| Survey aborts with `discovery stopped at N matching files` (a client's real estate, never the fixture) | The abort names the knobs: tighten the pack's `sources:`/`exclude:`, prune more with `LLM4TS_EXCLUDE_DIRS=.git,node_modules,generated`, or raise `LLM4TS_MAX_DISCOVER_RESULTS`. Rerun. |
+| Everything is on fire | `node kits/j2ee-nextjs/fixtures/demo-bank/reset-demo.mjs ~/demo` and restart the act; Act 1 re-runs in minutes. |
+
+## Rehearsal log (fill in — the durations above are placeholders until this is done twice)
+
+| Rehearsal | Date | Act 1 | Act 2/page | Full walk | Notes |
+| --- | --- | --- | --- | --- | --- |
+| 1 | | | | | |
+| 2 | | | | | |

package/kits/j2ee-nextjs/fixtures/demo-bank/legacy-j2ee/PAGES.md

@@ -0,0 +1,67 @@
+# DemoBank Legacy Portal - Page Inventory
+
+Synthetic legacy J2EE fixture for the bank-conversion PoC demo. Authored
+from scratch; no real bank code or branding. This file is the answer key
+for judging survey/extract quality: it lists every page, its live/dead
+status, and the page -> endpoint -> ESB-service mapping.
+
+All JSPs live under `src/main/webapp/`. Java sources live under
+`src/main/java/com/demobank/legacy/` (`web/` controllers, `dto/` data
+classes, `esb/` fake ESB service wrappers). The app is not runnable and is
+not meant to be; it only has to read as authentic mid-2000s J2EE.
+
+## Hero pages
+
+The three pages the workshop converts end to end. Each exercises a
+different legacy mix on purpose:
+
+| #   | Page                                                                | Mix it exercises                                                                                                                                                                         |
+| --- | ------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 1   | `accountOverview.jsp`                                               | Server-rendered JSTL table from a request-scoped model, plus a jQuery `$.ajax` GET that refreshes balances as JSON. Read-only.                                                           |
+| 2   | `beneficiaryList.jsp` + `beneficiaryEdit.jsp`                       | CRUD list + form. Client-side jQuery validation (inline + shared `validate.js`) AND server-side validation in the servlet; the two rule sets deliberately overlap but are not identical. |
+| 3   | `transferStep1.jsp` -> `transferStep2.jsp` -> `transferConfirm.jsp` | Multi-step wizard keeping a `TransferDraft` in `HttpSession` across steps; scriptlets mixed with JSTL. The hardest extraction case.                                                      |
+
+## Full page list
+
+| Page                  | Status        | Notes                                                                                                                                                   |
+| --------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `login.jsp`           | live          | Welcome page (see `web.xml` welcome-file). Filler shell; form posts to a servlet that does not exist on purpose (`j_security_check` style legacy stub). |
+| `dashboard.jsp`       | live          | Filler landing page after login; scriptlet date banner.                                                                                                 |
+| `accountOverview.jsp` | live (HERO 1) | Served by `AccountOverviewServlet` forward.                                                                                                             |
+| `beneficiaryList.jsp` | live (HERO 2) | Served by `BeneficiaryServlet` forward.                                                                                                                 |
+| `beneficiaryEdit.jsp` | live (HERO 2) | Add/edit form; posts back to `BeneficiaryServlet`.                                                                                                      |
+| `transferStep1.jsp`   | live (HERO 3) | Amount + beneficiary pick.                                                                                                                              |
+| `transferStep2.jsp`   | live (HERO 3) | Review screen; data comes from session draft.                                                                                                           |
+| `transferConfirm.jsp` | live (HERO 3) | Result screen; shows ESB reference number.                                                                                                              |
+| `settings.jsp`        | live          | Filler; scriptlet-heavy preference toggles, nothing wired.                                                                                              |
+| `profile.jsp`         | live          | Filler; static customer data with scriptlets.                                                                                                           |
+| `messages.jsp`        | live          | Filler; inbox-style static table.                                                                                                                       |
+| `help.jsp`            | live          | Filler; static FAQ.                                                                                                                                     |
+| `oldTransfer.jsp`     | DEAD          | Pre-wizard single-page transfer. Not in nav, not in `web.xml`, nothing links to it.                                                                     |
+| `promoQ3.jsp`         | DEAD          | Expired Q3 2011 campaign page. Unreferenced.                                                                                                            |
+| `testHarness.jsp`     | DEAD          | Developer scratch page hitting endpoints by hand. Unreferenced.                                                                                         |
+| `header.jsp`          | fragment      | Included via `<jsp:include>` from every page.                                                                                                           |
+| `nav.jsp`             | fragment      | Included from `header.jsp`; the nav link set defines "referenced".                                                                                      |
+| `footer.jsp`          | fragment      | Included via `<jsp:include>` from every page.                                                                                                           |
+
+Live pages: 12. Dead pages: 3. Fragments: 3. Total JSP files: 18.
+
+## Page -> endpoint -> ESB service (answer key)
+
+| Page                  | HTTP endpoint (`web.xml` url-pattern)                                            | Controller               | ESB wrapper                              | ESB service id   |
+| --------------------- | -------------------------------------------------------------------------------- | ------------------------ | ---------------------------------------- | ---------------- |
+| `accountOverview.jsp` | `GET /accountOverview` (HTML), `GET /accountOverview?fmt=json` (AJAX refresh)    | `AccountOverviewServlet` | `EsbAcctListService`                     | `ESB_ACCT_LIST`  |
+| `beneficiaryList.jsp` | `GET /beneficiary` (list), `GET /beneficiary?action=delete&benfId=..`            | `BeneficiaryServlet`     | `EsbBenfListService`                     | `ESB_BENF_LIST`  |
+| `beneficiaryEdit.jsp` | `GET /beneficiary?action=edit&benfId=..` (load form), `POST /beneficiary` (save) | `BeneficiaryServlet`     | `EsbBenfMaintService`                    | `ESB_BENF_MAINT` |
+| `transferStep1.jsp`   | `GET /transfer` (start), `POST /transfer` with `step=1`                          | `TransferServlet`        | `EsbBenfListService` (beneficiary combo) | `ESB_BENF_LIST`  |
+| `transferStep2.jsp`   | `POST /transfer` with `step=2` (validate draft)                                  | `TransferServlet`        | `EsbTrfValidateService`                  | `ESB_TRF_VAL`    |
+| `transferConfirm.jsp` | `POST /transfer` with `step=3` (execute)                                         | `TransferServlet`        | `EsbTrfExecService`                      | `ESB_TRF_EXEC`   |
+| dead pages            | none                                                                             | none                     | none                                     | none             |
+
+DTOs: `AcctOvwDTO` (hero 1), `BenfDTO` (hero 2), `TrfDTO` + session-held
+`TransferDraft` (hero 3). Field names use period-typical abbreviations
+(`acctNo`, `curBal`, `avlBal`, `ccyCd`, `benfNm`, `trfAmt`, ...) so the
+anti-corruption renaming in a Page Spec has something to bite on.
+
+All data is fictional: EUR accounts, fake IBAN-like numbers in the form
+`IT00 DEMO 0000 ...`, customer "MARIO BIANCHI" / customer id `CUST0042`.

package/kits/j2ee-nextjs/fixtures/demo-bank/legacy-j2ee/pom.xml

@@ -0,0 +1,49 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+  DemoBank legacy portal - build skeleton only.
+  This fixture is not meant to compile or deploy; the pom exists so the
+  tree reads as a period-typical Maven WAR module.
+-->
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
+  <modelVersion>4.0.0</modelVersion>
+
+  <groupId>com.demobank.legacy</groupId>
+  <artifactId>demobank-portal</artifactId>
+  <version>2.7.14-SNAPSHOT</version>
+  <packaging>war</packaging>
+  <name>DemoBank Internet Banking Portal</name>
+
+  <properties>
+    <project.build.sourceEncoding>ISO-8859-1</project.build.sourceEncoding>
+    <maven.compiler.source>1.6</maven.compiler.source>
+    <maven.compiler.target>1.6</maven.compiler.target>
+  </properties>
+
+  <dependencies>
+    <dependency>
+      <groupId>javax.servlet</groupId>
+      <artifactId>servlet-api</artifactId>
+      <version>2.5</version>
+      <scope>provided</scope>
+    </dependency>
+    <dependency>
+      <groupId>javax.servlet</groupId>
+      <artifactId>jstl</artifactId>
+      <version>1.2</version>
+    </dependency>
+    <dependency>
+      <groupId>javax.servlet.jsp</groupId>
+      <artifactId>jsp-api</artifactId>
+      <version>2.1</version>
+      <scope>provided</scope>
+    </dependency>
+    <!-- ESB connectivity jars are provided by the app server shared lib
+         (see deployment runbook DB-OPS-114, not part of this repo). -->
+  </dependencies>
+
+  <build>
+    <finalName>demobank-portal</finalName>
+  </build>
+</project>

package/kits/j2ee-nextjs/fixtures/demo-bank/legacy-j2ee/src/main/java/com/demobank/legacy/dto/AcctOvwDTO.java

@@ -0,0 +1,58 @@
+package com.demobank.legacy.dto;
+
+import java.io.Serializable;
+import java.math.BigDecimal;
+
+/**
+ * Account overview row DTO.
+ *
+ * Field names mirror the host copybook CBACCT01 (abbreviations kept on
+ * purpose so the mapping to ESB_ACCT_LIST stays 1:1). Do NOT rename: the
+ * JSPs and the JSON serializer rely on the getter names.
+ *
+ * @author gferri (2008)
+ */
+public class AcctOvwDTO implements Serializable {
+
+    private static final long serialVersionUID = 1L;
+
+    /** Account number, host format (12 digits, branch prefixed). */
+    private String acctNo;
+    /** IBAN presentation form, e.g. "IT00 DEMO 0101 0101 0000 0000 001". */
+    private String acctIban;
+    /** Short description from host, e.g. "CURRENT ACCOUNT". */
+    private String acctDesc;
+    /** ISO currency code, always EUR for domestic accounts. */
+    private String ccyCd;
+    /** Current (booked) balance. */
+    private BigDecimal curBal;
+    /** Available balance (booked minus holds). */
+    private BigDecimal avlBal;
+    /** Account status cd: A=active, B=blocked, C=closed. */
+    private String staCd;
+
+    public AcctOvwDTO() {
+        // bean constructor
+    }
+
+    public String getAcctNo() { return acctNo; }
+    public void setAcctNo(String acctNo) { this.acctNo = acctNo; }
+
+    public String getAcctIban() { return acctIban; }
+    public void setAcctIban(String acctIban) { this.acctIban = acctIban; }
+
+    public String getAcctDesc() { return acctDesc; }
+    public void setAcctDesc(String acctDesc) { this.acctDesc = acctDesc; }
+
+    public String getCcyCd() { return ccyCd; }
+    public void setCcyCd(String ccyCd) { this.ccyCd = ccyCd; }
+
+    public BigDecimal getCurBal() { return curBal; }
+    public void setCurBal(BigDecimal curBal) { this.curBal = curBal; }
+
+    public BigDecimal getAvlBal() { return avlBal; }
+    public void setAvlBal(BigDecimal avlBal) { this.avlBal = avlBal; }
+
+    public String getStaCd() { return staCd; }
+    public void setStaCd(String staCd) { this.staCd = staCd; }
+}