@llm4ts/shell 2.17.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/epic-design.js

@@ -4,6 +4,7 @@
 //     llm4ts run epic-design --repo ~/work/portal "Current account: balance, movements, statements"
 //   llm4ts run epic-design --repo ~/work/portal -- --epic <id>    # revise, or validate once approved
 //   llm4ts run epic-design --repo ~/work/portal -- --list         # the repository's briefs
+//   llm4ts run epic-design --repo ~/work/portal -- --coverage     # the ledger across every brief
 //
 // Runs rooted at the TARGET repository. The legacy repository must hold
 // modernize-extract's pack (docs/modernization/); modernize-refine's
@@ -18,34 +19,57 @@
 // from the approved brief. Seat: LLM4TS_REASONER (read-only, default
 // claude). LLM4TS_PACK describes the target stack when the target is new.
 // LLM4TS_CONTEXT_BUDGET bounds the legacy evidence in the prompt.
+//
+// Briefs of one repository are read together. What the approved briefs of
+// other epics decided is inherited: a scenario they dropped or found in the
+// target is not restated, one they own is not proposed again, one they
+// deferred is offered; deciding otherwise is a `[check]` open point naming
+// the other epic. --coverage writes .llm4ts/epics/coverage.md, the ledger of
+// every scenario of the pack against every brief, without calling a model.
 import { access, readdir } from "node:fs/promises";
-import { join } from "node:path";
+import { join, resolve } from "node:path";
 import * as Console from "effect/Console";
 import * as Effect from "effect/Effect";
 import { budget, cap } from "@llm4ts/flow/Context";
 import { Info, ScriptUsage, asReadOnly, nodePlainFileStore, openPack, resolveFlowInput, runFlowMain, runNode, stage } from "@llm4ts/runner";
-import { designEpic, parseEpicDesignArgs, renderBriefList, renderOutcome, resolveDesignTarget } from "./lib/epic-design.js";
-import { epicDirs, listBriefs, reasonerFromEnvironment } from "./lib/epic-stories.js";
+import { coverageReport, designEpic, parseEpicDesignArgs, renderBriefList, renderOutcome, resolveDesignTarget } from "./lib/epic-design.js";
+import { epicDirs, listBriefs, listEpics, loadBriefs, reasonerFromEnvironment } from "./lib/epic-stories.js";
 import { ModDir } from "./lib/modernize-extract.js";
 const program = Effect.gen(function* () {
     const flags = yield* parseEpicDesignArgs(process.argv.slice(2));
     const given = yield* resolveFlowInput("", flags.rest);
     const files = nodePlainFileStore;
-    const briefs = yield* listBriefs(files, given.workDir, yield* epicDirs(given.workDir));
+    const dirs = yield* epicDirs(given.workDir);
+    const briefs = yield* listBriefs(files, given.workDir, dirs);
     if (flags.list) {
         yield* Console.log(renderBriefList(briefs));
         return;
     }
-    const legacyRepo = process.env.LLM4TS_LEGACY_REPO?.trim();
-    if (legacyRepo === undefined || legacyRepo.length === 0) {
+    const legacyGiven = process.env.LLM4TS_LEGACY_REPO?.trim();
+    if (legacyGiven === undefined || legacyGiven.length === 0) {
         return yield* ScriptUsage.make({
             message: "LLM4TS_LEGACY_REPO is not set: point it at the legacy repository holding docs/modernization/"
         });
     }
-    const target = yield* resolveDesignTarget({ text: given.prompt, epic: flags.epic, briefs });
+    // One spelling of the path, so every brief of this repository names the same legacy.
+    const legacyRepo = resolve(given.workspace, legacyGiven);
     const specNames = yield* Effect.tryPromise(() => readdir(join(legacyRepo, ModDir, "specs"))).pipe(Effect.map((names) => names
         .filter((name) => name.endsWith(".md") && name !== "README.md")
         .map((name) => name.slice(0, -".md".length))), Effect.catch(() => Effect.succeed([])));
+    if (flags.coverage) {
+        const report = yield* coverageReport({
+            files,
+            targetDir: given.workDir,
+            legacyRepo,
+            specNames,
+            dirs,
+            epics: yield* listEpics(files, given.workDir)
+        });
+        yield* Console.log(`${report.headline}\n${report.path}`);
+        return;
+    }
+    const target = yield* resolveDesignTarget({ text: given.prompt, epic: flags.epic, briefs });
+    const loaded = yield* loadBriefs(files, given.workDir, dirs);
     const reasoning = asReadOnly(yield* reasonerFromEnvironment(process.env));
     yield* runNode({
         workDir: given.workDir,
@@ -83,6 +107,8 @@ const program = Effect.gen(function* () {
             budget: budget(process.env),
             guidance,
             packNote,
+            others: loaded.briefs,
+            unreadable: loaded.unreadable,
             pathExists: (absolute) => Effect.tryPromise(() => access(absolute)).pipe(Effect.as(true), Effect.catch(() => Effect.succeed(false)))
         }));
         for (const line of renderOutcome(outcome, target.epicId)) {

package/flows/lib/epic-design.js

@@ -5,12 +5,13 @@
 import { join } from "node:path";
 import * as Effect from "effect/Effect";
 import { cap } from "@llm4ts/flow/Context";
+import { buildLedger, inheritedFrom, ledgerHeadline, renderLedger } from "@llm4ts/flow/CoverageLedger";
 import { parseDecisions, scenarioTitles } from "@llm4ts/flow/Decisions";
-import { assembleBrief, checkEpicBrief, diffBriefs, EpicBriefProposal, epicBriefProposalJsonSchema, loopAction, normalizeBrief, parseEpicBrief, ProgramSelection, programSelectionJsonSchema, providedPointers, renderBriefProblem, renderEpicBrief, unanswered } from "@llm4ts/flow/EpicBrief";
+import { assembleBrief, checkEpicBrief, diffBriefs, dispositionWords, EpicBriefProposal, epicBriefProposalJsonSchema, loopAction, normalizeBrief, parseEpicBrief, ProgramSelection, programSelectionJsonSchema, providedPointers, renderBriefProblem, renderEpicBrief, unanswered } from "@llm4ts/flow/EpicBrief";
 import { structuredAndPublish } from "@llm4ts/flow/Flow";
 import { EpicBriefInvalid, ExtractPackMissing, OpenPointsPending } from "@llm4ts/flow/FlowError";
 import { ScriptUsage } from "@llm4ts/runner";
-import { epicIdFor, epicsDir } from "./epic-stories.js";
+import { epicIdFor, epicsDir, loadBriefs } from "./epic-stories.js";
 import { ModDir } from "./modernize-extract.js";
 // ---- Arguments ----------------------------------------------------------------
 export const epicDesignUsage = [
@@ -18,10 +19,12 @@ export const epicDesignUsage = [
     "  LLM4TS_LEGACY_REPO=<path>  the legacy repository holding docs/modernization/ (required)",
     "  LLM4TS_PACK=<name|dir>     the pack describing the target stack (a new or empty target)",
     "  --epic <id>                revise or validate an existing brief, no text needed",
-    "  --list                     this repository's briefs and their status"
+    "  --list                     this repository's briefs and their status",
+    "  --coverage                 write the coverage ledger across every brief (no model call)"
 ].join("\n");
 export const parseEpicDesignArgs = (argv) => Effect.gen(function* () {
     let list = false;
+    let coverage = false;
     let epic;
     const rest = [];
     for (let index = 0; index < argv.length; index += 1) {
@@ -29,6 +32,9 @@ export const parseEpicDesignArgs = (argv) => Effect.gen(function* () {
         if (argument === "--list") {
             list = true;
         }
+        else if (argument === "--coverage") {
+            coverage = true;
+        }
         else if (argument === "--epic" || argument.startsWith("--epic=")) {
             const value = argument.includes("=") ? argument.slice("--epic=".length) : argv[index + 1];
             if (!argument.includes("="))
@@ -50,7 +56,7 @@ export const parseEpicDesignArgs = (argv) => Effect.gen(function* () {
             rest.push(argument);
         }
     }
-    return { list, epic, rest };
+    return { list, coverage, epic, rest };
 });
 // ---- Which brief ---------------------------------------------------------------
 export const renderBriefList = (briefs) => briefs.length === 0
@@ -156,6 +162,16 @@ export const selectPrompt = (request, index) => [
 ].join("\n");
 export const proposePrompt = (options) => {
     const perProgram = Math.max(2_000, Math.floor(options.budget / Math.max(1, options.programs.length)));
+    const selected = new Set(options.programs.map((program) => program.name));
+    const inherited = (options.inherited ?? []).filter((decision) => selected.has(decision.program));
+    const decided = inherited.filter((decision) => decision.disposition !== "deferred");
+    const available = inherited.filter((decision) => decision.disposition === "deferred");
+    const settled = new Set(decided.map((decision) => `${decision.program}\u0000${decision.scenario}`));
+    const open = options.pack.index.programs
+        .filter((program) => selected.has(program.name))
+        .flatMap((program) => program.scenarios
+        .filter((scenario) => !settled.has(`${program.name}\u0000${scenario}`))
+        .map((scenario) => `- ${program.name} › ${scenario}`));
     const evidence = options.programs.flatMap((program) => [
         `===== ${program.name} — spec =====`,
         cap(options.pack.specs[program.name] ?? "", perProgram).text,
@@ -206,11 +222,27 @@ export const proposePrompt = (options) => {
         options.guidance,
         ...(options.packNote === undefined ? [] : ["", "The target stack's pack:", options.packNote]),
         "",
+        ...(decided.length === 0
+            ? []
+            : [
+                "Already decided by other epics (do not restate; they are inherited):",
+                ...decided.map((decision) => `- ${decision.program} › ${decision.scenario} — ${decision.disposition === "dropped"
+                    ? `dropped by epic ${decision.epic}`
+                    : `${dispositionWords[decision.disposition]} in epic ${decision.epic}`}${decision.note.length === 0 ? "" : ` (${decision.note})`}`),
+                ""
+            ]),
+        ...(available.length === 0
+            ? []
+            : [
+                "Deferred by other epics, available to this one (claim them if they belong here):",
+                ...available.map((decision) => `- ${decision.program} › ${decision.scenario} — deferred by epic ${decision.epic}${decision.note.length === 0 ? "" : `: ${decision.note}`}`),
+                ""
+            ]),
         "Every scenario to give a disposition to (the complete list; the evidence below may be",
         "abridged, these titles are not):",
-        ...options.pack.index.programs
-            .filter((program) => options.programs.some((selected) => selected.name === program.name))
-            .flatMap((program) => program.scenarios.map((scenario) => `- ${program.name} › ${scenario}`)),
+        ...(open.length === 0
+            ? ["(none: every scenario of these programs is already decided by other epics)"]
+            : open),
         "",
         "Legacy evidence:",
         ...evidence
@@ -233,14 +265,53 @@ const verifiedPointers = (deps, brief) => Effect.gen(function* () {
     }
     return found;
 });
-const check = (deps, pack, brief) => Effect.map(verifiedPointers(deps, brief), (pointers) => checkEpicBrief(brief, { pack: pack.index, pointers }));
+const check = (deps, pack, brief, others) => Effect.map(verifiedPointers(deps, brief), (pointers) => checkEpicBrief(brief, { pack: pack.index, pointers, others, epicId: deps.epicId }));
+/** The ledger of the other epics' briefs, against this pack. */
+const ledgerOfOthers = (deps, pack) => buildLedger({
+    pack: pack.index,
+    briefs: (deps.others ?? []).filter((other) => other.epicId !== deps.epicId),
+    epics: [],
+    legacy: deps.legacyRepo
+});
+/** Other briefs that fed nothing into this run, said in words. */
+const unusedBriefs = (deps, others) => [
+    ...(deps.unreadable ?? [])
+        .filter((brief) => brief.dir !== deps.epicId)
+        .map((brief) => `brief '${brief.dir}' could not be read (${brief.reason}): nothing is inherited from it`),
+    ...others.skipped.map((epic) => `brief '${epic}' was designed against another legacy repository: nothing is inherited from it`)
+];
+/** Per epic, how many scenarios of the considered programs a brief inherits. */
+const inheritedSummary = (inherited, programs) => {
+    const considered = new Set(programs.map((program) => program.name));
+    const perEpic = new Map();
+    for (const decision of inherited) {
+        if (decision.disposition === "deferred" || !considered.has(decision.program))
+            continue;
+        const seen = perEpic.get(decision.epic) ?? new Set();
+        seen.add(`${decision.program}\u0000${decision.scenario}`);
+        perEpic.set(decision.epic, seen);
+    }
+    return [...perEpic].map(([epic, scenarios]) => ({ epic, scenarios: scenarios.size }));
+};
 export const designEpic = Effect.fn("epic-design.design")(function* (deps) {
     const path = briefPath(deps.targetDir, deps.epicId);
     const pack = yield* readPackIndex(deps);
     const onDisk = yield* deps.files.read(path);
     const current = onDisk === undefined ? undefined : yield* parseEpicBrief(onDisk, path);
     const action = loopAction(current);
-    const outcome = (changes, problems, openPoints) => ({ action, path, targetDir: deps.targetDir, changes, problems, openPoints });
+    const others = ledgerOfOthers(deps, pack);
+    const inherited = inheritedFrom(others);
+    const warnings = unusedBriefs(deps, others);
+    const outcome = (changes, problems, openPoints, considered = []) => ({
+        action,
+        path,
+        targetDir: deps.targetDir,
+        changes,
+        problems,
+        openPoints,
+        inherited: inheritedSummary(inherited, considered),
+        warnings
+    });
     if (current !== undefined && action === "halt") {
         return yield* OpenPointsPending.make({
             path,
@@ -251,7 +322,7 @@ export const designEpic = Effect.fn("epic-design.design")(function* (deps) {
         return outcome([], [], 0);
     }
     if (current !== undefined && action === "validate") {
-        const problems = yield* check(deps, pack, current);
+        const problems = yield* check(deps, pack, current, inherited);
         if (problems.length > 0) {
             return yield* EpicBriefInvalid.make({ path, violations: problems.map(renderBriefProblem) });
         }
@@ -270,6 +341,7 @@ export const designEpic = Effect.fn("epic-design.design")(function* (deps) {
         budget: deps.budget,
         guidance: deps.guidance,
         packNote: deps.packNote,
+        inherited,
         ...(current === undefined ? {} : { current }),
         ...(problems === undefined ? {} : { problems })
     }), EpicBriefProposal, epicBriefProposalJsonSchema);
@@ -290,11 +362,11 @@ export const designEpic = Effect.fn("epic-design.design")(function* (deps) {
         ? proposed
         : EpicBriefProposal.make({ ...proposed, openPoints: [noPrograms, ...proposed.openPoints] });
     let proposal = withNotice(yield* propose());
-    let problems = yield* check(deps, pack, assemble(proposal));
+    let problems = yield* check(deps, pack, assemble(proposal), inherited);
     if (problems.length > 0) {
         // One bounded fix round; what still fails is shown to the human, never hidden.
         proposal = withNotice(yield* propose(problems));
-        problems = yield* check(deps, pack, assemble(proposal));
+        problems = yield* check(deps, pack, assemble(proposal), inherited);
     }
     const next = assemble(proposal, problems);
     // What is written must read back as the same brief: a file that parses to
@@ -309,10 +381,10 @@ export const designEpic = Effect.fn("epic-design.design")(function* (deps) {
         });
     }
     yield* deps.files.writeAtomic(path, written);
-    return outcome(diffBriefs(current, next), problems, next.openPoints.length);
+    return outcome(diffBriefs(current, next), problems, next.openPoints.length, next.programs);
 });
 /** What the flow prints after a run. */
-export const renderOutcome = (outcome, epicId) => {
+const outcomeLines = (outcome, epicId) => {
     const approve = `set \`Status: approved\` in ${outcome.path} once it is right`;
     const plan = `llm4ts run epic-stories --repo ${outcome.targetDir} -- --epic ${epicId}`;
     switch (outcome.action) {
@@ -330,6 +402,13 @@ export const renderOutcome = (outcome, epicId) => {
             return [
                 `${outcome.action === "propose" ? "proposed" : "revised"} ${outcome.path}:`,
                 ...outcome.changes.map((change) => `  ${change}`),
+                ...(outcome.inherited.length === 0
+                    ? []
+                    : [
+                        `  inherited from ${outcome.inherited
+                            .map((entry) => `${entry.epic} (${entry.scenarios} scenario${entry.scenarios === 1 ? "" : "s"})`)
+                            .join(", ")}: not restated here; see \`epic-design --coverage\``
+                    ]),
                 ...(outcome.problems.length === 0
                     ? []
                     : [`  ${outcome.problems.length} check(s) still failing, raised as [check] open points`]),
@@ -339,3 +418,36 @@ export const renderOutcome = (outcome, epicId) => {
             ];
     }
 };
+/** What the flow prints after a run; briefs it could not use are always said. */
+export const renderOutcome = (outcome, epicId) => [
+    ...outcomeLines(outcome, epicId),
+    ...outcome.warnings.map((warning) => `warning: ${warning}`)
+];
+// ---- The coverage ledger ---------------------------------------------------------
+export const coveragePath = (targetDir) => join(epicsDir(targetDir), "coverage.md");
+/** What epic-stories recorded for each planned epic, as the ledger reads it. */
+export const epicProgressOf = (epics) => epics.map((epic) => ({
+    epicId: epic.dir,
+    planned: true,
+    // 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
+}));
+/**
+ * The ledger across every brief of the target, written as coverage.md. A
+ * read of the repository: no model is called and no brief is edited.
+ */
+export const coverageReport = Effect.fn("epic-design.coverage")(function* (options) {
+    const pack = yield* readPackIndex(options);
+    const loaded = yield* loadBriefs(options.files, options.targetDir, options.dirs);
+    const ledger = buildLedger({
+        pack: pack.index,
+        briefs: loaded.briefs,
+        epics: epicProgressOf(options.epics),
+        legacy: options.legacyRepo
+    });
+    const path = coveragePath(options.targetDir);
+    yield* options.files.writeAtomic(path, renderLedger(ledger, { legacy: options.legacyRepo, unreadable: loaded.unreadable }));
+    return { path, headline: ledgerHeadline(ledger), ledger, unreadable: loaded.unreadable };
+});

package/flows/lib/epic-stories.js

@@ -5,6 +5,7 @@ import { readdir } from "node:fs/promises";
 import { isAbsolute, join, normalize } from "node:path";
 import * as Duration from "effect/Duration";
 import * as Effect from "effect/Effect";
+import * as Result from "effect/Result";
 import * as Schema from "effect/Schema";
 import { Dimension, Sample } from "@llm4ts/core/eval/Eval";
 import { judge } from "@llm4ts/core/eval/Judge";
@@ -12,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";
@@ -41,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;",
@@ -63,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) {
@@ -79,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("=")) {
@@ -116,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* () {
@@ -136,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,
@@ -151,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;
@@ -165,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");
@@ -187,6 +274,29 @@ export const listBriefs = (files, workDir, dirs) => Effect.gen(function* () {
     }
     return briefs;
 });
+/**
+ * Every brief of the repository, parsed, for the coverage ledger. A folder
+ * without a brief is skipped; a brief that does not parse is reported with
+ * the first thing wrong in it, never dropped silently.
+ */
+export const loadBriefs = (files, workDir, dirs) => Effect.gen(function* () {
+    const briefs = [];
+    const unreadable = [];
+    for (const dir of dirs) {
+        const path = join(epicsDir(workDir), dir, "brief.md");
+        const text = yield* files.read(path);
+        if (text === undefined)
+            continue;
+        const parsed = yield* Effect.result(parseEpicBrief(text, path));
+        if (Result.isSuccess(parsed)) {
+            briefs.push({ epicId: dir, brief: parsed.success });
+        }
+        else {
+            unreadable.push({ dir, reason: parsed.failure.violations[0] ?? "does not parse" });
+        }
+    }
+    return { briefs, unreadable };
+});
 /**
  * What the story planner reads in place of the one-line epic: the approved
  * brief in the epic's folder. Undefined when the plan is already written (the
@@ -545,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]) => {
@@ -787,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"
@@ -845,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 !== ".") {
@@ -867,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")
@@ -901,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);
@@ -930,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
@@ -954,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.17.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.17.0",
-    "@llm4ts/flow": "2.17.0",
-    "@llm4ts/runner": "2.17.0"
+    "@llm4ts/core": "2.19.0",
+    "@llm4ts/flow": "2.19.0",
+    "@llm4ts/runner": "2.19.0"
   },
   "peerDependencies": {
     "effect": "4.0.0-rc.115"