@llm4ts/shell 2.52.0 → 2.53.0

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.52.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/core": "2.52.0",
-    "@llm4ts/flow": "2.52.0",
-    "@llm4ts/runner": "2.52.0"
+    "@llm4ts/core": "2.53.0",
+    "@llm4ts/flow": "2.53.0",
+    "@llm4ts/runner": "2.53.0"
   },
   "peerDependencies": {
     "effect": "4.0.0"