@llm4ts/shell 2.1.0 → 2.2.0

package/flows/lib/modernize-extract.js

@@ -0,0 +1,217 @@
+// Shared core of the extraction phase: the per-program analyst ask, the
+// per-program cached judge, the fix turn, and the spec-pack README. Used by
+// `modernize-extract` (every program of a wave) and `modernize-refine`
+// (one program at a time, deepened with a focus — ADR 0015).
+import { join } from "node:path";
+import * as Effect from "effect/Effect";
+import { Sample } from "@llm4ts/core/eval/Eval";
+import { judge } from "@llm4ts/core/eval/Judge";
+import { capped, withShrink } from "@llm4ts/flow/Context";
+import { FlowEvents } from "@llm4ts/flow/FlowEvents";
+import { ReviewIssue } from "@llm4ts/flow/Review";
+import { cachedReview } from "@llm4ts/flow/ReviewCache";
+import { FlowLlmError, Info, ReviewResult, makeChat, reviewFingerprint } from "@llm4ts/runner";
+export const ModDir = "docs/modernization";
+export const positiveEnvInt = (name, fallback) => {
+    const raw = Number.parseInt(process.env[name] ?? "", 10);
+    return Number.isFinite(raw) && raw > 0 ? raw : fallback;
+};
+// Per-program turn budget — bounds a wedged agent, generous for real work.
+export const analystTurns = () => positiveEnvInt("LLM4TS_ANALYST_TURNS", 48);
+/**
+ * Max files named in one program's include closure. A program pulling more
+ * than this gets a bounded, visible subset rather than an unbounded read.
+ */
+export const maxClosureFiles = () => positiveEnvInt("LLM4TS_MAX_CLOSURE_FILES", 40);
+/** `cobol/ACCTXFR.cbl` → `ACCTXFR`: the program name keying every per-program artifact. */
+export const programName = (relativePath) => {
+    const base = relativePath.slice(relativePath.lastIndexOf("/") + 1);
+    const dot = base.lastIndexOf(".");
+    return dot > 0 ? base.slice(0, dot) : base;
+};
+/** The `- PROG` entries of `## Wave: <name>` in the survey's wave plan. */
+export const wavePrograms = (planText, wave) => {
+    const lines = planText.split(/\r?\n/);
+    const start = lines.findIndex((line) => line.trim() === `## Wave: ${wave}`);
+    if (start < 0) {
+        return [];
+    }
+    const section = [];
+    for (const line of lines.slice(start + 1)) {
+        if (line.trim().startsWith("## ")) {
+            break;
+        }
+        if (line.trim().startsWith("- ")) {
+            section.push(line.trim().slice(2).trim());
+        }
+    }
+    return section;
+};
+export const programArtifactsJsonSchema = {
+    type: "object",
+    properties: {
+        spec: { type: "string" },
+        feature: { type: "string" },
+        traceability: { type: "string" },
+        mapping: { type: "string" }
+    },
+    required: ["spec", "feature", "traceability", "mapping"]
+};
+/** The analyst's system prompt: the pack's analysis sidecar plus its lessons. */
+export const analystSystem = (pack) => [
+    pack.prompt("analysis"),
+    pack.lessons === undefined
+        ? undefined
+        : `Lessons from previous modernization runs — apply them:\n${pack.lessons}`
+]
+    .filter((part) => part !== undefined)
+    .join("\n\n");
+// The analyst gets a deterministically resolved include closure, not an open
+// "read anything it references" instruction: told to chase references itself,
+// the coding agent pulls files into its own context inside a single turn —
+// which is how extract blew a 1M-token window while its own cap sat untouched.
+export const programAsk = (pack, relativePath, closure, revision) => [
+    revision === undefined
+        ? `Extract the behavioural spec for ONE source unit of this repository: ${relativePath}`
+        : `DEEPEN the behavioural spec of ONE source unit of this repository: ${relativePath}`,
+    "",
+    ...(closure.length === 0
+        ? [`Read ${relativePath}. It has no resolved dependencies.`]
+        : [
+            `Read ${relativePath} and EXACTLY these resolved dependencies — do not go looking for others:`,
+            ...closure.map((file) => `- ${file}`)
+        ]),
+    `Spec ONLY ${relativePath} and do not modify legacy sources.`,
+    ...(revision === undefined
+        ? []
+        : [
+            "",
+            "This is a REVISION, not a fresh extraction. Start from the previous artifacts below and",
+            "revise them: keep every existing scenario title UNCHANGED unless the behaviour it names",
+            "no longer exists in the source, add what is missing, correct what is wrong. The focus of",
+            `this revision, which the result MUST address explicitly: ${revision.focus}`,
+            "",
+            "Previous spec:",
+            revision.previous.spec,
+            "",
+            "Previous feature file:",
+            revision.previous.feature,
+            "",
+            "Previous traceability fragment:",
+            revision.previous.traceability,
+            "",
+            "Previous mapping fragment:",
+            revision.previous.mapping
+        ]),
+    "",
+    'Respond only with JSON: {"spec":"…","feature":"…","traceability":"…","mapping":"…"} where:',
+    "",
+    `- "spec" — the behavioural spec for ${relativePath}, as Markdown.`,
+    pack.prompt("spec") ?? "",
+    "",
+    `- "feature" — BDD scenarios encoding that spec, as a well-formed Gherkin .feature file`,
+    "  (Feature: header, Scenario: blocks, Given/When/Then steps).",
+    pack.prompt("bdd") ?? "",
+    "",
+    `- "traceability" — EVERY source unit of ${relativePath} (each COBOL paragraph, each JCL`,
+    "  step) on its own line, mapped to the spec rules/scenarios that cover it:",
+    "  `<UNIT-NAME> — <refs>`. Unit names verbatim as they appear in the source.",
+    "",
+    `- "mapping" — data & interface mapping for ${relativePath}: tables/record layouts → target`,
+    "  entities; files/screens/queues → target service contracts."
+].join("\n");
+/** Sub-bar judge dimensions as Critical review issues, titled with their program. */
+export const judgeIssues = (pack, scored, program) => {
+    const issues = scored.scores.flatMap((score) => {
+        const maxScore = pack.judgeDimensions.find((d) => d.name === score.name)?.maxScore ?? 2;
+        return score.score < maxScore
+            ? [
+                ReviewIssue.make({
+                    severity: "Critical",
+                    title: `judge[${program}]: ${score.name} scored ${score.score}`,
+                    description: score.reasoning
+                })
+            ]
+            : [];
+    });
+    return ReviewResult.make({ issues, summary: `judge:${program}` });
+};
+export const judgeIssueProgram = (issue) => /^judge\[([^\]]+)\]: /.exec(issue.title)?.[1];
+export const issueLines = (issues) => issues.map((issue) => `- [${issue.severity}] ${issue.title}: ${issue.description}`).join("\n");
+export const programFixAsk = (name, relativePath, issues) => [
+    `The spec pack for ONE program did not clear its quality gate: ${name} (source: ${relativePath}).`,
+    `Fix these findings by editing ONLY this program's files — ${ModDir}/specs/${name}.md,`,
+    `${ModDir}/features/${name.toLowerCase()}.feature, ${ModDir}/traceability/${name}.md,`,
+    `${ModDir}/mapping/${name}.md — against the source at ${relativePath}. Then stop:`,
+    issueLines(issues)
+].join("\n");
+export const globalFixAsk = (issues) => [
+    "The spec pack did not clear its estate-wide quality gate. Fix these findings by editing the",
+    `per-program files under ${ModDir}/ (specs/, features/, traceability/<PROGRAM>.md,`,
+    `mapping/<PROGRAM>.md). ${ModDir}/traceability.md and ${ModDir}/mapping.md are REGENERATED`,
+    "from the fragments — do not edit them directly. Fix the findings in place, then stop:",
+    issueLines(issues)
+].join("\n");
+/** The spec pack README; `notes` records what a refinement changed after the gate passed. */
+export const readmeFor = (pack, verdict, notes = []) => [
+    `# Modernization spec pack — ${pack.name}`,
+    "",
+    `Extracted by the modernize-extract flow. Gate verdict: ${verdict}.`,
+    "",
+    "- specs/ — behavioural specs, one per program",
+    "- features/ — BDD acceptance scenarios",
+    "- traceability.md — source-unit → spec coverage matrix (generated from traceability/)",
+    "- mapping.md — data & interface mapping (generated from mapping/)",
+    "- rules.txt — every coverage unit, one per line (the rule universe verification reports against)",
+    "- plan.md — proposed implementation tasks",
+    "- decisions.md / domains.md — the refinement overlays, when modernize-refine has run (ADR 0015)",
+    ...(notes.length === 0
+        ? []
+        : ["", "Refined after the gate passed:", ...notes.map((n) => `- ${n}`)]),
+    "",
+    "Review everything, then flip the marker below and run the seed phase."
+].join("\n");
+/**
+ * Judging is resumable per program: the verdict persists under
+ * `gate/<NAME>.json`, fingerprinted over the source, spec, feature, and
+ * rubric it judged. Unchanged content reuses the stored verdict with NO
+ * model call, so a crash or quota death re-judges only what changed.
+ * Delete `gate/` to force a full re-judge. `extraRubric` (a deepen focus)
+ * joins the rubric and therefore the fingerprint.
+ */
+export const makeProgramJudge = (deps) => {
+    const { context, files, pack, modDirAbs, workDir, limit } = deps;
+    const packJudge = judge(context.reasoning, pack.judgeDimensions);
+    // The shared Context ladder: an oversized prompt retries at half, then
+    // quarter budget (repeating it identically cannot succeed), and every
+    // cap or shrink is recorded and published.
+    const judgeWithShrink = (name, spec, feature, source) => withShrink(`judge[${name}]`, (cap) => Effect.gen(function* () {
+        const response = yield* capped(`spec[${name}]`, `${spec}\n\n${feature}`, cap);
+        const source_ = yield* capped(`source[${name}]`, source, cap);
+        return yield* packJudge
+            .evaluate(Sample.make({ response, context: source_, query: context.userPrompt }))
+            .pipe(Effect.mapError(FlowLlmError.from));
+    }), { start: limit }).pipe(Effect.provideService(FlowEvents, context.events));
+    return (unit, extraRubric) => Effect.gen(function* () {
+        const spec = (yield* files.read(join(modDirAbs, "specs", `${unit.name}.md`))) ?? "";
+        const feature = (yield* files.read(join(modDirAbs, "features", `${unit.name.toLowerCase()}.feature`))) ?? "";
+        const source = (yield* files.read(join(workDir, unit.sourcePath))) ?? "";
+        const rubric = [
+            ...pack.judgeDimensions.map((dimension) => `${dimension.name} (0..${dimension.maxScore}): ${dimension.rubric}`),
+            ...(extraRubric === undefined ? [] : [extraRubric])
+        ].join("\n");
+        return yield* cachedReview(files, join(modDirAbs, "gate", `${unit.name}.json`), reviewFingerprint(source, spec, feature, rubric), context.events.publish(Info.make({ message: `judging ${unit.name}` })).pipe(Effect.andThen(judgeWithShrink(unit.name, spec, feature, source)), Effect.map((scored) => judgeIssues(pack, scored, unit.name))));
+    });
+};
+/**
+ * One bounded fix turn: the coder edits the pack against `ask`, then the
+ * working tree is committed. A wedged agent that trips its turn limit
+ * mid-fix still wrote something; the caller re-evaluates what landed.
+ */
+export const fixTurn = (context, system, ask, commitMessage) => Effect.gen(function* () {
+    const chat = yield* makeChat(context.coder, { system });
+    yield* chat.ask(ask).pipe(Effect.asVoid, Effect.catchIf((error) => error._tag === "Llm" && error.cause?._tag === "TurnLimitError", () => context.events.publish(Info.make({
+        message: "turn limit hit during a fix turn — re-evaluating what was written"
+    }))));
+    yield* context.git.commitAll(commitMessage).pipe(Effect.asVoid);
+});

package/flows/modernize-extract.js

@@ -31,33 +31,19 @@ import { join } from "node:path";
 import * as Effect from "effect/Effect";
 import * as Ref from "effect/Ref";
 import * as Semaphore from "effect/Semaphore";
-import { Sample } from "@llm4ts/core/eval/Eval";
-import { judge } from "@llm4ts/core/eval/Judge";
-import { budget, capped, withShrink } from "@llm4ts/flow/Context";
+import { budget, capped } from "@llm4ts/flow/Context";
 import { structuredAndPublish } from "@llm4ts/flow/Flow";
 import { FlowEvents } from "@llm4ts/flow/FlowEvents";
-import { FlowAborted, FlowLlmError, Info, ReviewResult, asReadOnly, coderFromEnv, defaultPlanInstructions, loadKitPatternCards, makeChat, makeNodeWorkspace, mergeReviewResults, nodePlainFileStore, openPack, planFrom, resolveFlowInput, reviewFingerprint, runFlowMain, runNode, stage, withTurnLimit } from "@llm4ts/runner";
+import { FlowAborted, Info, ReviewResult, asReadOnly, coderFromEnv, defaultPlanInstructions, loadKitPatternCards, makeNodeWorkspace, mergeReviewResults, nodePlainFileStore, openPack, planFrom, resolveFlowInput, runFlowMain, runNode, stage, withTurnLimit } from "@llm4ts/runner";
 import { loadPatternCards, matchingPatternCards } from "@llm4ts/flow/Patterns";
 import { legacySourceWorkspaceLimits, workspaceLimitsFromEnv } from "@llm4ts/flow/Workspace";
 import { ReviewIssue } from "@llm4ts/flow/Review";
-import { cachedReview } from "@llm4ts/flow/ReviewCache";
 import { coverageReport, coverageUnits, features, matchingFiles, specSchemaIssues } from "@llm4ts/flow/SpecChecks";
 import { SurveyGraph, closureFor, surveyGraph } from "@llm4ts/flow/Survey";
 import { withDraftApproval, requireApproval } from "@llm4ts/flow/Approval";
 import { ProgramArtifacts, ProgramUnit, extractProgramsResumably, programArtifactPaths } from "@llm4ts/flow/Artifacts";
-const ModDir = "docs/modernization";
+import { ModDir, analystSystem, analystTurns, fixTurn, globalFixAsk, judgeIssueProgram, makeProgramJudge, maxClosureFiles, positiveEnvInt, programArtifactsJsonSchema, programAsk, programFixAsk, programName, readmeFor, wavePrograms } from "./lib/modernize-extract.js";
 const MaxRounds = 3;
-const positiveEnvInt = (name, fallback) => {
-    const raw = Number.parseInt(process.env[name] ?? "", 10);
-    return Number.isFinite(raw) && raw > 0 ? raw : fallback;
-};
-// Per-program turn budget — bounds a wedged agent, generous for real work.
-const analystTurns = () => positiveEnvInt("LLM4TS_ANALYST_TURNS", 48);
-/**
- * Max files named in one program's include closure. A program pulling more
- * than this gets a bounded, visible subset rather than an unbounded read.
- */
-const maxClosureFiles = () => positiveEnvInt("LLM4TS_MAX_CLOSURE_FILES", 40);
 /**
  * Programs extracted (and judged) at once. The programs of a wave are
  * independent — each analyst reads its source and resolved closure, writes
@@ -66,117 +52,6 @@ const maxClosureFiles = () => positiveEnvInt("LLM4TS_MAX_CLOSURE_FILES", 40);
  * narration; the bound is about the coder seat's quota, not correctness.
  */
 const extractConcurrency = () => positiveEnvInt("LLM4TS_EXTRACT_CONCURRENCY", 1);
-/** `cobol/ACCTXFR.cbl` → `ACCTXFR`: the program name keying every per-program artifact. */
-const programName = (relativePath) => {
-    const base = relativePath.slice(relativePath.lastIndexOf("/") + 1);
-    const dot = base.lastIndexOf(".");
-    return dot > 0 ? base.slice(0, dot) : base;
-};
-/** The `- PROG` entries of `## Wave: <name>` in the survey's wave plan. */
-const wavePrograms = (planText, wave) => {
-    const lines = planText.split(/\r?\n/);
-    const start = lines.findIndex((line) => line.trim() === `## Wave: ${wave}`);
-    if (start < 0) {
-        return [];
-    }
-    const section = [];
-    for (const line of lines.slice(start + 1)) {
-        if (line.trim().startsWith("## ")) {
-            break;
-        }
-        if (line.trim().startsWith("- ")) {
-            section.push(line.trim().slice(2).trim());
-        }
-    }
-    return section;
-};
-const programArtifactsJsonSchema = {
-    type: "object",
-    properties: {
-        spec: { type: "string" },
-        feature: { type: "string" },
-        traceability: { type: "string" },
-        mapping: { type: "string" }
-    },
-    required: ["spec", "feature", "traceability", "mapping"]
-};
-// The analyst gets a deterministically resolved include closure, not an open
-// "read anything it references" instruction: told to chase references itself,
-// the coding agent pulls files into its own context inside a single turn —
-// which is how extract blew a 1M-token window while its own cap sat untouched.
-const programAsk = (pack, relativePath, closure) => [
-    `Extract the behavioural spec for ONE source unit of this repository: ${relativePath}`,
-    "",
-    ...(closure.length === 0
-        ? [`Read ${relativePath}. It has no resolved dependencies.`]
-        : [
-            `Read ${relativePath} and EXACTLY these resolved dependencies — do not go looking for others:`,
-            ...closure.map((file) => `- ${file}`)
-        ]),
-    `Spec ONLY ${relativePath} and do not modify legacy sources.`,
-    "",
-    'Respond only with JSON: {"spec":"…","feature":"…","traceability":"…","mapping":"…"} where:',
-    "",
-    `- "spec" — the behavioural spec for ${relativePath}, as Markdown.`,
-    pack.prompt("spec") ?? "",
-    "",
-    `- "feature" — BDD scenarios encoding that spec, as a well-formed Gherkin .feature file`,
-    "  (Feature: header, Scenario: blocks, Given/When/Then steps).",
-    pack.prompt("bdd") ?? "",
-    "",
-    `- "traceability" — EVERY source unit of ${relativePath} (each COBOL paragraph, each JCL`,
-    "  step) on its own line, mapped to the spec rules/scenarios that cover it:",
-    "  `<UNIT-NAME> — <refs>`. Unit names verbatim as they appear in the source.",
-    "",
-    `- "mapping" — data & interface mapping for ${relativePath}: tables/record layouts → target`,
-    "  entities; files/screens/queues → target service contracts."
-].join("\n");
-/** Sub-bar judge dimensions as Critical review issues, titled with their program. */
-const judgeIssues = (pack, scored, program) => {
-    const issues = scored.scores.flatMap((score) => {
-        const maxScore = pack.judgeDimensions.find((d) => d.name === score.name)?.maxScore ?? 2;
-        return score.score < maxScore
-            ? [
-                ReviewIssue.make({
-                    severity: "Critical",
-                    title: `judge[${program}]: ${score.name} scored ${score.score}`,
-                    description: score.reasoning
-                })
-            ]
-            : [];
-    });
-    return ReviewResult.make({ issues, summary: `judge:${program}` });
-};
-const judgeIssueProgram = (issue) => /^judge\[([^\]]+)\]: /.exec(issue.title)?.[1];
-const issueLines = (issues) => issues.map((issue) => `- [${issue.severity}] ${issue.title}: ${issue.description}`).join("\n");
-const programFixAsk = (name, relativePath, issues) => [
-    `The spec pack for ONE program did not clear its quality gate: ${name} (source: ${relativePath}).`,
-    `Fix these findings by editing ONLY this program's files — ${ModDir}/specs/${name}.md,`,
-    `${ModDir}/features/${name.toLowerCase()}.feature, ${ModDir}/traceability/${name}.md,`,
-    `${ModDir}/mapping/${name}.md — against the source at ${relativePath}. Then stop:`,
-    issueLines(issues)
-].join("\n");
-const globalFixAsk = (issues) => [
-    "The spec pack did not clear its estate-wide quality gate. Fix these findings by editing the",
-    `per-program files under ${ModDir}/ (specs/, features/, traceability/<PROGRAM>.md,`,
-    `mapping/<PROGRAM>.md). ${ModDir}/traceability.md and ${ModDir}/mapping.md are REGENERATED`,
-    "from the fragments — do not edit them directly. Fix the findings in place, then stop:",
-    issueLines(issues)
-].join("\n");
-const readmeFor = (pack, verdict) => [
-    `# Modernization spec pack — ${pack.name}`,
-    "",
-    `Extracted by the modernize-extract flow. Gate verdict: ${verdict}.`,
-    "",
-    "- specs/ — behavioural specs, one per program",
-    "- features/ — BDD acceptance scenarios",
-    "- traceability.md — source-unit → spec coverage matrix (generated from traceability/)",
-    "- mapping.md — data & interface mapping (generated from mapping/)",
-    "- rules.txt — every coverage unit, one per line (the rule universe verification reports against)",
-    "- plan.md — proposed implementation tasks",
-    "",
-    "Review everything, then flip the marker below and run the seed phase."
-].join("\n");
 const program = Effect.gen(function* () {
     const input = yield* resolveFlowInput("Extract the complete behavioural spec pack for this legacy estate");
     const coder = withTurnLimit(coderFromEnv(process.env), analystTurns());
@@ -198,14 +73,7 @@ const program = Effect.gen(function* () {
         }));
         const pack = opened.pack;
         yield* stage(context.events, "branch", context.git.checkoutOrCreate("modernize/spec-pack").pipe(Effect.asVoid));
-        const system = [
-            pack.prompt("analysis"),
-            pack.lessons === undefined
-                ? undefined
-                : `Lessons from previous modernization runs — apply them:\n${pack.lessons}`
-        ]
-            .filter((part) => part !== undefined)
-            .join("\n\n");
+        const system = analystSystem(pack);
         const all = yield* stage(context.events, "inventory", matchingFiles(repo, pack.programs ?? pack.sources ?? ".*", pack.exclude));
         const wave = process.env.LLM4TS_WAVE?.trim();
         const programs = wave === undefined || wave.length === 0
@@ -345,33 +213,14 @@ const program = Effect.gen(function* () {
         yield* stage(context.events, "draft", rebuildIndexes.pipe(Effect.andThen(writeRules), Effect.andThen(context.git
             .commitAll(`modernize(${pack.name}): spec pack draft (ungated)`)
             .pipe(Effect.asVoid))));
-        const packJudge = judge(context.reasoning, pack.judgeDimensions);
         const limit = budget();
-        // The shared Context ladder: an oversized prompt retries at half, then
-        // quarter budget (repeating it identically cannot succeed), and every
-        // cap or shrink is recorded and published.
-        const judgeWithShrink = (name, spec, feature, source) => withShrink(`judge[${name}]`, (cap) => Effect.gen(function* () {
-            const response = yield* capped(`spec[${name}]`, `${spec}\n\n${feature}`, cap);
-            const source_ = yield* capped(`source[${name}]`, source, cap);
-            return yield* packJudge
-                .evaluate(Sample.make({ response, context: source_, query: input.prompt }))
-                .pipe(Effect.mapError(FlowLlmError.from));
-        }), { start: limit }).pipe(Effect.provideService(FlowEvents, context.events));
-        /**
-         * Judging is resumable per program: the verdict persists under
-         * `gate/<NAME>.json`, fingerprinted over the source, spec, feature, and
-         * rubric it judged. Unchanged content reuses the stored verdict with NO
-         * model call, so a crash or quota death re-judges only what changed.
-         * Delete `gate/` to force a full re-judge.
-         */
-        const judgeProgram = (unit) => Effect.gen(function* () {
-            const spec = (yield* files.read(join(modDirAbs, "specs", `${unit.name}.md`))) ?? "";
-            const feature = (yield* files.read(join(modDirAbs, "features", `${unit.name.toLowerCase()}.feature`))) ?? "";
-            const source = (yield* files.read(join(input.workDir, unit.sourcePath))) ?? "";
-            const rubric = pack.judgeDimensions
-                .map((dimension) => `${dimension.name} (0..${dimension.maxScore}): ${dimension.rubric}`)
-                .join("\n");
-            return yield* cachedReview(files, join(modDirAbs, "gate", `${unit.name}.json`), reviewFingerprint(source, spec, feature, rubric), context.events.publish(Info.make({ message: `judging ${unit.name}` })).pipe(Effect.andThen(judgeWithShrink(unit.name, spec, feature, source)), Effect.map((scored) => judgeIssues(pack, scored, unit.name))));
+        const judgeProgram = makeProgramJudge({
+            context,
+            files,
+            pack,
+            modDirAbs,
+            workDir: input.workDir,
+            limit
         });
         const gateEvaluate = Effect.gen(function* () {
             yield* rebuildIndexes;
@@ -426,7 +275,7 @@ const program = Effect.gen(function* () {
             const wellFormed = yield* features(repo, join(ModDir, "features"));
             // Verdicts are per program and cached per program, so they judge
             // under the same bound as extraction; the merge is order-stable.
-            const judged = yield* Effect.forEach(units, judgeProgram, { concurrency });
+            const judged = yield* Effect.forEach(units, (unit) => judgeProgram(unit), { concurrency });
             return mergeReviewResults([covered, wellFormed, docs, ...judged]);
         });
         // One bounded fix turn per sub-bar program (own commit) plus one residual
@@ -446,16 +295,7 @@ const program = Effect.gen(function* () {
                     global.push(issue);
                 }
             }
-            const turn = (ask, commitMessage) => Effect.gen(function* () {
-                const chat = yield* makeChat(context.coder, { system });
-                yield* chat.ask(ask).pipe(Effect.asVoid, 
-                // A wedged agent that trips its turn limit mid-fix still wrote
-                // something; re-evaluate what landed instead of failing.
-                Effect.catchIf((error) => error._tag === "Llm" && error.cause?._tag === "TurnLimitError", () => context.events.publish(Info.make({
-                    message: "turn limit hit during a fix turn — re-evaluating what was written"
-                }))));
-                yield* context.git.commitAll(commitMessage).pipe(Effect.asVoid);
-            });
+            const turn = (ask, commitMessage) => fixTurn(context, system, ask, commitMessage);
             for (const [name, issues] of [...scoped.entries()].sort()) {
                 yield* context.events.publish(Info.make({ message: `fixing ${name} — ${issues.length} finding(s)` }));
                 const relativePath = relOf.get(name);

package/flows/modernize-implement.js

@@ -30,6 +30,7 @@ import { Provenance, makeProvenanceStore } from "@llm4ts/flow/Provenance";
 import { loadPatternCards, taggedPatternIds } from "@llm4ts/flow/Patterns";
 import { ReviewIssue } from "@llm4ts/flow/Review";
 import { checkWall, wallBreachMessage } from "@llm4ts/flow/Wall";
+import { parseDecisions } from "@llm4ts/flow/Decisions";
 const ModDir = "docs/modernization";
 const judgeRounds = () => {
     const raw = Number.parseInt(process.env.LLM4TS_JUDGE_ROUNDS ?? "", 10);
@@ -66,9 +67,32 @@ const specPrograms = Effect.fn("modernize-implement.specPrograms")(function* (ta
         .map((path) => path.split("/").at(-1) ?? path)
         .filter((name) => name.endsWith(".md"))
         .map((name) => name.slice(0, -".md".length))
-        .filter((name) => !["traceability", "mapping", "README"].includes(name))
+        .filter((name) => !["traceability", "mapping", "README", "decisions", "domains"].includes(name))
         .sort();
 });
+/**
+ * The decisions overlay seeded beside the specs (ADR 0015), rendered for a
+ * brief: what is out of scope and must not be built or scored, and which
+ * target capability a `provided` entry points at.
+ */
+const decisionsBrief = Effect.fn("modernize-implement.decisionsBrief")(function* (files, specsDirAbs) {
+    const text = yield* files.read(join(specsDirAbs, "decisions.md"));
+    if (text === undefined) {
+        return undefined;
+    }
+    const decisions = yield* parseDecisions(text, "decisions.md");
+    const lines = [
+        ...decisions.programs.map((entry) => `- ${entry.program} (whole program): ${entry.disposition} — ${entry.reason}` +
+            (entry.pointer === undefined ? "" : ` [provided by ${entry.pointer}]`)),
+        ...decisions.scenarios.map((entry) => `- ${entry.program} / ${entry.scenario}: ${entry.disposition} — ${entry.reason}` +
+            (entry.pointer === undefined ? "" : ` [provided by ${entry.pointer}]`))
+    ];
+    return lines.length === 0
+        ? undefined
+        : "Out of scope by decision (do not implement, do not test, do not score their absence; " +
+            "use the target capability a `provided` entry points at instead of rebuilding it):\n" +
+            lines.join("\n");
+});
 /**
  * One bounded estate-wide pass: the traceability index plus the changed-file
  * NAMES (never contents). Per-program judging cannot see cross-program
@@ -175,8 +199,10 @@ const program = Effect.gen(function* () {
         ];
         const cited = new Set(taggedPatternIds(specText));
         const playbook = cards.filter((card) => cited.has(card.id));
+        const scope = yield* decisionsBrief(files, join(input.workDir, pack.specsDir));
         const system = [
             pack.prompt("implement"),
+            scope,
             pack.lessons === undefined
                 ? undefined
                 : `Lessons from previous modernization runs — apply them:\n${pack.lessons}`,
@@ -265,7 +291,7 @@ const program = Effect.gen(function* () {
                     programs,
                     specFor: (program) => files
                         .read(join(specsDirAbs, `${program}.md`))
-                        .pipe(Effect.map((text) => text ?? "")),
+                        .pipe(Effect.map((text) => scope === undefined ? (text ?? "") : `${text ?? ""}\n\n${scope}`)),
                     query: input.prompt,
                     fingerprint: reviewFingerprint
                 });

package/flows/modernize-pack-check.js

@@ -32,7 +32,9 @@ const phasePrompts = [
     ["plan", "extract"],
     ["implement", "implement"],
     ["review", "review"],
-    ["vectors", "verify"]
+    ["vectors", "verify"],
+    ["refine-propose", "refine"],
+    ["consolidate", "refine"]
 ];
 const sampleSize = 5;
 const sample = (units) => units.length === 0
@@ -103,6 +105,10 @@ const program = Effect.gen(function* () {
             if (pack.lenses.length === 0) {
                 warnings.push("no reviewers/*.md sidecar — review runs without pack lenses");
             }
+            yield* say(pack.consolidate === undefined
+                ? "consolidate: (none — refine treats every program as its own domain feature)"
+                : `consolidate: cluster on ${pack.consolidate.cluster.join(", ") || "(nothing)"} · ` +
+                    `context via ${pack.consolidate.context.join(", ") || "(nothing)"}`);
             yield* say(`lessons: ${pack.lessons === undefined ? "(none yet)" : "present"}`);
         }));
         yield* stage(context.events, "estate", Effect.gen(function* () {