@llm4ts/shell 2.36.0 → 2.38.0

package/flows/modernize-survey.js

@@ -1,11 +1,13 @@
 // Legacy modernization phase 0: inventory the estate, refine its dependency graph, triage, and propose a human-approved wave plan.
 //
 // Runs rooted at the LEGACY repository (`--repo <legacy>`). Deterministic first:
-// the graph comes from the pack's `sources:` regex and `## Survey:` edge rules
-// (no LLM), then a read-only reasoning pass proposes the edges the regexes
-// missed (each with source evidence; `mergeSurveyEdges` validates and tags them
-// `llm-…`), and finally triage classifies every unit rewrite | retire | wrap
-// and slices the rewrites into dependency-coherent waves. The wave plan lands
+// the graph comes from the pack's `sources:` regex and its `## Survey:` /
+// `## Node:` / `## Edge:` / `## Join:` rules (no LLM; ADR 0030), cached under
+// `.llm4ts/graph/<pack>.json` by file hash. What the scanner could not resolve
+// becomes a bounded worklist for a read-only reasoning pass (attr fills and
+// edges between EXISTING nodes, each verified against the cited source line),
+// and finally triage classifies every unit rewrite | retire | wrap and slices
+// the rewrites into dependency-coherent waves. The wave plan lands
 // at docs/modernization/wave-plan.md with an UNCHECKED approval marker — a
 // human reviews, flips `- [x] Approved`, and only then does modernize-extract
 // start (LLM4TS_WAVE=<name> scopes extraction to one wave).
@@ -27,9 +29,13 @@ import { FlowAborted, Info, asReadOnly, coderFromEnv, makeNodeWorkspace, nodePla
 import { FlowEvents } from "@llm4ts/flow/FlowEvents";
 import { structuredAndPublish } from "@llm4ts/flow/Flow";
 import { loadBenchRecords, renderBenchReport } from "@llm4ts/flow/BenchReport";
-import { SurveyEdge, mergeSurveyEdges, renderSurveyGraphJson, renderSurveyInventory, surveyGraph, surveyRefinePrompt, surveyTriagePrompt } from "@llm4ts/flow/Survey";
+import { nodeKind, renderSurveyGraphJson, renderSurveyInventory, surveyTriagePrompt } from "@llm4ts/flow/Survey";
 import { discoveryOverflowAdvice, legacySourceWorkspaceLimits, workspaceLimitsFromEnv } from "@llm4ts/flow/Workspace";
 import { withDraftApproval } from "@llm4ts/flow/Approval";
+import { freshGraph, graphCachePath, updateGraphCache } from "@llm4ts/flow/GraphCache";
+import { WorklistAnswer, mergeWorklist, renderWorklistReport, verifyWorklistAnswer, worklistAnswerJsonSchema, worklistBatches, worklistOf, worklistPrompt } from "@llm4ts/flow/GraphWorklist";
+import { wholeView } from "@llm4ts/flow/GraphQuery";
+import { renderClusterDiagrams, renderEntryPaths, renderGraphDot } from "@llm4ts/flow/GraphRender";
 const ModDir = "docs/modernization";
 class NodeTriage extends Schema.Class("NodeTriage")({
     name: Schema.String,
@@ -80,63 +86,21 @@ const surveyOutcomeJsonSchema = {
     },
     required: ["triage", "waves", "notes"]
 };
-class RefinedEdge extends Schema.Class("RefinedEdge")({
-    from: Schema.String,
-    to: Schema.String,
-    kind: Schema.String,
-    evidence: Schema.String
-}) {
-}
-class GraphRefinement extends Schema.Class("GraphRefinement")({
-    edges: Schema.Array(RefinedEdge),
-    notes: Schema.Array(Schema.String)
-}) {
-}
-const graphRefinementJsonSchema = {
-    type: "object",
-    properties: {
-        edges: {
-            type: "array",
-            items: {
-                type: "object",
-                properties: {
-                    from: { type: "string" },
-                    to: { type: "string" },
-                    kind: { type: "string" },
-                    evidence: { type: "string" }
-                },
-                required: ["from", "to", "kind", "evidence"]
-            }
-        },
-        notes: { type: "array", items: { type: "string" } }
-    },
-    required: ["edges", "notes"]
-};
 const tableCell = (text) => text.split(/\r?\n/).join(" ").replaceAll("|", "\\|");
-const renderRefine = (refinement, kept) => {
-    const keptKeys = new Set(kept.map((edge) => `${edge.from}${edge.to}`));
-    const rows = refinement.edges.map((edge) => {
-        const status = keptKeys.has(`${edge.from}${edge.to}`)
-            ? "added"
-            : "dropped — duplicate, self-loop, or unknown unit";
-        return `| ${edge.from} | ${edge.to} | ${edge.kind} | ${status} | ${tableCell(edge.evidence)} |`;
-    });
-    const notes = refinement.notes.length === 0
-        ? []
-        : ["## Unresolved", "", ...refinement.notes.map((note) => `- ${tableCell(note)}`)];
-    return ([
-        "# Graph refine (LLM)",
-        "",
-        `${kept.length} of ${refinement.edges.length} proposed edge(s) merged into \`graph.json\` (kind prefixed \`llm-\`).`,
-        "Each carries the source statement that establishes it — verify before trusting a wave built on it.",
-        "",
-        "| From | To | Kind | Status | Evidence |",
-        "| ---- | -- | ---- | ------ | -------- |",
-        ...rows,
-        "",
-        ...notes
-    ].join("\n") + "\n");
-};
+/** inventory.md (units, cluster diagrams, entry paths), graph.json and graph.dot. */
+const writeGraphArtifacts = (repo, pack, graph) => Effect.gen(function* () {
+    const programs = graph.nodes
+        .filter((node) => nodeKind(node) === "file")
+        .map((node) => node.name);
+    const inventory = [
+        renderSurveyInventory(graph),
+        renderClusterDiagrams(graph, pack.consolidate ?? { cluster: [], context: [] }, programs),
+        renderEntryPaths(graph)
+    ].join("\n");
+    yield* repo.write(join(ModDir, "inventory.md"), inventory);
+    yield* repo.write(join(ModDir, "graph.json"), renderSurveyGraphJson(graph));
+    yield* repo.write(join(ModDir, "graph.dot"), renderGraphDot(wholeView(graph), graph));
+});
 const renderWavePlan = (outcome, graph, projection) => {
     const triageRows = [...outcome.triage]
         .sort((left, right) => left.name.localeCompare(right.name))
@@ -182,16 +146,15 @@ const program = Effect.gen(function* () {
             launchDir: input.workspace,
             flowDir: import.meta.dirname
         }));
-        if (pack.survey.length === 0) {
+        if (pack.graph.edges.length === 0 && pack.graph.joins.length === 0) {
             return yield* FlowAborted.make({
-                message: `pack '${pack.name}' has no '## Survey:' sections — add the dependency-edge ` +
-                    "regexes (CALL/COPY/EXEC PGM…) the graph should be built from"
+                message: `pack '${pack.name}' has no '## Survey:', '## Edge:' or '## Join:' sections — add the ` +
+                    "dependency-edge rules (CALL/COPY/EXEC PGM, ajax → servlet…) the graph should be built from"
             });
         }
-        const graph = yield* stage(context.events, "graph", Effect.gen(function* () {
-            const built = yield* surveyGraph(repo, pack.sources ?? ".*", pack.coverage, pack.survey, {
-                ...(pack.exclude === undefined ? {} : { exclude: pack.exclude })
-            }).pipe(
+        const cachePath = graphCachePath(input.workDir, pack.name);
+        const fresh = yield* stage(context.events, "graph", Effect.gen(function* () {
+            const built = yield* freshGraph(nodePlainFileStore, cachePath, pack, repo).pipe(
             // The cap is a guard against runaway trees, not a verdict on the
             // estate: name the three knobs instead of a bare limit number.
             Effect.catchTag("WorkspaceLimit", (error) => Effect.fail(error.operation === "discovery results"
@@ -199,33 +162,63 @@ const program = Effect.gen(function* () {
                     message: `${input.workDir}: ${discoveryOverflowAdvice(limits)}`
                 })
                 : error)));
-            yield* repo.write(join(ModDir, "inventory.md"), renderSurveyInventory(built));
-            yield* repo.write(join(ModDir, "graph.json"), renderSurveyGraphJson(built));
-            yield* context.events.publish(Info.make({ message: `${built.nodes.length} unit(s), ${built.edges.length} edge(s)` }));
+            yield* writeGraphArtifacts(repo, pack, built.graph);
+            yield* context.events.publish(Info.make({
+                message: `${built.graph.nodes.length} node(s), ${built.graph.edges.length} edge(s), ` +
+                    `${built.graph.unresolved.length} unresolved` +
+                    (built.reused ? " (graph cache reused)" : "")
+            }));
             return built;
         }));
+        const graph = fresh.graph;
         const refined = yield* stage(context.events, "graph refine", refineDisabled(process.env)
             ? context.events
                 .publish(Info.make({ message: "LLM4TS_GRAPH_REFINE=off — regex graph ships unrefined" }))
                 .pipe(Effect.as(graph))
             : Effect.gen(function* () {
-                const refinement = yield* withShrink("survey refine", (cap) => Effect.gen(function* () {
-                    const prompt = yield* capped("graph", surveyRefinePrompt(graph, {
-                        rules: pack.survey,
-                        guidance: pack.prompt("survey-refine")
-                    }), cap);
-                    return yield* structuredAndPublish(context.reasoning, context.events, prompt, GraphRefinement, graphRefinementJsonSchema);
-                })).pipe(Effect.provideService(FlowEvents, context.events));
-                const merged = mergeSurveyEdges(graph, refinement.edges.map((edge) => SurveyEdge.make({ from: edge.from, to: edge.to, kind: edge.kind })));
-                const kept = merged.edges.filter((edge) => edge.kind.startsWith("llm-"));
-                yield* repo.write(join(ModDir, "graph-refine.md"), renderRefine(refinement, kept));
-                if (kept.length > 0) {
-                    yield* repo.write(join(ModDir, "inventory.md"), renderSurveyInventory(merged));
-                    yield* repo.write(join(ModDir, "graph.json"), renderSurveyGraphJson(merged));
+                const contents = new Map();
+                const load = (path) => contents.has(path)
+                    ? Effect.void
+                    : repo.read(path).pipe(Effect.orElseSucceed(() => ""), Effect.map((text) => void contents.set(path, text)));
+                const read = (path) => contents.get(path);
+                for (const file of new Set(graph.unresolved.map((item) => item.file))) {
+                    yield* load(file);
+                }
+                const items = worklistOf(graph, read, pack.graph.worklistMax, pack.graph);
+                if (items.length === 0) {
+                    yield* context.events.publish(Info.make({ message: "nothing unresolved — no LLM pass needed" }));
+                    return graph;
+                }
+                let merged = graph;
+                const accepted = [];
+                const notes = [];
+                for (const batch of worklistBatches(items, pack.graph.batchSize)) {
+                    const answer = yield* withShrink("graph worklist", (cap) => Effect.gen(function* () {
+                        const prompt = yield* capped("worklist", worklistPrompt(batch, pack.prompt("survey-refine")), cap);
+                        return yield* structuredAndPublish(context.reasoning, context.events, prompt, WorklistAnswer, worklistAnswerJsonSchema);
+                    })).pipe(Effect.provideService(FlowEvents, context.events));
+                    for (const file of new Set([
+                        ...answer.edges.map((edge) => edge.evidence.file),
+                        ...answer.attrs.map((attr) => attr.evidence.file)
+                    ])) {
+                        yield* load(file);
+                    }
+                    const verified = verifyWorklistAnswer(answer, merged, read);
+                    merged = mergeWorklist(merged, verified, pack.graph);
+                    accepted.push(verified);
+                    notes.push(...answer.notes);
                 }
+                const all = {
+                    edges: accepted.flatMap((verified) => verified.edges),
+                    fills: accepted.flatMap((verified) => verified.fills),
+                    dropped: accepted.flatMap((verified) => verified.dropped)
+                };
+                yield* repo.write(join(ModDir, "graph-refine.md"), renderWorklistReport(items, all, notes));
+                yield* updateGraphCache(nodePlainFileStore, cachePath, fresh.cache, merged);
+                yield* writeGraphArtifacts(repo, pack, merged);
                 yield* context.events.publish(Info.make({
-                    message: `${kept.length} regex-missed edge(s) merged ` +
-                        `(${refinement.edges.length} proposed by the LLM)`
+                    message: `${all.edges.length} edge(s) and ${all.fills.length} fill(s) accepted from ` +
+                        `${items.length} unresolved item(s); ${all.dropped.length} dropped`
                 }));
                 return merged;
             }));

package/kits/j2ee-nextjs/flows/lib/convert.js

@@ -19,7 +19,8 @@ import { openApiFor, openApiForFeature, parsePageSpec, renderPageSpec } from "@l
 import { loadPatternCards, matchingPatternCards } from "@llm4ts/flow/Patterns";
 import { Task } from "@llm4ts/flow/Plan";
 import { judgeAllPrograms } from "@llm4ts/flow/ProgramJudge";
-import { closureFor, surveyGraph } from "@llm4ts/flow/Survey";
+import { closureFor } from "@llm4ts/flow/Survey";
+import { freshGraph, graphCachePath } from "@llm4ts/flow/GraphCache";
 import { estimatedUsageOptionsFromEnv, makeEstimatedUsageMeter } from "@llm4ts/flow/EstimatedUsage";
 import { legacySourceWorkspaceLimits, workspaceLimitsFromEnv } from "@llm4ts/flow/Workspace";
 export const positiveEnvInt = (environment, name, fallback) => {
@@ -213,7 +214,7 @@ const legacyEvidence = Effect.fn("convert.legacyEvidence")(function* (deps, page
     const source = sourcePath === undefined
         ? ""
         : yield* deps.legacy.read(sourcePath).pipe(Effect.orElseSucceed(() => ""));
-    const graph = yield* surveyGraph(deps.legacy, deps.pack.sources ?? ".*", deps.pack.coverage, deps.pack.survey);
+    const graph = (yield* freshGraph(deps.files, graphCachePath(deps.legacyDir, deps.pack.name), deps.pack, deps.legacy)).graph;
     const closure = closureFor(graph, page, positiveEnvInt(deps.environment, "LLM4TS_MAX_CLOSURE_FILES", 12));
     const parts = [];
     if (sourcePath !== undefined) {
@@ -480,7 +481,7 @@ export const convertFeature = Effect.fn("convert.feature")(function* (deps, feat
     for (const page of pages) {
         specs.set(page, yield* readSpec(deps, page));
     }
-    const graph = yield* surveyGraph(deps.legacy, deps.pack.sources ?? ".*", deps.pack.coverage, deps.pack.survey);
+    const graph = (yield* freshGraph(deps.files, graphCachePath(deps.legacyDir, deps.pack.name), deps.pack, deps.legacy)).graph;
     const order = navigationOrder({ ...feature, programs: pages }, graph, deps.pack.consolidate ?? { cluster: [], context: [] });
     const contractPath = `contracts/${feature.id}.openapi.yaml`;
     const contract = yield* openApiForFeature(feature, order.map((page) => specs.get(page)?.spec).filter((spec) => spec !== undefined));

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

@@ -49,15 +49,48 @@ unit: <jsp:include page="([^"]+)"
 files: .*web\.xml
 unit: <servlet-class>[a-z.]*\.([A-Za-z0-9]+)</servlet-class>
 
-## Survey: jsp-form-action
+## Node: ajax-call
 
-files: .*\.jsp
-unit: action="([^"]+)"
+files: .*\.(jsp|js)
+pattern: (?:["']?url["']?\s*:\s*|\$\.(?:get|post|getJSON)\(\s*)['"](?<name>[^'"]+)['"]
+attrs: url=name
 
-## Survey: jsp-ajax-target
+## Node: form
 
 files: .*\.jsp
-unit: url:\s*['"]([^'"?]+)
+pattern: <(?:[a-z]+:)?[Ff][Oo][Rr][Mm]\b[^>]*\b[Aa][Cc][Tt][Ii][Oo][Nn]=["'](?<name>[^"']+)["']
+attrs: url=name
+
+## Node: servlet-mapping
+
+files: .*web\.xml
+pattern: <servlet-mapping>\s*<servlet-name>(?<name>[^<]+)</servlet-name>\s*<url-pattern>(?<url>[^<]+)</url-pattern>
+descriptor: yes
+
+## Node: servlet-decl
+
+files: .*web\.xml
+pattern: <servlet>(?:(?!</servlet>)[\s\S])*?<servlet-name>(?<name>[^<]+)</servlet-name>(?:(?!</servlet>)[\s\S])*?<servlet-class>(?:[a-z0-9_]+\.)*(?<class>[A-Za-z0-9_]+)</servlet-class>
+descriptor: yes
+anchor: class
+
+## Join: jsp-ajax-target
+
+from: ajax-call.url
+to: servlet-mapping.url
+match: url
+
+## Join: jsp-form-action
+
+from: form.url
+to: servlet-mapping.url
+match: url
+
+## Join: servlet-wiring
+
+from: servlet-mapping.name
+to: servlet-decl.name
+scope: file
 
 ## Consolidate
 

package/kits/mainframe-java/packs/cobol-kafka/pack.md

@@ -49,3 +49,27 @@ unit: ^ {6}[ ]*COPY +([A-Z0-9]+)
 
 files: .*\.(jcl|JCL)
 unit: EXEC +PGM=([A-Z0-9]+)
+
+## Node: cobol-section
+
+files: .*\.(cbl|CBL)
+pattern: ^ {7}(?<name>[A-Z0-9][A-Z0-9-]*) +SECTION\.
+
+## Node: cobol-paragraph
+
+files: .*\.(cbl|CBL)
+pattern: ^ {7}(?<name>\d{4}-[A-Z0-9-]+)\.
+
+## Edge: performs
+
+files: .*\.(cbl|CBL)
+pattern: PERFORM +(?<to>\d{4}-[A-Z0-9-]+)(?: +THRU +(?<thru>\d{4}-[A-Z0-9-]+))?
+from: cobol-paragraph
+to: cobol-paragraph
+
+## Edge: goes-to
+
+files: .*\.(cbl|CBL)
+pattern: GO +TO +(?<to>\d{4}-[A-Z0-9-]+)
+from: cobol-paragraph
+to: cobol-paragraph

package/kits/mainframe-java/packs/cobol-springboot/pack.md

@@ -50,6 +50,30 @@ unit: ^ {6}[ ]*COPY +([A-Z0-9]+)
 files: .*\.(jcl|JCL)
 unit: EXEC +PGM=([A-Z0-9]+)
 
+## Node: cobol-section
+
+files: .*\.(cbl|CBL)
+pattern: ^ {7}(?<name>[A-Z0-9][A-Z0-9-]*) +SECTION\.
+
+## Node: cobol-paragraph
+
+files: .*\.(cbl|CBL)
+pattern: ^ {7}(?<name>\d{4}-[A-Z0-9-]+)\.
+
+## Edge: performs
+
+files: .*\.(cbl|CBL)
+pattern: PERFORM +(?<to>\d{4}-[A-Z0-9-]+)(?: +THRU +(?<thru>\d{4}-[A-Z0-9-]+))?
+from: cobol-paragraph
+to: cobol-paragraph
+
+## Edge: goes-to
+
+files: .*\.(cbl|CBL)
+pattern: GO +TO +(?<to>\d{4}-[A-Z0-9-]+)
+from: cobol-paragraph
+to: cobol-paragraph
+
 ## Consolidate
 
 - cluster: calls, exec-pgm

package/kits/port/README.md

@@ -26,9 +26,10 @@ another pair copies one of these and replaces the rulebook, the pitfall card,
 `target:`, the diagnostics command, the ledger regex and the two test
 commands.
 
-| Pack       | Source → target                 | Diagnostics                         | Ledger units             |
-| ---------- | ------------------------------- | ----------------------------------- | ------------------------ |
-| `zig-rust` | Zig → Rust                      | `cargo check --message-format=json` | pointer and slice fields |
-| `scala-ts` | Scala 3 / ZIO 2 → TS / Effect 4 | `tsc --pretty false`                | classes, objects, traits |
+| Pack                    | Source → target                                                                                          | Diagnostics                             | Ledger units                      |
+| ----------------------- | -------------------------------------------------------------------------------------------------------- | --------------------------------------- | --------------------------------- |
+| `zig-rust`              | Zig → Rust                                                                                               | `cargo check --message-format=json`     | pointer and slice fields          |
+| `scala-ts`              | Scala 3 / ZIO 2 → TS / Effect 4                                                                          | `tsc --pretty false`                    | classes, objects, traits          |
+| `cobol-springboot-port` | COBOL → Java / Spring Boot 3 (file by file; the clean-room sibling is `mainframe-java/cobol-springboot`) | `mvn -q -B -DskipTests compile` (javac) | level-01 records, FDs, paragraphs |
 
 `## Diagnostics` reads `json` (one object per line), `cargo` (`--message-format=json`), `tsc` (`--pretty false`) or `javac` (javac's and Maven's error lines, the Maven module as the unit).

package/kits/port/packs/cobol-springboot-port/pack.md

@@ -0,0 +1,48 @@
+# Pack: cobol-springboot-port
+
+source: cobol
+sources: .*\.(cbl|cob|cpy|CBL|COB|CPY)$
+exclude: (^|/)(target|build|\.git|node_modules)/
+target: src/main/java/legacy/{{dir}}/{{base}}.java
+comment: //
+specs-dir: docs/port
+features-dir: docs/port/features
+
+## Gates
+
+- compile: mvn -q -B -DskipTests compile
+- test: mvn -q -B test
+
+## Diagnostics
+
+- command: mvn -q -B -DskipTests compile
+- format: javac
+
+## Ledger
+
+- unit: ^\s{0,7}(?:01|77)\s+([A-Z][A-Z0-9-]*)|^\s{0,7}FD\s+([A-Z][A-Z0-9-]*)|^\s{0,7}([A-Z0-9][A-Z0-9-]*)\s*(?:SECTION)?\.\s*$
+- classes: RECORD, FILE, PARAGRAPH, SQL, CICS, COPYBOOK, REPORT, UTIL, UNKNOWN
+- question: What does this COBOL unit become in a Spring Boot port? RECORD (a level-01 or 77 data item → a Java record or class with BigDecimal for numerics), FILE (an FD / SELECT → a JPA entity with a Spring Data repository, or a reader for a flat file), PARAGRAPH (a paragraph or section → a private method on the program's @Service), SQL (a paragraph whose body is EXEC SQL → a repository query), CICS (EXEC CICS send/receive → a controller endpoint or a service boundary), COPYBOOK (a shared record → a class in the copybook package, ported once), REPORT (a print layout → a formatter), UTIL (a pure routine).
+
+## Differential
+
+- tests: ^tests/.*\.(txt|dat|json)$
+- legacy: scripts/legacy-run.sh {{file}}
+- target: scripts/target-run.sh {{file}}
+- timeout: 120
+
+## Audit
+
+- dimensions: data division and record layouts, PIC clauses and numeric semantics, files and embedded SQL, control flow (PERFORM, GO TO, fall-through), copybooks and shared records, batch versus online (CICS), transaction boundaries, test idioms, what not to translate
+
+## Review rules
+
+A `double` or `float` holding money, a quantity or any `COMP-3` field is a
+finding: numerics are `BigDecimal` with the PIC's scale, or `long` for
+unsigned integer PICs. A `MOVE` whose truncation or padding the source relied
+on must be written out, not assumed. `GO TO` is flattened into structured
+control flow with a `// PORTED: GO TO` note, never a `while (true)` with a
+state variable unless the source was a state machine. Every file and SQL
+access sits behind a Spring Data repository or a dedicated reader; every
+program that commits has one `@Transactional` boundary. A paragraph the
+source has that the draft lacks is a finding.

package/kits/port/packs/cobol-springboot-port/patterns/pitfalls-cobol-springboot-port.md

@@ -0,0 +1,36 @@
+---
+title: COBOL → Java/Spring Boot pitfalls — alike on the page, different at runtime
+matches: .
+tags: port, cobol, java, spring-boot
+---
+1. **Decimal scale.** `PIC S9(7)V99 COMP-3` has an implied point: `1234567.89`
+   is stored as nine digits. A `double` loses cents; a `BigDecimal` without
+   `setScale(2)` prints `1234567.9`.
+2. **Truncation on MOVE.** Moving `PIC X(10)` into `PIC X(5)` keeps the left
+   five characters; moving `PIC 9(5)` into `PIC 9(3)` keeps the right three
+   digits. Java assignment keeps everything.
+3. **Padding.** An alphanumeric field is space-padded to its width, so
+   `"ABC" = "ABC  "` is true in COBOL and false in Java. Trim or pad at the
+   boundary, in one place.
+4. **Signed overpunch.** `PIC S9(3)` in display format carries the sign in
+   the last byte (`12}` is `-120`). Parse it; never `Long.parseLong` the raw
+   bytes.
+5. **PERFORM THRU and fall-through.** Control falls into the next paragraph
+   unless something stops it; a `PERFORM A THRU C` runs `B` too. A method per
+   paragraph needs the range written out.
+6. **GO TO out of a PERFORM.** The paragraph's exit point moves. Flatten with
+   care, and say which exit the source used.
+7. **REDEFINES.** Two layouts over the same bytes; writing one view changes
+   the other. Two Java fields are two values; make the conversion explicit.
+8. **OCCURS DEPENDING ON.** The table's length is another field's value at
+   that moment; a fixed array hides out-of-range reads the source tolerated.
+9. **88-levels and VALUE.** A condition name tests the parent's current
+   value; `SET name TO TRUE` writes the first `VALUE`. Keep both directions.
+10. **Zero-based indexing.** COBOL subscripts start at 1. Every `OCCURS`
+    access shifts by one.
+11. **ROUNDED and ON SIZE ERROR.** `COMPUTE` truncates by default and
+    rounds only with `ROUNDED`; `RoundingMode.HALF_UP` is not the default.
+12. **Dates.** `YYMMDD` with a century window, `ACCEPT FROM DATE` in local
+    time: pin the rule and the clock.
+13. **Sequential file state.** `READ ... AT END` and `FILE STATUS` codes are
+    the control flow; a reader that throws on end-of-file changes it.

package/kits/port/packs/cobol-springboot-port/prompts/porting.md

@@ -0,0 +1,92 @@
+You are translating one COBOL source unit (a program or a copybook) to Java
+on Spring Boot 3. Read this whole document before writing any code. The first
+pass is a **draft** `.java` at the path the flow gives you, that captures the
+logic faithfully; it does **not** need to compile. The compile pass makes it
+compile module by module.
+
+## Ground rules
+
+- Same unit, same names, same order. The public class is named exactly as
+  the file the flow asked for (Java requires it); paragraphs become private
+  methods in the order they appear, named in camelCase after the paragraph
+  (`2000-READ-INPUT` → `readInput2000`, the number kept as a suffix so the
+  reviewer can diff the two files side by side). Data items keep their names
+  in camelCase (`WS-TOTAL-AMT` → `wsTotalAmt`).
+- A program is one `@Service` bean. Its `PROCEDURE DIVISION` is a public
+  `run(...)` method whose parameters are the `ACCEPT`ed values and the
+  `LINKAGE SECTION` items; its `WORKING-STORAGE` becomes fields on a private
+  state class created per run, never static fields.
+- A copybook is one class in the `legacy.copybook` package, ported once and
+  imported by every program that `COPY`s it. Do not inline it.
+- Numerics are exact. `PIC S9(7)V99 COMP-3` is `BigDecimal` with scale 2;
+  `PIC 9(5)` is `long`; `PIC X(n)` is `String` with the width recorded in a
+  comment. Money is never `double`.
+- Files and SQL are repositories. An `FD` with `SELECT ... ASSIGN` becomes a
+  JPA `@Entity` plus a Spring Data repository when the file is a keyed VSAM
+  or DB table, or a dedicated reader class for a sequential flat file.
+  `EXEC SQL` becomes a repository method; the host variables are its
+  parameters. One `@Transactional` on `run` where the program `COMMIT`s at
+  the end; explicit boundaries where it commits mid-way.
+- `EXEC CICS` is the online boundary: `SEND MAP` / `RECEIVE MAP` become a
+  request and response record on a `@RestController` that calls the service;
+  `LINK` / `XCTL` become a call to the other program's service bean.
+- `DISPLAY` is a logger call at `info`; `DISPLAY` of an error is `warn`.
+  `ACCEPT FROM DATE` is `LocalDate.now(clock)` with an injected `Clock`.
+  `STOP RUN` is a `return`; `GOBACK` is a `return` from the program method.
+- Leave `// TODO(port): <reason>` for anything you cannot translate
+  confidently. Do not guess.
+- Do not translate JCL, compile options, SORT control cards or `IDENTIFICATION
+  DIVISION` metadata; note them as `// SKIPPED(port): <what>`.
+
+## Type map
+
+| COBOL                              | Java / Spring Boot                                  |
+| ---------------------------------- | --------------------------------------------------- |
+| `PIC X(n)`                         | `String` (width `n` noted; pad or trim on `MOVE`)   |
+| `PIC 9(n)`                         | `long` (`int` when `n` ≤ 9 and the source never exceeds it) |
+| `PIC S9(n)V9(m)`, `COMP-3`         | `BigDecimal` with scale `m`, `RoundingMode.DOWN` unless `ROUNDED` |
+| `COMP` / `BINARY`                  | `int` or `long` by the PIC                          |
+| level-01 record                    | a `record` when read-only after construction, else a class |
+| `OCCURS n`                         | an array or `List` sized `n`; `OCCURS DEPENDING ON` → `List` |
+| `REDEFINES`                        | a second view class with explicit conversion methods |
+| 88-level condition name            | a `boolean` method on the owning record (`isActive()`) |
+| `FD` + `SELECT`                    | `@Entity` + `JpaRepository`, or a flat-file reader   |
+| `EXEC SQL`                         | a repository method or `JdbcTemplate` call           |
+| `EXEC CICS SEND/RECEIVE MAP`       | `@RestController` request/response records           |
+| `CALL 'PROG' USING ...`            | a call to `Prog.run(...)` on the injected bean       |
+| `PERFORM para`                     | a method call                                        |
+| `PERFORM para THRU other`          | calls to each paragraph in source order, in a method named after the range |
+| `PERFORM ... UNTIL cond`           | `while (!cond) { … }` (test before) or `do { … } while` (`WITH TEST AFTER`) |
+| `PERFORM VARYING`                  | a `for` loop                                          |
+| `EVALUATE`                         | `switch` with pattern matching, or an `if` chain for `EVALUATE TRUE` |
+| `GO TO`                            | structured flow with a `// PORTED: GO TO` note        |
+| `STRING` / `UNSTRING`              | `StringBuilder` / `split` with the delimiters written out |
+| `INSPECT ... TALLYING/REPLACING`   | explicit counting / `replace`                          |
+| `SORT` / `MERGE`                   | `Comparator` on a `List`, or a stream `sorted`         |
+| `DISPLAY` / `ACCEPT`               | `log.info` / a method parameter                        |
+
+## Idiom map
+
+- A `MOVE` between items of different widths truncates on the right for
+  alphanumerics and on the left for numerics; write the truncation out
+  (`substring`, `remainder`) where the source relies on it, and say so.
+- `ON SIZE ERROR` is an explicit range check before the assignment.
+- `ADD 1 TO WS-COUNT` is `wsCount++` only when the PIC cannot overflow;
+  otherwise the modulus the PIC implies.
+- A paragraph that is both `PERFORM`ed and fallen into is split: the
+  fall-through becomes an explicit call at the end of the preceding method.
+- Dates `PIC 9(6)` `YYMMDD` become `LocalDate` with the century rule the
+  program used, written in one place.
+- `FILE STATUS` checks become typed exceptions on the reader or repository.
+
+## Output format
+
+End the file with the trailer the flow reads:
+
+```java
+// PORT STATUS
+// source: <path>.cbl
+// confidence: high | medium | low
+// todos: <count of TODO(port)>
+// notes: <one line>
+```

package/kits/port/packs/cobol-springboot-port/reviewers/spring-fidelity.md

@@ -0,0 +1,15 @@
+---
+files: \.java$
+---
+Review a Java draft against the rulebook as a port reviewer would, with the
+COBOL source in mind: the diff is the draft. Report as findings: a paragraph,
+data item or 88-level the source has that the draft lacks; a `double` or
+`float` holding a `COMP-3`, money or quantity field; a `BigDecimal` whose
+scale differs from the PIC; a `MOVE` truncation or padding the source relied
+on that the draft assumes away; a `GO TO` turned into a state variable loop
+when the flow was structured; a `PERFORM THRU` range that skips a paragraph;
+file or SQL access outside a repository or reader; a program that commits
+with no `@Transactional` boundary; `WORKING-STORAGE` turned into static
+fields; a copybook inlined instead of imported; a guessed translation where a
+`TODO(port)` was honest. Do not report imports or beans that cannot resolve
+yet: the compile pass owns those.

package/package.json

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