@llm4ts/shell 2.1.0 → 2.2.1

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

@@ -1,5 +1,6 @@
 // Shared core of the J2EE→Next.js conversion flows (convert-page,
-// convert-all). One page = one branch = one conversion report. The Page Spec
+// convert-feature, convert-all). One page — or, once refine has produced an
+// approved domain map, one domain feature — = one branch = one conversion report. The Page Spec
 // extracted from the legacy repo is the contract; the legacy source is
 // consultable evidence (NOT clean-room — ADR 0012); the destination repo's
 // own pages are the style guide. All token/cost figures are ESTIMATES.
@@ -10,8 +11,10 @@ import { judge } from "@llm4ts/core/eval/Judge";
 import { TokenUsage } from "@llm4ts/core/Models";
 import { FlowAborted, Info, Plan, implementPlanFlow, lintCommand, loadKitPatternCards, makeChat, makeNodeWorkspace, makePlanStore, mergeReviewResults, minimalReviewers, nodePlainFileStore, nodeProcessExecutor, openPack, reviewFingerprint, stage } from "@llm4ts/runner";
 import { budget, capped } from "@llm4ts/flow/Context";
+import { Decisions, parseDecisions } from "@llm4ts/flow/Decisions";
+import { navigationOrder, parseDomains } from "@llm4ts/flow/Domains";
 import { FlowEvents } from "@llm4ts/flow/FlowEvents";
-import { openApiFor, parsePageSpec, renderPageSpec } from "@llm4ts/flow/PageSpec";
+import { openApiFor, openApiForFeature, parsePageSpec, renderPageSpec } from "@llm4ts/flow/PageSpec";
 import { loadPatternCards, matchingPatternCards } from "@llm4ts/flow/Patterns";
 import { Task } from "@llm4ts/flow/Plan";
 import { judgeAllPrograms } from "@llm4ts/flow/ProgramJudge";
@@ -117,6 +120,68 @@ const conversionPlan = (page, spec, contractPath) => Plan.make({
         })
     ]
 });
+/**
+ * The feature plan (ADR 0012 addendum): the shared port first, then one
+ * task per page in navigation order with its tests inside, so every task is
+ * a vertical slice behind the gate.
+ */
+export const featurePlan = (feature, order, specs, contractPath) => Plan.make({
+    epicId: `convert/${feature.id}`,
+    brief: [
+        `You are converting the legacy domain feature '${feature.name}' (${feature.id}) — pages`,
+        `${order.join(", ")} — into this Next.js SPA.`,
+        ...(feature.context.length === 0
+            ? []
+            : [
+                `The pages include the shared fragments ${feature.context.join(", ")}: they are context,`,
+                "already provided by the app layout — do not re-implement them here."
+            ]),
+        "",
+        ...order.flatMap((page) => {
+            const spec = specs.get(page);
+            return spec === undefined ? [] : [`===== ${page} =====`, renderPageSpec(spec).trimEnd(), ""];
+        }),
+        `The OpenAPI anti-corruption contract is ALREADY WRITTEN at ${contractPath} — it is the`,
+        "union of the pages' API sections and the contract of record. Do not edit it."
+    ].join("\n"),
+    tasks: [
+        Task.make({
+            title: `acl: ${feature.id} service port and mock`,
+            description: [
+                `Implement the anti-corruption service layer for '${feature.name}' from the contract at`,
+                `${contractPath}:`,
+                `- src/services/${feature.id}/port.ts — a typed port interface with one method per`,
+                "  OpenAPI operation, request/response types in the contract's DOMAIN names.",
+                `- src/services/${feature.id}/mock.ts — a mock adapter returning contract-shaped,`,
+                "  deterministic fixture data (transport fake, never business rules).",
+                "- Wire the port into src/services/registry.ts the same way the existing",
+                "  services are wired.",
+                "Imitate the existing services (e.g. src/services/cards/) exactly. No page code",
+                "in this task."
+            ].join("\n")
+        }),
+        ...order.map((page) => Task.make({
+            title: `page: ${page} component and tests`,
+            description: [
+                `Build the converted page under src/app/${page}/ using ONLY the destination`,
+                `design-system components and the '${feature.id}' port from the first task:`,
+                "- Respect the original form: same fields, same validation rules with their",
+                "  VERBATIM messages in the spec's order, same navigation between the feature's pages.",
+                "- Anything the legacy app kept in HttpSession or hidden fields becomes explicit",
+                "  client state (use the Stepper pattern for multi-step flows).",
+                "- No fetch in components; the page obtains its port from the registry.",
+                "- Read CONTRIBUTING.md and the existing pages first and match their style.",
+                `Then write its component tests at tests/${page}.page.test.tsx in the house test`,
+                "style (see the existing tests/ files): mock the registry port, render inside",
+                "AuthProvider, and assert EXACTLY three families of behaviour:",
+                "1. every spec'd form field renders,",
+                "2. every spec'd validation fires with its verbatim message,",
+                "3. the port is called with contract-shaped payloads on the happy path.",
+                "No snapshots, no styling assertions, nothing beyond those families."
+            ].join("\n")
+        }))
+    ]
+});
 const gateFor = (deps, name) => {
     const command = deps.pack.gate(name);
     return command === undefined
@@ -177,26 +242,36 @@ const destinationGuidance = Effect.fn("convert.destinationGuidance")(function* (
         ...pages.map((path) => `- ${path}`)
     ].join("\n");
 });
-export const convertPage = Effect.fn("convert.page")(function* (deps, page) {
-    const { context, environment, files, pack } = deps;
-    const specPath = join(deps.legacyDir, pack.specsDir, `${page}.md`);
-    const specMarkdown = yield* files.read(specPath);
-    if (specMarkdown === undefined) {
+const scopeFor = (decisions, pages) => {
+    const lines = pages.flatMap((page) => decisions.scenarios
+        .filter((entry) => entry.program === page)
+        .map((entry) => `- ${page} / ${entry.scenario}: ${entry.disposition} — ${entry.reason}`));
+    return lines.length === 0
+        ? undefined
+        : "Out of scope by decision (do not implement, do not test, do not score their absence):\n" +
+            lines.join("\n");
+};
+const readSpec = Effect.fn("convert.readSpec")(function* (deps, page) {
+    const path = join(deps.legacyDir, deps.pack.specsDir, `${page}.md`);
+    const markdown = yield* deps.files.read(path);
+    if (markdown === undefined) {
         return yield* FlowAborted.make({
-            message: `no spec at ${specPath} — run modernize-extract on the legacy repo first`
+            message: `no spec at ${path} — run modernize-extract on the legacy repo first`
         });
     }
     // Hard schema validation: a spec without a decodable pagespec block is an
     // incomplete extraction, not a page to guess at.
-    const spec = yield* parsePageSpec(specMarkdown);
-    const branch = `convert/${page}`;
+    const spec = yield* parsePageSpec(markdown);
+    return { path, markdown, spec };
+});
+const runConversion = Effect.fn("convert.run")(function* (deps, unit) {
+    const { context, environment, files, pack } = deps;
+    const branch = `convert/${unit.id}`;
     yield* stage(context.events, "branch", context.git.checkoutOrCreate(branch));
-    // The contract is a deterministic projection of the reviewed spec — written
+    // The contract is a deterministic projection of the reviewed spec(s) — written
     // by code before any model runs, committed with the first task.
-    const contractPath = `contracts/${page}.openapi.yaml`;
-    yield* stage(context.events, "contract", files.writeAtomic(join(deps.targetDir, contractPath), openApiFor(spec)));
-    const { source, evidence } = yield* legacyEvidence(deps, page);
-    const playbook = matchingPatternCards(source, deps.cards);
+    yield* stage(context.events, "contract", files.writeAtomic(join(deps.targetDir, unit.contractPath), unit.contract));
+    const playbook = matchingPatternCards(unit.source, deps.cards);
     const guidance = yield* destinationGuidance(deps);
     const system = [
         pack.prompt("implement"),
@@ -209,9 +284,10 @@ export const convertPage = Effect.fn("convert.page")(function* (deps, page) {
                 "the spec wins):\n\n" +
                 playbook.map((card) => `### ${card.id}\n${card.body}`).join("\n\n"),
         guidance,
-        evidence.trim().length === 0
+        unit.scope,
+        unit.evidence.trim().length === 0
             ? undefined
-            : `Legacy source evidence (for disambiguation only — the Page Spec wins):\n\n${evidence}`
+            : `Legacy source evidence (for disambiguation only — the Page Spec wins):\n\n${unit.evidence}`
     ]
         .filter((part) => part !== undefined)
         .join("\n\n");
@@ -222,8 +298,8 @@ export const convertPage = Effect.fn("convert.page")(function* (deps, page) {
     ]);
     yield* implementPlanFlow(context, {
         store: makePlanStore(files),
-        planPath: join(deps.targetDir, ".llm4ts", "convert", `${page}.plan.md`),
-        plan: Effect.succeed(conversionPlan(page, spec, contractPath)),
+        planPath: join(deps.targetDir, ".llm4ts", "convert", `${unit.id}.plan.md`),
+        plan: Effect.succeed(unit.plan),
         system,
         chatPerTask: true,
         checkoutBranch: false,
@@ -235,13 +311,14 @@ export const convertPage = Effect.fn("convert.page")(function* (deps, page) {
         const result = yield* verifyGate;
         if (!result.isClean) {
             return yield* FlowAborted.make({
-                message: `verify gate failed for ${page}:\n${issueLines(result)}`
+                message: `verify gate failed for ${unit.id}:\n${issueLines(result)}`
             });
         }
     }));
     yield* stage(context.events, "judge", Effect.gen(function* () {
         const complianceJudge = judge(context.reasoning, conversionDimensions);
         const rounds = positiveEnvInt(environment, "LLM4TS_JUDGE_ROUNDS", 2);
+        const specOf = new Map(unit.judged.map((entry) => [entry.name, entry.spec]));
         for (let round = 1; round <= rounds; round += 1) {
             const base = yield* context.git.defaultBase;
             const verdict = yield* judgeAllPrograms({
@@ -252,17 +329,17 @@ export const convertPage = Effect.fn("convert.page")(function* (deps, page) {
                 files,
                 gateDir: join(deps.targetDir, ".llm4ts", "convert", "gate"),
                 base,
-                programs: [page],
-                specFor: () => Effect.succeed(specMarkdown),
+                programs: unit.judged.map((entry) => entry.name),
+                specFor: (program) => Effect.succeed(specOf.get(program) ?? ""),
                 query: context.userPrompt,
                 fingerprint: reviewFingerprint
             });
             if (verdict.isClean) {
-                return yield* context.events.publish(Info.make({ message: `judge: ${page} cleared the bar` }));
+                return yield* context.events.publish(Info.make({ message: `judge: ${unit.id} cleared the bar` }));
             }
             if (round >= rounds) {
                 return yield* FlowAborted.make({
-                    message: `judge not cleared for ${page} after ${rounds} round(s):\n${issueLines(verdict)}`
+                    message: `judge not cleared for ${unit.id} after ${rounds} round(s):\n${issueLines(verdict)}`
                 });
             }
             const feedback = yield* makeChat(context.coder, {
@@ -271,33 +348,33 @@ export const convertPage = Effect.fn("convert.page")(function* (deps, page) {
                 agent: "coder"
             });
             yield* feedback.ask([
-                `The conversion of '${page}' scored below the bar. Close these gaps without`,
+                `The conversion of '${unit.id}' scored below the bar. Close these gaps without`,
                 "weakening any test, then stop:",
                 issueLines(verdict)
             ].join("\n"));
             const regated = yield* verifyGate;
             if (!regated.isClean) {
                 return yield* FlowAborted.make({
-                    message: `verify gate broke while addressing judge feedback on ${page}`
+                    message: `verify gate broke while addressing judge feedback on ${unit.id}`
                 });
             }
-            yield* context.git.commitAll(`convert/${page}: address judge feedback`);
+            yield* context.git.commitAll(`convert/${unit.id}: address judge feedback`);
         }
     }).pipe(Effect.provideService(FlowEvents, context.events)));
     const totals = yield* deps.totals;
-    const reportPath = `docs/conversion/${page}.md`;
+    const reportPath = `docs/conversion/${unit.id}.md`;
     const base = yield* context.git.defaultBase;
     const changed = yield* context.git.changedFilesVsBase(base);
     const report = [
-        `# Conversion report: ${page}`,
+        `# Conversion report: ${unit.id}`,
         "",
         "> Token and cost figures below are ESTIMATES from character counts",
         "> (see docs/adr/0012): the CLI seats report no usage. They are not",
         "> measurements.",
         "",
-        `- Legacy spec: ${specPath}`,
+        ...unit.reportLines,
         `- Branch: \`${branch}\` (awaiting human review — no auto-merge)`,
-        `- Contract: ${contractPath}`,
+        `- Contract: ${unit.contractPath}`,
         `- Gates: typecheck, lint, test, build — green at report time`,
         "- Judge: cleared (spec-compliance, acl-purity, house-fidelity)",
         ...(totals === undefined
@@ -312,20 +389,148 @@ export const convertPage = Effect.fn("convert.page")(function* (deps, page) {
         "## Files changed",
         "",
         ...changed.map((file) => `- ${file}`),
-        ...(spec.openQuestions.length === 0
+        ...(unit.openQuestions.length === 0
             ? []
-            : ["", "## Open questions carried forward", "", ...spec.openQuestions.map((q) => `- ${q}`)])
+            : [
+                "",
+                "## Open questions carried forward",
+                "",
+                ...unit.openQuestions.map((q) => unit.kind === "page" ? `- ${q.question}` : `- ${q.page}: ${q.question}`)
+            ])
     ].join("\n");
     yield* files.writeAtomic(join(deps.targetDir, reportPath), report + "\n");
-    yield* context.git.commitAll(`convert/${page}: conversion report`);
+    yield* context.git.commitAll(`convert/${unit.id}: conversion report`);
     return {
-        page,
+        page: unit.id,
         branch,
         reportPath,
         ...(totals === undefined ? {} : { estimatedTokens: totals.total }),
         ...(totals?.costUsd === undefined ? {} : { estimatedCostUsd: totals.costUsd })
     };
 });
+export const convertPage = Effect.fn("convert.page")(function* (deps, page) {
+    const { path: specPath, markdown: specMarkdown, spec } = yield* readSpec(deps, page);
+    // The decisions overlay (ADR 0015): a page disposed as a whole is never
+    // converted; disposed scenarios are out of scope for the coder and the judge.
+    const decisions = yield* legacyDecisions(deps.files, deps.legacyDir);
+    const pageDecision = decisions.programDecision(page);
+    if (pageDecision !== undefined) {
+        return yield* FlowAborted.make({
+            message: `${page} is marked '${pageDecision.disposition}' in the legacy pack's decisions.md — ${pageDecision.reason}`
+        });
+    }
+    const scope = scopeFor(decisions, [page]);
+    const contractPath = `contracts/${page}.openapi.yaml`;
+    const { source, evidence } = yield* legacyEvidence(deps, page);
+    return yield* runConversion(deps, {
+        id: page,
+        kind: "page",
+        contractPath,
+        contract: openApiFor(spec),
+        plan: conversionPlan(page, spec, contractPath),
+        source,
+        evidence,
+        scope,
+        judged: [
+            { name: page, spec: scope === undefined ? specMarkdown : `${specMarkdown}\n\n${scope}` }
+        ],
+        openQuestions: spec.openQuestions.map((question) => ({ page, question })),
+        reportLines: [`- Legacy spec: ${specPath}`]
+    });
+});
+/** The legacy pack's domain map, or undefined when refine never consolidated it. */
+export const legacyDomains = Effect.fn("convert.domains")(function* (files, legacyDir) {
+    const text = yield* files.read(join(legacyDir, "docs/modernization/domains.md"));
+    return text === undefined ? undefined : yield* parseDomains(text, "domains.md");
+});
+/**
+ * Convert ONE domain feature (ADR 0012 addendum): its surviving pages on one
+ * branch, one contract that is the union of their API sections, the port
+ * first and then each page with its tests in navigation order. The judge
+ * scores every page against its own spec plus the feature against its
+ * contract of record.
+ */
+export const convertFeature = Effect.fn("convert.feature")(function* (deps, featureId) {
+    const domains = yield* legacyDomains(deps.files, deps.legacyDir);
+    if (domains === undefined) {
+        return yield* FlowAborted.make({
+            message: "no docs/modernization/domains.md in the legacy pack — run modernize-refine first"
+        });
+    }
+    if (!domains.approved) {
+        return yield* FlowAborted.make({
+            message: "docs/modernization/domains.md is not approved — flip '- [x] Approved' first"
+        });
+    }
+    const feature = domains.features.find((candidate) => candidate.id === featureId);
+    if (feature === undefined) {
+        return yield* FlowAborted.make({
+            message: `no domain feature '${featureId}' in domains.md (known: ${domains.features.map((f) => f.id).join(", ")})`
+        });
+    }
+    const decisions = yield* legacyDecisions(deps.files, deps.legacyDir);
+    const pages = feature.programs.filter((page) => decisions.programDecision(page) === undefined);
+    if (pages.length === 0) {
+        return yield* FlowAborted.make({
+            message: `every page of '${featureId}' is disposed of in decisions.md — nothing to convert`
+        });
+    }
+    const specs = new Map();
+    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 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));
+    const sources = [];
+    const evidences = [];
+    for (const page of order) {
+        const { source, evidence } = yield* legacyEvidence(deps, page);
+        sources.push(source);
+        evidences.push(evidence);
+    }
+    const evidence = yield* capped(`legacy[${feature.id}]`, evidences.join("\n\n"), Math.floor(budget(deps.environment) / 3)).pipe(Effect.provideService(FlowEvents, deps.context.events));
+    const scope = scopeFor(decisions, order);
+    const specMap = new Map(order.map((page) => [page, specs.get(page)?.spec]));
+    const plan = featurePlan(feature, order, new Map([...specMap.entries()].flatMap(([k, v]) => (v === undefined ? [] : [[k, v]]))), contractPath);
+    return yield* runConversion(deps, {
+        id: feature.id,
+        kind: "feature",
+        contractPath,
+        contract: contract.yaml,
+        plan,
+        source: sources.join("\n"),
+        evidence,
+        scope,
+        judged: [
+            ...order.map((page) => {
+                const markdown = specs.get(page)?.markdown ?? "";
+                return { name: page, spec: scope === undefined ? markdown : `${markdown}\n\n${scope}` };
+            }),
+            // The feature itself is judged against its contract of record: the
+            // pack's feature-files scope is exactly the port and the contract.
+            {
+                name: feature.id,
+                spec: `# Contract of record for domain feature ${feature.name}\n\n` +
+                    "The service port under src/services/<feature>/ must expose one operation per path " +
+                    "and method below, with request and response types in the contract's domain names.\n\n" +
+                    "```yaml\n" +
+                    contract.yaml +
+                    "```"
+            }
+        ],
+        openQuestions: order.flatMap((page) => (specs.get(page)?.spec.openQuestions ?? []).map((question) => ({ page, question }))),
+        reportLines: [
+            `- Domain feature: ${feature.name} (${feature.id})`,
+            `- Pages, in navigation order: ${order.join(", ")}`,
+            ...(feature.context.length === 0
+                ? []
+                : [`- Context fragments: ${feature.context.join(", ")}`]),
+            ...order.map((page) => `- Legacy spec: ${specs.get(page)?.path ?? page}`)
+        ]
+    });
+});
 /**
  * The common wiring of both conversion flows: metered seats (estimates-only
  * accounting), the two workspaces (legacy read-only limits, target default),
@@ -392,22 +597,37 @@ export const parseWavePlan = (planText) => {
             continue;
         }
         const current = waves.at(-1);
-        if (collecting && current !== undefined && trimmed.startsWith("- ")) {
+        // The approval marker sits under the last wave; it is not a page.
+        if (collecting &&
+            current !== undefined &&
+            trimmed.startsWith("- ") &&
+            !/^- \[[ xX]\] /.test(trimmed)) {
             current.pages.push(trimmed.slice(2).trim());
         }
     }
     return waves;
 };
+/** The legacy pack's decisions overlay, empty when refine never ran. */
+export const legacyDecisions = Effect.fn("convert.decisions")(function* (files, legacyDir) {
+    const text = yield* files.read(join(legacyDir, "docs/modernization/decisions.md"));
+    return text === undefined ? Decisions.empty() : yield* parseDecisions(text, "decisions.md");
+});
 /**
  * The ordered page list: the approved wave plan when present, otherwise every
- * extracted spec. Pages appear in conversion order.
+ * extracted spec. Pages appear in conversion order; a page disposed as a whole
+ * by the decisions overlay carries its disposition and is skipped by the walk.
  */
 export const conversionInventory = Effect.fn("convert.inventory")(function* (files, legacy, legacyDir, pack) {
+    const decisions = yield* legacyDecisions(files, legacyDir);
+    const withDisposition = (entry) => {
+        const decision = decisions.programDecision(entry.page);
+        return decision === undefined ? entry : { ...entry, disposition: decision.disposition };
+    };
     const planText = yield* files.read(join(legacyDir, "docs/modernization/wave-plan.md"));
     if (planText !== undefined) {
         const waves = parseWavePlan(planText);
         if (waves.length > 0) {
-            return waves.flatMap((entry) => entry.pages.map((page) => ({ page, wave: entry.wave })));
+            return waves.flatMap((entry) => entry.pages.map((page) => withDisposition({ page, wave: entry.wave })));
         }
     }
     const specs = yield* legacy
@@ -415,10 +635,42 @@ export const conversionInventory = Effect.fn("convert.inventory")(function* (fil
         .pipe(Effect.orElseSucceed(() => []));
     return [...specs]
         .map((path) => path.split("/").at(-1) ?? path)
-        .filter((name) => name.endsWith(".md") && name !== "README.md")
+        .filter((name) => name.endsWith(".md") && !["README.md", "decisions.md", "domains.md"].includes(name))
         .map((name) => name.slice(0, -".md".length))
         .sort()
-        .map((page) => ({ page }));
+        .map((page) => withDisposition({ page }));
+});
+/**
+ * The feature walk (ADR 0012 addendum): the approved domain map's features
+ * ordered by the earliest wave of their pages, then by id; undefined when the
+ * legacy pack has no approved map, so the caller falls back to pages.
+ */
+export const featureInventory = Effect.fn("convert.featureInventory")(function* (files, legacy, legacyDir, pack) {
+    const domains = yield* legacyDomains(files, legacyDir);
+    if (domains === undefined || !domains.approved) {
+        return undefined;
+    }
+    const pages = yield* conversionInventory(files, legacy, legacyDir, pack);
+    const waveOf = new Map(pages.map((entry) => [entry.page, entry.wave]));
+    const waveIndex = [...new Set(pages.map((entry) => entry.wave))];
+    const decisions = yield* legacyDecisions(files, legacyDir);
+    return domains.features
+        .map((feature) => {
+        const waves = feature.programs
+            .map((page) => waveOf.get(page))
+            .filter((wave) => wave !== undefined)
+            .sort((left, right) => waveIndex.indexOf(left) - waveIndex.indexOf(right));
+        const wave = waves[0];
+        return {
+            feature,
+            ...(wave === undefined ? {} : { wave }),
+            disposed: feature.programs.every((page) => decisions.programDecision(page) !== undefined)
+        };
+    })
+        .sort((left, right) => {
+        const byWave = waveIndex.indexOf(left.wave ?? "") - waveIndex.indexOf(right.wave ?? "");
+        return byWave !== 0 ? byWave : left.feature.id.localeCompare(right.feature.id);
+    });
 });
 /**
  * Whole-estate summary with a deliberately naive projection: average estimated

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

@@ -8,6 +8,7 @@ programs: .*\.jsp
 specs-dir: docs/modernization/specs
 features-dir: docs/modernization/features
 program-files: (?:src/app/<NAME>(?:/.*)?|src/services/<NAME>(?:/.*)?|contracts/<NAME>\.openapi\.yaml|tests/<NAME>\..*)
+feature-files: (?:src/services/<NAME>(?:/.*)?|contracts/<NAME>\.openapi\.yaml)
 
 ## Gates
 
@@ -47,3 +48,18 @@ unit: <jsp:include page="([^"]+)"
 
 files: .*web\.xml
 unit: <servlet-class>[a-z.]*\.([A-Za-z0-9]+)</servlet-class>
+
+## Survey: jsp-form-action
+
+files: .*\.jsp
+unit: action="([^"]+)"
+
+## Survey: jsp-ajax-target
+
+files: .*\.jsp
+unit: url:\s*['"]([^'"?]+)
+
+## Consolidate
+
+- cluster: jsp-form-action, jsp-ajax-target
+- context: jsp-include

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

@@ -0,0 +1,10 @@
+In a JSP portal a domain feature is the set of pages one servlet serves and
+one ESB service pair backs: a list page with its detail or edit form, the
+steps of one wizard (a session draft carried from step to step and a confirm
+screen), a read-only screen with its ajax refresh. The shell — header, nav,
+footer and any fragment every page includes — is one feature of its own,
+planned first because every other feature renders inside it. Filler pages
+with no form and no API call (help, profile, messages, settings) may be
+folded into one "Portal shell and static pages" feature; say so in the
+evidence. Never join two features that talk to different ESB services unless
+one page posts to the other's servlet.

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

@@ -1,17 +1,25 @@
-Derive the conversion task list for ONE page from its Page Spec. The
-destination is an existing Next.js SPA with a design system, an AuthProvider,
-and a port/adapter service convention — imitate it, never fight it.
+Derive the conversion task list for ONE domain feature from the Page Specs of
+its programs. The destination is an existing Next.js SPA with a design system,
+an AuthProvider, and a port/adapter service convention — imitate it, never
+fight it. The feature's included fragments (header, nav, footer) are context:
+use their specs for layout and navigation, do not re-implement them here
+unless this feature IS the shell.
 
-- Task 1: the anti-corruption service layer — the typed port interface under
-  src/services/<page>/port.ts matching the OpenAPI contract at
-  contracts/<page>.openapi.yaml (domain names only), a mock adapter under
-  src/services/<page>/mock.ts returning contract-shaped fixture data, and the
-  registry wiring. No page code yet.
-- Task 2: the page component(s) under src/app/<page>/ using ONLY the
-  destination design-system components and the port — forms, validation with
-  VERBATIM messages, navigation, and explicit state for anything the legacy
-  app carried in the session or hidden fields.
-- Task 3: component tests under tests/<page>.page.test.tsx in the house test
-  style — spec'd fields render, spec'd validations fire with their exact
-  messages, the port is called with contract-shaped payloads. Nothing else.
-- Each task names the spec rules and scenarios it covers.
+- Task 1: the feature's anti-corruption service layer — the typed port
+  interface under src/services/<feature>/port.ts matching the OpenAPI contract
+  at contracts/<feature>.openapi.yaml (domain names only, one operation per
+  API call across all the feature's pages), a mock adapter under
+  src/services/<feature>/mock.ts returning contract-shaped fixture data, and
+  the registry wiring. No page code yet.
+- Then ONE task per page of the feature, in navigation order (the page with no
+  inbound link inside the feature first; list before edit; step 1 before
+  step 2 before confirm): the page component(s) under src/app/<page>/ using
+  ONLY the destination design-system components and the feature port —
+  forms, validation with VERBATIM messages, navigation, explicit state for
+  anything the legacy carried in the session or hidden fields — together with
+  its component tests under tests/<page>.page.test.tsx in the house test style:
+  spec'd fields render, spec'd validations fire with their exact messages, the
+  port is called with contract-shaped payloads. Nothing else.
+- Each task names the programs, spec rules, and scenarios it covers. Scenarios
+  the decisions overlay marks drop, provided, or defer are out of scope: do
+  not plan them, and use the target capability a `provided` entry points at.

package/kits/j2ee-nextjs/packs/j2ee-nextjs-spa/prompts/refine-propose.md

@@ -0,0 +1,16 @@
+The target is an existing Next.js SPA with a design system, an AuthProvider, a
+router, and a port/adapter service convention. Things such a target usually
+PROVIDES, so a legacy page or scenario about them is a `provided` candidate
+once you have found the file that proves it:
+
+- login, logout, session timeout, and "remember me" — the AuthProvider and its
+  login route own these; a legacy login JSP is provided, not converted;
+- navigation shell, header, footer, and the nav link set — the app layout;
+- "back" links, breadcrumbs, and page titles — the router and layout;
+- session-carried drafts between wizard steps — client state, not a session;
+- client-side validation libraries — the house Form validation map.
+
+Things commonly DEPRECATED in a JSP estate, `drop` candidates when the spec
+itself shows the evidence (dead route, expired campaign, developer harness,
+print-only view, applet or Flash embed, frameset): name the evidence, never
+guess from the page name alone. Never propose `defer`.

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

@@ -49,3 +49,8 @@ unit: ^ {6}[ ]*COPY +([A-Z0-9]+)
 
 files: .*\.(jcl|JCL)
 unit: EXEC +PGM=([A-Z0-9]+)
+
+## Consolidate
+
+- cluster: calls, exec-pgm
+- context: copies

package/kits/mainframe-java/packs/cobol-springboot/prompts/consolidate.md

@@ -0,0 +1,8 @@
+In a COBOL estate a domain feature is a job's worth of business behaviour: the
+program a JCL step executes together with every program it CALLs and the
+copybooks they share, or a set of programs that post to the same ledger
+tables. Copybooks are context, never features of their own. Programs that
+only compute (fee, interest, limit) and are CALLed from several jobs belong to
+the feature that owns their business rule, not to every caller; say which in
+the evidence. Never join two batch jobs that touch different ledgers unless
+one executes the other.

package/kits/mainframe-java/packs/cobol-springboot/prompts/refine-propose.md

@@ -0,0 +1,10 @@
+The target is a Spring Boot service with JPA entities, a validation chain, and
+JUnit 5 acceptance tests over the seeded feature files. Things such a target
+usually PROVIDES, so a legacy program or scenario about them is a `provided`
+candidate once you have found the file that proves it: audit rows written by
+an aspect or entity listener, request logging, the transaction boundary a
+COBOL program opened and closed by hand, date and time stamping, and sequence
+allocation. Things commonly DEPRECATED in a COBOL estate, `drop` candidates
+when the source shows the evidence (a job step nothing schedules, a program no
+JCL executes and nothing CALLs, a report format the business retired): name
+the evidence, never guess from the program name alone. Never propose `defer`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llm4ts/shell",
-  "version": "2.1.0",
+  "version": "2.2.1",
   "description": "Interactive shell and CLI for llm4ts: flow discovery, run-a-flow, and view",
   "license": "MIT",
   "type": "module",
@@ -23,6 +23,7 @@
     "./FlowCatalog": "./dist/FlowCatalog.js",
     "./FlowLaunch": "./dist/FlowLaunch.js",
     "./Menu": "./dist/Menu.js",
+    "./Refine": "./dist/Refine.js",
     "./Package": "./dist/Package.js",
     "./package.json": "./package.json"
   },
@@ -51,9 +52,9 @@
   "dependencies": {
     "@effect/platform-node": "4.0.0-rc.115",
     "@effect/platform-node-shared": "4.0.0-rc.115",
-    "@llm4ts/flow": "2.1.0",
-    "@llm4ts/runner": "2.1.0",
-    "@llm4ts/core": "2.1.0"
+    "@llm4ts/flow": "2.2.1",
+    "@llm4ts/runner": "2.2.1",
+    "@llm4ts/core": "2.2.1"
   },
   "peerDependencies": {
     "effect": "4.0.0-rc.115"