@llm4ts/shell 2.17.0 → 2.18.0

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,35 @@ 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,
+    stories: epic.stories,
+    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";
@@ -187,6 +188,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

package/package.json

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