@llm4ts/shell 2.0.0 → 2.2.0

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);

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