@llm4ts/shell 2.18.0 → 2.19.0

package/dist/Cli.d.ts

@@ -41,7 +41,7 @@ export interface CostsFlags {
 }
 /** Turns the `costs` flags into program options; every rejection is a usage error. */
 export declare const costsOptionsFrom: (flags: CostsFlags, cwd?: string) => Effect.Effect<CostsOptions, ShellUsageError>;
-export declare const shellCommand: Command.Command<"llm4ts", {} | {}, {}, import("./FlowLaunch.ts").FlowLaunchError | import("@llm4ts/flow/FlowError.ts").DecisionsInvalid | ShellUsageError | ShellActionError | import("@llm4ts/flow/FlowError.ts").PersistenceError | import("@llm4ts/flow/FlowError.ts").PlanParseError | import("@llm4ts/flow/FlowError.ts").UnsupportedSchemaVersion | import("@llm4ts/flow/FlowError.ts").WorkspacePathError | import("@llm4ts/flow/FlowError.ts").WorkspaceLimitError | import("@llm4ts/flow/FlowError.ts").WorkspaceIoError | import("@llm4ts/flow/FlowError.ts").FlowAborted | import("@llm4ts/flow/FlowError.ts").ProcessError | import("@llm4ts/flow/FlowError.ts").FlowLlmError | import("@llm4ts/flow/FlowError.ts").FlowCapabilityDenied | import("@llm4ts/flow/FlowError.ts").ColumnNotFound | import("@llm4ts/flow/FlowError.ts").BudgetExceeded | import("@llm4ts/flow/FlowError.ts").StoryPlanInvalid | import("@llm4ts/flow/FlowError.ts").PerimeterViolation | import("@llm4ts/flow/FlowError.ts").MissingDependency | import("@llm4ts/flow/FlowError.ts").MergeConflict | import("@llm4ts/flow/FlowError.ts").EpicCheckoutDirty | import("@llm4ts/flow/FlowError.ts").RosterExhausted | import("@llm4ts/flow/FlowError.ts").RosterInvalid | import("@llm4ts/flow/FlowError.ts").EpicIncomplete | import("@llm4ts/flow/FlowError.ts").LandingFailed | import("@llm4ts/flow/FlowError.ts").StoryFailed | import("@llm4ts/flow/FlowError.ts").OpenPointsPending | import("@llm4ts/flow/FlowError.ts").ContractConflict | import("@llm4ts/flow/FlowError.ts").ExtractPackMissing | import("@llm4ts/flow/FlowError.ts").EpicBriefInvalid | import("@llm4ts/flow/FlowError.ts").EpicBriefNotApproved, import("effect/unstable/cli/Prompt").Environment>;
+export declare const shellCommand: Command.Command<"llm4ts", {} | {}, {}, import("./FlowLaunch.ts").FlowLaunchError | import("@llm4ts/flow/FlowError.ts").DecisionsInvalid | ShellUsageError | ShellActionError | import("@llm4ts/flow/FlowError.ts").PersistenceError | import("@llm4ts/flow/FlowError.ts").PlanParseError | import("@llm4ts/flow/FlowError.ts").UnsupportedSchemaVersion | import("@llm4ts/flow/FlowError.ts").WorkspacePathError | import("@llm4ts/flow/FlowError.ts").WorkspaceLimitError | import("@llm4ts/flow/FlowError.ts").WorkspaceIoError | import("@llm4ts/flow/FlowError.ts").FlowAborted | import("@llm4ts/flow/FlowError.ts").ProcessError | import("@llm4ts/flow/FlowError.ts").FlowLlmError | import("@llm4ts/flow/FlowError.ts").FlowCapabilityDenied | import("@llm4ts/flow/FlowError.ts").ColumnNotFound | import("@llm4ts/flow/FlowError.ts").BudgetExceeded | import("@llm4ts/flow/FlowError.ts").StoryPlanInvalid | import("@llm4ts/flow/FlowError.ts").PerimeterViolation | import("@llm4ts/flow/FlowError.ts").MissingDependency | import("@llm4ts/flow/FlowError.ts").MergeConflict | import("@llm4ts/flow/FlowError.ts").EpicCheckoutDirty | import("@llm4ts/flow/FlowError.ts").RosterExhausted | import("@llm4ts/flow/FlowError.ts").RosterInvalid | import("@llm4ts/flow/FlowError.ts").EpicIncomplete | import("@llm4ts/flow/FlowError.ts").LandingFailed | import("@llm4ts/flow/FlowError.ts").StoryFailed | import("@llm4ts/flow/FlowError.ts").OpenPointsPending | import("@llm4ts/flow/FlowError.ts").ContractConflict | import("@llm4ts/flow/FlowError.ts").ExtractPackMissing | import("@llm4ts/flow/FlowError.ts").EpicBriefInvalid | import("@llm4ts/flow/FlowError.ts").EpicBriefNotApproved | import("@llm4ts/flow/FlowError.ts").RefineRefused, import("effect/unstable/cli/Prompt").Environment>;
 export declare const runShellCommand: (argv: ReadonlyArray<string>) => Effect.Effect<void, unknown, Command.Environment>;
 export {};
 //# sourceMappingURL=Cli.d.ts.map

package/dist/Cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Cli.d.ts","sourceRoot":"","sources":["../src/Cli.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAA;AAC9C,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAEvC,OAAO,KAAK,OAAO,MAAM,6BAA6B,CAAA;AAGtD,OAAO,EAIL,KAAK,YAAY,EAClB,MAAM,sBAAsB,CAAA;AAU7B,OAAO,EAA8C,KAAK,aAAa,EAAE,MAAM,qBAAqB,CAAA;AACpG,OAAO,EAGL,KAAK,cAAc,EACnB,KAAK,aAAa,EACnB,MAAM,kBAAkB,CAAA;;;;AAMzB,qBAAa,eAAgB,SAAQ,oBAEnC;CAAG;;;;AAEL,qBAAa,gBAAiB,SAAQ,qBAEpC;CAAG;AAEL,eAAO,MAAM,eAAe,QAAO,MAA6D,CAAA;AAEhG,eAAO,MAAM,cAAc,GAAI,UAAU;IACvC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,WAAW,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAA;CACpE,KAAG,aAaH,CAAA;AAQD,eAAO,MAAM,aAAa,GACxB,MAAM,aAAa,CAAC,aAAa,CAAC,EAClC,UAAU;IAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAA;CAAE,KACpC,MA+BF,CAAA;AAED,eAAO,MAAM,cAAc,GACzB,OAAO,aAAa,CAAC,cAAc,CAAC,EACpC,UAAU;IAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAA;CAAE,KACpC,MAyBF,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,WAAW,iGAwBtB,CAAA;AA0NF,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC,MAAM,CAAC,CAAA;IACpC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;IACrC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;IAClC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;CAC3C;AAED,sFAAsF;AACtF,eAAO,MAAM,gBAAgB,GAC3B,OAAO,UAAU,EACjB,MAAK,MAAsB,KAC1B,MAAM,CAAC,MAAM,CAAC,YAAY,EAAE,eAAe,CA2B1C,CAAA;AA4GJ,eAAO,MAAM,YAAY,sqDAwBxB,CAAA;AAED,eAAO,MAAM,eAAe,GAC1B,MAAM,aAAa,CAAC,MAAM,CAAC,KAC1B,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,WAAW,CACe,CAAA"}
+{"version":3,"file":"Cli.d.ts","sourceRoot":"","sources":["../src/Cli.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAA;AAC9C,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAEvC,OAAO,KAAK,OAAO,MAAM,6BAA6B,CAAA;AAGtD,OAAO,EAIL,KAAK,YAAY,EAClB,MAAM,sBAAsB,CAAA;AAU7B,OAAO,EAA8C,KAAK,aAAa,EAAE,MAAM,qBAAqB,CAAA;AACpG,OAAO,EAGL,KAAK,cAAc,EACnB,KAAK,aAAa,EACnB,MAAM,kBAAkB,CAAA;;;;AAMzB,qBAAa,eAAgB,SAAQ,oBAEnC;CAAG;;;;AAEL,qBAAa,gBAAiB,SAAQ,qBAEpC;CAAG;AAEL,eAAO,MAAM,eAAe,QAAO,MAA6D,CAAA;AAEhG,eAAO,MAAM,cAAc,GAAI,UAAU;IACvC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,WAAW,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAA;CACpE,KAAG,aAaH,CAAA;AAQD,eAAO,MAAM,aAAa,GACxB,MAAM,aAAa,CAAC,aAAa,CAAC,EAClC,UAAU;IAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAA;CAAE,KACpC,MA+BF,CAAA;AAED,eAAO,MAAM,cAAc,GACzB,OAAO,aAAa,CAAC,cAAc,CAAC,EACpC,UAAU;IAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAA;CAAE,KACpC,MAyBF,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,WAAW,iGAwBtB,CAAA;AA0NF,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC,MAAM,CAAC,CAAA;IACpC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;IACrC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;IAClC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;CAC3C;AAED,sFAAsF;AACtF,eAAO,MAAM,gBAAgB,GAC3B,OAAO,UAAU,EACjB,MAAK,MAAsB,KAC1B,MAAM,CAAC,MAAM,CAAC,YAAY,EAAE,eAAe,CA2B1C,CAAA;AA4GJ,eAAO,MAAM,YAAY,0tDAwBxB,CAAA;AAED,eAAO,MAAM,eAAe,GAC1B,MAAM,aAAa,CAAC,MAAM,CAAC,KAC1B,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,WAAW,CACe,CAAA"}

package/flows/lib/epic-design.js

@@ -429,8 +429,9 @@ export const coveragePath = (targetDir) => join(epicsDir(targetDir), "coverage.m
 export const epicProgressOf = (epics) => epics.map((epic) => ({
     epicId: epic.dir,
     planned: true,
-    stories: epic.stories,
-    merged: epic.merged,
+    // A refine round's stories are the epic's work too (ADR 0021).
+    stories: epic.rounds.reduce((sum, round) => sum + (round.plan?.stories.length ?? 0), epic.stories),
+    merged: epic.rounds.reduce((sum, round) => sum + round.merged, epic.merged),
     landed: epic.landed !== undefined
 }));
 /**

package/flows/lib/epic-stories.js

@@ -13,14 +13,16 @@ import { TokenUsage } from "@llm4ts/core/Models";
 import { cap } from "@llm4ts/flow/Context";
 import { parseEpicBrief, renderEpicBrief, unanswered } from "@llm4ts/flow/EpicBrief";
 import { structuredAndPublish } from "@llm4ts/flow/Flow";
-import { EpicBriefInvalid, EpicBriefNotApproved } from "@llm4ts/flow/FlowError";
+import { EpicBriefInvalid, EpicBriefNotApproved, EpicCheckoutDirty, LandingFailed, RefineRefused } from "@llm4ts/flow/FlowError";
 import { Info } from "@llm4ts/flow/FlowEvents";
+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";
 import { loadVersioned } from "@llm4ts/flow/Persistence";
 import { BlockedVerdict, StoryState, StoryStateVersion } from "@llm4ts/flow/Stories";
 import { stableHash } from "@llm4ts/flow/Plan";
 import { ReviewIssue } from "@llm4ts/flow/Review";
-import { StoryPlan, dependenciesOf, makeStoryPlanStore, pathsNamedIn } from "@llm4ts/flow/StoryPlan";
+import { StoryPlan, dependenciesOf, makeStoryPlanStore, parseStoryPlan, pathsNamedIn } from "@llm4ts/flow/StoryPlan";
 import * as Console from "effect/Console";
 import { CliConnectorConfig } from "@llm4ts/core/ConnectorConfig";
 import { budget } from "@llm4ts/flow/Context";
@@ -42,6 +44,9 @@ export const epicUsage = [
     "  --list              list this repository's epics (id, stories merged, landed) and stop",
     "  --epic <id>         work on an existing epic by id, no text needed. Without text or",
     "                      --epic, the one epic not landed yet is chosen; several stop the run",
+    "  --refine            the text is feedback on the finished epic: plan a round of follow-up",
+    "                      stories from it and run them on the epic branch (before landing).",
+    "                      A plain rerun finishes an open round; --plan-only stops after planning",
     "  --concurrency <n>   stories implemented at once (default 3)",
     "  --fail-fast         stop the epic at the first failed story",
     "Seats: LLM4TS_REASONER (claude|gemini|…, default claude) splits, reviews, judges;",
@@ -64,6 +69,7 @@ export const parseEpicArgs = (argv) => Effect.gen(function* () {
     let land;
     let keepWorktrees = false;
     let list = false;
+    let refine = false;
     let epic;
     const rest = [];
     for (let index = 0; index < argv.length; index += 1) {
@@ -80,6 +86,9 @@ export const parseEpicArgs = (argv) => Effect.gen(function* () {
         else if (argument === "--list") {
             list = true;
         }
+        else if (argument === "--refine") {
+            refine = true;
+        }
         else if (argument === "--epic" || argument.startsWith("--epic=")) {
             const value = argument.includes("=") ? argument.slice("--epic=".length) : argv[index + 1];
             if (!argument.includes("=")) {
@@ -117,8 +126,79 @@ export const parseEpicArgs = (argv) => Effect.gen(function* () {
             rest.push(argument);
         }
     }
-    return { planOnly, failFast, concurrency, land, keepWorktrees, list, epic, rest };
+    return { planOnly, failFast, concurrency, land, keepWorktrees, list, epic, refine, rest };
+});
+export const roundDir = (stateDir, round) => join(stateDir, "rounds", String(round));
+const mergedStories = (files, stateDir, plan) => Effect.gen(function* () {
+    let merged = 0;
+    for (const story of plan.stories) {
+        const state = yield* loadVersioned(files, join(stateDir, "stories", `${story.id}.json`), StoryStateVersion, StoryState).pipe(Effect.catch(() => Effect.succeed(undefined)));
+        if (state?.status === "merged") {
+            merged += 1;
+        }
+    }
+    return merged;
+});
+/**
+ * The epic's rounds, numbered from 1 without gaps: the first `rounds/<n>`
+ * without a plan ends the list. A plan that does not parse, or breaks the
+ * plan's rules, is a round that cannot be used, never one silently skipped.
+ */
+export const loadRounds = (files, stateDir) => Effect.gen(function* () {
+    const rounds = [];
+    for (let round = 1;; round += 1) {
+        const dir = roundDir(stateDir, round);
+        const path = join(dir, "plan.md");
+        const text = yield* files.read(path);
+        if (text === undefined) {
+            // A plan missing while the next round has one is a hole, not the end.
+            if ((yield* files.read(join(roundDir(stateDir, round + 1), "plan.md"))) === undefined) {
+                return rounds;
+            }
+            rounds.push({
+                round,
+                stateDir: dir,
+                plan: undefined,
+                merged: 0,
+                notPlanned: 0,
+                unreadable: `${path} is missing while round ${round + 1} exists`
+            });
+            continue;
+        }
+        const notPlanned = countNotPlanned((yield* files.read(join(dir, "not-planned.md"))) ?? "");
+        const parsed = yield* Effect.result(parseStoryPlan(text).pipe(Effect.flatMap(validateStoryPlan)));
+        if (Result.isSuccess(parsed)) {
+            rounds.push({
+                round,
+                stateDir: dir,
+                plan: parsed.success,
+                merged: yield* mergedStories(files, dir, parsed.success),
+                notPlanned,
+                unreadable: undefined
+            });
+        }
+        else {
+            rounds.push({
+                round,
+                stateDir: dir,
+                plan: undefined,
+                merged: 0,
+                notPlanned,
+                unreadable: `${path}: ${parsed.failure.message}`
+            });
+        }
+    }
 });
+/** The rounds as the run decision reads them. */
+export const roundProgress = (rounds) => rounds.map((round) => ({
+    round: round.round,
+    stories: round.plan?.stories.length ?? 0,
+    merged: round.merged,
+    ...(round.unreadable === undefined ? {} : { unreadable: round.unreadable })
+}));
+const renderRound = (round) => round.plan === undefined
+    ? `round ${round.round}: unreadable plan`
+    : `round ${round.round}: ${round.merged}/${round.plan.stories.length} merged${round.notPlanned === 0 ? "" : `, ${round.notPlanned} not planned`}`;
 export const epicsDir = (workDir) => join(workDir, ".llm4ts", "epics");
 /** Every epic with a plan in this repository, oldest folder name first. */
 export const listEpics = (files, workDir) => Effect.gen(function* () {
@@ -137,13 +217,7 @@ export const listEpics = (files, workDir) => Effect.gen(function* () {
         if (plan === undefined) {
             continue;
         }
-        let merged = 0;
-        for (const story of plan.stories) {
-            const state = yield* loadVersioned(files, join(stateDir, "stories", `${story.id}.json`), StoryStateVersion, StoryState).pipe(Effect.catch(() => Effect.succeed(undefined)));
-            if (state?.status === "merged") {
-                merged += 1;
-            }
-        }
+        const merged = yield* mergedStories(files, stateDir, plan);
         const landed = yield* loadVersioned(files, landedPath(stateDir), EpicLandedVersion, EpicLanded).pipe(Effect.catch(() => Effect.succeed(undefined)));
         summaries.push({
             dir: entry.name,
@@ -152,7 +226,19 @@ export const listEpics = (files, workDir) => Effect.gen(function* () {
             epic: plan.epic,
             stories: plan.stories.length,
             merged,
-            landed: landed?.target
+            landed: landed?.target,
+            // Rounds that cannot be read are reported, never dropped: an epic
+            // must not look free of rounds when it lands.
+            rounds: yield* loadRounds(files, stateDir).pipe(Effect.catch((error) => Effect.succeed([
+                {
+                    round: 1,
+                    stateDir: roundDir(stateDir, 1),
+                    plan: undefined,
+                    merged: 0,
+                    notPlanned: 0,
+                    unreadable: `${join(stateDir, "rounds")}: ${error.message}`
+                }
+            ])))
         });
     }
     return summaries;
@@ -166,7 +252,7 @@ export const renderEpicList = (epics) => epics.length === 0
                 ? epic.merged === epic.stories
                     ? "finished, not landed"
                     : "in progress"
-                : `landed on ${epic.landed}`}  (--epic ${epic.epicId})`,
+                : `landed on ${epic.landed}`}${epic.rounds.map((round) => ` · ${renderRound(round)}`).join("")}  (--epic ${epic.epicId})`,
             `  "${epic.epic.length > 110 ? `${epic.epic.slice(0, 109)}…` : epic.epic}"`
         ])
     ].join("\n");
@@ -569,6 +655,128 @@ export const generateStoryPlan = (reasoning, events, epic, epicId, guidance,
 brief) => structuredAndPublish(reasoning, events, `${storyPlanInstructions(epicId, guidance)}\n\nEpic:\n${brief ?? epic}`, StoryPlan, storyPlanJsonSchema).pipe(
 // The id and the epic text are ours, whatever the model echoed back.
 Effect.map((plan) => StoryPlan.make({ ...plan, epicId, epic })));
+/** The round planner's constraints: the story planner's, for feedback on finished work. */
+export const refinePlanInstructions = (inputs) => [
+    "You are the orchestrator of a parallel implementation. The epic below is finished: every",
+    "story is merged into the epic branch, which is checked out in front of you. A person tried",
+    "it and gave the feedback at the end of this message. Turn the feedback into follow-up",
+    "stories that independent coding agents will implement AT THE SAME TIME, each in its own git",
+    "worktree, each confined to the paths it owns. Read the code before you answer.",
+    "",
+    "Rules (violations are rejected mechanically):",
+    "- Every story has a kebab-case id, a title, a description precise enough to implement alone,",
+    "  `dependsOn`, `owned` (repo-relative paths it may create or change), `sharedReadOnly`",
+    "  (prefixes it may read but never change), and `provides`.",
+    "- One story per feedback item, or per group of items that change the same files. The",
+    "  description quotes the feedback items it answers, word for word.",
+    "- `owned` lists the files the story will change, existing files included: name them from the",
+    "  code. The earlier stories below are merged, so their paths are free to claim.",
+    "- `owned` sets are pairwise DISJOINT within this round: items that need the same file go",
+    "  into ONE story.",
+    "- `dependsOn` names stories of THIS round only, and only when one needs the other's result.",
+    "- `provides` says what the person who gave the feedback will see changed.",
+    "- Tests that cover the changed behaviour are updated in the same story, and the test files",
+    "  are in its `owned`.",
+    "- Shared surfaces (the kit, the theme, house rules) are owned only by a story the feedback",
+    "  asks to change them.",
+    "- An item that is unclear, contradicts another item, or cannot be tied to a file is NOT",
+    "  guessed: it goes to `notPlanned` with the question whose answer would make it plannable.",
+    `- Ids are short; each is prefixed \`${roundPrefix(inputs.round)}\` for you (round ${inputs.round} of epic "${inputs.epicId}").`,
+    "",
+    "Respond only with JSON:",
+    '{"stories":[{"id":"...","title":"...","description":"...","dependsOn":[],"owned":[],',
+    '"sharedReadOnly":[],"provides":[]}],"notPlanned":[{"item":"...","reason":"..."}]}',
+    "",
+    "Earlier stories (merged: what was built, and where):",
+    ...(inputs.earlier.length === 0
+        ? ["(none)"]
+        : inputs.earlier.map((story) => `- ${story.id}: ${story.title} — owns: ${story.owned.join(", ")} — provides: ${story.provides.join("; ")}`)),
+    ...(inputs.brief === undefined ? [] : ["", "The epic's approved brief:", inputs.brief]),
+    ...(inputs.openItems === undefined
+        ? []
+        : [
+            "",
+            "Left unplanned in the previous round (the new feedback may answer these):",
+            inputs.openItems
+        ]),
+    "",
+    "Target repository guidance (house rules and layout — the vocabulary to use):",
+    inputs.guidance
+].join("\n");
+export const generateRefineProposal = (reasoning, events, inputs) => structuredAndPublish(reasoning, events, `${refinePlanInstructions(inputs)}\n\nFeedback:\n${inputs.feedback}`, RefineProposal, refineProposalJsonSchema);
+const bulletLines = (markdown) => markdown
+    .split("\n")
+    .filter((line) => line.startsWith("- "))
+    .join("\n");
+/**
+ * Plans a round from feedback and writes it: `feedback.md`, `plan.md`, and
+ * `not-planned.md` when something was left out. Nothing is written unless the
+ * plan is valid, and no round is created when no story could be planned.
+ */
+export const planRound = Effect.fn("flows/epic-stories.planRound")(function* (deps) {
+    const open = deps.round > 1
+        ? bulletLines((yield* deps.files.read(join(roundDir(deps.stateDir, deps.round - 1), "not-planned.md"))) ?? "")
+        : "";
+    const earlier = earlierStories(deps.plans);
+    const proposal = yield* generateRefineProposal(deps.reasoning, deps.events, {
+        epicId: deps.epicId,
+        round: deps.round,
+        guidance: deps.guidance,
+        earlier,
+        feedback: deps.feedback,
+        ...(deps.brief === undefined ? {} : { brief: deps.brief }),
+        ...(open.length === 0 ? {} : { openItems: open })
+    });
+    if (proposal.stories.length === 0) {
+        return { plan: undefined, notPlanned: proposal.notPlanned };
+    }
+    const plan = yield* validateStoryPlan(assembleRound({
+        epicId: deps.epicId,
+        round: deps.round,
+        feedback: deps.feedback,
+        proposal,
+        earlier: earlier.map((story) => story.id)
+    }));
+    const dir = roundDir(deps.stateDir, deps.round);
+    yield* deps.files.writeAtomic(join(dir, "feedback.md"), `${deps.feedback}\n`);
+    // Always written: a reused folder must not keep an older round's list.
+    yield* deps.files.writeAtomic(join(dir, "not-planned.md"), renderNotPlanned(deps.round, proposal.notPlanned));
+    // The plan goes last: it is what makes the folder a round.
+    yield* makeStoryPlanStore(deps.files).save(join(dir, "plan.md"), plan);
+    return { plan, notPlanned: proposal.notPlanned };
+});
+/**
+ * The epic a `--refine` run works on. The text on the command line is
+ * feedback, so it never names or creates an epic: only one with a story plan
+ * can take a round.
+ */
+export const refineEpic = (choice) => choice._tag === "Existing"
+    ? Effect.succeed(choice.epic)
+    : choice._tag === "Brief"
+        ? Effect.fail(RefineRefused.make({
+            epicId: choice.dir,
+            reason: "it has no story plan yet: run the epic first"
+        }))
+        : Effect.fail(ScriptUsage.make({
+            message: `--refine needs a finished epic, and this repository has none to pick: run an epic first, or name one with --epic <id>\n${epicUsage}`
+        }));
+/**
+ * The planned epic a choice lands on: the one picked, or the one whose folder
+ * the given text derives (an epic rerun by its text is still that epic).
+ */
+export const epicOnDisk = (choice, epics) => choice._tag === "Existing"
+    ? choice.epic
+    : choice._tag === "Text"
+        ? epics.find((epic) => epic.dir === epicIdFor(choice.prompt))
+        : undefined;
+/** The rounds as the landing takes them; one whose plan cannot be read stops it. */
+export const landRounds = (epicId, target, rounds) => Effect.forEach(rounds, (round) => round.plan === undefined
+    ? Effect.fail(LandingFailed.make({
+        epicBranch: `epic/${epicId}`,
+        target,
+        reason: `round ${round.round}'s plan cannot be read (${round.unreadable ?? ""}); ${roundRepair(round.round)}`
+    }))
+    : Effect.succeed({ plan: round.plan, stateDir: round.stateDir }));
 // ---- Usage ---------------------------------------------------------------------
 /** Sums two meters into one per-story estimate. */
 export const combineTotals = (first, second) => Effect.map(Effect.all([first, second]), ([left, right]) => {
@@ -811,13 +1019,45 @@ export const runEpicStories = (options) => Effect.gen(function* () {
         yield* Console.log(renderEpicList(epics));
         return;
     }
+    // With `--refine` the text is feedback on a finished epic, never an epic's text.
+    const feedback = flags.refine ? given.prompt.trim() : "";
     const choice = yield* chooseEpic({
-        text: given.prompt,
+        text: flags.refine ? "" : given.prompt,
         epic: flags.epic,
         epics,
         briefs: yield* listBriefs(files, given.workDir, yield* epicDirs(given.workDir)),
         defaultEpic
     });
+    if (flags.refine) {
+        yield* refineEpic(choice);
+    }
+    // What this run does (ADR 0021): the plan's stories, the open refine round,
+    // a new round, or the landing. Refusals come before any seat is resolved.
+    const existing = epicOnDisk(choice, epics);
+    const rounds = existing?.rounds ?? [];
+    const action = existing !== undefined
+        ? runAction({
+            planned: true,
+            stories: existing.stories,
+            merged: existing.merged,
+            landed: existing.landed,
+            rounds: roundProgress(rounds),
+            refine: flags.refine,
+            feedback,
+            land: flags.land !== undefined
+        })
+        : flags.land !== undefined
+            ? { _tag: "Land" }
+            : { _tag: "RunPlan" };
+    if (action._tag === "Refused") {
+        return yield* RefineRefused.make({
+            epicId: existing?.epicId ?? "",
+            reason: action.reason
+        });
+    }
+    if (action._tag === "Usage") {
+        return yield* ScriptUsage.make({ message: `${action.message}\n${epicUsage}` });
+    }
     const input = {
         ...given,
         prompt: choice._tag === "Existing"
@@ -869,9 +1109,72 @@ export const runEpicStories = (options) => Effect.gen(function* () {
         yield* events.publish(Info.make({
             message: `story plan: ${plan.stories.length} stories at ${planPath} (edit and rerun to re-plan)`
         }));
-        if (flags.planOnly) {
+        if (flags.planOnly && action._tag !== "PlanRound") {
             return;
         }
+        const epicBranch = `epic/${plan.epicId}`;
+        // 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}` };
+        if (action._tag === "RunRound") {
+            const open = rounds.find((round) => round.round === action.round);
+            if (open?.plan !== undefined) {
+                unit = {
+                    plan: open.plan,
+                    stateDir: open.stateDir,
+                    label: `Epic: ${plan.epicId} · round ${open.round}`
+                };
+                yield* events.publish(Info.make({
+                    message: `refine round ${open.round}: ${open.merged}/${open.plan.stories.length} stories merged; finishing it`
+                }));
+            }
+        }
+        if (action._tag === "PlanRound") {
+            // The planner reads the code as the person tried it: the epic
+            // branch, with nothing uncommitted carried over onto it.
+            const stray = statusPaths(yield* context.git.status);
+            if (stray.length > 0) {
+                return yield* EpicCheckoutDirty.make({ checkout: input.workDir, paths: stray });
+            }
+            yield* stage(events, "epic branch", context.git.checkoutOrCreate(epicBranch));
+            const roundBrief = yield* files.read(join(stateDir, "brief.md"));
+            const planned = yield* stage(events, `refine round ${action.round} plan`, planRound({
+                files,
+                reasoning: reasoningMeter.service,
+                events,
+                stateDir,
+                epicId: plan.epicId,
+                round: action.round,
+                feedback,
+                guidance,
+                plans: [
+                    plan,
+                    ...rounds.flatMap((round) => (round.plan === undefined ? [] : [round.plan]))
+                ],
+                ...(roundBrief === undefined ? {} : { brief: roundBrief })
+            }));
+            for (const left of planned.notPlanned) {
+                yield* events.publish(Info.make({ message: `not planned: ${left.item} — ${left.reason}` }));
+            }
+            if (planned.plan === undefined) {
+                yield* events.publish(Info.make({
+                    message: `refine round ${action.round}: no feedback item could be planned; answer the questions above and run --refine again`
+                }));
+                return;
+            }
+            const dir = roundDir(stateDir, action.round);
+            yield* events.publish(Info.make({
+                message: `refine round ${action.round}: ${planned.plan.stories.length} follow-up stories at ${join(dir, "plan.md")} (edit and rerun to re-plan)${planned.notPlanned.length === 0 ? "" : `; ${planned.notPlanned.length} item(s) not planned, listed in ${join(dir, "not-planned.md")}`}`
+            }));
+            if (flags.planOnly) {
+                return;
+            }
+            unit = {
+                plan: planned.plan,
+                stateDir: dir,
+                label: `Epic: ${plan.epicId} · round ${action.round}`
+            };
+        }
         // Setup and gates run where the application is, in every checkout.
         const appDir = yield* appDirFor(input.workDir, process.env);
         if (appDir !== ".") {
@@ -891,6 +1194,7 @@ export const runEpicStories = (options) => Effect.gen(function* () {
                 files,
                 stateDir,
                 target: flags.land,
+                rounds: yield* landRounds(plan.epicId, flags.land, rounds),
                 keepWorktrees: flags.keepWorktrees,
                 gates: inAppDir(appDir, gatesIn(nodeProcessExecutor, events, commands)),
                 system: ["House rules of the target repository (CONTRIBUTING.md):", guidance].join("\n")
@@ -925,11 +1229,12 @@ export const runEpicStories = (options) => Effect.gen(function* () {
         const setupCommand = worktreeSetupCommand(process.env);
         const healthUrl = serverHealthUrl(localServer, process.env);
         const report = yield* implementStoriesFlow({ ...context, reasoning: reasoningMeter.service }, {
-            plan,
+            plan: unit.plan,
             files,
-            stateDir,
+            stateDir: unit.stateDir,
+            epicBranch,
             worktreeRoot: worktreeRootFor(input.workDir, plan.epicId, process.env),
-            board: makeLocalBoardSync(files, stateDir, `Epic: ${plan.epicId}`),
+            board: makeLocalBoardSync(files, unit.stateDir, unit.label),
             contextFor: (workDir, contextOptions) => Effect.gen(function* () {
                 const rebound = yield* contextFor(workDir, contextOptions);
                 const coderMeter = yield* makeEstimatedUsageMeter(rebound.coder, estimateOptions);
@@ -954,14 +1259,14 @@ export const runEpicStories = (options) => Effect.gen(function* () {
             // With a roster, the judge and the verifier are leased per story,
             // away from the executor coding it (ADR 0019).
             judge: options.storyJudge({
-                plan,
+                plan: unit.plan,
                 budget: contextBudget,
                 reasoning: reasoningMeter.service,
                 events,
                 files,
                 houseRules: guidance
             }),
-            verifyBlocked: (story, need, workDir, seats) => verifyBlockedOn(seats.context.roster?.forRole("verifier") ?? reasoningMeter.service, events, files, plan)(story, need, workDir),
+            verifyBlocked: (story, need, workDir, seats) => verifyBlockedOn(seats.context.roster?.forRole("verifier") ?? reasoningMeter.service, events, files, unit.plan)(story, need, workDir),
             // A roster waits for its own executors (the story's next lease
             // does); without one, poll the single coder's engine.
             awaitRecovery: context.roster === undefined
@@ -978,7 +1283,7 @@ export const runEpicStories = (options) => Effect.gen(function* () {
             failFast: flags.failFast
         });
         yield* events.publish(Info.make({
-            message: `epic ${report.epicId}: ${report.count("done")} done, ${report.count("failed")} failed, ${report.count("waiting")} waiting — report at ${join(stateDir, "report.md")} (usage figures estimated)`
+            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)`
         }));
     }));
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llm4ts/shell",
-  "version": "2.18.0",
+  "version": "2.19.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.18.0",
-    "@llm4ts/runner": "2.18.0",
-    "@llm4ts/flow": "2.18.0"
+    "@llm4ts/core": "2.19.0",
+    "@llm4ts/flow": "2.19.0",
+    "@llm4ts/runner": "2.19.0"
   },
   "peerDependencies": {
     "effect": "4.0.0-rc.115"