@llm4ts/shell 2.1.0 → 2.2.1

package/flows/modernize-seed.js

@@ -27,6 +27,7 @@ import { packageVersion } from "@llm4ts/flow/Package";
 import { Provenance, makeProvenanceStore } from "@llm4ts/flow/Provenance";
 import { matchingFiles } from "@llm4ts/flow/SpecChecks";
 import { requireApproval } from "@llm4ts/flow/Approval";
+import { Decisions, filterFeature, parseDecisions } from "@llm4ts/flow/Decisions";
 const ModDir = "docs/modernization";
 const skipped = new Set([".git", "target", "node_modules", "dist"]);
 const Seats = Schema.Record(Schema.String, Schema.String);
@@ -84,7 +85,20 @@ const program = Effect.gen(function* () {
         }));
         const pack = opened.pack;
         const specPackRoot = join(legacyRepo, ModDir);
-        yield* stage(context.events, "approval", requireApproval(files, join(specPackRoot, "README.md")));
+        // The README always; each refinement overlay when it exists (ADR 0015):
+        // a pack refined after its gate passed is seeded only as approved.
+        yield* stage(context.events, "approval", Effect.gen(function* () {
+            yield* requireApproval(files, join(specPackRoot, "README.md"));
+            for (const overlay of ["decisions.md", "domains.md"]) {
+                if ((yield* files.read(join(specPackRoot, overlay))) !== undefined) {
+                    yield* requireApproval(files, join(specPackRoot, overlay));
+                }
+            }
+        }));
+        const decisionsText = yield* files.read(join(specPackRoot, "decisions.md"));
+        const decisions = decisionsText === undefined
+            ? Decisions.empty()
+            : yield* parseDecisions(decisionsText, `${ModDir}/decisions.md`);
         yield* stage(context.events, "scaffold", Effect.gen(function* () {
             const existing = (yield* target.discover().pipe(Effect.orElseSucceed(() => []))).filter((path) => !path.startsWith(".git/"));
             if (existing.length > 0) {
@@ -116,8 +130,42 @@ const program = Effect.gen(function* () {
                         "check LLM4TS_LEGACY_REPO and that extraction wrote its spec pack"
                 });
             }
+            // The projection (ADR 0015): a feature file reaches the target
+            // with only its surviving scenarios, so the coder never sees a
+            // scenario it must not encode; a program disposed as a whole
+            // ships no feature file at all. Specs are copied unchanged, with
+            // the overlays beside them for the judges.
             const features = yield* copyTree(legacy, target, `${ModDir}/features`, pack.featuresDir);
-            for (const index of ["traceability.md", "mapping.md", "rules.txt"]) {
+            let projected = 0;
+            if (!decisions.isEmpty) {
+                const featurePaths = yield* target
+                    .discover(`${pack.featuresDir}/**`)
+                    .pipe(Effect.orElseSucceed(() => []));
+                for (const path of featurePaths) {
+                    const stem = (path.split("/").at(-1) ?? "").replace(/\.feature$/, "").toLowerCase();
+                    const program = [...decisions.programs, ...decisions.scenarios]
+                        .map((entry) => entry.program)
+                        .find((name) => name.toLowerCase() === stem);
+                    if (program === undefined) {
+                        continue;
+                    }
+                    projected += 1;
+                    if (decisions.programDecision(program) !== undefined) {
+                        yield* target.write(path, "");
+                        continue;
+                    }
+                    const text = yield* target.read(path);
+                    yield* target.write(path, filterFeature(text, decisions.disposedScenarios(program)));
+                }
+                yield* context.events.publish(Info.make({ message: `projected decisions onto ${projected} feature file(s)` }));
+            }
+            for (const index of [
+                "traceability.md",
+                "mapping.md",
+                "rules.txt",
+                "decisions.md",
+                "domains.md"
+            ]) {
                 yield* copyFile(legacy, target, `${ModDir}/${index}`, join(pack.specsDir, index));
             }
             return specs + features;

package/flows/modernize-verify.js

@@ -229,7 +229,7 @@ const triagePrompt = (pack, failing, specText) => {
 /** The spec'd programs: top-level `<NAME>.md` files under the specs dir, indexes aside. */
 const specPrograms = Effect.fn("modernize-verify.specPrograms")(function* (target, specsDir) {
     const paths = yield* matchingFiles(target, `^${specsDir}/[^/]+\\.md$`).pipe(Effect.orElseSucceed(() => []));
-    const excluded = new Set(["traceability", "mapping", "README"]);
+    const excluded = new Set(["traceability", "mapping", "README", "decisions", "domains"]);
     return paths
         .map((path) => (path.split("/").at(-1) ?? path).replace(/\.md$/, ""))
         .filter((name) => !excluded.has(name))
@@ -268,10 +268,17 @@ const program = Effect.gen(function* () {
             yield* context.events.publish(Info.make({ message: "clean-room wall: no legacy source in the target workspace" }));
         }));
         const rulesText = (yield* files.read(join(input.workDir, pack.specsDir, "rules.txt"))) ?? "";
-        const universe = rulesText
-            .split(/\r?\n/)
-            .map((line) => line.trim())
-            .filter((line) => line.length > 0);
+        // Everything above `# waived` is the universe; the units below it were
+        // waived by a decision (ADR 0015) and are neither expected nor flagged.
+        const rulesLines = rulesText.split(/\r?\n/).map((line) => line.trim());
+        const waivedAt = rulesLines.indexOf("# waived");
+        const universe = (waivedAt < 0 ? rulesLines : rulesLines.slice(0, waivedAt)).filter((line) => line.length > 0);
+        const waived = waivedAt < 0 ? [] : rulesLines.slice(waivedAt + 1).filter((l) => l.length > 0);
+        if (waived.length > 0) {
+            yield* context.events.publish(Info.make({
+                message: `${waived.length} rule(s) waived by decision are left out of the universe`
+            }));
+        }
         if (universe.length === 0) {
             yield* context.events.publish(Info.make({
                 message: "no rules.txt in the seeded spec pack — the report will use the vectors' own " +

package/kits/j2ee-nextjs/README.md

@@ -15,10 +15,11 @@ target) the [workshop runbook](fixtures/demo-bank/RUNBOOK.md) rehearses on.
 | [`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 |
+| Flow              | What it does                                                                             |
+| ----------------- | ---------------------------------------------------------------------------------------- |
+| `convert-page`    | Convert ONE extracted page into the Next.js target on its own branch                     |
+| `convert-feature` | Convert ONE domain feature of the approved `domains.md`: one branch, one merged contract |
+| `convert-all`     | Walk the approved domain map (features) or the survey inventory (pages), one branch each |
 
 ```sh
 llm4ts run modernize-pack-check --pack j2ee-nextjs-spa --repo /path/to/legacy-estate

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

@@ -119,6 +119,49 @@ estate once every wave is in.
 LLM4TS_WAVE=wave-2 llm4ts run modernize-extract --repo ~/demo/legacy-j2ee
 ```
 
+### Refine — the pack becomes what the client wants built (optional beat)
+
+Extraction says what the legacy does. Refinement (ADR 0015) says what the
+target should become, in two files the audience can read on screen:
+
+```bash
+llm4ts refine --repo ~/demo/legacy-j2ee --target ~/demo/nextjs
+```
+
+Three marks, then run:
+
+1. **Mark programs** — `promoQ3`, `oldTransfer`, `testHarness`: `drop`
+   ("dead, nothing links here"); `login`: `?` with the note "the target has
+   an AuthProvider". The proposal reads `~/demo/nextjs` read-only and comes
+   back with `provided — src/auth/AuthProvider.tsx`, or an open point if it
+   could not find the proof. Say that `defer` is never proposed by the model.
+2. **Deepen a program** — `accountOverview` with the focus "the date-range
+   filter on movements is missing; check AccountOverviewServlet". Watch the
+   analyst revise the spec (own commit, `deepen accountOverview`), the judge
+   score the focus, and the mark stamp `[done <commit>]`.
+3. **Run modernize-refine** — the map lands at
+   `docs/modernization/domains.md`: `beneficiaryList` + `beneficiaryEdit`
+   become "Beneficiary maintenance" (they share the `/beneficiary` form
+   target), the three transfer steps "Wire transfer", header/nav/footer the
+   shell; the filler pages are folded only if the model proposed it with
+   evidence. `plan.md` is regenerated per feature and `rules.txt` gains a
+   `# waived` section listing the dropped pages' units. Answer any open
+   point in the menu, rerun, then **Approve the overlays** — and point out
+   that the README went back to `- [ ] Approved` the moment refine wrote
+   anything.
+
+Off stage the same beat is: edit `decisions.md` by hand (its header explains
+the vocabulary) and `LLM4TS_TARGET_REPO=~/demo/nextjs llm4ts run
+modernize-refine --repo ~/demo/legacy-j2ee`. Skip the beat entirely and the
+pipeline behaves exactly as before.
+
+Once `domains.md` is approved, Act 2 may convert **one feature instead of
+two pages**: `llm4ts run convert-feature --repo ~/demo/nextjs
+beneficiary-maintenance` lands `beneficiaryList` and `beneficiaryEdit` on one
+`convert/beneficiary-maintenance` branch behind one merged contract, and
+`convert-all` walks the features rather than the pages. Rehearse the timing
+before choosing it on stage: it is the two pages' cost in one run.
+
 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

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

@@ -65,3 +65,29 @@ 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`.
+
+## Refinement answer key (ADR 0015)
+
+What `modernize-refine` should produce on this estate once the three dead
+pages are marked `drop` and `login` resolves to `provided` by the target's
+AuthProvider:
+
+| Domain feature (deterministic cluster)                       | Programs                                                  | Why they cluster                              |
+| ------------------------------------------------------------ | --------------------------------------------------------- | --------------------------------------------- |
+| Portal shell                                                 | `header.jsp`, `nav.jsp`, `footer.jsp`                     | fragments: targets of `jsp-include` edges     |
+| Account overview                                             | `accountOverview.jsp`                                     | its ajax target names no other page           |
+| Beneficiary maintenance                                      | `beneficiaryList.jsp`, `beneficiaryEdit.jsp`              | both post to `/beneficiary` (`jsp-form-action`) |
+| Wire transfer                                                | `transferStep1.jsp`, `transferStep2.jsp`, `transferConfirm.jsp` | all post to `/transfer`                  |
+| one singleton each (fold into the shell only by proposal)    | `dashboard.jsp`, `settings.jsp`, `profile.jsp`, `messages.jsp`, `help.jsp` | no shared form or ajax target |
+
+Waived coverage units after the drops: every `url-pattern`, form action, and
+ajax url captured only from `oldTransfer.jsp`, `promoQ3.jsp`, and
+`testHarness.jsp`; `login.jsp`'s form action once it is `provided`.
+
+Feature contracts `convert-feature` writes once the map above is approved:
+`contracts/beneficiary-maintenance.openapi.yaml` unions `GET /beneficiary`
+(list, both pages), `GET /beneficiary?action=edit` and `POST /beneficiary`
+(edit) over the shared `Beneficiary` DTO; `contracts/wire-transfer.openapi.yaml`
+unions the three `POST /transfer` steps — same path, one operation per
+`step`, so the pages must agree on the `TransferDraft` DTO or the map gets a
+conflict open point.

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

@@ -1,4 +1,4 @@
-// Convert the whole legacy estate: walk the survey inventory in wave order, one branch per page, progress board, estimated-cost migration report.
+// Convert the whole legacy estate: walk the approved domain map (one branch per feature) or the survey inventory (one branch per page) in wave order, progress board, estimated-cost migration report.
 //
 // Runs rooted at the TARGET repository (`--repo <nextjs>`), with
 // LLM4TS_LEGACY_REPO pointing at the extracted legacy repository:
@@ -24,7 +24,7 @@ import { AdoConfig, makeAzureDevOpsTool } from "@llm4ts/flow/AzureDevOpsTool";
 import { BoardItem, composeBoardSync, makeAdoBoardSync, makeLocalBoardSync } from "@llm4ts/flow/BoardSync";
 import { describeFlowError } from "@llm4ts/flow/FlowError";
 import { Info, asReadOnly, coderFromEnv, nodePlainFileStore, nodeProcessExecutor, resolveFlowInput, runFlowMain, runNode, stage } from "@llm4ts/runner";
-import { conversionInventory, convertPage, migrationReport, setupConversion } from "./lib/convert.js";
+import { conversionInventory, convertFeature, convertPage, featureInventory, migrationReport, setupConversion } from "./lib/convert.js";
 const program = Effect.gen(function* () {
     const input = yield* resolveFlowInput("Convert the legacy estate into the destination SPA");
     const coder = coderFromEnv(process.env);
@@ -57,39 +57,75 @@ const program = Effect.gen(function* () {
             yield* context.events.publish(Info.make({ message: `ADO board mirror enabled: ${orgUrl}/${project}` }));
         }
         const board = composeBoardSync(boards);
-        const inventory = yield* stage(context.events, "inventory", conversionInventory(files, deps.legacy, deps.legacyDir, deps.pack));
-        if (inventory.length === 0) {
+        // ADR 0012 addendum: an approved domain map makes the feature the
+        // unit of delivery; without one the walk is per page as before.
+        const features = yield* stage(context.events, "inventory", featureInventory(files, deps.legacy, deps.legacyDir, deps.pack));
+        let items;
+        if (features !== undefined) {
+            yield* context.events.publish(Info.make({
+                message: `approved domain map: converting ${features.length} feature(s), one branch each`
+            }));
+            items = features.map((entry) => ({
+                id: entry.feature.id,
+                title: entry.feature.name,
+                ...(entry.wave === undefined ? {} : { wave: entry.wave }),
+                detail: `pages: ${entry.feature.programs.join(", ")}`,
+                ...(entry.disposed ? { skip: "every page disposed by decision" } : {}),
+                convert: convertFeature(deps, entry.feature.id)
+            }));
+        }
+        else {
+            const inventory = yield* conversionInventory(files, deps.legacy, deps.legacyDir, deps.pack);
+            items = yield* Effect.forEach(inventory, ({ page, wave, disposition }) => Effect.gen(function* () {
+                const specPath = join(deps.legacyDir, deps.pack.specsDir, `${page}.md`);
+                const missing = (yield* files.read(specPath)) === undefined;
+                return {
+                    id: page,
+                    title: page,
+                    ...(wave === undefined ? {} : { wave }),
+                    // A page the decisions overlay disposed of as a whole (ADR 0015)
+                    // is listed with its disposition, like a page triaged dead.
+                    ...(disposition !== undefined
+                        ? { skip: `${disposition} by decision` }
+                        : missing
+                            ? { skip: "no extracted spec" }
+                            : {}),
+                    convert: convertPage(deps, page)
+                };
+            }));
+        }
+        if (items.length === 0) {
             yield* context.events.publish(Info.make({ message: "inventory is empty — extract the legacy estate first" }));
             return;
         }
         // The whole estate lands on the board as planned up front — the
         // breadth view exists from minute one.
-        yield* stage(context.events, "board", board.plan(inventory.map(({ page, wave }) => BoardItem.make({
-            id: page,
-            title: page,
+        yield* stage(context.events, "board", board.plan(items.map((item) => BoardItem.make({
+            id: item.id,
+            title: item.title,
             status: "planned",
-            ...(wave === undefined ? {} : { wave })
+            ...(item.wave === undefined ? {} : { wave: item.wave }),
+            ...(item.detail === undefined ? {} : { detail: item.detail })
         }))));
         const baseBranch = yield* context.git.currentBranch;
         const failFast = process.env.LLM4TS_FAIL_FAST === "1";
-        for (const { page } of inventory) {
+        for (const item of items) {
             const snapshot = yield* board.snapshot;
-            const known = snapshot.items.find((item) => item.id === page);
+            const known = snapshot.items.find((candidate) => candidate.id === item.id);
             if (known !== undefined && known.status !== "planned" && known.status !== "failed") {
-                yield* context.events.publish(Info.make({ message: `resume: ${page} is already ${known.status} — skipping` }));
+                yield* context.events.publish(Info.make({ message: `resume: ${item.id} is already ${known.status} — skipping` }));
                 continue;
             }
-            const specPath = join(deps.legacyDir, deps.pack.specsDir, `${page}.md`);
-            if ((yield* files.read(specPath)) === undefined) {
-                yield* board.skip(page, "no extracted spec");
+            if (item.skip !== undefined) {
+                yield* board.skip(item.id, item.skip);
                 continue;
             }
             const checkpoint = yield* context.git.checkpoint;
-            yield* board.start(page);
-            const result = yield* Effect.result(convertPage(deps, page));
+            yield* board.start(item.id);
+            const result = yield* Effect.result(item.convert);
             if (result._tag === "Success") {
                 const outcome = result.success;
-                yield* board.complete(page, {
+                yield* board.complete(item.id, {
                     branch: outcome.branch,
                     reportPath: outcome.reportPath,
                     ...(outcome.estimatedTokens === undefined
@@ -103,15 +139,15 @@ const program = Effect.gen(function* () {
             }
             else {
                 const reason = describeFlowError(result.failure);
-                // A stuck page must not sink the walk: reset the working tree,
+                // A stuck unit must not sink the walk: reset the working tree,
                 // mark the failure, keep going (LLM4TS_FAIL_FAST=1 to stop).
                 yield* context.git.rollback(checkpoint);
                 yield* context.git.checkout(baseBranch);
-                yield* board.fail(page, reason);
+                yield* board.fail(item.id, reason);
                 if (failFast) {
                     return yield* Effect.fromResult(result);
                 }
-                yield* context.events.publish(Info.make({ message: `page ${page} failed — continuing: ${reason}` }));
+                yield* context.events.publish(Info.make({ message: `${item.id} failed — continuing: ${reason}` }));
             }
         }
         const finalBoard = yield* board.snapshot;

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

@@ -0,0 +1,48 @@
+// Convert ONE domain feature of the approved domains.md into the destination Next.js SPA: one branch, one merged contract, the port then each page in navigation order.
+//
+// Runs rooted at the TARGET repository (`--repo <nextjs>`), with
+// LLM4TS_LEGACY_REPO pointing at the refined legacy repository whose
+// docs/modernization/domains.md is approved. The task text is the feature id:
+//
+//   LLM4TS_LEGACY_REPO=~/estates/demo-bank-legacy \
+//     llm4ts run convert-feature --repo ~/estates/demo-bank-nextjs beneficiary-maintenance
+//
+// ADR 0012 addendum: the unit of delivery is the domain feature — its
+// surviving pages share `contracts/<feature>.openapi.yaml` (the deterministic
+// union of their API sections; conflicts are open points in domains.md, never
+// silent merges), one port under src/services/<feature>/, page components
+// and tests per page. Gates and judge as convert-page, plus the feature
+// judged against its contract of record. Branch `convert/<feature>`, no PR.
+import * as Effect from "effect/Effect";
+import { FlowAborted, Info, asReadOnly, coderFromEnv, resolveFlowInput, runFlowMain, runNode } from "@llm4ts/runner";
+import { convertFeature, setupConversion } from "./lib/convert.js";
+const program = Effect.gen(function* () {
+    const input = yield* resolveFlowInput("Convert one domain feature into the destination SPA");
+    const feature = input.prompt.trim().split(/\s+/)[0] ?? "";
+    const coder = coderFromEnv(process.env);
+    yield* runNode({
+        workDir: input.workDir,
+        workspace: input.workspace,
+        userPrompt: input.prompt,
+        coder,
+        reasoning: asReadOnly(coder),
+        reviewers: [asReadOnly(coder)],
+        environment: process.env
+    }, (context) => Effect.gen(function* () {
+        if (feature.length === 0) {
+            return yield* FlowAborted.make({
+                message: "pass the domain feature id to convert, e.g.: llm4ts run convert-feature beneficiary-maintenance"
+            });
+        }
+        const deps = yield* setupConversion(context, input, process.env, import.meta.dirname);
+        const outcome = yield* convertFeature(deps, feature);
+        yield* context.events.publish(Info.make({
+            message: `converted feature ${outcome.page} on branch ${outcome.branch} — ` +
+                `report at ${outcome.reportPath}` +
+                (outcome.estimatedTokens === undefined
+                    ? ""
+                    : ` (~${outcome.estimatedTokens} tokens, ESTIMATED)`)
+        }));
+    }));
+});
+runFlowMain(program);