@llm4ts/shell 2.30.0 → 2.31.0

package/flows/fixtures/epic-stories/epic-light.md

@@ -0,0 +1,69 @@
+# Epic: epic-light
+
+Add a shared format contract, greet in English or Italian, and keep a click history in the counter; restore the skipped counter test on the way.
+
+## Waves
+
+1. format-contract
+2. greeting-locale, counter-history
+
+## Stories
+
+The fixed plan of the light comparison epic against the `epic-light` starter (`examples/starters/epic-light`, seeded by `examples/seed.sh epic`). The block below is the source of truth: the seed drops it at `.llm4ts/epics/epic-light/plan.md`, so a run plans nothing and two releases compare on the same stories. Planted on purpose: `src/platform/clock.test.ts` is red on `main` and no story owns it; `counter.test.ts` skips one test that `counter-history` must restore; `counter-history` cannot meet its acceptance without changing an existing expectation and declares `testsChange: true`.
+
+## Plan block
+
+```json storyplan
+{
+  "epicId": "epic-light",
+  "epic": "Add a shared format contract, greet in English or Italian, and keep a click history in the counter; restore the skipped counter test on the way.",
+  "stories": [
+    {
+      "id": "format-contract",
+      "title": "Shared format contract",
+      "description": "Create src/contracts/format.ts exporting a `Locale` type (\"en\" | \"it\"), `formatCount(count: number, locale: Locale): string` (\"3 clicks\" / \"3 clic\", singular \"1 click\" / \"1 clic\"), and `formatName(name: string): string` (trimmed, first letter upper-cased). Add src/contracts/format.test.ts covering both locales, the singular, and the name trimming. Follow CONTRIBUTING.md: one describe per module, Vitest imports.",
+      "dependsOn": [],
+      "owned": ["src/contracts/format.ts", "src/contracts/format.test.ts"],
+      "sharedReadOnly": ["CONTRIBUTING.md", "src/features/greeting/greeting.ts"],
+      "readFirst": ["src/features/greeting/greeting.ts", "CONTRIBUTING.md"],
+      "acceptance": [
+        "src/contracts/format.ts exports Locale, formatCount and formatName",
+        "formatCount(1, \"en\") is \"1 click\" and formatCount(3, \"it\") is \"3 clic\"",
+        "src/contracts/format.test.ts exists and covers both locales and formatName"
+      ],
+      "provides": ["Locale, formatCount, formatName from src/contracts/format.ts"]
+    },
+    {
+      "id": "greeting-locale",
+      "title": "Greeting in English or Italian",
+      "description": "Extend src/features/greeting/greeting.ts so `greet(name, locale)` takes a `Locale` from src/contracts/format.ts and answers \"Hello, <Name>!\" in English or \"Ciao, <Name>!\" in Italian, passing the name through `formatName`. Keep the existing one-argument call working (English by default). Extend greeting.test.ts with the Italian case and the default.",
+      "dependsOn": ["format-contract"],
+      "owned": ["src/features/greeting"],
+      "sharedReadOnly": ["src/contracts", "CONTRIBUTING.md"],
+      "readFirst": ["src/contracts/format.ts", "src/features/greeting/greeting.ts"],
+      "acceptance": [
+        "greet(\"ada\", \"it\") is \"Ciao, Ada!\" and greet(\"Ada\") is still \"Hello, Ada!\"",
+        "greeting.test.ts covers the Italian greeting and the default locale",
+        "nothing outside src/features/greeting changes"
+      ],
+      "provides": ["greet(name, locale?) from src/features/greeting/greeting.ts"]
+    },
+    {
+      "id": "counter-history",
+      "title": "Counter with click history",
+      "description": "Give the counter in src/features/counter/counter.ts a `history: ReadonlyArray<number>` of every count it has had (make() starts with [0]; increment and reset append). Un-skip the \"resets to zero\" test in counter.test.ts and make it pass; update the \"starts at zero\" expectation to the new shape and add a test for the history. Then update src/app.ts (the composition point this story owns) so `run(name, locale)` greets through greet(name, locale) and renders the count with formatCount from src/contracts/format.ts.",
+      "dependsOn": ["format-contract"],
+      "owned": ["src/features/counter", "src/app.ts"],
+      "sharedReadOnly": ["src/contracts", "src/features/greeting", "CONTRIBUTING.md"],
+      "readFirst": ["src/features/counter/counter.ts", "src/contracts/format.ts", "src/app.ts"],
+      "acceptance": [
+        "make().history is [0] and increment(make()).history is [0, 1]",
+        "counter.test.ts has no it.skip and its reset test passes",
+        "run(\"ada\", \"it\") contains \"Ciao, Ada!\" and \"1 clic\""
+      ],
+      "provides": ["Counter.history from src/features/counter/counter.ts", "run(name, locale) from src/app.ts"],
+      "testsChange": true
+    }
+  ]
+}
+```

package/flows/implement.js

@@ -1,6 +1,7 @@
 // Persistent plan: plan the task, then implement, review, and commit one task at a time.
 import { join } from "node:path";
 import * as Effect from "effect/Effect";
+import { withContract } from "@llm4ts/flow/AutonomyContract";
 import { coderFromEnv, defaultPlanPath, implementPlanFlow, makePlanStore, nodePlainFileStore, planFrom, resolveFlowInput, runFlowMain, runNode } from "@llm4ts/runner";
 const program = Effect.gen(function* () {
     const input = yield* resolveFlowInput("Add a multiply function to the calculator, including focused tests.");
@@ -16,7 +17,7 @@ const program = Effect.gen(function* () {
         store,
         planPath,
         plan: planFrom(context.reasoning, input.prompt),
-        system: "Implement one task at a time in the current repository."
+        system: withContract("Implement one task at a time in the current repository.")
     }));
 });
 runFlowMain(program);

package/flows/issue-pr.js

@@ -1,6 +1,7 @@
 // GitHub issue to pull request: assess the issue, plan, implement, push, and open a PR.
 import { join } from "node:path";
 import * as Effect from "effect/Effect";
+import { withContract } from "@llm4ts/flow/AutonomyContract";
 import { FlowAborted, ScriptUsage, coderFromEnv, implementPlanFlow, makePlanStore, nodePlainFileStore, resolveFlowInput, runFlowMain, runNode, stage } from "@llm4ts/runner";
 import { parseIssueRef } from "@llm4ts/flow/GitHubTool";
 import { assessThenPlan } from "@llm4ts/flow/Planner";
@@ -44,7 +45,7 @@ const program = Effect.gen(function* () {
             store,
             planPath,
             plan: Effect.succeed(plan),
-            system: "Implement one issue task at a time in the current repository.",
+            system: withContract("Implement one issue task at a time in the current repository."),
             reviewers: allReviewers
         });
         yield* stage(context.events, "push branch", context.git.push("origin", completed.epicId));

package/flows/lib/epic-stories.js

@@ -26,6 +26,8 @@ import { loadVersioned } from "@llm4ts/flow/Persistence";
 import { BlockedVerdict, StoryState, StoryStateVersion, StoryVerdict } from "@llm4ts/flow/Stories";
 import { stableHash } from "@llm4ts/flow/Plan";
 import { ReviewIssue } from "@llm4ts/flow/Review";
+import { compactGateArtifacts, gatesIn } from "@llm4ts/flow/Gates";
+import { loadTranscript, nodeTranscriptFiles } from "@llm4ts/runner/Transcripts";
 import { StoryPlan, dependenciesOf, makeStoryPlanStore, parseStoryPlan, isSafeAnchor, pathsNamedIn, pruneReadFirst } from "@llm4ts/flow/StoryPlan";
 import { defaultOrientationChars, orientationChars, orientationOf } from "@llm4ts/flow/Orientation";
 import * as Clock from "effect/Clock";
@@ -39,7 +41,7 @@ import { implementStoriesFlow } from "@llm4ts/flow/Stories";
 import { validateStoryPlan } from "@llm4ts/flow/StoryPlan";
 import { asReadOnly, nodePlainFileStore, nodeProcessExecutor, resolveFlowInput, runNode, stage, withModel } from "@llm4ts/runner";
 import { claude, coderIds, judgmentConnectorFromEnvironment, pi } from "@llm4ts/runner/Connectors";
-import { FlowAborted, FlowLlmError, ReviewResult, ScriptUsage, coderFor, lintCommand, mergeReviewResults } from "@llm4ts/runner";
+import { FlowAborted, FlowLlmError, ReviewResult, ScriptUsage, coderFor, lintCommand } from "@llm4ts/runner";
 export const epicUsage = [
     "epic-stories flags:",
     "  --plan-only         write (or re-validate) the story plan and stop",
@@ -620,7 +622,8 @@ export const storyPlanJsonSchema = {
                     sharedReadOnly: { type: "array", items: { type: "string" } },
                     readFirst: { type: "array", items: { type: "string" } },
                     acceptance: { type: "array", items: { type: "string" } },
-                    provides: { type: "array", items: { type: "string" } }
+                    provides: { type: "array", items: { type: "string" } },
+                    testsChange: { type: "boolean" }
                 },
                 required: [
                     "id",
@@ -659,6 +662,9 @@ orientation) => [
     "  the diff by a reviewer who will not run the app (a route that answers, a screen that shows",
     "  X, a test file beside the feature that covers Y). The coder plans its tasks against them",
     "  and the judge scores against them.",
+    "- `testsChange`: true only for a story whose job includes deleting, skipping or rewriting",
+    "  existing tests (a migration of a test suite, a removed feature). Every other story leaves",
+    "  it out: the gates fail a story that deletes a test file or adds a skip marker.",
     "- `owned` sets are pairwise DISJOINT: no path prefix appears under two stories.",
     "- Shared surfaces (the kit, the theme, house rules) are never edited by a feature story. A new",
     "  shared component is its own story, and every story using it depends on it.",
@@ -969,7 +975,7 @@ export const appDirFor = (workDir, environment) => Effect.gen(function* () {
     return candidates.length === 1 ? (candidates[0] ?? ".") : ".";
 });
 /** Runs a per-checkout step in the app directory of whichever checkout it is given. */
-export const inAppDir = (appDir, step) => (workDir) => step(appDir === "." ? workDir : join(workDir, appDir));
+export const inAppDir = (appDir, step) => (workDir, ...rest) => step(appDir === "." ? workDir : join(workDir, appDir), ...rest);
 // ---- Worktree setup --------------------------------------------------------------
 export const defaultWorktreeSetup = ["pnpm", "install", "--offline"];
 /**
@@ -1041,18 +1047,27 @@ export const gateCommands = (environment, scripts) => {
         .filter((part) => part.length > 0))
         .filter((command) => command.length > 0);
 };
-/** Runs the gates in a directory, stopping at the first red one (later output would be noise). */
-export const gatesIn = (process, events, commands) => (workDir, laneEvents) => Effect.gen(function* () {
-    const results = [];
-    for (const command of commands) {
-        const result = yield* lintCommand(process, laneEvents ?? events, command, workDir);
-        results.push(result);
-        if (!result.isClean) {
-            break;
-        }
-    }
-    return mergeReviewResults(results);
-});
+/** The gate runner lives in `@llm4ts/flow/Gates` (ADR 0027); re-exported for forks and tests. */
+export { gatesIn };
+/** `LLM4TS_GATE_TIMEOUT` in seconds (default 1200): a gate still running after it is a hang. */
+export const gateTimeoutSeconds = (environment) => {
+    const raw = Number.parseInt(environment.LLM4TS_GATE_TIMEOUT ?? "", 10);
+    return Number.isFinite(raw) && raw > 0 ? raw : 1200;
+};
+/** `LLM4TS_GATE_TAIL_CHARS` (default 4000): how much gate output the fix prompt carries. */
+export const gateTailChars = (environment) => {
+    const raw = Number.parseInt(environment.LLM4TS_GATE_TAIL_CHARS ?? "", 10);
+    return Number.isFinite(raw) && raw > 0 ? raw : 4000;
+};
+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)));
+/**
+ * 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
+ * still gets the tail and ignores the path.
+ */
+export const fixPromptOptions = (environment) => ({ tailChars: gateTailChars(environment), showPaths: true });
 /**
  * Transcripts are on by default for epic-stories: a slow story is only
  * explainable from them. `LLM4TS_TRANSCRIPT=off` (or `0`, `false`, `no`)
@@ -1415,9 +1430,17 @@ export const runEpicStories = (options) => Effect.gen(function* () {
                 target: flags.land,
                 rounds: yield* landRounds(plan.epicId, flags.land, rounds),
                 keepWorktrees: flags.keepWorktrees,
-                gates: inAppDir(appDir, gatesIn(nodeProcessExecutor, events, commands)),
+                gates: inAppDir(appDir, gatesIn(nodeProcessExecutor, events, commands, gateRunOptions(process.env))),
                 system: ["House rules of the target repository (CONTRIBUTING.md):", guidance].join("\n")
             });
+            // The gates' memory goes with the landed epic: baselines are
+            // reproducible, logs keep only their failing lines (ADR 0027).
+            const gateArtifacts = yield* compactGateArtifacts(files, stateDir, plan.stories.map((story) => story.id), commands);
+            if (gateArtifacts.baselines > 0 || gateArtifacts.logs > 0) {
+                yield* events.publish(Info.make({
+                    message: `epic ${plan.epicId}: removed ${gateArtifacts.baselines} gate baseline file(s), compacted ${gateArtifacts.logs} gate log(s) to their failing lines`
+                }));
+            }
             // The epic's earlier runs' transcripts go with it; this run's may still be read.
             const earlier = (yield* readEpicRuns(files, stateDir))
                 .map((run) => run.runId)
@@ -1457,7 +1480,8 @@ 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));
+        const gates = inAppDir(appDir, gatesIn(nodeProcessExecutor, events, commands, gateRunOptions(process.env)));
+        const testCommand = testGateCommand(commands);
         const setupCommand = worktreeSetupCommand(process.env);
         const healthUrl = serverHealthUrl(localServer, process.env);
         const report = yield* implementStoriesFlow({ ...context, reasoning: reasoningMeter.service }, {
@@ -1488,6 +1512,23 @@ export const runEpicStories = (options) => Effect.gen(function* () {
                     setupAgent: setupAgentEnabled(process.env)
                 }),
             gates,
+            // Gates with a memory (ADR 0027): a story is charged only with
+            // the failing lines it added to the epic head it started from.
+            gateCommands: commands,
+            appDir,
+            ...(testCommand === undefined
+                ? {}
+                : {
+                    testGate: inAppDir(appDir, gatesIn(nodeProcessExecutor, events, [testCommand], gateRunOptions(process.env)))
+                }),
+            fix: fixPromptOptions(process.env),
+            // A task's `verified:` claims are checked against the tool calls
+            // its transcript shows (ADR 0027 decision 6); no transcript, no check.
+            toolCalls: (story, since) => context.trace === undefined
+                ? Effect.succeed(undefined)
+                : Effect.map(loadTranscript(nodeTranscriptFiles, join(input.workDir, ".llm4ts", "transcripts", context.trace.runId), { lane: story.id }), (entries) => entries === undefined
+                    ? undefined
+                    : entries.flatMap((entry) => entry._tag === "Tool" && entry.at >= since ? [entry.args] : [])),
             // With a roster, the judge and the verifier are leased per story,
             // away from the executor coding it (ADR 0019).
             ...storyContextChars(process.env),

package/flows/modernize-implement.js

@@ -20,6 +20,7 @@
 // Run: modernize-implement --repo ~/services/meridian-transfers
 import { join } from "node:path";
 import * as Effect from "effect/Effect";
+import { withContract } from "@llm4ts/flow/AutonomyContract";
 import { Dimension, Sample } from "@llm4ts/core/eval/Eval";
 import { judge } from "@llm4ts/core/eval/Judge";
 import { FlowAborted, FlowLlmError, Info, ReviewResult, asReadOnly, coderFromEnv, implementTaskLoop, lintCommand, loadKitPatternCards, makeChat, makeNodeWorkspace, makePlanStore, mergeReviewResults, minimalReviewers, nodePlainFileStore, nodeProcessExecutor, openPack, resolveFlowInput, reviewAndFixLoop, reviewFingerprint, runFlowMain, runNode, stage } from "@llm4ts/runner";
@@ -246,7 +247,7 @@ const program = Effect.gen(function* () {
         // tasks.
         yield* implementTaskLoop(store, context.events, planPath, plan, (task) => Effect.gen(function* () {
             const testsTask = task.title === firstTitle;
-            const coderChat = yield* makeChat(context.coder, { system });
+            const coderChat = yield* makeChat(context.coder, { system: withContract(system) });
             yield* coderChat.ask(plan.taskPrompt(task));
             yield* reviewAndFixLoop({
                 reviewers: [...minimalReviewers, ...pack.lenses],
@@ -263,6 +264,11 @@ const program = Effect.gen(function* () {
                     : testGate === undefined
                         ? {}
                         : { lint: testGate }),
+                oracle: {
+                    diff: context.git.diffAll,
+                    declared: testsTask,
+                    ...(pack.oracle === undefined ? {} : { rules: pack.oracle })
+                },
                 parallelism: 1
             });
             if (testsTask && testGate !== undefined) {

package/flows/sdd.js

@@ -1,6 +1,7 @@
 // Spec-driven development: write a specification, encode it as red tests, implement to green.
 import { join } from "node:path";
 import * as Effect from "effect/Effect";
+import { withContract } from "@llm4ts/flow/AutonomyContract";
 import { FlowAborted, Plan, asReadOnly, coderFromEnv, defaultPlanInstructions, defaultPlanPath, implementTaskLoop, lintCommand, makeChat, makePlanStore, minimalReviewers, nodePlainFileStore, nodeProcessExecutor, planFrom, resolveFlowInput, reviewAndFixLoop, runFlowMain, runNode, stage, withModel, writeBrief } from "@llm4ts/runner";
 import { gemini } from "@llm4ts/runner/Connectors";
 const proModel = process.env.LLM4TS_REASONING_MODEL ?? "gemini-3-pro-preview";
@@ -70,7 +71,7 @@ const program = Effect.gen(function* () {
                 .pipe(Effect.andThen(context.git.commitAll(`${planWithSpec.epicId}: specification`)), Effect.asVoid)
             : Effect.void)));
         const coderChat = yield* makeChat(context.coder, {
-            system: "Implement one task at a time. The committed specification is the contract; do not weaken its tests."
+            system: withContract("Implement one task at a time. The committed specification is the contract; do not weaken its tests.")
         });
         const testGate = lintCommand(nodeProcessExecutor, context.events, ["mvn", "-q", "test"], input.workDir);
         const compileGate = lintCommand(nodeProcessExecutor, context.events, ["mvn", "-q", "test-compile"], input.workDir);
@@ -86,6 +87,9 @@ const program = Effect.gen(function* () {
                 currentDiff: context.git.diffAll,
                 events: context.events,
                 lint: testsTask ? compileGate : testGate,
+                // The red tests are the contract: the first task may write
+                // them, no later task may delete or skip them (ADR 0027).
+                oracle: { diff: context.git.diffAll, declared: testsTask },
                 parallelism: 1
             });
             if (testsTask) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llm4ts/shell",
-  "version": "2.30.0",
+  "version": "2.31.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",
     "@effect/platform-node-shared": "4.0.0",
-    "@llm4ts/core": "2.30.0",
-    "@llm4ts/flow": "2.30.0",
-    "@llm4ts/runner": "2.30.0"
+    "@llm4ts/core": "2.31.0",
+    "@llm4ts/runner": "2.31.0",
+    "@llm4ts/flow": "2.31.0"
   },
   "peerDependencies": {
     "effect": "4.0.0"