@llm4ts/shell 0.17.0 → 0.18.1

package/flows/modernize-implement.js

@@ -22,25 +22,14 @@ import { join } from "node:path";
 import * as Effect from "effect/Effect";
 import { Dimension, Sample } from "@llm4ts/core/eval/Eval";
 import { judge } from "@llm4ts/core/eval/Judge";
-import { makeChat } from "@llm4ts/flow/Chat";
+import { FlowAborted, FlowLlmError, Info, ReviewResult, asReadOnly, coderFromEnv, implementTaskLoop, lintCommand, loadKitPatternCards, makeChat, makeNodeWorkspace, makePlanStore, mergeReviewResults, minimalReviewers, nodePlainFileStore, nodeProcessExecutor, openPack, resolveFlowInput, reviewAndFixLoop, reviewFingerprint, runFlowMain, runNode, stage } from "@llm4ts/runner";
 import { capped, renderTruncation, truncations, withShrink } from "@llm4ts/flow/Context";
-import { FlowAborted, FlowLlmError } from "@llm4ts/flow/FlowError";
-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 { loadPatternCards, taggedPatternIds } from "@llm4ts/flow/Patterns";
-import { makePlanStore } from "@llm4ts/flow/Persistence";
-import { implementTaskLoop, stage } from "@llm4ts/flow/PlanExecution";
-import { ReviewIssue, ReviewResult, lintCommand, mergeReviewResults, minimalReviewers, reviewAndFixLoop } from "@llm4ts/flow/Review";
+import { ReviewIssue } from "@llm4ts/flow/Review";
 import { checkWall, wallBreachMessage } from "@llm4ts/flow/Wall";
-import { asReadOnly, coderFromEnv } from "@llm4ts/runner/Connectors";
-import { reviewFingerprint } from "@llm4ts/runner/ReviewFingerprint";
-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 { loadUniversalPatternCards, openPack } from "@llm4ts/runner/Packs";
 const ModDir = "docs/modernization";
 const judgeRounds = () => {
     const raw = Number.parseInt(process.env.LLM4TS_JUDGE_ROUNDS ?? "", 10);
@@ -182,7 +171,7 @@ const program = Effect.gen(function* () {
         const specText = yield* gatherSpecs(target, pack.specsDir);
         const cards = [
             ...(yield* loadPatternCards(opened.workspace, `${opened.dir}/patterns`)),
-            ...(yield* loadUniversalPatternCards([input.workspace, import.meta.dirname]))
+            ...(yield* loadKitPatternCards(opened))
         ];
         const cited = new Set(taggedPatternIds(specText));
         const playbook = cards.filter((card) => cited.has(card.id));

package/flows/modernize-pack-check.js

@@ -21,16 +21,9 @@
 import { existsSync } from "node:fs";
 import { join } from "node:path";
 import * as Effect from "effect/Effect";
-import { FlowAborted } from "@llm4ts/flow/FlowError";
-import { Info } from "@llm4ts/flow/FlowEvents";
-import { stage } from "@llm4ts/flow/PlanExecution";
+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";
-import { mock } from "@llm4ts/runner/Connectors";
-import { resolveFlowInput } from "@llm4ts/runner/FlowArgs";
-import { runFlowMain, runNode } from "@llm4ts/runner/FlowRunner";
-import { makeNodeWorkspace } from "@llm4ts/runner/NodeWorkspace";
-import { openPack } from "@llm4ts/runner/Packs";
 /** Prompt sidecars the modernization phases read, with the phase that reads each. */
 const phasePrompts = [
     ["analysis", "extract"],

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,232 @@
+# 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, the `claude` CLI, and that the installed `llm4ts` ships
+the `j2ee-nextjs` kit with its `j2ee-nextjs-spa` pack (`@llm4ts/shell`
+0.18.0 or newer). 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. It is a bare pack name, resolved across
+the kits `llm4ts kits` lists — the `j2ee-nextjs` kit ships it — and every
+`llm4ts run` below accepts the same value as `--pack j2ee-nextjs-spa` if you
+would rather have it visible in the command on stage. Prove the whole
+selection before anyone is watching, with no model call and no cost:
+
+```bash
+llm4ts kits
+llm4ts run modernize-pack-check --pack j2ee-nextjs-spa --repo ~/demo/legacy-j2ee
+```
+
+The check must end `check passed with 1 warning`: 34 source files, 18 JSP
+programs, the servlet, form, ajax, include, and servlet-class rules each
+capturing real units, and the one expected warning — the pack ships no
+`vectors` prompt because it runs no replay phase. If it says `not found: no kit ships it`, the installed shell is
+older than 0.18.0. 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, and that the pack travels in a **kit** with its scaffold and
+review lenses: a client with a different stack copies the kit into
+`.llm4ts/kits/<client>/`, edits markdown, and runs `modernize-pack-check`
+until it passes — the pipeline is untouched. 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
+```
+
+Act 2 opens with `accountOverview`, and the survey's plan puts that page in
+**wave-2** (wave-1 is the navigation shell: login, header, footer, nav,
+dashboard, profile, settings, messages, help), so extract wave-2 as well
+before Act 2 — it is one page plus its servlet and DTO, minutes not tens of
+minutes. Each wave gates only its own units; the pages of later waves are
+listed as "not gating" — say so when the line scrolls past, and mention the
+closing run without `LLM4TS_WAVE` that enforces coverage over the whole
+estate once every wave is in.
+
+```bash
+LLM4TS_WAVE=wave-2 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.
+The kit is the deliverable the client keeps: their packs, scaffold, lenses,
+and the lessons the review phase appends, in one directory they own.
+
+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. |
+| `pack 'j2ee-nextjs-spa' not found: no kit ships it` | The shell predates kits (0.18.0) or `LLM4TS_PACK` was overwritten with a path: `llm4ts kits` shows what it sees; `npm i -g @llm4ts/shell@latest`; re-export the bare name. Never happens after a green Act 0. |
+| 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 | 2026-09-14/15 | survey 5m47s ($1.08 est.); extract wave-1 (9 pages, concurrency 3): 11m06s extraction + 1m40s gate + fix rounds ≈ 30–45 min; extract wave-2 (1 page): 2m27s extraction + gate/fix rounds ≈ 16 min | accountOverview 44m29s: acl 12m36s, page 18m33s, tests 12m25s, verify 11s, judge 44s — judge NOT cleared | ≈ 2h30 of flow time, plus reruns | first live walk; 4 findings below, 3 fixed in 0.18.1; the demo estate was a scratch copy, the coder seat `claude` |
+| 2 | | | | | |
+
+### Rehearsal 1 findings (2026-09-14/15)
+
+1. **Act 2's first page is not in wave-1.** The survey puts `accountOverview`
+   in wave-2 (wave-1 is the navigation shell). Act 1 now extracts wave-2 as
+   well (see above). Runbook fixed.
+2. **A wave-scoped extraction could never clear its gate.** Coverage ran
+   over the whole estate, so wave-1 failed on `/accountOverview` and
+   `doTransfer` (wave-2/4 units) and burned three fix rounds — ~17 min per
+   attempt — trying to cover them. Fixed in 0.18.1: a wave gates only its
+   own units and lists the rest as not gating; one closing run without
+   `LLM4TS_WAVE` enforces estate-wide coverage.
+3. **A malformed `pagespec` block reached `convert-page`.** The old
+   estate-wide fix round had drafted `accountOverview.md` with `apiCalls`
+   as prose strings; the judge scored it, and `convert-page` was the first
+   to reject it (`invalid page spec block ... at ["apiCalls"][0]`). Fixed in
+   0.18.1: J2EE packs declare `spec-schema: pagespec`, the extraction gate
+   decodes every block by code before the judge, and the finding states the
+   exact shape the analyst must produce (the first fix round without that
+   hint failed twice; with it, one round).
+4. **The page spec cannot express a list response.** `apiCalls[].response`
+   is a flat list of field mappings, so the deterministic OpenAPI contract
+   flattened `accts[].curBal` into a single `currentBalance` scalar and the
+   coder built a one-balance page; the judge scored spec-compliance 0
+   against the spec's per-account table. OPEN: `PageSpec` needs a DTO
+   reference with a list/single shape on the response (and `openApiFor`
+   an array schema) before Act 2 can pass on `accountOverview`. Until then,
+   rehearse Act 2 on a single-object page, or accept the judge failure as
+   the governance beat it is (the branch, contract, tests, and gates are all
+   there; only the judge verdict blocks).
+
+Also observed, not fixed: Claude's structured replies for page specs
+arrived with raw control characters inside JSON strings on three of nine
+wave-1 pages, each costing one repair retry (self-healed); the extraction
+judge's context is narrower than the analyst's closure, so it scored
+`faithfulness` 1 for facts the analyst legitimately read from the servlet
+and ESB sources; `convert-page` places `layout.tsx`, `registry.ts`, and
+`components.css` edits outside the pack's `programFiles`, so the judge sees
+them only as a summary and returns three "cannot verify" findings. Cost
+figures were estimates throughout; the first wave-1 attempt alone reported
+$12.26 estimated before it was stopped.

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; }
+}