@llm4ts/shell 2.51.0 → 2.52.0

package/flows/epic-stories.js

@@ -5,6 +5,8 @@
 //   llm4ts run epic-stories --repo ~/demo/portal -- --land            # land the finished epic on main
 //   llm4ts run epic-stories --repo ~/demo/portal -- --list            # the repository's epics
 //   llm4ts run epic-stories --repo ~/demo/portal -- --epic <id>       # resume one, no text needed
+//   llm4ts run epic-stories --repo ~/demo/portal -- --defer-tests "…" # missing tests become debt
+//   llm4ts run epic-stories --repo ~/demo/portal -- --harden --epic <id> # plan that debt as a round
 //
 // The reasoning seat (LLM4TS_REASONER, default claude) splits the epic,
 // reviews every task and judges every story; the coder seat (LLM4TS_CODER,
@@ -21,6 +23,10 @@
 // Transcripts (what each seat was told and answered) are ON by default for
 // this flow — LLM4TS_TRANSCRIPT=off turns them off — and --land compacts them
 // (shape kept, content removed) rather than deleting them (ADR 0025).
+// With --defer-tests the judge's tests score is never a finding and what it
+// excused is written to debt.md; --harden plans that debt (ADR 0045).
+import * as Effect from "effect/Effect";
 import { runFlowMain } from "@llm4ts/runner";
-import { rubricStoryJudge, runEpicStories } from "./lib/epic-stories.js";
-runFlowMain(runEpicStories({ storyJudge: rubricStoryJudge }));
+import { epicStoriesOptions, parseStoriesFlags } from "./lib/debt.js";
+import { runEpicStories } from "./lib/epic-stories.js";
+runFlowMain(Effect.flatMap(parseStoriesFlags(process.argv.slice(2), process.env), (flags) => runEpicStories({ ...epicStoriesOptions(flags), argv: flags.argv })));

package/flows/lib/debt.js

@@ -0,0 +1,132 @@
+// Debt an epic run deferred and a later round pays (ADR 0043, ADR 0045):
+// `debt.md` per unit, `debt.paid.md` once a hardening round settles, and
+// the `--harden` policy both epic-draft and epic-stories use.
+import { join } from "node:path";
+import * as Effect from "effect/Effect";
+import { Info } from "@llm4ts/flow/FlowEvents";
+import { countNotPlanned } from "@llm4ts/flow/RefineRound";
+import { lastStoryVerdict } from "@llm4ts/flow/Stories";
+import { ScriptUsage } from "@llm4ts/runner";
+import { deferringTestsJudge, epicUsage, loadRounds, rubricStoryJudge, unitStateDirs } from "./epic-stories.js";
+// ---- The debt ---------------------------------------------------------------
+export const counted = (count, one, many) => `${count} ${count === 1 ? one : many}`;
+/** What a unit deferred: the tests owed, the findings, the test gate it skipped. */
+export const debtPath = (stateDir) => join(stateDir, "debt.md");
+/** Debt a settled hardening round consumed. */
+export const paidPath = (stateDir) => join(stateDir, "debt.paid.md");
+// ---- Tests the judge excused (ADR 0045) -------------------------------------
+/**
+ * After an epic-stories unit run with `--defer-tests`: `debt.md` with one
+ * section per merged story whose last verdict scored `tests` below the bar,
+ * each acceptance outcome a test owed. A story the plan exempts from tests,
+ * or one a hardening round paid, owes nothing. Deferred findings are left
+ * out: `--defer-findings` already plans them as their own round.
+ */
+export const testsDebtAfterUnit = (unit, report) => Effect.gen(function* () {
+    const paid = new Set(((yield* unit.files.read(paidPath(unit.stateDir))) ?? "")
+        .split("\n")
+        .flatMap((line) => (line.startsWith("## ") ? [line.slice(3).trim()] : [])));
+    const sections = [];
+    let owed = 0;
+    let stories = 0;
+    for (const story of unit.plan.stories) {
+        const merged = report.stories.some((outcome) => outcome.id === story.id && outcome.status === "done");
+        if (!merged || story.testsDeferred !== undefined || paid.has(story.id)) {
+            continue;
+        }
+        const verdict = yield* lastStoryVerdict(unit.files, unit.stateDir, story.id);
+        const tests = verdict?.excused?.find((dimension) => dimension.id === "tests");
+        if (tests === undefined) {
+            continue;
+        }
+        owed += story.acceptance.length;
+        stories += 1;
+        sections.push(`## ${story.id}`, "", `judge scored tests ${tests.score}/${tests.max}: ${tests.reasoning}`, "", ...story.acceptance.map((outcome) => `- [ ] test: ${outcome}`), "");
+    }
+    if (stories === 0) {
+        return;
+    }
+    const path = debtPath(unit.stateDir);
+    yield* unit.files.writeAtomic(path, [`# Debt — ${unit.plan.epicId}`, "", ...sections].join("\n"));
+    yield* unit.events.publish(Info.make({
+        message: `debt: ${counted(owed, "test owed", "tests owed")} by ${counted(stories, "story", "stories")} — read it, then run epic-stories --harden (${path})`
+    }));
+});
+// ---- Hardening --------------------------------------------------------------
+/** The open debt lists of an epic, by state folder; empty ones are paid. */
+export 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 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`
+        }));
+    }
+});
+/** `--harden`: the open debt planned as a round under epic-stories' full bar. */
+export const hardenOptions = {
+    storyJudge: rubricStoryJudge,
+    refineFeedback: hardenFeedback,
+    afterUnit: hardenAfterUnit
+};
+export const parseStoriesFlags = (argv, environment) => Effect.gen(function* () {
+    const deferTests = argv.includes("--defer-tests") ||
+        /^(1|true|on|yes)$/i.test(environment.LLM4TS_DEFER_TESTS?.trim() ?? "");
+    const harden = argv.includes("--harden");
+    if (deferTests && harden) {
+        return yield* ScriptUsage.make({
+            message: `--harden pays the debt under the full bar; it does not take --defer-tests (or LLM4TS_DEFER_TESTS)\n${epicUsage}`
+        });
+    }
+    const rest = argv.filter((arg) => arg !== "--defer-tests" && arg !== "--harden");
+    return { deferTests, harden, argv: harden ? ["--refine", ...rest] : rest };
+});
+/** epic-stories' policy for its flags: the rubric judge, excusing tests, or hardening. */
+export const epicStoriesOptions = (flags) => flags.harden
+    ? hardenOptions
+    : flags.deferTests
+        ? {
+            storyJudge: deferringTestsJudge,
+            stories: () => ({ judgeBar: "defer-tests" }),
+            afterUnit: testsDebtAfterUnit
+        }
+        : { storyJudge: rubricStoryJudge };

package/flows/lib/epic-draft.js

@@ -2,16 +2,15 @@
 // 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";
+import { counted, debtPath, hardenOptions, paidPath } from "./debt.js";
+import { storyPlanInstructions, storyPlanJsonSchema, withoutTestGate } from "./epic-stories.js";
 export const parseDraftFlags = (argv) => {
     const harden = argv.includes("--harden");
     const withTests = argv.includes("--with-tests");
@@ -36,10 +35,8 @@ export const generateDraftPlan = (inputs) => structuredAndPublish(inputs.reasoni
 // 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");
+// The debt files and `--harden` live in debt.ts, shared with epic-stories (ADR 0045).
+export { debtPath, hardenAfterUnit, hardenFeedback, paidPath } from "./debt.js";
 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}`,
@@ -55,7 +52,6 @@ export const renderDebt = (plan, report, deferred, testFailures) => [
         ? []
         : ["## 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
@@ -98,67 +94,13 @@ export const draftAfterUnit = (withTests) => (unit, report) => Effect.gen(functi
             : 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
-    }
+    ? hardenOptions
     : {
         generatePlan: generateDraftPlan,
         stories: () => ({

package/flows/lib/epic-stories.js

@@ -73,6 +73,10 @@ export const epicUsage = [
     "                      settle, the judge clears without them); the rest are deferred and, once",
     "                      every story is merged, planned and run as one refine round.",
     "                      LLM4TS_DEFER_FINDINGS=1 sets it too",
+    "  --defer-tests       the judge's tests score, even 0, never fails a story: the tests it",
+    "                      excused are written to debt.md (the coder is still asked for tests;",
+    "                      a red test gate still fails). LLM4TS_DEFER_TESTS=1 sets it too",
+    "  --harden            plan the epic's open debt as a refine round under the full bar",
     "Seats: LLM4TS_REASONER (claude|gemini|…, default claude) splits, reviews, judges;",
     "       LLM4TS_CODER (default pi) implements; LLM4TS_REASONING_MODEL / LLM4TS_CODER_MODEL",
     "       pick their models (pi: provider/model); LLM4TS_CODER_FLAGS / LLM4TS_REASONING_FLAGS",
@@ -1038,15 +1042,18 @@ export const storyDimensions = [
  * a partial score elsewhere is a Warning a follow-up round can close.
  */
 export const judgeSeverity = (name, score) => name === "provides" || score <= 0 ? "Critical" : "Warning";
-/** The dimensions a story is held to: all of them, less `tests` when the plan deferred them. */
-export const judgedDimensionsOf = (story) => storyDimensions
+/**
+ * The dimensions a story is held to: all of them, less `tests` when the plan
+ * deferred them or the run's bar does.
+ */
+export const judgedDimensionsOf = (story, bar = {}) => storyDimensions
     .map((dimension) => dimension.name)
-    .filter((name) => story.testsDeferred === undefined || name !== "tests");
-const subBar = (scored, story) => ReviewResult.make({
+    .filter((name) => name !== "tests" || (story.testsDeferred === undefined && bar.deferTests !== true));
+const maxScoreOf = (name) => storyDimensions.find((dimension) => dimension.name === name)?.maxScore ?? 2;
+const subBar = (scored, story, bar) => ReviewResult.make({
     issues: scored.scores
-        .filter((score) => judgedDimensionsOf(story).includes(score.name) &&
-        score.score <
-            (storyDimensions.find((dimension) => dimension.name === score.name)?.maxScore ?? 2))
+        .filter((score) => judgedDimensionsOf(story, bar).includes(score.name) &&
+        score.score < maxScoreOf(score.name))
         .map((score) => ReviewIssue.make({
         severity: judgeSeverity(score.name, score.score),
         title: `judge[${story.id}]: ${score.name} scored ${score.score}`,
@@ -1061,6 +1068,11 @@ export const testsDeferredLines = (reason) => reason === undefined
         `Tests deferred by the plan: ${reason}`,
         "No test file is expected; do not mark any dimension down for its absence."
     ];
+/** What a judge is told under `--defer-tests` (ADR 0045): score tests, hold nothing else to them. */
+export const deferTestsLines = [
+    "Tests may be deferred to a later round: score `tests` on what the diff shows,",
+    "but do not mark any other dimension down because tests are missing."
+];
 /**
  * What the story judge reads beside the diff: the story, and what every
  * story it depends on provides. Without the dependencies the judge cannot
@@ -1068,7 +1080,7 @@ export const testsDeferredLines = (reason) => reason === undefined
  * importing `paymentsDomain` from `payments.fake.ts`, exactly where the
  * payments contract story declared it.
  */
-export const storyJudgeQuery = (story, plan, subject = "diff") => {
+export const storyJudgeQuery = (story, plan, subject = "diff", bar = {}) => {
     const dependencies = plan === undefined
         ? []
         : dependenciesOf(plan, story.id).flatMap((id) => {
@@ -1092,6 +1104,7 @@ export const storyJudgeQuery = (story, plan, subject = "diff") => {
         `Owned paths: ${story.owned.join(", ")}`,
         `Shared read-only: ${story.sharedReadOnly.join(", ") || "(none)"}`,
         ...testsDeferredLines(story.testsDeferred),
+        ...(story.testsDeferred === undefined && bar.deferTests === true ? deferTestsLines : []),
         ...(dependencies.length === 0
             ? []
             : [
@@ -1117,19 +1130,32 @@ export const storyJudgeQuery = (story, plan, subject = "diff") => {
     ].join("\n");
 };
 /** The story-level judge over the branch diff, bounded by the character budget. */
-export const judgeStory = (reasoning, story, diff, budget, plan, subject = "diff") => judge(reasoning, storyDimensions)
+export const judgeStory = (reasoning, story, diff, budget, plan, subject = "diff", bar = {}) => judge(reasoning, storyDimensions)
     .evaluate(Sample.make({
-    query: storyJudgeQuery(story, plan, subject),
+    query: storyJudgeQuery(story, plan, subject, bar),
     response: cap(diff, budget).text
 }))
-    .pipe(Effect.mapError(FlowLlmError.from), Effect.map((scored) => StoryVerdict.make({
-    ...subBar(scored, story),
-    dimensions: scored.scores.map((score) => ({
+    .pipe(Effect.mapError(FlowLlmError.from), Effect.map((scored) => {
+    // Below the bar but not held to it: kept, with why, for the debt (ADR 0045).
+    const excused = scored.scores
+        .filter((score) => !judgedDimensionsOf(story, bar).includes(score.name) &&
+        score.score < maxScoreOf(score.name))
+        .map((score) => ({
         id: score.name,
         score: score.score,
-        max: storyDimensions.find((dimension) => dimension.name === score.name)?.maxScore ?? 2
-    }))
-})));
+        max: maxScoreOf(score.name),
+        reasoning: score.reasoning
+    }));
+    return StoryVerdict.make({
+        ...subBar(scored, story, bar),
+        dimensions: scored.scores.map((score) => ({
+            id: score.name,
+            score: score.score,
+            max: maxScoreOf(score.name)
+        })),
+        ...(excused.length === 0 ? {} : { excused })
+    });
+}));
 // ---- App directory ----------------------------------------------------------------
 /** Folders never taken for the application: dependencies, build output, llm4ts state. */
 const ignoredAppDirs = new Set(["node_modules", "dist", "build", "out", "coverage"]);
@@ -1450,6 +1476,8 @@ 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);
+/** The rubric judge under `--defer-tests` (ADR 0045): `tests` is scored, never a finding. */
+export const deferringTestsJudge = (context) => (story, diff, seats, subject) => judgeStory(seats.context.roster?.forRole("judge") ?? seats.context.judge ?? seats.context.reasoning, story, diff, context.budget, context.plan, subject, { deferTests: true });
 /** 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];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llm4ts/shell",
-  "version": "2.51.0",
+  "version": "2.52.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.51.0",
-    "@llm4ts/core": "2.51.0",
-    "@llm4ts/runner": "2.51.0"
+    "@llm4ts/core": "2.52.0",
+    "@llm4ts/flow": "2.52.0",
+    "@llm4ts/runner": "2.52.0"
   },
   "peerDependencies": {
     "effect": "4.0.0"