@llm4ts/shell 0.18.0 → 1.0.0

package/flows/modernize-extract.js

@@ -41,7 +41,7 @@ import { loadPatternCards, matchingPatternCards } from "@llm4ts/flow/Patterns";
 import { legacySourceWorkspaceLimits, workspaceLimitsFromEnv } from "@llm4ts/flow/Workspace";
 import { ReviewIssue } from "@llm4ts/flow/Review";
 import { cachedReview } from "@llm4ts/flow/ReviewCache";
-import { coverage, coverageUnits, features, matchingFiles } from "@llm4ts/flow/SpecChecks";
+import { coverageReport, coverageUnits, features, matchingFiles, specSchemaIssues } from "@llm4ts/flow/SpecChecks";
 import { SurveyGraph, closureFor, surveyGraph } from "@llm4ts/flow/Survey";
 import { withDraftApproval, requireApproval } from "@llm4ts/flow/Approval";
 import { ProgramArtifacts, ProgramUnit, extractProgramsResumably, programArtifactPaths } from "@llm4ts/flow/Artifacts";
@@ -227,6 +227,12 @@ const program = Effect.gen(function* () {
                 message: `no source units matched the pack's programs/sources regex under ${input.workDir}`
             });
         }
+        const waveScope = wave === undefined || wave.length === 0
+            ? undefined
+            : (() => {
+                const names = new Set(programs.map(programName));
+                return (path) => names.has(programName(path));
+            })();
         const units = programs.map((rel) => ProgramUnit.make({ name: programName(rel), sourcePath: rel }));
         // Pattern cards are selected deterministically from the SOURCE, never by
         // the model: implementation later injects exactly the cards cited here.
@@ -371,8 +377,16 @@ const program = Effect.gen(function* () {
             yield* rebuildIndexes;
             const trace = (yield* files.read(join(modDirAbs, "traceability.md"))) ?? "";
             const mapping = (yield* files.read(join(modDirAbs, "mapping.md"))) ?? "";
+            // The pack's declared spec schema is checked by code, per program,
+            // before any judge runs: a pagespec block the converter could not
+            // decode is an incomplete extraction, not a page to guess at.
+            const schemaIssues = yield* specSchemaIssues(pack.specSchema, yield* Effect.forEach(units, (unit) => Effect.map(files.read(join(modDirAbs, "specs", `${unit.name}.md`)), (markdown) => ({
+                name: unit.name,
+                markdown
+            }))));
             const docs = ReviewResult.make({
                 issues: [
+                    ...schemaIssues,
                     ...(trace.trim().length === 0
                         ? [
                             ReviewIssue.make({
@@ -394,7 +408,21 @@ const program = Effect.gen(function* () {
                 ],
                 summary: "docs"
             });
-            const covered = yield* coverage(repo, pack.coverage, trace);
+            // A wave-scoped run gates only the units its own programs' files
+            // capture; units of other waves (and of estate-wide descriptors such
+            // as web.xml) are left to the run without LLM4TS_WAVE that closes
+            // the estate — otherwise no wave but the last could ever clear.
+            const scoped = yield* coverageReport(repo, pack.coverage, trace, {
+                ...(waveScope === undefined ? {} : { inScope: waveScope })
+            });
+            if (scoped.outOfScope.length > 0) {
+                yield* context.events.publish(Info.make({
+                    message: `${scoped.outOfScope.length} uncovered unit(s) belong to other waves and do not gate ` +
+                        `'${wave}' (${scoped.outOfScope.slice(0, 5).join(", ")}${scoped.outOfScope.length > 5 ? ", …" : ""}); ` +
+                        "run modernize-extract without LLM4TS_WAVE after the last wave to enforce estate-wide coverage"
+                }));
+            }
+            const covered = scoped.result;
             const wellFormed = yield* features(repo, join(ModDir, "features"));
             // Verdicts are per program and cached per program, so they judge
             // under the same bound as extraction; the merge is order-stable.

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

@@ -18,9 +18,10 @@ 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):
+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
@@ -43,11 +44,26 @@ export LLM4TS_EXTRACT_CONCURRENCY=3 # pages extracted and judged at once (measur
 
 `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:
+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
@@ -78,15 +94,31 @@ triaged out, waves proposed. Three beats, in the order the artifacts land:
    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).
+(`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
@@ -124,6 +156,8 @@ 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):
 
@@ -145,6 +179,7 @@ export LLM4TS_ADO_PROJECT=<project>
 | 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. |
 
@@ -152,5 +187,46 @@ export LLM4TS_ADO_PROJECT=<project>
 
 | Rehearsal | Date | Act 1 | Act 2/page | Full walk | Notes |
 | --- | --- | --- | --- | --- | --- |
-| 1 | | | | | |
+| 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/preflight.mjs

@@ -26,6 +26,14 @@ tool("git available", "git", ["--version"])
 tool("node >= 20", "node", ["--version"])
 tool("pnpm available", "pnpm", ["--version"])
 tool("claude CLI available (the coder seat)", "claude", ["--version"])
+check("llm4ts CLI available", () => execFileSync("llm4ts", ["--version"], { stdio: "pipe" }))
+check("llm4ts kits ships j2ee-nextjs/j2ee-nextjs-spa (ADR 0014)", () => {
+  const kits = JSON.parse(execFileSync("llm4ts", ["kits", "--json"], { encoding: "utf8" }))
+  const kit = kits.find((candidate) => candidate.name === "j2ee-nextjs")
+  if (kit === undefined || !kit.packs.includes("j2ee-nextjs-spa")) {
+    throw new Error("the j2ee-nextjs kit or its j2ee-nextjs-spa pack is missing — upgrade @llm4ts/shell to 0.18.0+")
+  }
+})
 
 check("legacy fixture seeds + smoke", () =>
   execFileSync("node", [join(here, "smoke-legacy-j2ee.mjs")], { stdio: "pipe" })

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

@@ -3,6 +3,7 @@
 source: jsp
 scaffold: ../../scaffolds/nextjs-spa
 sources: .*\.(jsp|java|xml)
+spec-schema: pagespec
 programs: .*\.jsp
 specs-dir: docs/modernization/specs
 features-dir: docs/modernization/features

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

@@ -23,7 +23,11 @@ The spec markdown for a page has two mandatory parts:
        "domainName", "type" }] }],
      "apiCalls": [{ "operation": "<domain verb, e.g. listAccounts>",
        "method", "path", "esbService", "request": [{ "legacyName",
-       "domainName", "type" }], "response": [{ ... }] }],
+       "domainName", "type" }],
+       "response": [{ "legacyName", "domainName", "type" }]   // ad-hoc object, OR
+       "responseDto": "<domainName of one of the dtos>",       // the DTO returned,
+       "responseShape": "single" | "list"                     // a table screen is a list
+     }],
      "navigation": { "inbound": [], "outbound": [], "steps": [] },
      "sessionState": ["<what the session carries and why>"],
      "openQuestions": []

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llm4ts/shell",
-  "version": "0.18.0",
+  "version": "1.0.0",
   "description": "Interactive shell and CLI for llm4ts: flow discovery, run-a-flow, and view",
   "license": "MIT",
   "type": "module",
@@ -51,9 +51,9 @@
   "dependencies": {
     "@effect/platform-node": "4.0.0-beta.102",
     "@effect/platform-node-shared": "4.0.0-beta.102",
-    "@llm4ts/core": "0.18.0",
-    "@llm4ts/flow": "0.18.0",
-    "@llm4ts/runner": "0.18.0"
+    "@llm4ts/core": "1.0.0",
+    "@llm4ts/flow": "1.0.0",
+    "@llm4ts/runner": "1.0.0"
   },
   "peerDependencies": {
     "effect": "4.0.0-beta.102"