@llm4ts/shell 2.51.0 → 2.53.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/flows/lib/roundtable-personas.js

@@ -0,0 +1,124 @@
+/**
+ * The bundled persona cards of the roundtable (ADR 0046, decision 2). They
+ * are the same markdown a user writes under `.llm4ts/personas/<name>.md`;
+ * `llm4ts run roundtable -- --eject-personas` writes them there to be
+ * edited, and a card of the same name there wins over the bundled one.
+ */
+import * as Effect from "effect/Effect";
+import { parsePersona } from "@llm4ts/flow/Roundtable";
+const card = (name, order, sections) => [
+    "---",
+    `name: ${name}`,
+    `order: ${order}`,
+    "---",
+    "",
+    "## Mandate",
+    "",
+    sections.mandate,
+    "",
+    "## Cares about",
+    "",
+    sections.caresAbout,
+    "",
+    "## Pushes back on",
+    "",
+    sections.pushesBackOn,
+    "",
+    "## Never decides alone",
+    "",
+    sections.neverDecidesAlone,
+    "",
+    "## Voice",
+    "",
+    sections.voice,
+    "",
+    ...(sections.outlineTemplate === undefined
+        ? []
+        : ["## Outline template", "", ...sections.outlineTemplate, ""]),
+    ...(sections.planTemplate === undefined
+        ? []
+        : ["## Plan template", "", ...sections.planTemplate, ""])
+].join("\n");
+export const scribeName = "Scribe";
+/** The six attendees a meeting gets when `--agents` is not given, in speaking order. */
+export const defaultAttendees = [
+    "PO",
+    "PM",
+    "Sr SW Eng",
+    "Cloud Architect",
+    "DevOps",
+    "SRE"
+];
+export const bundledPersonaCards = {
+    PO: card("PO", 10, {
+        mandate: "Owns the problem and the outcome. Says what the solution must do for whom, and what success looks like.",
+        caresAbout: "User and business value, the order things are delivered in, what is out of scope, acceptance criteria that can be checked.",
+        pushesBackOn: "Solutions in search of a problem, gold plating, scope that grows without a user behind it, plans with no first usable release.",
+        neverDecidesAlone: "Technical architecture, operability, security controls.",
+        voice: "Plain language, user stories and examples. Opens the discussion by framing the problem before anyone proposes a solution."
+    }),
+    PM: card("PM", 20, {
+        mandate: "Owns delivery: sequencing, dependencies, risks, who does what, and what the plan promises to whom.",
+        caresAbout: "Milestones, dependencies on other teams, risks and their owners, what can be parallelised, what must be decided early.",
+        pushesBackOn: "Plans without owners or dates, hidden dependencies, risks nobody tracks, decisions deferred to 'later' without a trigger.",
+        neverDecidesAlone: "Product scope, technical design, what is operationally acceptable.",
+        voice: "Structured, asks who and when. Turns positions into phases and workstreams."
+    }),
+    "Sr SW Eng": card("Sr SW Eng", 30, {
+        mandate: "Owns the code-level design: modules, interfaces, data model, testability, and how the team will actually build it.",
+        caresAbout: "Clear module boundaries, typed contracts, testability, incremental delivery, avoiding rewrites, the developer experience.",
+        pushesBackOn: "Big-bang designs, abstractions with one caller, untestable components, hand-waved data models, hidden coupling.",
+        neverDecidesAlone: "Product scope, infrastructure choices, release sequencing.",
+        voice: "Concrete, names modules and interfaces, gives an example. Asks how it would be tested."
+    }),
+    "Cloud Architect": card("Cloud Architect", 40, {
+        mandate: "Owns the system shape: components, integration style, data flows, platform services, and the architecture's fit with the company standards.",
+        caresAbout: "Boundaries between systems, synchronous versus event-driven integration, data ownership, security architecture, standards and reference architectures, cost of the platform.",
+        pushesBackOn: "Point-to-point integration that will not scale, designs that ignore an existing platform service, undocumented data ownership, deviations from a standard without a recorded reason.",
+        neverDecidesAlone: "Product scope, team capacity, on-call acceptance.",
+        voice: "Draws the picture in words: components and arrows. Cites the standard being applied or deviated from, and proposes decisions explicitly."
+    }),
+    DevOps: card("DevOps", 50, {
+        mandate: "Owns how the solution is built, tested, deployed and configured: pipelines, environments, infrastructure as code, secrets, release mechanics.",
+        caresAbout: "Repeatable builds, environment parity, deployment safety (canary, rollback), configuration and secrets handling, the path from a commit to production.",
+        pushesBackOn: "Manual steps, snowflake environments, secrets in config, releases that cannot be rolled back, infrastructure nobody can recreate.",
+        neverDecidesAlone: "Product scope, application architecture, SLOs.",
+        voice: "Practical, step by step. Asks how it gets to production and how it gets back out."
+    }),
+    SRE: card("SRE", 60, {
+        mandate: "Keeps the solution operable: SLOs, failure modes, capacity, observability, incident response and the on-call reality.",
+        caresAbout: "What breaks and how it is seen, blast radius, degradation over outage, alerting that means something, capacity and latency budgets, runbooks.",
+        pushesBackOn: "Anything without a failure story, dashboards without alerts, alerts without runbooks, single points of failure, retries without limits.",
+        neverDecidesAlone: "Product scope, feature priorities.",
+        voice: "Short, concrete, asks for numbers. Speaks last and names what the others missed."
+    }),
+    [scribeName]: card(scribeName, 90, {
+        mandate: "Writes the deliverables from the whole transcript: the solution outline and the plan, in one voice, saying what the room settled and marking what depends on an unanswered question.",
+        caresAbout: "Fidelity to the decisions as recorded, their dissent kept visible, assumptions stated where the owner has not answered, documents a reader can act on without the transcript.",
+        pushesBackOn: "Inventing decisions the room did not take, smoothing over dissent, silently resolving a parked question.",
+        neverDecidesAlone: "Everything: the Scribe records, it does not decide.",
+        voice: "Clear, structured prose under the template headings. No meeting narration.",
+        outlineTemplate: [
+            "## Context",
+            "## Goal and non-goals",
+            "## Proposed solution",
+            "## Components and integration",
+            "## Data",
+            "## Security, reliability and operations",
+            "## Standards applied and deviations",
+            "## Alternatives considered",
+            "## Risks",
+            "## Open questions and assumptions"
+        ],
+        planTemplate: [
+            "## Phases",
+            "## Workstreams and owners",
+            "## Dependencies",
+            "## Milestones",
+            "## Risks and mitigations",
+            "## First usable release"
+        ]
+    })
+};
+/** The bundled cards, parsed. A card that does not parse is a defect in this file. */
+export const bundledPersonas = Effect.forEach(Object.entries(bundledPersonaCards), ([name, text]) => parsePersona(name, text));

package/flows/lib/roundtable.js

@@ -0,0 +1,600 @@
+/**
+ * roundtable (ADR 0046): the flow half of the meeting. The protocol — what
+ * settles an item, who speaks next, when to judge, draft and finish — is
+ * `@llm4ts/flow/Roundtable`; this module reads and writes the meeting's
+ * files, builds the prompts, drives one read-only seat and the judgment
+ * service, and reports to the person.
+ */
+import { join } from "node:path";
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+import { truthOf } from "@llm4ts/core/judgment/Judgment";
+import { truth } from "@llm4ts/core/judgment/Schemas";
+import { cap } from "@llm4ts/flow/Context";
+import { Info, RoundtableTurn, StageCompleted, StageStarted } from "@llm4ts/flow/FlowEvents";
+import { AgendaPending, FlowAborted } from "@llm4ts/flow/FlowError";
+import { decide, judgeOrEscalate } from "@llm4ts/flow/Judgment";
+import { AgendaProposal, agendaProposalJsonSchema, assembleAgenda, assembleTurn, briefingFor, chairSpeaker, closingItem, decodeTurns, encodeTurn, itemOf, itemState, maxAgendaItems, Meeting, minAgendaItems, nextAction, parseMeeting, parsePersona, recordOwner, renderAgendaItem, renderDecisions, renderDiscussion, renderMeeting, renderOpenQuestions, renderTurn, reviewItem, syncAnswers, Turn, TurnProposal, turnProposalJsonSchema } from "@llm4ts/flow/Roundtable";
+import { structuredAndPublish } from "@llm4ts/flow/Usage";
+import { ScriptUsage } from "@llm4ts/runner/FlowArgs";
+import { terminalSafe } from "@llm4ts/runner/Terminal";
+import { bundledPersonaCards, scribeName } from "./roundtable-personas.js";
+// ---- Flags ----------------------------------------------------------------------
+export const roundtableUsage = [
+    'usage: llm4ts run roundtable --repo <dir> "<topic>" -- --goal "<goal>" [--agents "PO,PM,..."] [--meeting <id>]',
+    "                             [--context <dir>] [--rounds <n>] [--max-turns <n>] [--no-pause]",
+    "       llm4ts run roundtable --repo <dir> -- --meeting <id>        # continue or finish a meeting",
+    "       llm4ts run roundtable --repo <dir> -- --eject-personas      # write the bundled cards to .llm4ts/personas/",
+    "       llm4ts run roundtable --repo <dir> -- --list                # the repository's meetings",
+    "  --goal <text>      what the meeting must reach (required the first time)",
+    "  --agents <names>   attendees by persona name, in any order; default: PO,PM,Sr SW Eng,Cloud Architect,DevOps,SRE",
+    "  --meeting <id>     the meeting folder under .llm4ts/meetings/; default: a slug of the topic",
+    "  --context <dir>    documents every attendee reads (standards, architecture notes)",
+    "  --rounds <n>       complete rounds an item gets before it is left open (default 3)",
+    "  --max-turns <n>    turns in the whole discussion before drafting starts (default 40)",
+    "  --no-pause         do not stop after the agenda is proposed",
+    "The meeting file is the state: .llm4ts/meetings/<id>/meeting.md. Answer the questions under",
+    "'## Answers', write under '## Feedback', and rerun."
+].join("\n");
+export const parseRoundtableArgs = (argv) => Effect.gen(function* () {
+    let goal;
+    let agents;
+    let meeting;
+    let context;
+    let rounds;
+    let maxTurns;
+    let noPause = false;
+    let ejectPersonas = false;
+    let list = false;
+    const rest = [];
+    for (let index = 0; index < argv.length; index += 1) {
+        const argument = argv[index] ?? "";
+        const is = (name) => argument === name || argument.startsWith(`${name}=`);
+        const valued = (name) => {
+            const value = argument.includes("=") ? argument.slice(name.length + 1) : argv[index + 1];
+            if (!argument.includes("="))
+                index += 1;
+            return value === undefined || value.trim().length === 0 || value.startsWith("--")
+                ? ScriptUsage.make({ message: `${name} needs a value\n${roundtableUsage}` })
+                : Effect.succeed(value.trim());
+        };
+        const counted = (name) => Effect.flatMap(valued(name), (value) => /^\d+$/.test(value) && Number.parseInt(value, 10) > 0
+            ? Effect.succeed(Number.parseInt(value, 10))
+            : ScriptUsage.make({ message: `${name} needs a positive number, got: ${value}` }));
+        if (is("--goal"))
+            goal = yield* valued("--goal");
+        else if (is("--agents"))
+            agents = (yield* valued("--agents"))
+                .split(",")
+                .map((name) => name.trim())
+                .filter((name) => name.length > 0);
+        else if (is("--meeting"))
+            meeting = yield* valued("--meeting");
+        else if (is("--context"))
+            context = yield* valued("--context");
+        else if (is("--rounds"))
+            rounds = yield* counted("--rounds");
+        else if (is("--max-turns"))
+            maxTurns = yield* counted("--max-turns");
+        else if (argument === "--no-pause")
+            noPause = true;
+        else if (argument === "--eject-personas")
+            ejectPersonas = true;
+        else if (argument === "--list")
+            list = true;
+        else
+            rest.push(argument);
+    }
+    return { goal, agents, meeting, context, rounds, maxTurns, noPause, ejectPersonas, list, rest };
+});
+// ---- Places -------------------------------------------------------------------
+export const meetingsDir = (workDir) => join(workDir, ".llm4ts", "meetings");
+export const meetingDir = (workDir, id) => join(meetingsDir(workDir), id);
+export const personasDir = (workDir) => join(workDir, ".llm4ts", "personas");
+/** The folder name a topic gets: lower case, words joined by dashes, at most 60 characters. */
+export const meetingSlug = (topic) => {
+    const slug = topic
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 60)
+        .replace(/-+$/g, "");
+    return slug.length === 0 ? "meeting" : slug;
+};
+const meetingFiles = (dir) => ({
+    meeting: join(dir, "meeting.md"),
+    turns: join(dir, "turns.jsonl"),
+    discussion: join(dir, "discussion.md"),
+    outline: join(dir, "outline.md"),
+    plan: join(dir, "plan.md"),
+    decisions: join(dir, "decisions.md"),
+    openQuestions: join(dir, "open-questions.md")
+});
+/**
+ * The cards the meeting uses: bundled ones, each replaced by a custom card
+ * of the same name (`.llm4ts/personas/<name>.md`, read by the caller).
+ * Attendees are named; the Scribe is always present.
+ */
+export const resolvePersonas = Effect.fn("roundtable.resolvePersonas")(function* (custom, attendees) {
+    const cards = { ...bundledPersonaCards, ...custom };
+    const personas = new Map();
+    for (const [name, text] of Object.entries(cards)) {
+        const persona = yield* parsePersona(name, text);
+        personas.set(name, persona);
+    }
+    const known = [...personas.keys()].filter((name) => name !== scribeName);
+    const missing = attendees.filter((name) => !personas.has(name) || name === scribeName);
+    if (missing.length > 0) {
+        return yield* ScriptUsage.make({
+            message: `unknown persona(s): ${missing.join(", ")}; known: ${known.join(", ")} — add a card under .llm4ts/personas/<name>.md`
+        });
+    }
+    if (attendees.length === 0) {
+        return yield* ScriptUsage.make({ message: `--agents names at least one persona` });
+    }
+    const scribe = personas.get(scribeName);
+    if (scribe === undefined) {
+        return yield* ScriptUsage.make({ message: `no ${scribeName} card` });
+    }
+    const chosen = [...new Set(attendees)]
+        .flatMap((name) => {
+        const persona = personas.get(name);
+        return persona === undefined ? [] : [persona];
+    })
+        .sort((left, right) => left.order - right.order || left.name.localeCompare(right.name));
+    return { attendees: chosen, scribe };
+});
+/** Writes every bundled card the folder lacks; returns the paths written. */
+export const ejectPersonas = Effect.fn("roundtable.ejectPersonas")(function* (files, workDir) {
+    const written = [];
+    for (const [name, text] of Object.entries(bundledPersonaCards)) {
+        const path = join(personasDir(workDir), `${name}.md`);
+        const existing = yield* files.read(path);
+        if (existing !== undefined)
+            continue;
+        yield* files.writeAtomic(path, text);
+        written.push(path);
+    }
+    return written;
+});
+// ---- The Scribe's output ------------------------------------------------------
+export class DraftProposal extends Schema.Class("DraftProposal")({
+    outline: Schema.String,
+    plan: Schema.String
+}) {
+}
+export const draftProposalJsonSchema = {
+    type: "object",
+    properties: { outline: { type: "string" }, plan: { type: "string" } },
+    required: ["outline", "plan"]
+};
+const personaBrief = (persona) => [
+    `You are the ${persona.name} in a roundtable of specialists.`,
+    "",
+    `Mandate: ${persona.mandate}`,
+    ...(persona.caresAbout.length === 0 ? [] : [`You care about: ${persona.caresAbout}`]),
+    ...(persona.pushesBackOn.length === 0 ? [] : [`You push back on: ${persona.pushesBackOn}`]),
+    ...(persona.neverDecidesAlone.length === 0
+        ? []
+        : [`You never decide alone: ${persona.neverDecidesAlone}`]),
+    ...(persona.voice.length === 0 ? [] : [`Voice: ${persona.voice}`])
+].join("\n");
+const meetingBrief = (meeting) => [
+    `Topic: ${meeting.topic}`,
+    `Goal: ${meeting.goal}`,
+    `Attendees: ${meeting.attendees.join(", ")}`
+].join("\n");
+const contextBrief = (docs, budget) => {
+    if (docs.length === 0)
+        return "";
+    const each = Math.max(1_000, Math.floor(budget / 2 / docs.length));
+    return [
+        "",
+        "Context documents (standards and notes the room works within):",
+        ...docs.flatMap((doc) => ["", `--- ${doc.path} ---`, cap(doc.text, each).text])
+    ].join("\n");
+};
+const agendaPrompt = (persona, meeting, docs, budget) => [
+    personaBrief(persona),
+    "",
+    meetingBrief(meeting),
+    contextBrief(docs, budget),
+    "",
+    `Propose the agenda: between ${minAgendaItems} and ${maxAgendaItems} items, each a short title and the one question the room must settle under it. Order them problem first, then solution, then how it is delivered and run. Do not add a goal check: the chair closes the meeting with one.`,
+    "",
+    'Reply with JSON: {"items": [{"title": "...", "question": "..."}]}'
+].join("\n");
+const kindsGuide = [
+    "Kinds of turn:",
+    "- position: your view on the question, with reasons.",
+    "- proposal: a concrete decision you want the room to take; write it so it can be recorded as is.",
+    "- objection: against an earlier turn (name it in answers). blocking=true only when the goal cannot be reached unless it is addressed; otherwise it is recorded as dissent.",
+    "- question: for the room, or for the owner (needsHuman=true) when only the person who called the meeting can answer; then state the assumption you proceed on.",
+    "- agreement: you accept an earlier turn (name it in answers). Close your own blocking objection this way when it has been answered.",
+    "- pass: nothing to add this round."
+].join("\n");
+const turnPrompt = (options) => {
+    const { persona, meeting, item, round, caps, turns, addressed, docs, budget } = options;
+    const briefing = briefingFor(meeting, turns, item.number, caps);
+    const isReview = item.number === reviewItem(meeting).number;
+    return [
+        personaBrief(persona),
+        "",
+        meetingBrief(meeting),
+        contextBrief(docs, budget),
+        "",
+        "Decisions so far:",
+        ...(briefing.decisions.length === 0
+            ? ["- none yet"]
+            : briefing.decisions.map((decision) => `- item ${decision.item.number} (${decision.item.title}): ${decision.proposal.body} — proposed by ${decision.proposal.speaker}${decision.dissent.length === 0 ? "" : `; dissent from ${decision.dissent.map((turn) => turn.speaker).join(", ")}`}`)),
+        "",
+        "Questions parked for the owner (proceed on the stated assumption):",
+        ...(briefing.parked.length === 0
+            ? ["- none"]
+            : briefing.parked.map((turn) => `- #${turn.id} ${turn.speaker}: ${turn.body}${turn.assumption === undefined ? "" : ` (assuming: ${turn.assumption})`}`)),
+        "",
+        `Agenda item ${renderAgendaItem(item)}`,
+        `Round ${round} of at most ${caps.roundsPerItem}.`,
+        ...(isReview
+            ? [
+                "",
+                "The Scribe has written outline.md and plan.md from the discussion. Review them from your mandate: object (blocking only for what makes them wrong or unusable), agree, or pass."
+            ]
+            : []),
+        "",
+        "The discussion on this item so far:",
+        ...(briefing.current.length === 0
+            ? ["(nobody has spoken yet)"]
+            : briefing.current.map(renderTurn)),
+        "",
+        ...(addressed.length === 0
+            ? []
+            : ["Aimed at your earlier turns, still open:", ...addressed.map(renderTurn), ""]),
+        kindsGuide,
+        "",
+        `Speak as the ${persona.name}, in your voice, once. Answer turns by their #id on this item only. Keep the body to a short paragraph.`,
+        "",
+        'Reply with JSON: {"kind": "position|proposal|objection|question|agreement|pass", "answers": [ids], "blocking": false, "needsHuman": false, "assumption": "optional", "body": "..."}'
+    ].join("\n");
+};
+const draftPrompt = (options) => {
+    const { scribe, meeting, docs, budget, previous } = options;
+    return [
+        personaBrief(scribe),
+        "",
+        meetingBrief(meeting),
+        contextBrief(docs, budget),
+        "",
+        previous === undefined
+            ? "Write the two deliverables from the transcript below. Say what the room settled; keep every decision's dissent visible; where a question is parked for the owner, state the assumption the document rests on. Do not invent decisions the room did not take."
+            : "Revise the two deliverables below so that every blocking objection from the review is addressed. Change nothing the objections do not touch.",
+        "",
+        ...(previous === undefined
+            ? []
+            : [
+                "Blocking objections from the review:",
+                ...previous.objections.map(renderTurn),
+                "",
+                "Current outline.md:",
+                cap(previous.outline, Math.floor(budget / 6)).text,
+                "",
+                "Current plan.md:",
+                cap(previous.plan, Math.floor(budget / 6)).text,
+                ""
+            ]),
+        "Decisions (as recorded):",
+        cap(options.decisions, Math.floor(budget / 6)).text,
+        "",
+        "Open questions (as recorded):",
+        cap(options.openQuestions, Math.floor(budget / 8)).text,
+        "",
+        "Transcript:",
+        cap(options.discussion, Math.floor(budget / 2)).text,
+        "",
+        "Outline sections:",
+        scribe.outlineTemplate ??
+            "## Context\n## Proposed solution\n## Risks\n## Open questions and assumptions",
+        "",
+        "Plan sections:",
+        scribe.planTemplate ?? "## Phases\n## Workstreams and owners\n## Risks and mitigations",
+        "",
+        'Reply with JSON: {"outline": "<complete markdown document>", "plan": "<complete markdown document>"}'
+    ].join("\n");
+};
+/** The meeting, driven from its files until it halts for the person or is done. */
+export const runRoundtable = Effect.fn("roundtable.run")(function* (deps) {
+    const { files, events, caps } = deps;
+    const dir = meetingDir(deps.workDir, deps.meetingId);
+    const paths = meetingFiles(dir);
+    const say = (message) => events.publish(Info.make({ message }));
+    const save = (meeting) => files.writeAtomic(paths.meeting, renderMeeting(meeting));
+    const loaded = yield* loadMeeting(files, paths.meeting);
+    let meeting;
+    if (loaded === undefined) {
+        const topic = (deps.topic ?? "").trim();
+        const goal = (deps.goal ?? "").trim();
+        if (topic.length === 0 || goal.length === 0) {
+            return yield* ScriptUsage.make({
+                message: `no meeting at ${paths.meeting}: give the topic and --goal to start one\n${roundtableUsage}`
+            });
+        }
+        meeting = Meeting.make({
+            id: deps.meetingId,
+            status: "agenda-proposed",
+            topic,
+            goal,
+            attendees: deps.attendees.map((persona) => persona.name),
+            agenda: [],
+            answers: [],
+            feedback: "",
+            drafts: 0
+        });
+        yield* save(meeting);
+        yield* say(`roundtable: ${paths.meeting} opened — ${meeting.attendees.join(", ")}`);
+    }
+    else {
+        meeting = loaded;
+    }
+    // Every attendee is a lane in the dashboard, from the first event of the run (ADR 0046).
+    for (const name of meeting.attendees) {
+        yield* events.publish(StageStarted.make({ stage: `attendee ${name}`, lane: name }));
+    }
+    const personaOf = (name) => deps.attendees.find((persona) => persona.name === name);
+    for (const name of meeting.attendees) {
+        if (personaOf(name) === undefined) {
+            return yield* ScriptUsage.make({
+                message: `the meeting lists attendee ${name} but no such persona is known; pass --agents with the meeting's attendees, or add .llm4ts/personas/${name}.md`
+            });
+        }
+    }
+    let turns = yield* decodeTurns((yield* files.read(paths.turns)) ?? "", paths.turns);
+    const appendTurn = (turn) => Effect.gen(function* () {
+        yield* files.append(paths.turns, `${encodeTurn(turn)}\n`);
+        turns = [...turns, turn];
+        yield* files.writeAtomic(paths.discussion, renderDiscussion(meeting, turns, caps));
+        const synced = syncAnswers(meeting, turns);
+        if (synced.answers.length !== meeting.answers.length) {
+            meeting = synced;
+            yield* save(meeting);
+        }
+        yield* events.publish(RoundtableTurn.make({
+            lane: turn.speaker,
+            meeting: meeting.id,
+            item: turn.item,
+            itemTitle: itemOf(meeting, turn.item)?.title ?? "",
+            round: turn.round,
+            turn: turn.id,
+            kind: turn.kind,
+            blocking: turn.blocking,
+            answers: turn.answers,
+            summary: firstLine(turn.body)
+        }));
+    });
+    // The item under discussion is the run's open stage.
+    let openItem;
+    const itemStage = (item) => `item ${item.number}: ${item.title}`;
+    const leaveItem = () => Effect.gen(function* () {
+        if (openItem === undefined)
+            return;
+        yield* events.publish(StageCompleted.make({ stage: itemStage(openItem) }));
+        openItem = undefined;
+    });
+    const enterItem = (item) => Effect.gen(function* () {
+        if (openItem?.number === item.number)
+            return;
+        yield* leaveItem();
+        yield* events.publish(StageStarted.make({ stage: itemStage(item) }));
+        openItem = item;
+    });
+    const writeRecords = () => Effect.gen(function* () {
+        yield* files.writeAtomic(paths.decisions, renderDecisions(meeting, turns, caps));
+        yield* files.writeAtomic(paths.openQuestions, renderOpenQuestions(meeting, turns, caps));
+    });
+    const askScribe = (previous) => Effect.gen(function* () {
+        const proposal = yield* structuredAndPublish(deps.seat, events, draftPrompt({
+            scribe: deps.scribe,
+            meeting,
+            discussion: renderDiscussion(meeting, turns, caps),
+            decisions: renderDecisions(meeting, turns, caps),
+            openQuestions: renderOpenQuestions(meeting, turns, caps),
+            docs: deps.context,
+            budget: deps.budget,
+            ...(previous === undefined ? {} : { previous })
+        }), DraftProposal, draftProposalJsonSchema, "scribe");
+        yield* files.writeAtomic(paths.outline, `${proposal.outline.trim()}\n`);
+        yield* files.writeAtomic(paths.plan, `${proposal.plan.trim()}\n`);
+    });
+    let guard = 0;
+    for (;;) {
+        guard += 1;
+        if (guard > caps.maxTurns * 4 + 64) {
+            return yield* FlowAborted.make({
+                message: `roundtable ${deps.meetingId}: the chair did not reach an end after ${guard} steps; the files under ${dir} are intact`
+            });
+        }
+        const action = nextAction(meeting, turns, caps);
+        switch (action._tag) {
+            case "Refused":
+                return yield* ScriptUsage.make({
+                    message: `roundtable ${deps.meetingId}: ${action.reason}`
+                });
+            case "Done":
+                return {
+                    _tag: "NothingToDo",
+                    message: `meeting ${deps.meetingId} is done; answer a question under '## Answers' or write '## Feedback' in ${paths.meeting} to reopen it`
+                };
+            case "ProposeAgenda": {
+                const persona = personaOf(action.speaker) ?? deps.attendees[0];
+                if (persona === undefined) {
+                    return yield* ScriptUsage.make({ message: "the meeting has no attendees" });
+                }
+                const proposal = yield* structuredAndPublish(deps.seat, events, agendaPrompt(persona, meeting, deps.context, deps.budget), AgendaProposal, agendaProposalJsonSchema, persona.name);
+                const items = assembleAgenda(proposal);
+                if (items.length === 0) {
+                    return yield* FlowAborted.make({
+                        message: `${persona.name} proposed no agenda item; rerun`
+                    });
+                }
+                meeting = Meeting.make({ ...meeting, agenda: items });
+                yield* save(meeting);
+                yield* say(`roundtable: ${persona.name} proposed ${items.length} agenda item(s):\n${items.map((item) => `  ${renderAgendaItem(item)}`).join("\n")}`);
+                if (!deps.noPause) {
+                    return yield* AgendaPending.make({ path: paths.meeting, items: items.length });
+                }
+                continue;
+            }
+            case "OpenDiscussion":
+                meeting = Meeting.make({ ...meeting, status: "discussing" });
+                yield* save(meeting);
+                yield* say(`roundtable: discussing ${meeting.agenda.length} item(s) plus the goal check, ${meeting.attendees.length} attendees, up to ${caps.roundsPerItem} rounds each`);
+                continue;
+            case "RecordOwner": {
+                const recorded = recordOwner(meeting, turns, action);
+                for (const turn of recorded) {
+                    yield* appendTurn(turn);
+                    yield* say(renderTurn(turn));
+                }
+                meeting = Meeting.make({ ...meeting, status: "discussing", feedback: "" });
+                yield* save(meeting);
+                continue;
+            }
+            case "Judge": {
+                yield* enterItem(action.item);
+                const result = yield* judgeOrEscalate({
+                    judgment: deps.judgment,
+                    reasoning: deps.seat,
+                    events,
+                    request: {
+                        state: {
+                            question: action.item.question,
+                            objection: `${action.objection.speaker}: ${action.objection.body}`,
+                            reply: `${action.reply.speaker}: ${action.reply.body}`
+                        },
+                        questions: {
+                            resolved: truth("The reply answers the objection well enough that a reasonable objector would withdraw it.")
+                        }
+                    }
+                });
+                const answer = yield* truthOf(result, "resolved").pipe(Effect.option);
+                const resolved = answer._tag === "Some" && decide(answer.value) !== "hold" && answer.value.truth >= 0.5;
+                const probability = answer._tag === "Some" ? answer.value.truth.toFixed(2) : "n/a";
+                const chair = Turn.make({
+                    id: turns.length + 1,
+                    round: action.reply.round,
+                    item: action.item.number,
+                    speaker: chairSpeaker,
+                    kind: resolved ? "agreement" : "position",
+                    answers: [action.objection.id],
+                    blocking: false,
+                    needsHuman: false,
+                    body: resolved
+                        ? `Judged resolved by #${action.reply.id} (p=${probability}).`
+                        : `Judged still open after #${action.reply.id} (p=${probability}); ${action.objection.speaker} may close it or the item is left open at the cap.`
+                });
+                yield* appendTurn(chair);
+                yield* say(renderTurn(chair));
+                continue;
+            }
+            case "Speak": {
+                yield* enterItem(action.item);
+                const persona = personaOf(action.speaker);
+                if (persona === undefined) {
+                    return yield* ScriptUsage.make({ message: `no persona for ${action.speaker}` });
+                }
+                const proposal = yield* structuredAndPublish(deps.seat, events, turnPrompt({
+                    persona,
+                    meeting,
+                    item: action.item,
+                    round: action.round,
+                    caps,
+                    turns,
+                    addressed: action.addressed,
+                    docs: deps.context,
+                    budget: deps.budget
+                }), TurnProposal, turnProposalJsonSchema, persona.name);
+                const turn = assembleTurn(proposal, {
+                    id: turns.length + 1,
+                    round: action.round,
+                    item: action.item.number,
+                    speaker: persona.name,
+                    existing: turns
+                });
+                yield* appendTurn(turn);
+                yield* say(`[item ${action.item.number}, round ${action.round}] ${renderTurn(turn)}`);
+                const state = itemState(meeting, turns, action.item.number, caps);
+                if (state.settled)
+                    yield* say(`item ${action.item.number} settled.`);
+                else if (state.capped)
+                    yield* say(`item ${action.item.number} left open at the cap.`);
+                continue;
+            }
+            case "Draft": {
+                yield* leaveItem();
+                if (meeting.status !== "drafting") {
+                    meeting = Meeting.make({ ...meeting, status: "drafting" });
+                    yield* save(meeting);
+                }
+                yield* writeRecords();
+                yield* askScribe();
+                meeting = Meeting.make({ ...meeting, status: "reviewing", drafts: meeting.drafts + 1 });
+                yield* save(meeting);
+                yield* say(`scribe: draft ${meeting.drafts} written — ${paths.outline}, ${paths.plan}, ${paths.decisions}, ${paths.openQuestions}`);
+                continue;
+            }
+            case "Finalize": {
+                yield* leaveItem();
+                if (action.objections.length > 0) {
+                    const outline = (yield* files.read(paths.outline)) ?? "";
+                    const plan = (yield* files.read(paths.plan)) ?? "";
+                    yield* askScribe({ outline, plan, objections: action.objections });
+                    yield* say(`scribe: fix pass for ${action.objections.length} blocking objection(s)`);
+                }
+                yield* writeRecords();
+                meeting = Meeting.make({ ...meeting, status: "done" });
+                yield* save(meeting);
+                const parked = meeting.answers.filter((point) => (point.answer ?? "").trim().length === 0);
+                const closing = closingItem(meeting);
+                const open = [...meeting.agenda, closing].filter((item) => !itemState(meeting, turns, item.number, caps).settled);
+                const summary = [
+                    `roundtable ${deps.meetingId} done after ${turns.length} turns and ${meeting.drafts} draft(s)`,
+                    `outline: ${paths.outline}`,
+                    `plan: ${paths.plan}`,
+                    `decisions: ${paths.decisions}`,
+                    `open questions: ${paths.openQuestions}${open.length === 0 ? "" : ` (${open.length} item(s) left open)`}`,
+                    ...(parked.length === 0
+                        ? []
+                        : [
+                            `${parked.length} question(s) for you under '## Answers' in ${paths.meeting}; answer and rerun to fold them in`
+                        ])
+                ];
+                for (const line of summary)
+                    yield* say(line);
+                for (const name of meeting.attendees) {
+                    yield* events.publish(StageCompleted.make({ stage: `attendee ${name}`, lane: name }));
+                }
+                return { _tag: "Finished", summary };
+            }
+        }
+    }
+});
+/**
+ * The first line of a turn's body, cut short: what the dashboard shows on
+ * the lane. A model's reply is untrusted text on its way to a terminal:
+ * escape sequences and control characters are dropped, not painted.
+ */
+const firstLine = (text) => {
+    const line = terminalSafe(text.split(/\r?\n/)[0] ?? "")
+        // eslint-disable-next-line no-control-regex
+        .replace(/[\u0000-\u001f\u007f-\u009f]/g, "")
+        .replace(/\s+/g, " ")
+        .trim();
+    return line.length > 80 ? `${line.slice(0, 77)}...` : line;
+};
+const loadMeeting = Effect.fn("roundtable.loadMeeting")(function* (files, path) {
+    const text = yield* files.read(path);
+    if (text === undefined)
+        return undefined;
+    return yield* parseMeeting(text, path);
+});
+/** Markdown of the bundled and custom cards, for `--list` and for the docs. */
+export const describePersonas = (personas) => personas.map((persona) => `- ${persona.name}: ${persona.mandate}`).join("\n");

package/flows/roundtable.js

@@ -0,0 +1,163 @@
+// Run a meeting of personas on a topic toward a goal: they discuss item by item, a Scribe writes the solution outline and the plan, you steer from the meeting file.
+//
+//   llm4ts run roundtable --repo ~/work/portal "Architecture outline for the payments hub" \
+//     -- --goal "An outline and a plan the committee can approve, within our standards" \
+//        --agents "PO,PM,Sr SW Eng,Cloud Architect,DevOps,SRE" --context docs/standards
+//   llm4ts run roundtable --repo ~/work/portal -- --meeting payments-hub     # continue, or fold in your answers
+//   llm4ts run roundtable --repo ~/work/portal -- --eject-personas           # the bundled cards, to edit
+//   llm4ts run roundtable --repo ~/work/portal -- --list                     # meetings and personas
+//
+// Code chairs the meeting (ADR 0046). The first attendee proposes the agenda;
+// the run stops for you to edit it unless --no-pause. Then every attendee is
+// asked once per round, in persona order, on each item: a position, a
+// proposal, an objection (blocking or not), a question (for the room, or
+// parked for you), an agreement, or a pass. An item settles after a complete
+// round with no open blocking objection and no open question; silence is
+// consent. Three rounds per item (--rounds), forty turns in all (--max-turns);
+// what is still open is written down, never forced. Then the Scribe writes
+// outline.md and plan.md, code renders decisions.md (with the dissent) and
+// open-questions.md, every attendee reviews once, the Scribe fixes what
+// blocks, and the meeting is done.
+//
+// The FILE is the state: <repo>/.llm4ts/meetings/<id>/meeting.md. Answer a
+// parked question under `## Answers`, or write under `## Feedback`, and
+// rerun: your words become turns, the item reopens for one more round and the
+// drafts are rewritten. Personas are cards: bundled ones, replaced by
+// .llm4ts/personas/<name>.md of the same name. Every persona borrows one
+// read-only, toolless seat: LLM4TS_REASONER (default claude). --context
+// gives every attendee the same documents, under LLM4TS_CONTEXT_BUDGET.
+// Nothing in the repository's git is touched.
+import { readdir } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import * as Console from "effect/Console";
+import * as Effect from "effect/Effect";
+import { budget } from "@llm4ts/flow/Context";
+import { judgmentOf } from "@llm4ts/flow/Judgment";
+import { parseMeeting } from "@llm4ts/flow/Roundtable";
+import { ScriptUsage, asToolless, nodePlainFileStore, resolveFlowInput, runFlowMain, runNode, stage } from "@llm4ts/runner";
+import { reasonerFromEnvironment } from "./lib/epic-stories.js";
+import { describePersonas, ejectPersonas, meetingDir, meetingSlug, meetingsDir, parseRoundtableArgs, personasDir, resolvePersonas, runRoundtable } from "./lib/roundtable.js";
+import { defaultAttendees } from "./lib/roundtable-personas.js";
+const files = nodePlainFileStore;
+const namesIn = (dir, suffix) => Effect.tryPromise(() => readdir(dir, { withFileTypes: true })).pipe(Effect.map((entries) => entries
+    .filter((entry) => entry.isFile() && entry.name.endsWith(suffix))
+    .map((entry) => entry.name.slice(0, -suffix.length))
+    .sort()), Effect.catch(() => Effect.succeed([])));
+const foldersIn = (dir) => Effect.tryPromise(() => readdir(dir, { withFileTypes: true })).pipe(Effect.map((entries) => entries
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => entry.name)
+    .sort()), Effect.catch(() => Effect.succeed([])));
+/** `.llm4ts/personas/<name>.md`, keyed by name. */
+const customCards = Effect.fn("roundtable.customCards")(function* (workDir) {
+    const dir = personasDir(workDir);
+    const names = yield* namesIn(dir, ".md");
+    const cards = {};
+    for (const name of names) {
+        const text = yield* files.read(join(dir, `${name}.md`));
+        if (text !== undefined)
+            cards[name] = text;
+    }
+    return cards;
+});
+const textLike = /\.(md|markdown|txt|adoc|rst)$/i;
+/** Every text document under `--context`, recursively, in path order. */
+const contextDocs = Effect.fn("roundtable.contextDocs")(function* (dir) {
+    if (dir === undefined)
+        return [];
+    const entries = yield* Effect.tryPromise(() => readdir(dir, { withFileTypes: true, recursive: true })).pipe(Effect.catch(() => ScriptUsage.make({ message: `--context ${dir} is not a readable directory` })));
+    const paths = entries
+        .filter((entry) => entry.isFile() && textLike.test(entry.name))
+        .map((entry) => join(entry.parentPath, entry.name))
+        .sort();
+    const docs = [];
+    for (const path of paths) {
+        const text = yield* files.read(path);
+        if (text !== undefined)
+            docs.push({ path: path.slice(dir.length + 1), text });
+    }
+    return docs;
+});
+const program = Effect.gen(function* () {
+    const flags = yield* parseRoundtableArgs(process.argv.slice(2));
+    const given = yield* resolveFlowInput("", flags.rest);
+    const workDir = given.workDir;
+    if (flags.ejectPersonas) {
+        const written = yield* ejectPersonas(files, workDir);
+        yield* Console.log(written.length === 0
+            ? `every bundled card is already under ${personasDir(workDir)}`
+            : `wrote ${written.length} card(s):\n${written.map((path) => `  ${path}`).join("\n")}`);
+        return;
+    }
+    const custom = yield* customCards(workDir);
+    if (flags.list) {
+        const ids = yield* foldersIn(meetingsDir(workDir));
+        const lines = [];
+        for (const id of ids) {
+            const text = yield* files.read(join(meetingDir(workDir, id), "meeting.md"));
+            const meeting = text === undefined ? undefined : yield* parseMeeting(text).pipe(Effect.option);
+            lines.push(meeting === undefined || meeting._tag === "None"
+                ? `  ${id}  (no readable meeting.md)`
+                : `  ${id}  ${meeting.value.status}  ${meeting.value.topic}`);
+        }
+        const personas = yield* resolvePersonas(custom, defaultAttendees);
+        yield* Console.log([
+            lines.length === 0 ? `no meetings under ${meetingsDir(workDir)}` : "meetings:",
+            ...lines,
+            "",
+            `personas (bundled${Object.keys(custom).length === 0 ? "" : `, ${Object.keys(custom).length} custom`}):`,
+            describePersonas([...personas.attendees, personas.scribe])
+        ].join("\n"));
+        return;
+    }
+    const topic = given.prompt.trim();
+    const meetingId = flags.meeting ?? (topic.length === 0 ? undefined : meetingSlug(topic));
+    if (meetingId === undefined) {
+        return yield* ScriptUsage.make({
+            message: `give the topic to start a meeting, or --meeting <id> to continue one`
+        });
+    }
+    // An existing meeting's attendees are the file's; --agents only seats a new one.
+    const existing = yield* files.read(join(meetingDir(workDir, meetingId), "meeting.md"));
+    const attendeeNames = existing === undefined
+        ? (flags.agents ?? defaultAttendees)
+        : (yield* parseMeeting(existing, join(meetingDir(workDir, meetingId), "meeting.md")))
+            .attendees;
+    const personas = yield* resolvePersonas(custom, attendeeNames);
+    // Relative to the repository: the standards usually live beside the code.
+    const docs = yield* contextDocs(flags.context === undefined ? undefined : resolve(workDir, flags.context));
+    const reasoning = asToolless(yield* reasonerFromEnvironment(process.env));
+    const outcome = yield* runNode({
+        workDir,
+        workspace: given.workspace,
+        userPrompt: topic.length === 0 ? `roundtable ${meetingId}` : topic,
+        // No coder turn is ever taken: the toolless reasoning seat fills both.
+        coder: reasoning,
+        reasoning,
+        environment: process.env
+    }, (context) => stage(context.events, "roundtable", runRoundtable({
+        files,
+        events: context.events,
+        seat: context.reasoning,
+        judgment: judgmentOf(context),
+        workDir,
+        meetingId,
+        topic,
+        goal: flags.goal,
+        attendees: personas.attendees,
+        scribe: personas.scribe,
+        context: docs,
+        caps: {
+            roundsPerItem: flags.rounds ?? 3,
+            maxTurns: flags.maxTurns ?? 40
+        },
+        noPause: flags.noPause,
+        budget: budget(process.env)
+    })));
+    if (outcome._tag === "NothingToDo") {
+        yield* Console.log(outcome.message);
+    }
+    else {
+        yield* Console.log(outcome.summary.join("\n"));
+    }
+});
+runFlowMain(program);

package/package.json

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