@llm4ts/shell 2.50.0 → 2.52.0

package/dist/OperatorTools.d.ts

@@ -235,6 +235,7 @@ export declare const profile: Tool.Tool<"profile", {
             readonly exploreBeforeEdit: Schema.Int;
             readonly unverifiedClaims: Schema.Int;
             readonly lowConfidenceTasks: Schema.Int;
+            readonly reviewDiffLines: Schema.optionalKey<Schema.Int>;
         }>>;
         readonly skipped: Schema.$Array<Schema.String>;
         readonly totals: Schema.Struct<{
@@ -484,6 +485,7 @@ export declare const readToolkit: Toolkit.Toolkit<{
                 readonly exploreBeforeEdit: Schema.Int;
                 readonly unverifiedClaims: Schema.Int;
                 readonly lowConfidenceTasks: Schema.Int;
+                readonly reviewDiffLines: Schema.optionalKey<Schema.Int>;
             }>>;
             readonly skipped: Schema.$Array<Schema.String>;
             readonly totals: Schema.Struct<{

package/dist/OperatorTools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"OperatorTools.d.ts","sourceRoot":"","sources":["../src/OperatorTools.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"OperatorTools.d.ts","sourceRoot":"","sources":["../src/OperatorTools.ts"],"names":[],"mappings":"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"}

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,72 +94,20 @@ 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: () => ({
             reviewers: [correctnessReviewer],
+            // One round, whether the lens reviews each task or the story (ADR 0044).
             maxRounds: 1,
+            reviewRounds: 1,
             deferNonBlocking: true
         }),
         ...(flags.withTests ? {} : { selectGates: withoutTestGate }),

package/flows/lib/epic-stories.js

@@ -58,8 +58,10 @@ export const epicUsage = [
     "                      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",
-    "  --judge-rounds <n>  judge attempts per story (default 2 = one revision); a story the judge",
-    "                      has not cleared after n attempts fails. LLM4TS_JUDGE_ROUNDS sets it too",
+    "  --review-at <task|story> where the review lenses run (default story: once per story,",
+    "                      beside the judge; task: every task, as before 2.51)",
+    "  --review-rounds <n> rounds of the story review (default 3); in task mode, judge attempts",
+    "                      (default 2). --judge-rounds and LLM4TS_JUDGE_ROUNDS set it too",
     "  --task-concurrency <n> coders one story may hold at once (default 1: every task in order).",
     "                      Above 1, a task the plan says needs nothing still running, and whose",
     "                      Owns: paths overlap no running task's, goes to a free coder in its own",
@@ -71,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",
@@ -91,6 +97,7 @@ export const parseEpicArgs = (argv) => Effect.gen(function* () {
     let failFast = false;
     let concurrency;
     let judgeRounds;
+    let reviewAt;
     let deferFindings = false;
     let mergeRevisions;
     let taskConcurrency;
@@ -183,17 +190,31 @@ export const parseEpicArgs = (argv) => Effect.gen(function* () {
             }
             mergeRevisions = parsed;
         }
-        else if (argument === "--judge-rounds" || argument.startsWith("--judge-rounds=")) {
-            const raw = argument.includes("=")
-                ? argument.slice("--judge-rounds=".length)
-                : argv[index + 1];
+        else if (argument === "--review-at" || argument.startsWith("--review-at=")) {
+            const raw = argument.includes("=") ? argument.slice("--review-at=".length) : argv[index + 1];
+            if (!argument.includes("=")) {
+                index += 1;
+            }
+            if (raw !== "task" && raw !== "story") {
+                return yield* ScriptUsage.make({
+                    message: `--review-at takes task or story\n${epicUsage}`
+                });
+            }
+            reviewAt = raw;
+        }
+        else if (argument === "--judge-rounds" ||
+            argument.startsWith("--judge-rounds=") ||
+            argument === "--review-rounds" ||
+            argument.startsWith("--review-rounds=")) {
+            const name = argument.split("=")[0] ?? argument;
+            const raw = argument.includes("=") ? argument.slice(name.length + 1) : argv[index + 1];
             if (!argument.includes("=")) {
                 index += 1;
             }
             const parsed = Number.parseInt(raw ?? "", 10);
             if (!Number.isInteger(parsed) || parsed < 1) {
                 return yield* ScriptUsage.make({
-                    message: `--judge-rounds requires a positive integer\n${epicUsage}`
+                    message: `${name} requires a positive integer\n${epicUsage}`
                 });
             }
             judgeRounds = parsed;
@@ -207,6 +228,8 @@ export const parseEpicArgs = (argv) => Effect.gen(function* () {
         failFast,
         concurrency,
         judgeRounds,
+        reviewAt,
+        reviewRounds: judgeRounds,
         deferFindings,
         mergeRevisions,
         taskConcurrency,
@@ -270,6 +293,21 @@ export const judgeRoundsOption = (flag, environment) => {
     const raw = Number.parseInt(environment.LLM4TS_JUDGE_ROUNDS ?? "", 10);
     return Number.isInteger(raw) && raw > 0 ? { judgeRounds: raw } : {};
 };
+/**
+ * Where the lenses run and for how many rounds (ADR 0044): per story unless
+ * `--review-at task`. The rounds (`--review-rounds`, `--judge-rounds`, or
+ * `LLM4TS_JUDGE_ROUNDS`) bound the story review, or in task mode count judge
+ * attempts as before.
+ */
+export const reviewOptions = (reviewAt, rounds, environment) => {
+    const at = reviewAt ?? "story";
+    const { judgeRounds } = judgeRoundsOption(rounds, environment);
+    return judgeRounds === undefined
+        ? { reviewAt: at }
+        : at === "story"
+            ? { reviewAt: at, reviewRounds: judgeRounds }
+            : { reviewAt: at, judgeRounds };
+};
 export const roundDir = (stateDir, round) => join(stateDir, "rounds", String(round));
 const mergedStories = (files, stateDir, plan) => Effect.gen(function* () {
     let merged = 0;
@@ -1004,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}`,
@@ -1027,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
@@ -1034,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) => {
@@ -1058,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
             ? []
             : [
@@ -1083,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"]);
@@ -1416,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];
@@ -1857,7 +1919,7 @@ export const runEpicStories = (options) => Effect.gen(function* () {
                 ...appDirNote,
                 ...(orientation === undefined ? [] : ["", orientation])
             ].join("\n")),
-            ...judgeRoundsOption(flags.judgeRounds, process.env),
+            ...reviewOptions(flags.reviewAt, flags.reviewRounds, process.env),
             ...mergeRevisionsOption(flags.mergeRevisions, process.env),
             ...taskConcurrencyOption(flags.taskConcurrency, process.env),
             concurrency,

package/package.json

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