@llm4ts/shell 2.4.1 → 2.5.0

package/flows/lib/pack-fork.js

@@ -96,14 +96,22 @@ export const backendPasses = [
     }
 ];
 export const passesForTargetKind = (kind) => kind === "frontend" ? frontendPasses : backendPasses;
-export const conventionPassAsk = (pass, grounding) => [
+export const conventionPassAsk = (pass, grounding, refinement) => [
     pass.instructions,
     `Respond with a single markdown section starting with "## ${pass.heading}".`,
     "If a topic doesn't apply to this repository, say so explicitly rather than " +
         "inventing one.",
     ...(grounding === undefined || grounding.length === 0
         ? []
-        : [`Repository files for grounding:\n\n${grounding}`])
+        : [`Repository files for grounding:\n\n${grounding}`]),
+    ...(refinement === undefined
+        ? []
+        : [
+            "A previous run of this analysis produced the findings below, and a human " +
+                "reviewed them. Revise — do not simply repeat what you had before:\n\n" +
+                `Previous findings (all categories):\n\n${refinement.priorConventions}\n\n` +
+                `Human feedback on that previous run:\n\n${refinement.feedback}`
+        ])
 ].join("\n\n");
 export class ConventionSection extends Schema.Class("ConventionSection")({
     markdown: Schema.String
@@ -120,9 +128,122 @@ export const conventionSectionJsonSchema = {
     },
     required: ["markdown"]
 };
-export const techStackGroundingFiles = (kind) => kind === "frontend"
-    ? ["package.json", "tsconfig.json"]
-    : ["pom.xml", "build.gradle", "build.gradle.kts"];
+export class GroundingSelection extends Schema.Class("GroundingSelection")({
+    selections: Schema.Array(Schema.Struct({
+        category: Schema.String,
+        path: Schema.String,
+        reason: Schema.String
+    }))
+}) {
+}
+export const groundingSelectionJsonSchema = {
+    type: "object",
+    properties: {
+        selections: {
+            type: "array",
+            items: {
+                type: "object",
+                properties: {
+                    category: {
+                        type: "string",
+                        description: "Must exactly match one of the category headings given."
+                    },
+                    path: {
+                        type: "string",
+                        description: "Must be copied EXACTLY from the candidate file paths given — never " +
+                            "invented or guessed."
+                    },
+                    reason: {
+                        type: "string",
+                        description: "One line explaining why this file is relevant to the category."
+                    }
+                },
+                required: ["category", "path", "reason"]
+            }
+        }
+    },
+    required: ["selections"]
+};
+/** At most this many selected files get read (and fed as grounding) per category. */
+export const maxSelectedFilesPerCategory = 6;
+export const groundingSelectionAsk = (passes, candidatePaths, refinement) => [
+    "A coding agent needs to analyze this repository's real conventions across the " +
+        "categories below. From the list of real file paths given, select the files " +
+        "most likely to reveal each category's conventions — representative source " +
+        "and configuration files, not every file of a kind.",
+    ...passes.map((pass) => `## ${pass.heading}\n\n${pass.instructions}`),
+    `Select at most ${maxSelectedFilesPerCategory} files per category — quality over ` +
+        "quantity. Every path you return must be copied EXACTLY from the candidate " +
+        "list below; never invent or guess a path. A category with nothing relevant " +
+        "in this repository can have zero selections — say so via an empty selection " +
+        "list for it rather than forcing an irrelevant file in.",
+    `Candidate file paths (${candidatePaths.length}):\n\n${candidatePaths.join("\n")}`,
+    ...(refinement === undefined
+        ? []
+        : [
+            "A previous run selected files and produced the findings below; a human " +
+                "reviewed them and gave feedback. Reconsider the selection in light of " +
+                "it — the feedback may point at files that were missed entirely:\n\n" +
+                `Previous findings (all categories):\n\n${refinement.priorConventions}\n\n` +
+                `Human feedback on that previous run:\n\n${refinement.feedback}`
+        ])
+].join("\n\n");
+/**
+ * Drops any selection whose path wasn't in the real candidate list (never trust
+ * an LLM-fabricated path into a file read) and caps each category at
+ * `maxSelectedFilesPerCategory`, keeping the model's own priority order.
+ */
+export const validSelections = (selection, candidatePaths) => {
+    const candidates = new Set(candidatePaths);
+    const perCategoryCount = new Map();
+    const kept = [];
+    for (const item of selection.selections) {
+        if (!candidates.has(item.path)) {
+            continue;
+        }
+        const count = perCategoryCount.get(item.category) ?? 0;
+        if (count >= maxSelectedFilesPerCategory) {
+            continue;
+        }
+        perCategoryCount.set(item.category, count + 1);
+        kept.push(item);
+    }
+    return kept;
+};
+export const selectionsForCategory = (selections, category) => selections
+    .filter((selection) => selection.category === category)
+    .map((selection) => selection.path);
+export const provenanceMarkdown = (kind, selections, feedback) => {
+    const lines = [
+        "# Provenance",
+        "",
+        "Which real files this pack's conventions.md was grounded on, and why — trace a " +
+            "rule back to the file that justified it.",
+        ""
+    ];
+    if (feedback !== undefined && feedback.length > 0) {
+        lines.push("## Feedback applied this run", "", feedback, "");
+    }
+    for (const pass of passesForTargetKind(kind)) {
+        lines.push(`## ${pass.heading}`, "");
+        const forCategory = selections.filter((selection) => selection.category === pass.heading);
+        if (forCategory.length === 0) {
+            lines.push("No files selected for grounding — this category's findings rely on the " +
+                "model's general knowledge only, not a specific file in this repository.", "");
+        }
+        else {
+            for (const selection of forCategory) {
+                lines.push(`- \`${selection.path}\` — ${selection.reason}`);
+            }
+            lines.push("");
+        }
+    }
+    return lines.join("\n");
+};
+export const parseFeedback = (environment) => {
+    const raw = environment.LLM4TS_FEEDBACK?.trim();
+    return raw === undefined || raw.length === 0 ? undefined : raw;
+};
 export const readGroundingFiles = (workspace, paths) => Effect.gen(function* () {
     const sections = [];
     for (const path of paths) {

package/flows/modernize-implement.js

@@ -27,6 +27,7 @@ import { capped, renderTruncation, truncations, withShrink } from "@llm4ts/flow/
 import { FlowEvents } from "@llm4ts/flow/FlowEvents";
 import { judgeAllPrograms } from "@llm4ts/flow/ProgramJudge";
 import { Provenance, makeProvenanceStore } from "@llm4ts/flow/Provenance";
+import { ApprovedMarker, DraftApprovalMarker, requireApproval } from "@llm4ts/flow/Approval";
 import { loadPatternCards, taggedPatternIds } from "@llm4ts/flow/Patterns";
 import { ReviewIssue } from "@llm4ts/flow/Review";
 import { checkWall, wallBreachMessage } from "@llm4ts/flow/Wall";
@@ -160,6 +161,20 @@ const program = Effect.gen(function* () {
             flowDir: import.meta.dirname
         }));
         const pack = opened.pack;
+        // A pack whose own README.md carries the draft/approved marker (a
+        // fork from pack-fork, today — see docs/adr/0018-pack-fork.md) must
+        // be approved before this flow touches anything. A plain pack with
+        // no README.md, or one that never opted into the marker convention,
+        // is unaffected.
+        yield* stage(context.events, "approval", Effect.gen(function* () {
+            const readmeAbs = join(opened.workspace.root, opened.dir, "README.md");
+            const readmeContent = yield* files.read(readmeAbs);
+            if (readmeContent !== undefined &&
+                (readmeContent.includes(DraftApprovalMarker) ||
+                    readmeContent.includes(ApprovedMarker))) {
+                yield* requireApproval(files, readmeAbs);
+            }
+        }));
         yield* stage(context.events, "wall", Effect.gen(function* () {
             if (pack.sources === undefined) {
                 return yield* context.events.publish(Info.make({ message: "pack has no sources regex — wall check skipped" }));

package/flows/pack-fork.js

@@ -10,6 +10,12 @@
 //   LLM4TS_PACK=<source pack>       resolved as for any flow (default cobol-springboot)
 //   LLM4TS_TARGET_KIND=frontend|backend
 //   LLM4TS_FORK_AS=<new pack name>  lowercase kebab-case
+// Optional:
+//   LLM4TS_FEEDBACK=<free text>     revise an existing fork under the same
+//                                   LLM4TS_FORK_AS instead of starting over —
+//                                   the prior conventions.md and this feedback
+//                                   both feed every pass, including file
+//                                   selection, which can change too.
 //
 // The forked pack lands at
 // `<repo>/.llm4ts/kits/forked/packs/<LLM4TS_FORK_AS>/` — a dedicated
@@ -18,8 +24,9 @@
 // would hide its other packs from this project). `scaffold:` is dropped:
 // the whole point is that the target repository already exists.
 //
-// One-shot, not resumable: re-running overwrites the previous fork under
-// the same LLM4TS_FORK_AS name.
+// Not resumable: re-running clears and overwrites the previous fork under
+// the same LLM4TS_FORK_AS name (LLM4TS_FEEDBACK revises the CONTENT of that
+// overwrite, not the one-shot-per-run mechanics).
 import { basename, join, relative as relativePath, resolve as resolvePath } from "node:path";
 import { rmSync } from "node:fs";
 import * as Effect from "effect/Effect";
@@ -28,8 +35,8 @@ import { FlowEvents, Info } from "@llm4ts/flow/FlowEvents";
 import { capped, withShrink } from "@llm4ts/flow/Context";
 import { withDraftApproval } from "@llm4ts/flow/Approval";
 import { legacySourceWorkspaceLimits, workspaceLimitsFromEnv } from "@llm4ts/flow/Workspace";
-import { asReadOnly, coderFromEnv, makeNodeWorkspace, nodePlainFileStore, openPack, resolveFlowInput, runFlowMain, runNode, ScriptUsage, stage } from "@llm4ts/runner";
-import { ConventionSection, conventionPassAsk, conventionSectionJsonSchema, forkPackMarkdown, forkedReadme, parseForkAs, parseTargetKind, passesForTargetKind, readGroundingFiles, targetConventionsReviewer, techStackGroundingFiles } from "./lib/pack-fork.js";
+import { asReadOnly, asToolless, coderFromEnv, makeNodeWorkspace, nodePlainFileStore, openPack, resolveFlowInput, runFlowMain, runNode, ScriptUsage, stage } from "@llm4ts/runner";
+import { ConventionSection, conventionPassAsk, conventionSectionJsonSchema, forkPackMarkdown, forkedReadme, GroundingSelection, groundingSelectionAsk, groundingSelectionJsonSchema, parseFeedback, parseForkAs, parseTargetKind, passesForTargetKind, provenanceMarkdown, readGroundingFiles, selectionsForCategory, targetConventionsReviewer, validSelections } from "./lib/pack-fork.js";
 const forkPackFiles = Effect.fn("flows/pack-fork.forkPackFiles")(function* (source, destinationAbs, files) {
     // `source.dir` is "." for an absolute-path pack reference (Packs.ts's
     // `locatePack`), "packs/<name>" for a relative-directory or kit pack
@@ -73,6 +80,7 @@ const program = Effect.gen(function* () {
     const input = yield* resolveFlowInput("Analyze the target repository and fork the pack with its conventions.");
     const targetKind = yield* parseTargetKind(process.env);
     const forkAs = yield* parseForkAs(process.env);
+    const feedback = parseFeedback(process.env);
     const coder = asReadOnly(coderFromEnv(process.env));
     const files = nodePlainFileStore;
     yield* runNode({
@@ -80,7 +88,14 @@ const program = Effect.gen(function* () {
         workspace: input.workspace,
         userPrompt: input.prompt,
         coder,
-        reasoning: coder,
+        // Every convention pass runs as a one-shot structuredAndPublish()
+        // call with no tool-loop continuation — a model that reaches for a
+        // tool mid-turn (invited by "Explore the repository…" in three of
+        // the four passes) resolves with no text instead of an error
+        // ("empty response … no text to parse as structured output"). A
+        // read-only coder still offers a read tool over some connectors
+        // (pi in particular); asToolless offers none.
+        reasoning: asToolless(coderFromEnv(process.env)),
         environment: process.env
     }, (context) => Effect.gen(function* () {
         const repo = yield* makeNodeWorkspace(input.workDir, workspaceLimitsFromEnv(process.env, legacySourceWorkspaceLimits));
@@ -107,42 +122,64 @@ const program = Effect.gen(function* () {
                     "pack, or choose a different LLM4TS_FORK_AS."
             });
         }
-        const grounding = yield* stage(context.events, "grounding", readGroundingFiles(repo, techStackGroundingFiles(targetKind)));
+        // Captured BEFORE "clean" (below) can remove it — a --feedback re-run
+        // revises what a previous run found rather than starting from zero.
+        const priorConventions = feedback === undefined
+            ? undefined
+            : yield* repo
+                .read(join(destinationRel, "conventions.md"))
+                .pipe(Effect.catch(() => Effect.succeed(undefined)));
+        const refinement = priorConventions === undefined || feedback === undefined
+            ? undefined
+            : { priorConventions, feedback };
+        const candidatePaths = yield* stage(context.events, "discover", repo.discover("**"));
         const passes = passesForTargetKind(targetKind);
+        const selectionAsk = groundingSelectionAsk(passes, candidatePaths, refinement);
+        const selectionResult = yield* stage(context.events, "select grounding", withShrink("select grounding", (cap) => Effect.gen(function* () {
+            const prompt = yield* capped("select grounding", selectionAsk, cap);
+            return yield* structuredAndPublish(context.reasoning, context.events, prompt, GroundingSelection, groundingSelectionJsonSchema);
+        })).pipe(Effect.provideService(FlowEvents, context.events)));
+        const selections = validSelections(selectionResult, candidatePaths);
+        yield* context.events.publish(Info.make({ message: provenanceMarkdown(targetKind, selections, feedback) }));
         const sections = [];
-        for (const [index, pass] of passes.entries()) {
-            const askText = conventionPassAsk(pass, index === 0 ? grounding : undefined);
-            // Tech Stack & Dependencies (index 0) is the only pass carrying
-            // grounding file content — a real package.json/tsconfig.json can
-            // make it substantially larger than the other three, ungrounded
-            // passes. `capped` bounds every attempt's prompt size (guarding
-            // against a truncated, unparseable structured response); `withShrink`
-            // retries at a smaller budget on an actual provider overflow —
-            // the same pairing every other modernize-* flow already uses
-            // ahead of a structuredAndPublish call.
+        for (const pass of passes) {
+            const groundingPaths = selectionsForCategory(selections, pass.heading);
+            const grounding = yield* readGroundingFiles(repo, groundingPaths);
+            const askText = conventionPassAsk(pass, grounding, refinement);
+            // `capped` bounds every attempt's prompt size (guarding against a
+            // truncated, unparseable structured response); `withShrink` retries
+            // at a smaller budget on an actual provider overflow — the same
+            // pairing every other modernize-* flow already uses ahead of a
+            // structuredAndPublish call.
             const result = yield* stage(context.events, pass.heading, withShrink(pass.heading, (cap) => Effect.gen(function* () {
                 const prompt = yield* capped(pass.heading, askText, cap);
                 return yield* structuredAndPublish(context.reasoning, context.events, prompt, ConventionSection, conventionSectionJsonSchema);
             })).pipe(Effect.provideService(FlowEvents, context.events)));
+            yield* context.events.publish(Info.make({ message: result.markdown }));
             sections.push(result.markdown);
         }
         const conventionsMd = sections.join("\n\n");
+        const provenanceMd = provenanceMarkdown(targetKind, selections, feedback);
         yield* stage(context.events, "clean", Effect.sync(() => rmSync(destinationAbs, { recursive: true, force: true })));
         yield* stage(context.events, "fork", forkPackFiles(opened, destinationAbs, files));
         yield* stage(context.events, "fork patterns", forkKitPatterns(opened, destinationAbs, files));
         const sourcePackMd = yield* opened.workspace.read(`${opened.dir}/pack.md`);
         yield* files.writeAtomic(join(destinationAbs, "pack.md"), forkPackMarkdown(sourcePackMd, forkAs));
         yield* files.writeAtomic(join(destinationAbs, "conventions.md"), conventionsMd);
+        yield* files.writeAtomic(join(destinationAbs, "provenance.md"), provenanceMd);
         yield* files.writeAtomic(join(destinationAbs, "reviewers", "target-conventions.md"), targetConventionsReviewer);
         yield* files.writeAtomic(join(destinationAbs, "README.md"), withDraftApproval(forkedReadme(opened.pack.name, forkAs, targetKind, basename(input.workDir))));
         yield* stage(context.events, "commit", context.git
             .commitPaths(`pack-fork: fork '${opened.pack.name}' as '${forkAs}'`, [destinationRel])
             .pipe(Effect.asVoid));
         yield* context.events.publish(Info.make({
-            message: `forked pack ready — review ${destinationRel}/README.md and ` +
-                `${destinationRel}/conventions.md, set '- [x] Approved', then from ` +
+            message: `forked pack ready — review ${destinationRel}/README.md, ` +
+                `${destinationRel}/conventions.md, and ${destinationRel}/provenance.md ` +
+                "(which file justified which rule), set '- [x] Approved', then from " +
                 `inside ${input.workDir} run modernize-implement with ` +
-                `LLM4TS_PACK=forked/${forkAs}`
+                `LLM4TS_PACK=forked/${forkAs}. Not satisfied? Re-run this same command ` +
+                "with LLM4TS_FEEDBACK=<what to fix> to revise this fork instead of " +
+                "starting over."
         }));
     }));
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llm4ts/shell",
-  "version": "2.4.1",
+  "version": "2.5.0",
   "description": "Interactive shell and CLI for llm4ts: flow discovery, run-a-flow, and view",
   "license": "MIT",
   "type": "module",
@@ -52,9 +52,9 @@
   "dependencies": {
     "@effect/platform-node": "4.0.0-rc.115",
     "@effect/platform-node-shared": "4.0.0-rc.115",
-    "@llm4ts/core": "2.4.1",
-    "@llm4ts/runner": "2.4.1",
-    "@llm4ts/flow": "2.4.1"
+    "@llm4ts/core": "2.5.0",
+    "@llm4ts/flow": "2.5.0",
+    "@llm4ts/runner": "2.5.0"
   },
   "peerDependencies": {
     "effect": "4.0.0-rc.115"