@llm4ts/shell 0.10.0 → 0.10.1

package/flows/modernize-extract.js

@@ -21,14 +21,17 @@
 // Pack: LLM4TS_PACK=<dir> (default packs/cobol-springboot, resolved against the
 // launch dir, then against the flow's own directory — the built-in packs).
 // LLM4TS_WAVE=<name> scopes the run to one wave of the approved plan. Judge
-// context is bounded by LLM4TS_JUDGE_SOURCES_LIMIT (chars).
+// context is bounded by LLM4TS_CONTEXT_BUDGET (chars;
+// LLM4TS_JUDGE_SOURCES_LIMIT is the deprecated alias). The analyst is bounded
+// by LLM4TS_ANALYST_TURNS and LLM4TS_MAX_CLOSURE_FILES.
 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 { budget, capped, withShrink } from "@llm4ts/flow/Context";
 import { FlowAborted, FlowLlmError } from "@llm4ts/flow/FlowError";
 import { structuredAndPublish } from "@llm4ts/flow/Flow";
-import { Info } from "@llm4ts/flow/FlowEvents";
+import { FlowEvents, Info } from "@llm4ts/flow/FlowEvents";
 import { makeChat } from "@llm4ts/flow/Chat";
 import { loadPatternCards, matchingPatternCards } from "@llm4ts/flow/Patterns";
 import { legacySourceWorkspaceLimits, workspaceLimitsFromEnv } from "@llm4ts/flow/Workspace";
@@ -37,9 +40,10 @@ import { defaultPlanInstructions, planFrom } from "@llm4ts/flow/Planner";
 import { ReviewIssue, ReviewResult, mergeReviewResults } from "@llm4ts/flow/Review";
 import { cachedReview } from "@llm4ts/flow/ReviewCache";
 import { coverage, coverageUnits, features, matchingFiles } from "@llm4ts/flow/SpecChecks";
+import { SurveyGraph, closureFor, surveyGraph } from "@llm4ts/flow/Survey";
 import { withDraftApproval, requireApproval } from "@llm4ts/modernize/Approval";
 import { ProgramArtifacts, ProgramUnit, extractProgramsResumably } from "@llm4ts/modernize/Artifacts";
-import { asReadOnly, coderFromEnv } from "@llm4ts/runner/Connectors";
+import { asReadOnly, coderFromEnv, withTurnLimit } from "@llm4ts/runner/Connectors";
 import { resolveFlowInput } from "@llm4ts/runner/FlowArgs";
 import { runFlowMain, runNode } from "@llm4ts/runner/FlowRunner";
 import { reviewFingerprint } from "@llm4ts/runner/ReviewFingerprint";
@@ -48,18 +52,17 @@ import { makeNodeWorkspace } from "@llm4ts/runner/NodeWorkspace";
 import { loadUniversalPatternCards, openPack } from "@llm4ts/runner/Packs";
 const ModDir = "docs/modernization";
 const MaxRounds = 3;
-const judgeSourcesLimit = () => {
-    const raw = Number.parseInt(process.env.LLM4TS_JUDGE_SOURCES_LIMIT ?? "", 10);
-    return Number.isFinite(raw) && raw > 0 ? raw : 400_000;
-};
-/** Past the limit keep head + tail so entry points and trailing rules stay visible. */
-const capText = (text, limit) => {
-    if (text.length <= limit) {
-        return text;
-    }
-    const head = Math.floor((limit * 3) / 4);
-    return `${text.slice(0, head)}\n\n… [truncated] …\n\n${text.slice(text.length - (limit - head))}`;
+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);
 /** `cobol/ACCTXFR.cbl` → `ACCTXFR`: the program name keying every per-program artifact. */
 const programName = (relativePath) => {
     const base = relativePath.slice(relativePath.lastIndexOf("/") + 1);
@@ -94,11 +97,20 @@ const programArtifactsJsonSchema = {
     },
     required: ["spec", "feature", "traceability", "mapping"]
 };
-const programAsk = (pack, relativePath) => [
+// 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}`,
     "",
-    "Read the source file and anything it references (copybooks, includes, called programs)",
-    `for context, but spec ONLY ${relativePath} and do not modify legacy sources.`,
+    ...(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:',
     "",
@@ -164,7 +176,7 @@ const readmeFor = (pack, verdict) => [
 ].join("\n");
 const program = Effect.gen(function* () {
     const input = yield* resolveFlowInput("Extract the complete behavioural spec pack for this legacy estate");
-    const coder = coderFromEnv(process.env);
+    const coder = withTurnLimit(coderFromEnv(process.env), analystTurns());
     const files = nodePlainFileStore;
     const modDirAbs = join(input.workDir, ModDir);
     yield* runNode({
@@ -219,6 +231,15 @@ const program = Effect.gen(function* () {
             ...(yield* loadPatternCards(opened.workspace, `${opened.dir}/patterns`)),
             ...(yield* loadUniversalPatternCards([input.workspace, import.meta.dirname]))
         ];
+        // The dependency graph the analysts' include closures are resolved
+        // from — walked over the pack's `## Survey:` edge regexes.
+        const graph = yield* stage(context.events, "graph", pack.survey.length === 0
+            ? context.events
+                .publish(Info.make({
+                message: "pack has no '## Survey:' edge regexes — the analyst gets no resolved closure"
+            }))
+                .pipe(Effect.as(SurveyGraph.make({ nodes: [], edges: [] })))
+            : surveyGraph(repo, pack.sources ?? ".*", pack.coverage, pack.survey));
         // One structured analyst call per program, resumable per program: a rerun
         // skips every program whose spec exists, and each program gets its own commit.
         yield* stage(context.events, "extract", Effect.gen(function* () {
@@ -227,7 +248,7 @@ const program = Effect.gen(function* () {
                     yield* context.events.publish(Info.make({
                         message: `extracting ${target.sourcePath} (${index + 1}/${units.length})`
                     }));
-                    return yield* structuredAndPublish(context.coder, context.events, `${system}\n\n${programAsk(pack, target.sourcePath)}`, ProgramArtifacts, programArtifactsJsonSchema, "coder").pipe(
+                    return yield* structuredAndPublish(context.coder, context.events, `${system}\n\n${programAsk(pack, target.sourcePath, closureFor(graph, target.name, maxClosureFiles()))}`, ProgramArtifacts, programArtifactsJsonSchema, "coder").pipe(
                     // A turn-limit trip is the wedged-agent tail, not a
                     // failure: keep whatever the analyst already produced.
                     Effect.catchIf((error) => error.cause?._tag === "TurnLimitError", (error) => Effect.gen(function* () {
@@ -300,29 +321,17 @@ const program = Effect.gen(function* () {
             .commitAll(`modernize(${pack.name}): spec pack draft (ungated)`)
             .pipe(Effect.asVoid))));
         const packJudge = judge(context.reasoning, pack.judgeDimensions);
-        const limit = judgeSourcesLimit();
-        /**
-         * An empty structured response that survives the in-run retries is
-         * usually DETERMINISTIC (context overflow), so repeating the same
-         * prompt cannot succeed — retry at half, then quarter context instead.
-         */
-        const judgeWithShrink = (spec, feature, source) => {
-            const attempt = (cap, rest) => packJudge
-                .evaluate(Sample.make({
-                response: capText(`${spec}\n\n${feature}`, cap),
-                context: capText(source, cap),
-                query: input.prompt
-            }))
-                .pipe(Effect.mapError(FlowLlmError.from), Effect.catchIf((error) => rest.length > 0 && error.message.includes("empty response"), (error) => {
-                const [next, ...remaining] = rest;
-                return context.events
-                    .publish(Info.make({
-                    message: `judge returned empty at cap ${cap} chars — shrinking to ${next ?? cap}: ${error.message}`
-                }))
-                    .pipe(Effect.andThen(attempt(next ?? cap, remaining)));
-            }));
-            return attempt(limit, [Math.floor(limit / 2), Math.floor(limit / 4)]);
-        };
+        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
@@ -337,7 +346,7 @@ const program = Effect.gen(function* () {
             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(spec, feature, source)), Effect.map((scored) => judgeIssues(pack, scored, unit.name))));
+            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 gateEvaluate = Effect.gen(function* () {
             yield* rebuildIndexes;
@@ -427,7 +436,8 @@ const program = Effect.gen(function* () {
                         specTexts.push(spec);
                     }
                 }
-                const plan = yield* planFrom(context.reasoning, capText(specTexts.join("\n\n"), limit), `${defaultPlanInstructions}\n\n${pack.prompt("plan") ?? ""}`);
+                const plannerSpecs = yield* capped("plan specs", specTexts.join("\n\n"), limit).pipe(Effect.provideService(FlowEvents, context.events));
+                const plan = yield* planFrom(context.reasoning, plannerSpecs, `${defaultPlanInstructions}\n\n${pack.prompt("plan") ?? ""}`);
                 yield* files.writeAtomic(join(modDirAbs, "plan.md"), plan.render);
             }));
         }

package/flows/modernize-implement.js

@@ -23,14 +23,18 @@ import * as Effect from "effect/Effect";
 import { Dimension, Sample } from "@llm4ts/core/eval/Eval";
 import { judge } from "@llm4ts/core/eval/Judge";
 import { makeChat } from "@llm4ts/flow/Chat";
+import { capped, renderTruncation, truncations, withShrink } from "@llm4ts/flow/Context";
 import { FlowAborted, FlowLlmError } from "@llm4ts/flow/FlowError";
-import { Info } from "@llm4ts/flow/FlowEvents";
+import { FlowEvents, Info } from "@llm4ts/flow/FlowEvents";
+import { judgeAllPrograms } from "@llm4ts/flow/ProgramJudge";
+import { Provenance, makeProvenanceStore } from "@llm4ts/flow/Provenance";
 import { loadPatternCards, taggedPatternIds } from "@llm4ts/flow/Patterns";
 import { makePlanStore } from "@llm4ts/flow/Persistence";
 import { implementTaskLoop, stage } from "@llm4ts/flow/PlanExecution";
-import { lintCommand, minimalReviewers, reviewAndFixLoop } from "@llm4ts/flow/Review";
+import { ReviewIssue, ReviewResult, lintCommand, mergeReviewResults, minimalReviewers, reviewAndFixLoop } from "@llm4ts/flow/Review";
 import { checkWall, wallBreachMessage } from "@llm4ts/flow/Wall";
 import { asReadOnly, coderFromEnv } from "@llm4ts/runner/Connectors";
+import { reviewFingerprint } from "@llm4ts/runner/ReviewFingerprint";
 import { resolveFlowInput } from "@llm4ts/runner/FlowArgs";
 import { runFlowMain, runNode } from "@llm4ts/runner/FlowRunner";
 import { nodePlainFileStore } from "@llm4ts/runner/NodePlainFileStore";
@@ -66,6 +70,62 @@ const gatherSpecs = Effect.fn("modernize-implement.gatherSpecs")(function* (targ
     return parts.join("\n\n");
 });
 const issueText = (issues) => issues.map((issue) => `${issue.title}\n${issue.description}`.trim()).join("\n\n");
+/** The spec'd programs: top-level `<NAME>.md` under the specs dir, indexes aside. */
+const specPrograms = Effect.fn("modernize-implement.specPrograms")(function* (target, specsDir) {
+    const paths = yield* target.discover(`${specsDir}/*.md`).pipe(Effect.orElseSucceed(() => []));
+    return [...paths]
+        .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))
+        .sort();
+});
+/**
+ * One bounded estate-wide pass: the traceability index plus the changed-file
+ * NAMES (never contents). Per-program judging cannot see cross-program
+ * problems — a rule that moved between programs, a scenario orphaned when two
+ * programs were merged — because each of its calls only ever sees one
+ * program's slice of the diff. This pass is the compensating check. Both
+ * parts are capped, not just the index: on a full-estate branch the
+ * changed-file name list alone can run to five figures of lines.
+ */
+const traceabilityPass = (complianceJudge, dimensions, trace, changedFiles, userPrompt) => withShrink("judge[traceability]", (cap) => Effect.gen(function* () {
+    const cappedTrace = yield* capped("traceability", trace, Math.floor(cap / 2));
+    const cappedNames = yield* capped("changed files", `Files changed on this branch:\n${changedFiles.join("\n")}`, Math.floor(cap / 2));
+    return yield* complianceJudge
+        .evaluate(Sample.make({ response: cappedNames, context: cappedTrace, query: userPrompt }))
+        .pipe(Effect.mapError(FlowLlmError.from));
+})).pipe(Effect.map((scored) => traceabilityIssues(scored, dimensions)));
+const traceabilityIssues = (scored, dimensions) => {
+    const subBar = scored.scores.filter((score) => score.score < (dimensions.find((dimension) => dimension.name === score.name)?.maxScore ?? 2));
+    return ReviewResult.make({
+        issues: subBar.map((score) => ReviewIssue.make({
+            severity: "Critical",
+            title: `judge[traceability]: ${score.name} scored ${score.score}`,
+            description: score.reasoning
+        })),
+        summary: "judge:traceability"
+    });
+};
+/**
+ * Append this run's recorded context truncations to the manifest, so a
+ * verdict rendered on a partially-read spec pack says so in the evidence
+ * chain rather than only in the console log. A repo seeded before provenance
+ * existed simply has no manifest — skip rather than fail.
+ */
+const recordTruncations = (manifestPath, events) => Effect.gen(function* () {
+    const recorded = yield* truncations;
+    if (recorded.length === 0) {
+        return;
+    }
+    const store = makeProvenanceStore(nodePlainFileStore);
+    yield* store
+        .extend(manifestPath, (current) => Provenance.make({
+        ...current,
+        contextTruncations: [...current.contextTruncations, ...recorded.map(renderTruncation)]
+    }))
+        .pipe(Effect.asVoid, Effect.catch(() => events.publish(Info.make({ message: "no provenance.json — seeded by an older run; skipping" }))));
+});
 const program = Effect.gen(function* () {
     const input = yield* resolveFlowInput("Implement the seeded modernization plan");
     const coder = coderFromEnv(process.env);
@@ -141,10 +201,14 @@ const program = Effect.gen(function* () {
         if (playbook.length > 0) {
             yield* context.events.publish(Info.make({ message: `${playbook.length} pattern card(s) cited by the specs` }));
         }
-        const coderChat = yield* makeChat(context.coder, { system });
         const firstTitle = plan.tasks[0]?.title;
+        // One chat per task: `Chat` replays its full message list on each ask,
+        // so a shared chat would carry every earlier task's transcript into
+        // task N's prompt. The repo, not the transcript, carries state between
+        // tasks.
         yield* implementTaskLoop(store, context.events, planPath, plan, (task) => Effect.gen(function* () {
             const testsTask = task.title === firstTitle;
+            const coderChat = yield* makeChat(context.coder, { system });
             yield* coderChat.ask(plan.taskPrompt(task));
             yield* reviewAndFixLoop({
                 reviewers: [...minimalReviewers, ...pack.lenses],
@@ -187,39 +251,58 @@ const program = Effect.gen(function* () {
                 }
             }));
         }
-        // The branch-level judge: bounded rounds of feedback, each re-gated and
-        // committed, failing the flow if the bar is never cleared.
+        // The spec-compliance judge, decomposed: one ProgramJudge pass per
+        // program's own slice of the diff (cached, resumable), plus one
+        // bounded traceability pass over the whole estate — never the whole
+        // spec pack times the whole branch diff in a single call. Bounded
+        // rounds of feedback, each re-gated and committed, failing the flow
+        // if the bar is never cleared.
         yield* stage(context.events, "judge", Effect.gen(function* () {
-            const contractText = yield* gatherSpecs(target, pack.specsDir);
             const complianceJudge = judge(context.reasoning, complianceDimensions);
+            const specsDirAbs = join(input.workDir, pack.specsDir);
+            const gateDir = join(input.workDir, ModDir, "gate");
             const rounds = judgeRounds();
             for (let round = 1; round <= rounds; round += 1) {
                 const base = yield* context.git.defaultBase;
-                const diff = yield* context.git.diffVsBase(base);
-                const scored = yield* complianceJudge
-                    .evaluate(Sample.make({
-                    response: diff,
-                    context: contractText,
-                    query: input.prompt
-                }))
-                    .pipe(Effect.mapError(FlowLlmError.from));
-                const below = scored.scores.filter((score) => {
-                    const max = complianceDimensions.find((d) => d.name === score.name)?.maxScore ?? 2;
-                    return score.score < max;
+                const programs = yield* specPrograms(target, pack.specsDir);
+                const perProgram = yield* judgeAllPrograms({
+                    pack,
+                    judge: complianceJudge,
+                    dimensions: complianceDimensions,
+                    git: context.git,
+                    files,
+                    gateDir,
+                    base,
+                    programs,
+                    specFor: (program) => files
+                        .read(join(specsDirAbs, `${program}.md`))
+                        .pipe(Effect.map((text) => text ?? "")),
+                    query: input.prompt,
+                    fingerprint: reviewFingerprint
                 });
-                if (below.length === 0) {
+                const trace = yield* files
+                    .read(join(specsDirAbs, "traceability.md"))
+                    .pipe(Effect.map((text) => text ?? ""));
+                const changed = yield* context.git.changedFilesVsBase(base);
+                const traced = yield* traceabilityPass(complianceJudge, complianceDimensions, trace, changed, input.prompt);
+                const merged = mergeReviewResults([perProgram, traced]);
+                if (merged.isClean) {
                     return yield* context.events.publish(Info.make({ message: "spec-compliance judge: branch cleared the bar" }));
                 }
                 if (round >= rounds) {
                     return yield* FlowAborted.make({
                         message: `spec-compliance judge not cleared after ${rounds} round(s):\n` +
-                            below.map((d) => `- ${d.name} ${d.score}: ${d.reasoning}`).join("\n")
+                            merged.issues.map((i) => `- ${i.title}: ${i.description}`).join("\n")
                     });
                 }
-                yield* coderChat.ask([
+                // Feedback goes to a FRESH chat: the judge findings carry their
+                // own context, and replaying the whole implementation transcript
+                // is exactly the accumulation this flow no longer does.
+                const feedbackChat = yield* makeChat(context.coder, { system });
+                yield* feedbackChat.ask([
                     "The final spec-compliance review scored the branch below the bar. Close these gaps",
                     "without weakening any test, then stop:",
-                    ...below.map((d) => `- ${d.name} (${d.score}): ${d.reasoning}`)
+                    ...merged.issues.map((i) => `- ${i.title}: ${i.description}`)
                 ].join("\n"));
                 if (verifyGate !== undefined) {
                     const regated = yield* verifyGate;
@@ -233,7 +316,12 @@ const program = Effect.gen(function* () {
                     .commitAll(`${plan.epicId}: address spec-compliance feedback`)
                     .pipe(Effect.asVoid);
             }
-        }));
+        }).pipe(Effect.provideService(FlowEvents, context.events)));
+        // Truncations recorded while judging land in the evidence chain, and
+        // the per-program verdict cache is committed with them: it is part of
+        // the evidence, and a rerun on a fresh clone resumes from it.
+        yield* recordTruncations(join(input.workDir, ModDir, "provenance.json"), context.events);
+        yield* context.git.commitAll(`${plan.epicId}: judge verdicts`).pipe(Effect.asVoid);
         // Publishing is best-effort: a repository with no remote or forge is a
         // normal local run, not a failure.
         yield* stage(context.events, "publish", Effect.gen(function* () {

package/flows/modernize-review.js

@@ -17,11 +17,14 @@
 import { join } from "node:path";
 import * as Effect from "effect/Effect";
 import * as Schema from "effect/Schema";
-import { Dimension, Sample } from "@llm4ts/core/eval/Eval";
+import { Dimension } from "@llm4ts/core/eval/Eval";
 import { judge } from "@llm4ts/core/eval/Judge";
-import { FlowAborted, FlowLlmError } from "@llm4ts/flow/FlowError";
+import { capped, renderTruncation, truncations, withShrink } from "@llm4ts/flow/Context";
+import { FlowAborted } from "@llm4ts/flow/FlowError";
 import { structuredAndPublish } from "@llm4ts/flow/Flow";
-import { Info } from "@llm4ts/flow/FlowEvents";
+import { FlowEvents, Info } from "@llm4ts/flow/FlowEvents";
+import { judgeAllPrograms } from "@llm4ts/flow/ProgramJudge";
+import { Provenance, makeProvenanceStore } from "@llm4ts/flow/Provenance";
 import { appendPackLesson } from "@llm4ts/flow/Pack";
 import { makePlanStore } from "@llm4ts/flow/Persistence";
 import { Plan, Task } from "@llm4ts/flow/Plan";
@@ -34,6 +37,7 @@ import { runFlowMain, runNode } from "@llm4ts/runner/FlowRunner";
 import { nodePlainFileStore } from "@llm4ts/runner/NodePlainFileStore";
 import { makeNodeWorkspace } from "@llm4ts/runner/NodeWorkspace";
 import { openPack } from "@llm4ts/runner/Packs";
+import { reviewFingerprint } from "@llm4ts/runner/ReviewFingerprint";
 const ModDir = "docs/modernization";
 class FixSpec extends Schema.Class("FixSpec")({
     title: Schema.String,
@@ -94,10 +98,17 @@ const gatherDir = Effect.fn("modernize-review.gatherDir")(function* (workspace,
     }
     return parts.join("\n\n");
 });
-const distillPrompt = (pack, findings, scored, diff) => [
+/**
+ * The distill prompt carries findings and judge verdicts, NOT the diff: every
+ * finding already names what it is about (reviewer issues carry file/line,
+ * judge issues name their program), so anything the distiller needs arrived
+ * scoped upstream — reintroducing the whole diff here is exactly the
+ * unbounded prompt this flow no longer sends.
+ */
+const distillPrompt = (pack, findings, judged) => [
     pack.prompt("review") ?? "",
     "",
-    "Below are the raw reviewer findings and judge scores for a modernization increment.",
+    "Below are the raw reviewer findings and judge verdicts for a modernization increment.",
     "Distill them:",
     '- "fixes": findings where the implementation VIOLATES the committed specs. Each gets a',
     "  short spec document (Markdown: what is wrong, the spec rule it violates, the expected",
@@ -112,12 +123,35 @@ const distillPrompt = (pack, findings, scored, diff) => [
         .map((issue) => `- [${issue.severity}] ${issue.title}: ${issue.description}`)
         .join("\n"),
     "",
-    "Judge scores:",
-    scored.scores.map((score) => `- ${score.name}: ${score.score} — ${score.reasoning}`).join("\n"),
-    "",
-    "Diff under review:",
-    diff
+    "Judge findings (per-program spec-compliance):",
+    judged.isClean
+        ? "- all programs cleared the bar"
+        : judged.issues.map((issue) => `- ${issue.title}: ${issue.description}`).join("\n")
 ].join("\n");
+/** The spec'd programs: top-level `<NAME>.md` under the specs dir, indexes aside. */
+const specPrograms = Effect.fn("modernize-review.specPrograms")(function* (target, specsDir) {
+    const paths = yield* target.discover(`${specsDir}/*.md`).pipe(Effect.orElseSucceed(() => []));
+    return [...paths]
+        .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))
+        .sort();
+});
+/** Append this run's recorded truncations to provenance.json, when present. */
+const recordTruncations = (manifestPath, events) => Effect.gen(function* () {
+    const recorded = yield* truncations;
+    if (recorded.length === 0) {
+        return;
+    }
+    const store = makeProvenanceStore(nodePlainFileStore);
+    yield* store
+        .extend(manifestPath, (current) => Provenance.make({
+        ...current,
+        contextTruncations: [...current.contextTruncations, ...recorded.map(renderTruncation)]
+    }))
+        .pipe(Effect.asVoid, Effect.catch(() => events.publish(Info.make({ message: "no provenance.json — seeded by an older run; skipping" }))));
+});
 const program = Effect.gen(function* () {
     const input = yield* resolveFlowInput("Review the modernization increment against its spec pack");
     const coder = coderFromEnv(process.env);
@@ -167,15 +201,45 @@ const program = Effect.gen(function* () {
             const roster = [...allReviewers, ...pack.lenses].filter((lens) => lens.matches(changedFiles));
             const results = [];
             for (const lens of roster) {
-                const prompt = `${lens.systemPrompt}\n\n${reviewPrompt(`modernization increment vs committed specs\n\n${specText}`, diff)}`;
-                results.push(yield* structuredAndPublish(reviewService, context.events, prompt, ReviewResult, reviewJsonSchema, "reviewer"));
+                // Scope the diff to what this lens actually cares about; a lens
+                // matching everything still sees the whole diff, just capped
+                // like everything else below.
+                const scoped = changedFiles.filter((file) => lens.matches([file]));
+                const lensDiff = yield* context.git.diffVsBaseScoped(base, scoped);
+                results.push(yield* withShrink(`review[${lens.name}]`, (cap) => Effect.gen(function* () {
+                    const cappedSpecs = yield* capped(`specs[${lens.name}]`, specText, cap);
+                    const cappedDiff = yield* capped(`diff[${lens.name}]`, lensDiff, cap);
+                    const prompt = `${lens.systemPrompt}\n\n${reviewPrompt(`modernization increment vs committed specs\n\n${cappedSpecs}`, cappedDiff)}`;
+                    return yield* structuredAndPublish(reviewService, context.events, prompt, ReviewResult, reviewJsonSchema, "reviewer");
+                })));
             }
             return mergeReviewResults(results);
-        }));
-        const scored = yield* stage(context.events, "judge", judge(context.reasoning, complianceDimensions)
-            .evaluate(Sample.make({ response: diff, context: specText, query: input.prompt }))
-            .pipe(Effect.mapError(FlowLlmError.from)));
-        const outcome = yield* stage(context.events, "distill", structuredAndPublish(context.reasoning, context.events, distillPrompt(pack, findings, scored, diff), ReviewOutcome, reviewOutcomeJsonSchema));
+        }).pipe(Effect.provideService(FlowEvents, context.events)));
+        // Per-program spec-compliance judging: each judge call sees one
+        // program's spec and one program's slice of the diff, cached under
+        // the gate dir so an unchanged program re-judges nothing.
+        const judged = yield* stage(context.events, "judge", Effect.gen(function* () {
+            const programs = yield* specPrograms(target, pack.specsDir);
+            return yield* judgeAllPrograms({
+                pack,
+                judge: judge(context.reasoning, complianceDimensions),
+                dimensions: complianceDimensions,
+                git: context.git,
+                files,
+                gateDir: join(input.workDir, ModDir, "gate"),
+                base,
+                programs,
+                specFor: (program) => files
+                    .read(join(input.workDir, pack.specsDir, `${program}.md`))
+                    .pipe(Effect.map((text) => text ?? "")),
+                query: input.prompt,
+                fingerprint: reviewFingerprint
+            });
+        }).pipe(Effect.provideService(FlowEvents, context.events)));
+        const outcome = yield* stage(context.events, "distill", withShrink("distill", (cap) => Effect.gen(function* () {
+            const prompt = yield* capped("distill prompt", distillPrompt(pack, findings, judged), cap);
+            return yield* structuredAndPublish(context.reasoning, context.events, prompt, ReviewOutcome, reviewOutcomeJsonSchema);
+        })).pipe(Effect.provideService(FlowEvents, context.events)));
         yield* stage(context.events, "fix specs", Effect.gen(function* () {
             const documents = [
                 ...outcome.fixes.map((fix) => ["fix", fix]),
@@ -221,6 +285,9 @@ const program = Effect.gen(function* () {
                     "review and commit the pack change"
             }));
         }));
+        // Truncations recorded while reviewing/judging land in the evidence
+        // chain — before the commit stage, so the manifest change is included.
+        yield* recordTruncations(join(input.workDir, ModDir, "provenance.json"), context.events);
         yield* stage(context.events, "commit", context.git
             .commitAll(`modernize(${pack.name}): review — ${outcome.fixes.length} fix(es), ` +
             `${outcome.improvements.length} improvement(s)`)

package/flows/modernize-verify.js

@@ -21,10 +21,11 @@ import { join } from "node:path";
 import * as Effect from "effect/Effect";
 import * as Schema from "effect/Schema";
 import { CurrentEquivSchema, EquivVector, Observations, canonicaliseFieldMap, readEquivVectors, replayEquivVector, diffObservations, writeEquivVectors } from "@llm4ts/flow/Equiv";
+import { capped, renderTruncation, truncations, withShrink } from "@llm4ts/flow/Context";
 import { renderEquivReport, VectorVerdict } from "@llm4ts/flow/EquivReport";
 import { FlowAborted, PlanParseError } from "@llm4ts/flow/FlowError";
 import { structuredAndPublish } from "@llm4ts/flow/Flow";
-import { Info } from "@llm4ts/flow/FlowEvents";
+import { FlowEvents, Info } from "@llm4ts/flow/FlowEvents";
 import { makePlanStore } from "@llm4ts/flow/Persistence";
 import { stage } from "@llm4ts/flow/PlanExecution";
 import { Plan, Task } from "@llm4ts/flow/Plan";
@@ -192,6 +193,12 @@ const generatePrompt = (pack, program, spec, feature, rules) => [
     "Scenarios:",
     feature
 ].join("\n");
+/**
+ * One triage call per program (not one for the whole estate): mismatches
+ * already carry their program, so each prompt needs only that program's spec —
+ * never the whole estate's specs concatenated, which is what blows a real
+ * estate's context budget.
+ */
 const triagePrompt = (pack, failing, specText) => {
     const details = failing
         .map((verdict) => {
@@ -295,7 +302,13 @@ const program = Effect.gen(function* () {
                 const feature = featurePath === undefined
                     ? ""
                     : yield* target.read(featurePath).pipe(Effect.orElseSucceed(() => ""));
-                const generated = yield* structuredAndPublish(context.reasoning, context.events, generatePrompt(pack, name, spec, feature, universe), GeneratedVectors, generatedVectorsJsonSchema);
+                // `universe` is every rule in the estate's rules.txt, sent
+                // once per program, so this is the largest prompt the phase
+                // builds — budget it like the rest.
+                const generated = yield* withShrink(`vectors[${name}]`, (cap) => Effect.gen(function* () {
+                    const prompt = yield* capped(`vectors[${name}]`, generatePrompt(pack, name, spec, feature, universe), cap);
+                    return yield* structuredAndPublish(context.reasoning, context.events, prompt, GeneratedVectors, generatedVectorsJsonSchema);
+                })).pipe(Effect.provideService(FlowEvents, context.events));
                 if (generated.vectors.length === 0) {
                     return yield* FlowAborted.make({
                         message: `generator produced no vectors for ${name}`
@@ -370,13 +383,26 @@ const program = Effect.gen(function* () {
         yield* stage(context.events, "report", files.writeAtomic(join(input.workDir, ModDir, "equivalence.md"), renderEquivReport(verdicts, allRules)));
         if (failing.length > 0) {
             yield* stage(context.events, "triage", Effect.gen(function* () {
-                const specTexts = [
-                    (yield* files.read(join(input.workDir, pack.specsDir, "traceability.md"))) ?? ""
-                ];
-                for (const name of programs) {
-                    specTexts.push((yield* files.read(join(input.workDir, pack.specsDir, `${name}.md`))) ?? "");
+                // One triage call PER PROGRAM, each carrying only that program's
+                // spec — not the whole estate's specs in one prompt.
+                const byProgram = [
+                    ...new Set(failing.map((verdict) => verdict.vector.program))
+                ].sort();
+                const fixes = [];
+                for (const name of byProgram) {
+                    const programFailing = failing.filter((verdict) => verdict.vector.program === name);
+                    const spec = (yield* files.read(join(input.workDir, pack.specsDir, `${name}.md`))) ?? "";
+                    // Cap the WHOLE rendered prompt, not just the spec: the
+                    // mismatch detail block is unbounded too, and shrinking one
+                    // ingredient while another grows leaves the ladder failing
+                    // all three rungs and then advising a knob that cannot help.
+                    const outcome = yield* withShrink(`triage[${name}]`, (cap) => Effect.gen(function* () {
+                        const prompt = yield* capped(`triage[${name}]`, triagePrompt(pack, programFailing, spec), cap);
+                        return yield* structuredAndPublish(context.reasoning, context.events, prompt, VerifyOutcome, verifyOutcomeJsonSchema);
+                    })).pipe(Effect.provideService(FlowEvents, context.events));
+                    fixes.push(...outcome.fixes);
                 }
-                const outcome = yield* structuredAndPublish(context.reasoning, context.events, triagePrompt(pack, failing, specTexts.join("\n\n")), VerifyOutcome, verifyOutcomeJsonSchema);
+                const outcome = VerifyOutcome.make({ fixes });
                 for (const fix of outcome.fixes) {
                     yield* files.writeAtomic(join(input.workDir, pack.specsDir, "fixes", `fix-${slug(fix.title)}.md`), `# ${fix.title}\n\n${fix.spec}\n`);
                 }
@@ -413,11 +439,20 @@ const program = Effect.gen(function* () {
             const provenance = makeProvenanceStore(files);
             const hashes = yield* provenance.hashFiles(input.workDir, [`${ModDir}/equivalence.md`]);
             const report = Object.values(hashes)[0];
+            const recorded = yield* truncations;
             // Spreading into a plain object would not satisfy the schema's
-            // encoder — the manifest must stay a Provenance instance.
-            yield* provenance.extend(manifest, (current) => report === undefined
-                ? current
-                : Provenance.make({ ...current, equivalenceReport: report }));
+            // encoder — the manifest must stay a Provenance instance. The
+            // truncations recorded while generating and triaging land here so
+            // a verdict rendered on a partially-read spec pack says so in the
+            // evidence chain.
+            yield* provenance.extend(manifest, (current) => Provenance.make({
+                ...current,
+                ...(report === undefined ? {} : { equivalenceReport: report }),
+                contextTruncations: [
+                    ...current.contextTruncations,
+                    ...recorded.map(renderTruncation)
+                ]
+            }));
         }));
         const generated = verdicts.filter((verdict) => verdict.vector.tier === "generated").length;
         const captured = verdicts.filter((verdict) => verdict.vector.tier === "captured").length;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llm4ts/shell",
-  "version": "0.10.0",
+  "version": "0.10.1",
   "description": "Interactive shell and CLI for llm4ts: flow discovery, run-a-flow, and view",
   "license": "MIT",
   "type": "module",
@@ -49,10 +49,10 @@
   ],
   "dependencies": {
     "@effect/platform-node": "4.0.0-beta.102",
-    "@llm4ts/flow": "0.10.0",
-    "@llm4ts/core": "0.10.0",
-    "@llm4ts/runner": "0.10.0",
-    "@llm4ts/modernize": "0.10.0"
+    "@llm4ts/core": "0.10.1",
+    "@llm4ts/flow": "0.10.1",
+    "@llm4ts/modernize": "0.10.1",
+    "@llm4ts/runner": "0.10.1"
   },
   "peerDependencies": {
     "effect": "4.0.0-beta.102"