@llm4ts/shell 2.25.0 → 2.27.0

package/flows/epic-retro.js

@@ -0,0 +1,66 @@
+// Read what a failed epic-stories run left behind and propose the fixes the next run applies once approved.
+//
+//   llm4ts run epic-retro --repo ~/demo/portal                       # the one open epic, its latest run
+//   llm4ts run epic-retro --repo ~/demo/portal -- --epic <id>        # one epic
+//   llm4ts run epic-retro --repo ~/demo/portal -- --epic <id> --run run-1759…   # one run of it
+//
+// The evidence is the run's trace, its transcripts when it was started with
+// --transcript, the board, the report, and each story's plan, findings and
+// judge verdict under .llm4ts/epics/<epic-id>/. Code digests them (the digest
+// is written first, at retro/<runId>.digest.md); one read-only seat
+// (LLM4TS_REASONER, the judge seat) turns the digest into a proposal: per
+// story a diagnosis and exactly one fix — tasks appended to its plan, an
+// edit to its entry (which restarts it), a refine round, or nothing — plus
+// run advice and, where the library misbehaved, advice for llm4ts
+// (retro/<runId>-library.md). Code validates the proposal before writing
+// retro/<runId>.md, which ends in `- [ ] Approved`. Tick it and rerun
+// epic-stories: the approved fixes are applied before any story runs, and
+// the report is marked Applied. Nothing is applied unapproved; nothing in
+// the target's git is touched.
+import { join } from "node:path";
+import * as Console from "effect/Console";
+import * as Effect from "effect/Effect";
+import { ScriptUsage, asReadOnly, nodePlainFileStore, resolveFlowInput, runFlowMain, runNode } from "@llm4ts/runner";
+import { loadTranscript, nodeTranscriptFiles } from "@llm4ts/runner/Transcripts";
+import { parseEpicRetroArgs, resolveRetroTarget, runRetro } from "./lib/epic-retro.js";
+import { chooseEpic, defaultEpic, epicsDir, listEpics, reasonerFromEnvironment } from "./lib/epic-stories.js";
+const program = Effect.gen(function* () {
+    const flags = yield* parseEpicRetroArgs(process.argv.slice(2));
+    const given = yield* resolveFlowInput("", flags.rest);
+    const files = nodePlainFileStore;
+    const epics = yield* listEpics(files, given.workDir);
+    const choice = yield* chooseEpic({ text: "", epic: flags.epic, epics, defaultEpic });
+    if (choice._tag !== "Existing") {
+        return yield* ScriptUsage.make({
+            message: `no planned epic to look at in ${given.workDir}; run epic-stories first`
+        });
+    }
+    const epicDir = choice.epic.dir;
+    const stateDir = join(epicsDir(given.workDir), epicDir);
+    const target = yield* resolveRetroTarget(files, stateDir, flags.run);
+    const transcriptDir = join(given.workDir, ".llm4ts", "transcripts", target.run.runId);
+    const reasoning = asReadOnly(yield* reasonerFromEnvironment(process.env));
+    const outcome = yield* runNode({
+        workDir: given.workDir,
+        workspace: given.workspace,
+        userPrompt: `retro of run ${target.run.runId} of epic ${target.plan.epicId}`,
+        // No coder turn is ever taken: the read-only reasoning seat fills both.
+        coder: reasoning,
+        reasoning,
+        environment: process.env
+    }, (context) => runRetro({
+        files,
+        events: context.events,
+        seat: context.judge ?? context.reasoning,
+        workDir: given.workDir,
+        epicDir,
+        target,
+        transcript: (lane) => loadTranscript(nodeTranscriptFiles, transcriptDir, { lane }),
+        environment: process.env,
+        now: Date.now()
+    }));
+    if (outcome._tag === "NothingToDo") {
+        yield* Console.log(outcome.message);
+    }
+});
+runFlowMain(program);

package/flows/lib/epic-retro.js

@@ -0,0 +1,150 @@
+/**
+ * epic-retro: read what a failed epic-stories run left behind, explain each
+ * failed story, and propose the fix the next run applies once approved.
+ * The policy (digest, proposal schema, validation, report, apply) lives in
+ * `@llm4ts/flow/Retro`; this module finds the run and its files and drives
+ * one read-only seat.
+ */
+import { join } from "node:path";
+import * as Effect from "effect/Effect";
+import { readEpicRuns } from "@llm4ts/flow/EpicRuns";
+import { Info } from "@llm4ts/flow/FlowEvents";
+import { readTrace } from "@llm4ts/flow/Replay";
+import { RetroProposal, defaultRetroChars, loadEpicFiles, loadStoryFiles, renderRetroDigest, retroCandidates, retroPaths, retroPrompt, retroProposalJsonSchema, validateRetroProposal, writeRetro } from "@llm4ts/flow/Retro";
+import { makeStoryPlanStore } from "@llm4ts/flow/StoryPlan";
+import { structuredAndPublish } from "@llm4ts/flow/Usage";
+import { ScriptUsage } from "@llm4ts/runner/FlowArgs";
+import { roundDir } from "./epic-stories.js";
+export const epicRetroUsage = [
+    "usage: llm4ts run epic-retro --repo <target> [-- --epic <id>] [-- --run <runId>]",
+    "  --epic <id>   the epic (folder name or plan id); default: the one open epic",
+    "  --run <id>    the run to look at; default: the epic's latest run",
+    "Reads the run's trace, transcripts (when kept), board, report, story plans, findings and",
+    "verdicts; writes .llm4ts/epics/<epic>/retro/<runId>.md with proposed fixes behind an",
+    "approval line, and <runId>-library.md with advice for llm4ts when there is any."
+].join("\n");
+export const parseEpicRetroArgs = (argv) => Effect.gen(function* () {
+    let epic;
+    let run;
+    const rest = [];
+    for (let index = 0; index < argv.length; index += 1) {
+        const argument = argv[index] ?? "";
+        const valued = (name) => {
+            const value = argument.includes("=") ? argument.slice(name.length + 1) : argv[index + 1];
+            if (!argument.includes("=")) {
+                index += 1;
+            }
+            return value === undefined || value.trim().length === 0 || value.startsWith("--")
+                ? ScriptUsage.make({ message: `${name} needs a value\n${epicRetroUsage}` })
+                : Effect.succeed(value.trim());
+        };
+        if (argument === "--epic" || argument.startsWith("--epic=")) {
+            epic = yield* valued("--epic");
+        }
+        else if (argument === "--run" || argument.startsWith("--run=")) {
+            run = yield* valued("--run");
+        }
+        else {
+            rest.push(argument);
+        }
+    }
+    return { epic, run, rest };
+});
+export const resolveRetroTarget = Effect.fn("epic-retro.resolveTarget")(function* (files, epicStateDir, runId) {
+    const runs = yield* readEpicRuns(files, epicStateDir);
+    const run = runId === undefined ? runs.at(-1) : runs.find((candidate) => candidate.runId === runId);
+    if (run === undefined) {
+        return yield* ScriptUsage.make({
+            message: runId === undefined
+                ? `no run recorded in ${join(epicStateDir, "runs.jsonl")}; run epic-stories first`
+                : `no run '${runId}' in ${join(epicStateDir, "runs.jsonl")}; recorded: ${runs.map((r) => r.runId).join(", ") || "none"}`
+        });
+    }
+    const stateDir = run.round !== undefined && (run.action === "RunRound" || run.action === "PlanRound")
+        ? roundDir(epicStateDir, run.round)
+        : epicStateDir;
+    const plan = yield* makeStoryPlanStore(files).load(join(stateDir, "plan.md"));
+    if (plan === undefined) {
+        return yield* ScriptUsage.make({ message: `no plan at ${join(stateDir, "plan.md")}` });
+    }
+    return { run, stateDir, plan };
+});
+const retroChars = (environment) => {
+    const value = Number.parseInt(environment.LLM4TS_RETRO_CHARS ?? "", 10);
+    return Number.isInteger(value) && value > 0 ? value : defaultRetroChars;
+};
+/** The whole retro: evidence, one structured call, validation, the files. */
+export const runRetro = Effect.fn("epic-retro.run")(function* (deps) {
+    const { files, target } = deps;
+    const { stateDir, plan, run } = target;
+    const trace = yield* readTrace(files, run.tracePath);
+    const epic = yield* loadEpicFiles(files, stateDir);
+    const stories = yield* Effect.forEach(plan.stories, (story) => loadStoryFiles(files, stateDir, story));
+    const withoutTranscripts = {
+        runId: run.runId,
+        plan,
+        trace,
+        transcripts: undefined,
+        report: epic.report,
+        board: epic.board,
+        stories,
+        budget: retroChars(deps.environment)
+    };
+    const candidates = retroCandidates(withoutTranscripts);
+    if (candidates.length === 0) {
+        return {
+            _tag: "NothingToDo",
+            message: `run ${run.runId} of epic ${plan.epicId} left no failed, waiting or unfinished story; nothing to look at`
+        };
+    }
+    // Transcripts are read per candidate lane; the first answer says whether
+    // the run kept any at all.
+    const transcripts = new Map();
+    let kept = false;
+    for (const candidate of candidates) {
+        const entries = yield* deps.transcript(candidate.story.id);
+        if (entries !== undefined) {
+            kept = true;
+            transcripts.set(candidate.story.id, entries);
+        }
+    }
+    const inputs = { ...withoutTranscripts, transcripts: kept ? transcripts : undefined };
+    const digest = renderRetroDigest(inputs);
+    const paths = retroPaths(stateDir, run.runId);
+    // The digest is on disk before the seat is asked: a failed call still leaves it to read.
+    yield* files.writeAtomic(paths.digest, digest);
+    yield* deps.events.publish(Info.make({
+        message: `retro: ${candidates.length} stor${candidates.length === 1 ? "y" : "ies"} to look at in run ${run.runId}${kept ? "" : " (no transcripts; rerun with --transcript for more)"} — digest at ${paths.digest}`
+    }));
+    const withPlans = new Set(stories.filter((entry) => entry.plan !== undefined).map((entry) => entry.story.id));
+    const proposal = yield* structuredAndPublish(deps.seat, deps.events, retroPrompt(digest, [...withPlans]), RetroProposal, retroProposalJsonSchema, "retro");
+    const validated = validateRetroProposal(proposal, plan, withPlans);
+    const written = yield* writeRetro(files, stateDir, {
+        runId: run.runId,
+        plan,
+        validated,
+        workDir: deps.workDir,
+        epicDir: deps.epicDir,
+        digest,
+        at: deps.now
+    });
+    const applies = validated.proposal.stories.filter((s) => s.kind === "tasks" || s.kind === "story");
+    const summary = [
+        `retro of run ${run.runId}: ${validated.proposal.summary.trim()}`,
+        ...validated.proposal.stories.map((entry) => `  ${entry.id}: ${entry.kind === "tasks" ? `${entry.tasks?.length ?? 0} task(s)` : entry.kind === "story" ? "edit the story (restart)" : entry.kind === "refine" ? "needs a refine round" : "no change"}`),
+        ...(validated.dropped.length === 0
+            ? []
+            : [`  dropped ${validated.dropped.length} item(s) the plan cannot take; see the report`]),
+        `report: ${written.report}`,
+        ...(validated.proposal.libraryAdvice.length === 0
+            ? []
+            : [`advice for llm4ts: ${written.library}`]),
+        applies.length === 0
+            ? "nothing to apply; the report is for reading"
+            : `tick '- [x] Approved' in the report, then rerun: llm4ts run epic-stories --repo ${deps.workDir} -- --epic ${deps.epicDir}`
+    ];
+    for (const line of summary) {
+        yield* deps.events.publish(Info.make({ message: line }));
+    }
+    return { _tag: "Written", paths: written, summary };
+});

package/flows/lib/epic-stories.js

@@ -16,6 +16,7 @@ import { structuredAndPublish } from "@llm4ts/flow/Flow";
 import { EpicBriefInvalid, EpicBriefNotApproved, EpicCheckoutDirty, LandingFailed, RefineRefused } from "@llm4ts/flow/FlowError";
 import { Info } from "@llm4ts/flow/FlowEvents";
 import { nodePreflight } from "@llm4ts/flow/NodePreflight";
+import { applyApprovedRetros } from "@llm4ts/flow/Retro";
 import { statusPaths } from "@llm4ts/flow/GitTool";
 import { EpicLanded, EpicLandedVersion, landedPath } from "@llm4ts/flow/Landing";
 import { RefineProposal, assembleRound, countNotPlanned, earlierStories, refineProposalJsonSchema, renderNotPlanned, roundPrefix, roundRepair, runAction } from "@llm4ts/flow/RefineRound";
@@ -864,7 +865,10 @@ export const storyJudgeQuery = (story, plan, subject = "diff") => {
                 "the epic branch, shown as additions: judge whether the story is already in place —",
                 "everything it provides exists and is tested — not the diff's size or novelty."
             ]
-            : [])
+            : []),
+        "",
+        "The response holds the complete subject. Judge what it shows; do not explore the",
+        "repository, read other files, or run anything."
     ].join("\n");
 };
 /** The story-level judge over the branch diff, bounded by the character budget. */
@@ -1047,7 +1051,7 @@ const withOptionalModel = (config, model) => {
 const withExtraFlags = (config, flags) => Object.keys(flags).length === 0
     ? config
     : CliConnectorConfig.make({ ...config, flags: { ...config.flags, ...flags } });
-const defaultEpic = "Add the retail customer's current account (Conto) with balance and movements, and wire " +
+export const defaultEpic = "Add the retail customer's current account (Conto) with balance and movements, and wire " +
     "transfers (Bonifico) with beneficiary, review, SCA confirmation, and history.";
 export const runEpicStories = (options) => Effect.gen(function* () {
     const flags = yield* parseEpicArgs(process.argv.slice(2));
@@ -1164,14 +1168,31 @@ export const runEpicStories = (options) => Effect.gen(function* () {
             return;
         }
         const epicBranch = `epic/${plan.epicId}`;
+        // An approved retro of an earlier run (epic-retro) is applied before
+        // any story runs: tasks onto story plans, story edits onto the plan.
+        const retroState = action._tag === "RunRound"
+            ? (rounds.find((round) => round.round === action.round)?.stateDir ?? stateDir)
+            : stateDir;
+        const retroPlan = action._tag === "RunRound"
+            ? rounds.find((round) => round.round === action.round)?.plan
+            : action._tag === "RunPlan"
+                ? plan
+                : undefined;
+        const applied = retroPlan === undefined
+            ? undefined
+            : yield* applyApprovedRetros(files, retroState, retroPlan, events, Date.now());
         // The unit the executor works on: the epic's plan, or one refine round.
         // Same branch, seats, gates and judge; its own plan and state folder.
-        let unit = { plan, stateDir, label: `Epic: ${plan.epicId}` };
+        let unit = {
+            plan: action._tag === "RunPlan" && applied !== undefined ? applied.plan : plan,
+            stateDir,
+            label: `Epic: ${plan.epicId}`
+        };
         if (action._tag === "RunRound") {
             const open = rounds.find((round) => round.round === action.round);
             if (open?.plan !== undefined) {
                 unit = {
-                    plan: open.plan,
+                    plan: applied?.plan ?? open.plan,
                     stateDir: open.stateDir,
                     label: `Epic: ${plan.epicId} · round ${open.round}`
                 };
@@ -1351,5 +1372,25 @@ export const runEpicStories = (options) => Effect.gen(function* () {
         yield* events.publish(Info.make({
             message: `${unit.label.replace("Epic: ", "epic ")}: ${report.count("done")} done, ${report.count("failed")} failed, ${report.count("waiting")} waiting — report at ${join(unit.stateDir, "report.md")} (usage figures estimated)`
         }));
+        const hint = retroHint(report, input.workDir, epicId);
+        if (hint !== undefined) {
+            yield* events.publish(Info.make({ message: hint }));
+        }
     }));
 });
+/**
+ * The one command away from a red run: what to type to have the run's trace
+ * and transcripts read and fixes proposed. `undefined` when every story is done.
+ */
+export const retroHint = (report, workDir, epicDir) => {
+    const failed = report.count("failed");
+    const waiting = report.count("waiting");
+    if (failed === 0 && waiting === 0) {
+        return undefined;
+    }
+    const what = [
+        ...(failed === 0 ? [] : [`${failed} failed`]),
+        ...(waiting === 0 ? [] : [`${waiting} waiting`])
+    ].join(", ");
+    return `${what}: llm4ts run epic-retro --repo ${workDir} -- --epic ${epicDir} reads this run's trace and transcripts and proposes fixes for the next run`;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llm4ts/shell",
-  "version": "2.25.0",
+  "version": "2.27.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",
     "@effect/platform-node-shared": "4.0.0",
-    "@llm4ts/core": "2.25.0",
-    "@llm4ts/flow": "2.25.0",
-    "@llm4ts/runner": "2.25.0"
+    "@llm4ts/core": "2.27.0",
+    "@llm4ts/flow": "2.27.0",
+    "@llm4ts/runner": "2.27.0"
   },
   "peerDependencies": {
     "effect": "4.0.0"