@llm4ts/shell 2.48.0 → 2.49.0

package/flows/epic-draft.js

@@ -0,0 +1,17 @@
+// Working code first, tests and validation later: the planner cuts stories without tests, coders build under one review lens and the build gates, and what was deferred is written as debt that --harden plans under the full bar (ADR 0043).
+//
+//   llm4ts run epic-draft --repo ~/demo/portal "Add the current account and wire transfers"
+//   llm4ts run epic-draft --repo ~/demo/portal -- --plan-only "…"   # write the draft plan and stop
+//   llm4ts run epic-draft --repo ~/demo/portal -- --harden          # write the tests owed, close findings
+//   llm4ts run epic-draft --repo ~/demo/portal -- --land            # land, hardened or not
+//
+// Same seats, flags and environment as epic-stories, plus --with-tests to
+// keep the test gate while drafting. After a draft run, debt.md beside the
+// plan lists each merged story's tests owed, its deferred findings and the
+// test gate's failures on the epic checkout; a settled --harden round moves
+// what it paid to debt.paid.md.
+import { runFlowMain } from "@llm4ts/runner";
+import { epicDraftOptions, parseDraftFlags } from "./lib/epic-draft.js";
+import { runEpicStories } from "./lib/epic-stories.js";
+const flags = parseDraftFlags(process.argv.slice(2));
+runFlowMain(runEpicStories({ ...epicDraftOptions(flags), argv: flags.argv }));

package/flows/lib/epic-draft.js

@@ -0,0 +1,171 @@
+// epic-draft (ADR 0043): the epic-stories spine with tests and validation
+// deferred, not dropped. A draft run plans and builds without tests, under
+// one review lens and the build gates; what it deferred is written to
+// debt.md, and `--harden` plans that debt as a round under the full bar.
+import { join } from "node:path";
+import * as Effect from "effect/Effect";
+import { Info } from "@llm4ts/flow/FlowEvents";
+import { failingLinesOf } from "@llm4ts/flow/GateTriage";
+import { countNotPlanned } from "@llm4ts/flow/RefineRound";
+import { correctnessReviewer } from "@llm4ts/flow/Review";
+import { deferredPath, EpicReport } from "@llm4ts/flow/Stories";
+import { StoryPlan } from "@llm4ts/flow/StoryPlan";
+import { structuredAndPublish } from "@llm4ts/flow/Usage";
+import { loadRounds, rubricStoryJudge, storyPlanInstructions, storyPlanJsonSchema, unitStateDirs, withoutTestGate } from "./epic-stories.js";
+export const parseDraftFlags = (argv) => {
+    const harden = argv.includes("--harden");
+    const withTests = argv.includes("--with-tests");
+    const rest = argv.filter((arg) => arg !== "--harden" && arg !== "--with-tests");
+    return { harden, withTests, argv: harden ? ["--refine", ...rest] : rest };
+};
+// ---- The draft plan ---------------------------------------------------------
+/** The epic-stories planner's rules, then the draft cut on top. */
+export const draftPlanInstructions = (epicId, guidance, orientation) => [
+    storyPlanInstructions(epicId, guidance, orientation),
+    "",
+    "Draft cut (this run is epic-draft: working code first, tests and validation in a later",
+    "hardening round). These rules override the ones above where they differ:",
+    "- No story writes or owns test files now; leave them out of `owned`.",
+    "- `acceptance` still lists two to six outcomes per story: each one is a test the hardening",
+    "  round will write, so make each checkable by an automated test.",
+    "- Prefer fewer, thinner stories: the shortest path to working code.",
+    "- Leave `testsDeferred` out: every outcome's test is owed and planned later."
+].join("\n");
+/** The draft planner: the epic-stories plan under the draft cut. */
+export const generateDraftPlan = (inputs) => structuredAndPublish(inputs.reasoning, inputs.events, `${draftPlanInstructions(inputs.epicId, inputs.guidance, inputs.orientation)}\n\nEpic:\n${inputs.brief ?? inputs.epic}`, StoryPlan, storyPlanJsonSchema).pipe(
+// The id and the epic text are ours, whatever the model echoed back.
+Effect.map((plan) => StoryPlan.make({ ...plan, epicId: inputs.epicId, epic: inputs.epic })));
+// ---- The debt ---------------------------------------------------------------
+/** What a draft unit deferred: the tests owed, the findings, the skipped test gate. */
+export const debtPath = (stateDir) => join(stateDir, "debt.md");
+/** Debt a settled hardening round consumed. */
+export const paidPath = (stateDir) => join(stateDir, "debt.paid.md");
+const merged = (plan, report) => plan.stories.filter((story) => report.stories.some((outcome) => outcome.id === story.id && outcome.status === "done"));
+export const renderDebt = (plan, report, deferred, testFailures) => [
+    `# Debt — ${plan.epicId}`,
+    "",
+    ...merged(plan, report).flatMap((story) => [
+        `## ${story.id}`,
+        "",
+        ...story.acceptance.map((outcome) => `- [ ] test: ${outcome}`),
+        ""
+    ]),
+    ...(deferred === undefined ? [] : ["## Deferred findings", "", deferred, ""]),
+    ...(testFailures === undefined
+        ? []
+        : ["## Test gate on the epic checkout (skipped while drafting)", "", testFailures, ""])
+].join("\n");
+const counted = (count, one, many) => `${count} ${count === 1 ? one : many}`;
+/**
+ * After a draft unit: `debt.md` with the merged stories' owed tests, their
+ * deferred findings and, when the draft skipped it, one run of the test gate
+ * on the epic checkout — gates with a memory would otherwise call those
+ * failures inherited and never charge a hardening story with them.
+ */
+export const draftAfterUnit = (withTests) => (unit, report) => Effect.gen(function* () {
+    // A story whose debt a hardening round already paid owes nothing again.
+    const paid = new Set(((yield* unit.files.read(paidPath(unit.stateDir))) ?? "")
+        .split("\n")
+        .flatMap((line) => (line.startsWith("## ") ? [line.slice(3).trim()] : [])));
+    const stories = merged(unit.plan, report).filter((story) => !paid.has(story.id));
+    const findings = [];
+    for (const story of stories) {
+        const text = yield* unit.files.read(deferredPath(unit.stateDir, story.id));
+        findings.push(...(text ?? "").split("\n").filter((line) => line.startsWith("- [")));
+    }
+    const gate = withTests || unit.testGate === undefined
+        ? undefined
+        : yield* unit.testGate(unit.workDir, unit.events);
+    // The failing lines alone: a test run's whole output would crowd the planner's prompt.
+    const failing = gate === undefined || gate.issues.length === 0
+        ? []
+        : failingLinesOf(gate, [unit.workDir]).map((line) => `- ${line}`);
+    const testFailures = gate === undefined || gate.issues.length === 0
+        ? undefined
+        : (failing.length > 0 ? failing : gate.issues.map((issue) => `- ${issue.title}`)).join("\n");
+    const owed = stories.reduce((sum, story) => sum + story.acceptance.length, 0);
+    if (owed === 0 && findings.length === 0 && testFailures === undefined) {
+        return;
+    }
+    const path = debtPath(unit.stateDir);
+    yield* unit.files.writeAtomic(path, renderDebt(unit.plan, EpicReport.make({
+        ...report,
+        stories: report.stories.filter((outcome) => !paid.has(outcome.id))
+    }), findings.length === 0 ? undefined : findings.join("\n"), testFailures));
+    yield* unit.events.publish(Info.make({
+        message: `debt: ${counted(owed, "test owed", "tests owed")}, ${findings.length === 0
+            ? "no deferred findings"
+            : counted(findings.length, "deferred finding", "deferred findings")}${testFailures === undefined ? "" : ", test gate red"} — run epic-draft --harden (${path})`
+    }));
+});
+// ---- Hardening --------------------------------------------------------------
+/** The open debt lists of an epic, by state folder; empty ones are paid. */
+const openDebt = (files, epicStateDir) => Effect.gen(function* () {
+    const open = [];
+    for (const dir of yield* unitStateDirs(files, epicStateDir)) {
+        const text = (yield* files.read(debtPath(dir)))?.trim() ?? "";
+        if (text.length > 0) {
+            open.push({ dir, text });
+        }
+    }
+    return open;
+});
+/** `--harden`: the text given, then every open debt list, as the round to plan. */
+export const hardenFeedback = (epicStateDir, text, files) => Effect.gen(function* () {
+    // An open round finishes before another is planned: with text, runAction would refuse it.
+    const rounds = yield* loadRounds(files, epicStateDir).pipe(Effect.catch(() => Effect.succeed([])));
+    const last = rounds.at(-1);
+    if (last?.plan !== undefined && last.merged < last.plan.stories.length) {
+        return text;
+    }
+    const open = yield* openDebt(files, epicStateDir);
+    return open.length === 0
+        ? text
+        : [
+            "Pay this epic's draft debt: write the tests owed as deterministic tests in the house",
+            "style, make the test gate green, and close the findings that still apply.",
+            ...(text.length === 0 ? [] : ["", text]),
+            "",
+            ...open.flatMap((debt) => [debt.text, ""])
+        ].join("\n");
+});
+/** After a hardening round that settled (nothing failed or waiting), its debt is paid. */
+export const hardenAfterUnit = (unit, report) => Effect.gen(function* () {
+    if (report.count("failed") > 0 || report.count("waiting") > 0) {
+        return;
+    }
+    for (const debt of yield* openDebt(unit.files, unit.epicStateDir)) {
+        const paid = (yield* unit.files.read(paidPath(debt.dir))) ?? "";
+        yield* unit.files.writeAtomic(paidPath(debt.dir), `${paid}${debt.text}\n`);
+        yield* unit.files.writeAtomic(debtPath(debt.dir), "");
+    }
+    // What the round's planner left out is listed, never carried (ADR 0031 decision 6).
+    const notPlannedPath = join(unit.stateDir, "not-planned.md");
+    const left = countNotPlanned((yield* unit.files.read(notPlannedPath)) ?? "");
+    if (left > 0) {
+        yield* unit.events.publish(Info.make({
+            message: `harden: ${counted(left, "debt item was", "debt items were")} not planned (${notPlannedPath}); pass them to --harden as text if they still matter`
+        }));
+    }
+});
+// ---- The policy -------------------------------------------------------------
+/**
+ * The epic-stories spine with epic-draft's policy (ADR 0043). A draft defers
+ * tests and validation; `--harden` runs epic-stories' own bar over the debt.
+ */
+export const epicDraftOptions = (flags) => flags.harden
+    ? {
+        storyJudge: rubricStoryJudge,
+        refineFeedback: hardenFeedback,
+        afterUnit: hardenAfterUnit
+    }
+    : {
+        generatePlan: generateDraftPlan,
+        stories: () => ({
+            reviewers: [correctnessReviewer],
+            maxRounds: 1,
+            deferNonBlocking: true
+        }),
+        ...(flags.withTests ? {} : { selectGates: withoutTestGate }),
+        afterUnit: draftAfterUnit(flags.withTests)
+    };

package/flows/lib/epic-mvp.js

@@ -21,7 +21,7 @@ import { Story, StoryPlan } from "@llm4ts/flow/StoryPlan";
 import { commandFor, criterionTags, evidenceSourceFromEnvironment, parseJUnit, statusFromReport, testPaths } from "@llm4ts/flow/TestEvidence";
 import { structuredAndPublish } from "@llm4ts/flow/Usage";
 import { nodeProcessExecutor, ScriptUsage } from "@llm4ts/runner";
-import { storyJsonSchema, storyPlanInstructions } from "./epic-stories.js";
+import { storyJsonSchema, storyPlanInstructions, unitStateDirs } from "./epic-stories.js";
 export const parseMvpFlags = (argv) => {
     const iterate = argv.includes("--iterate");
     const review = argv.includes("--review");
@@ -381,20 +381,9 @@ export const mvpAfterUnit = (source) => (unit, report) => Effect.gen(function* (
 const Verdict = Schema.fromJsonString(MvpVerdict);
 const encodeVerdict = Schema.encodeSync(Verdict);
 const decodeVerdict = Schema.decodeUnknownOption(Verdict);
-/** The state folders whose verdicts the landing reads: the epic's and each round's. */
-const verdictDirs = (files, epicStateDir) => Effect.gen(function* () {
-    const dirs = [epicStateDir];
-    for (let round = 1;; round += 1) {
-        const dir = join(epicStateDir, "rounds", String(round));
-        if ((yield* files.read(join(dir, "plan.md"))) === undefined) {
-            return dirs;
-        }
-        dirs.push(dir);
-    }
-});
 /** `--land` only once the MVP is reached, in the epic and in every round. */
 export const mvpBeforeLand = (epicStateDir, files) => Effect.gen(function* () {
-    for (const dir of yield* verdictDirs(files, epicStateDir)) {
+    for (const dir of yield* unitStateDirs(files, epicStateDir)) {
         const text = yield* files.read(verdictPath(dir));
         const verdict = text === undefined ? undefined : decodeVerdict(text);
         if (verdict === undefined || Option.isNone(verdict)) {
@@ -415,7 +404,7 @@ export const mvpBeforeLand = (epicStateDir, files) => Effect.gen(function* () {
 /** `--iterate`: the text given, then every parked list of the epic as what to plan. */
 export const mvpIterateFeedback = (epicStateDir, text, files) => Effect.gen(function* () {
     const parked = [];
-    for (const dir of yield* verdictDirs(files, epicStateDir)) {
+    for (const dir of yield* unitStateDirs(files, epicStateDir)) {
         const list = yield* files.read(parkedPath(dir));
         if (list !== undefined) {
             parked.push(list);

package/flows/lib/epic-stories.js

@@ -1284,6 +1284,16 @@ export const stallOptions = (environment) => {
 export const gateRunOptions = (environment) => ({ timeout: Duration.seconds(gateTimeoutSeconds(environment)) });
 /** The gate command that runs the tests, for the one flaky rerun; undefined when none does. */
 export const testGateCommand = (commands) => commands.find((command) => command.some((part, index) => index > 0 && /(?:^|[^a-z])(?:test|vitest|jest)/iu.test(part)));
+/** The gates less the test command (ADR 0043): a draft defers its tests, not its build. */
+export const withoutTestGate = (commands) => {
+    const test = testGateCommand(commands);
+    return test === undefined
+        ? { commands, note: "test gate: none recognised, every gate kept" }
+        : {
+            commands: commands.filter((command) => command !== test),
+            note: `test gate deferred: ${test.join(" ")}`
+        };
+};
 /**
  * How gate output reaches the coder: a capped tail, and the log's path. The
  * epic-stories coders are CLI harnesses that can open a file; an API coder
@@ -1405,6 +1415,17 @@ export const rubricStoryJudge = (context) => (story, diff, seats, subject) => ju
 // The story's own seat, not the run's: its time counts for the story.
 // And the judge seat, never the writing reasoner: a judge reads.
 seats.context.roster?.forRole("judge") ?? seats.context.judge ?? seats.context.reasoning, story, diff, context.budget, context.plan, subject);
+/** A unit's state folders, the epic's and then each planned round's (ADR 0021). */
+export const unitStateDirs = (files, epicStateDir) => Effect.gen(function* () {
+    const dirs = [epicStateDir];
+    for (let round = 1;; round += 1) {
+        const dir = join(epicStateDir, "rounds", String(round));
+        if ((yield* files.read(join(dir, "plan.md"))) === undefined) {
+            return dirs;
+        }
+        dirs.push(dir);
+    }
+});
 /** The runner options the two flags above add; empty when neither is set. */
 export const epicRunnerOptions = Effect.fn("epic-stories.runnerOptions")(function* (options, environment) {
     const judgment = options.judgmentFromEnvironment === true
@@ -1663,8 +1684,14 @@ export const runEpicStories = (options) => Effect.gen(function* () {
             scripts: yield* appScripts(files, join(input.workDir, appDir)),
             pack
         });
-        const commands = resolvedGates.commands;
-        yield* events.publish(Info.make({ message: gateListMessage(resolvedGates) }));
+        const selected = options.selectGates === undefined
+            ? undefined
+            : options.selectGates(resolvedGates.commands);
+        const commands = selected?.commands ?? resolvedGates.commands;
+        yield* events.publish(Info.make({ message: gateListMessage({ ...resolvedGates, commands }) }));
+        if (selected?.note !== undefined) {
+            yield* events.publish(Info.make({ message: selected.note }));
+        }
         // The Node the gates would run on is the one on PATH, not the one
         // the application pins; a mismatch is a red first story that says
         // nothing about Node. Ask now, and name both.
@@ -1734,10 +1761,15 @@ export const runEpicStories = (options) => Effect.gen(function* () {
                 `The application lives in ${appDir}/ — its package.json, sources and tests; the gates run there.`
             ];
         const gates = inAppDir(appDir, gatesIn(nodeProcessExecutor, events, commands, gateRunOptions(process.env)));
-        const testCommand = testGateCommand(commands);
-        const testGate = testCommand === undefined
-            ? undefined
-            : inAppDir(appDir, gatesIn(nodeProcessExecutor, events, [testCommand], gateRunOptions(process.env)));
+        const testGateOf = (from) => {
+            const testCommand = testGateCommand(from);
+            return testCommand === undefined
+                ? undefined
+                : inAppDir(appDir, gatesIn(nodeProcessExecutor, events, [testCommand], gateRunOptions(process.env)));
+        };
+        const testGate = testGateOf(commands);
+        // A policy that deferred the test gate still gets it, to run once on its own terms.
+        const unitTestGate = testGateOf(resolvedGates.commands);
         const unitContext = (work) => ({
             plan: work.plan,
             stateDir: work.stateDir,
@@ -1746,7 +1778,7 @@ export const runEpicStories = (options) => Effect.gen(function* () {
             appDir,
             files,
             events,
-            testGate
+            testGate: unitTestGate
         });
         const setupCommand = worktreeSetupCommand(process.env, pack);
         const healthUrl = serverHealthUrl(localServer, process.env);

package/package.json

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