@danypops/papyrus 0.27.14 → 0.28.0

package/extension/src/discuss-ask-view.ts

@@ -56,6 +56,9 @@ export type AskDisplayMode = "overlay" | "inline";
 export interface AskQuestionParams {
 	question: string;
 	context?: string;
+	/** Plain orientation line ("which discussion is this"), shown dim above the question -- not a
+	 * labeled section like context. Typically the Discussion's own title. */
+	subtitle?: string;
 	options?: AskOption[];
 	allowMultiple?: boolean;
 	allowFreeform?: boolean;
@@ -621,6 +624,7 @@ class AskComponent extends Container {
 	constructor(
 		private question: string,
 		private context: string | undefined,
+		private subtitle: string | undefined,
 		private options: AskOption[],
 		private allowMultiple: boolean,
 		private allowFreeform: boolean,
@@ -781,6 +785,9 @@ class AskComponent extends Container {
 				"",
 			];
 		}
+		// Only meaningful when reached by escaping OUT of a real select list -- see showFreeformMode's
+		// identical guard for the non-overlay layout.
+		if (this.options.length === 0) return [];
 		return [...new Text(this.theme.fg("accent", this.theme.bold("Custom answer")), 1, 0).render(width), ""];
 	}
 
@@ -864,7 +871,11 @@ class AskComponent extends Container {
 
 	private updateStaticText(): void {
 		const theme = this.theme;
-		this.titleText.setText(theme.fg("accent", theme.bold(this.mode === "comment" ? "Optional comment" : "Question")));
+		// Reuses the same slot for two different purposes: a plain "which discussion is this" subtitle
+		// normally, or "Optional comment" while in comment mode. A generic "Question" header above the
+		// real question text added nothing beyond what the question itself already says, and read
+		// confusingly like the question text WAS the header.
+		this.titleText.setText(this.mode === "comment" ? theme.fg("accent", theme.bold("Optional comment")) : this.subtitle ? theme.fg("dim", this.subtitle) : "");
 		this.questionText.setText(theme.fg("text", theme.bold(this.question)));
 		if (this.contextComponent && this.context) {
 			if (this.contextComponent instanceof Markdown) (this.contextComponent as Markdown).setText(`**Context:**\n${this.context}`);
@@ -985,8 +996,13 @@ class AskComponent extends Container {
 		const editor = this.ensureEditor();
 		this.setEditorText(this.freeformDraft);
 		(editor as any).focused = this._focused;
-		this.modeContainer.addChild(new Text(this.theme.fg("accent", this.theme.bold("Custom answer")), 1, 0));
-		this.modeContainer.addChild(new Spacer(1));
+		// Only meaningful when reached by escaping OUT of a real select list ("instead of these
+		// options, here's a custom one") -- with no options at all there's nothing to contrast
+		// against, so the label is pure noise.
+		if (this.options.length > 0) {
+			this.modeContainer.addChild(new Text(this.theme.fg("accent", this.theme.bold("Custom answer")), 1, 0));
+			this.modeContainer.addChild(new Spacer(1));
+		}
 		this.modeContainer.addChild(editor);
 		this.updateHelpText();
 		this.invalidate();
@@ -1165,7 +1181,7 @@ async function askQuestionBlocking(
 		const factory = (tui: TUI, theme: Theme, keybindings: KeybindingsManager, done: (result: AskResponse | null) => void) => {
 			if (params.signal) params.signal.addEventListener("abort", () => done(null), { once: true });
 			if (params.timeout && params.timeout > 0) setTimeout(() => done(null), params.timeout);
-			return new AskComponent(params.question, normalizedContext, options, allowMultiple, allowFreeform, allowComment, displayMode, tui, theme, keybindings, shortcuts, done);
+			return new AskComponent(params.question, normalizedContext, params.subtitle, options, allowMultiple, allowFreeform, allowComment, displayMode, tui, theme, keybindings, shortcuts, done);
 		};
 
 		const overlayToggle = shortcuts.overlayToggle;

package/extension/src/discuss.ts

@@ -82,14 +82,15 @@ export async function showDiscussions(ctx: ExtensionCommandContext): Promise<voi
 			}
 			if (choice === "Reply") {
 				const pending = (() => { try { return readDiscussionExtra(discussion.extra); } catch { return undefined; } })();
-				const question = `Reply to "${discussion.title}":`;
-				// Same fix as the live discuss tool: the title alone isn't the actual question -- show
-				// the most recent round's real content as context, not a bare title prompt.
+				// Same fix as the live discuss tool: the most recent round's own content IS the real
+				// question -- the title becomes a plain orientation subtitle, not a labeled-backwards
+				// "Context:" section under a generic "Reply to <title>:" wrapper.
 				const transcript = await callService<Record<string, unknown>, DiscussionAndRounds>("discuss.show", { id: discussion.id });
-				const context = transcript.rounds.at(-1)?.content?.trim() || undefined;
+				const question = transcript.rounds.at(-1)?.content?.trim() || `Reply to "${discussion.title}":`;
+				const subtitle = discussion.title;
 				const answer = pending?.pendingOptions && pending.pendingOptions.length > 0 && pending.pendingOptionsMode
-					? await askQuestion(commandCtx, { question, context, options: pending.pendingOptions.map((title) => ({ title })), allowMultiple: pending.pendingOptionsMode === "multi" })
-					: await askQuestion(commandCtx, { question, context });
+					? await askQuestion(commandCtx, { question, subtitle, options: pending.pendingOptions.map((title, index) => ({ title, description: pending.pendingOptionDescriptions?.[index] || undefined })), allowMultiple: pending.pendingOptionsMode === "multi" })
+					: await askQuestion(commandCtx, { question, subtitle });
 				if (!answer) return; // canceled
 				await callService("discuss.reply", { id: discussion.id, actor: ACTOR, content: answer.content, ...(answer.selected ? { selected: answer.selected } : {}), source: SOURCE });
 				commandCtx.ui.notify(answer.selected ? `Selected: ${answer.selected.join(", ")}` : "Reply added.", "info");

package/extension/src/domain-tools.ts

@@ -39,25 +39,55 @@ function text(message: string, details: unknown = {}) {
  * is available, never throws -- an unanswered live prompt still leaves the round it already
  * recorded intact.
  */
+/**
+ * The discuss tool accepts each option as either a bare string (self-evident choices) or
+ * {title, description} (a real tradeoff worth spelling out) -- normalizes to the two parallel
+ * arrays discuss.open/discuss.reply actually expect (options: string[], option_descriptions:
+ * string[], index-aligned, empty string meaning "none for this one"). Mutates params in place.
+ */
+function normalizeDiscussOptions(params: Record<string, unknown>): void {
+	const raw = params.options;
+	if (!Array.isArray(raw)) return;
+	let anyDescription = false;
+	const titles: string[] = [];
+	const descriptions: string[] = [];
+	for (const entry of raw) {
+		if (typeof entry === "string") { titles.push(entry); descriptions.push(""); continue; }
+		if (entry && typeof entry === "object" && typeof (entry as Record<string, unknown>).title === "string") {
+			const record = entry as Record<string, unknown>;
+			titles.push(record.title as string);
+			const description = typeof record.description === "string" ? record.description : "";
+			if (description) anyDescription = true;
+			descriptions.push(description);
+			continue;
+		}
+		titles.push(String(entry));
+		descriptions.push("");
+	}
+	params.options = titles;
+	if (anyDescription) params.option_descriptions = descriptions;
+}
+
 async function liveAnswer(ctx: ExtensionContext, discussion: Artifact, latestContent: string | undefined, onUpdate: AgentToolUpdateCallback | undefined, signal: AbortSignal | undefined): Promise<{ content: string; selected?: string[] } | undefined> {
 	if (!ctx.hasUI) return undefined;
 	const pending = (() => { try { return readDiscussionExtra(discussion.extra); } catch { return undefined; } })();
-	const question = `Reply to "${discussion.title}":`;
-	// The discussion's title alone is often not the actual question -- a human staring at a bare
-	// "Reply to '<title>':" prompt with no visible content has no way to tell what's being asked.
-	// The just-recorded round's own content is the real question text; show it as context.
-	const context = latestContent?.trim() || undefined;
+	// The just-recorded round's own content IS the real question -- a generic "Reply to <title>:"
+	// wrapper as the primary question, with the real content demoted to "Context:", left a human
+	// staring at a labeled-backwards prompt (live-observed). The wrapper is now only a fallback for
+	// the degenerate case of empty content; the title becomes a plain orientation subtitle instead.
+	const question = latestContent?.trim() || `Reply to "${discussion.title}":`;
+	const subtitle = discussion.title;
 	if (pending?.pendingOptions && pending.pendingOptions.length > 0 && pending.pendingOptionsMode) {
 		return askQuestion(ctx, {
 			question,
-			context,
-			options: pending.pendingOptions.map((title) => ({ title })),
+			subtitle,
+			options: pending.pendingOptions.map((title, index) => ({ title, description: pending.pendingOptionDescriptions?.[index] || undefined })),
 			allowMultiple: pending.pendingOptionsMode === "multi",
 			onUpdate,
 			signal,
 		});
 	}
-	return askQuestion(ctx, { question, context, onUpdate, signal });
+	return askQuestion(ctx, { question, subtitle, onUpdate, signal });
 }
 
 /**
@@ -680,7 +710,7 @@ export function registerDomainTools(pi: ExtensionAPI): void {
 	pi.registerTool({
 		name: "discuss",
 		label: "Discuss",
-		description: "Native Papyrus deliberation with a real lifecycle -- distinct from a one-shot ask: a Discussion persists, takes multiple rounds, and can genuinely block a Task's completion until settled or deferred. ACTIONS: open, reply, defer, resume, settle, block, unblock, show, rounds, list. open starts round 1 and optionally blocks_task_ids immediately. reply is refused once deferred or settled -- resume first. defer is explicitly non-blocking (paused, resumable); settle is terminal and archives the discussion. block/unblock manage the blocking relationship to a task independently of open. A task's completion is refused while any active Discussion blocks it. open/reply can pose a structured choice via options (2-10 entries) + options_mode ('single' mutually exclusive, 'multi' allows several); reply answers a currently pending choice via selected, validated against it. Pass live:true on open or reply to get the human's answer synchronously in this same call, via an interactive prompt (the pending choice's picker if one was posed, otherwise a freeform question) -- covers a completely open question with no artifact (open with no prior discussion) and a question tied to a specific existing artifact (reply, addressed by name) alike. Only takes effect with an interactive UI available; otherwise degrades silently to the normal async round. PREFER `name` (the discussion's exact title) over `id`, `task_name`/`blocks_task_names` over `task_id`/`blocks_task_ids` -- all are backend implementation details, resolved from name automatically.",
+		description: "Native Papyrus deliberation with a real lifecycle -- distinct from a one-shot ask: a Discussion persists, takes multiple rounds, and can genuinely block a Task's completion until settled or deferred. ACTIONS: open, reply, defer, resume, settle, block, unblock, show, rounds, list. open starts round 1 and optionally blocks_task_ids immediately. reply is refused once deferred or settled -- resume first. defer is explicitly non-blocking (paused, resumable); settle is terminal and archives the discussion. block/unblock manage the blocking relationship to a task independently of open. A task's completion is refused while any active Discussion blocks it. open/reply can pose a structured choice via options (2-10 entries) + options_mode ('single' mutually exclusive, 'multi' allows several); reply answers a currently pending choice via selected, validated against it. Each option is either a bare string (fine for a self-evident choice like yes/no) or {title, description} -- add a description only when there's a genuine tradeoff, risk, or consequence worth conveying (a real pro/con), keep it to one line, and never pad it with something the title already says; skip descriptions entirely when the options don't need them. Pass live:true on open or reply to get the human's answer synchronously in this same call, via an interactive prompt (the pending choice's picker if one was posed, otherwise a freeform question) -- covers a completely open question with no artifact (open with no prior discussion) and a question tied to a specific existing artifact (reply, addressed by name) alike. Only takes effect with an interactive UI available; otherwise degrades silently to the normal async round. PREFER `name` (the discussion's exact title) over `id`, `task_name`/`blocks_task_names` over `task_id`/`blocks_task_ids` -- all are backend implementation details, resolved from name automatically.",
 		parameters: Type.Object({
 			action: Type.String(),
 			id: Type.Optional(Type.String()),
@@ -699,7 +729,7 @@ export function registerDomainTools(pi: ExtensionAPI): void {
 			state: Type.Optional(Type.String()),
 			after_round: Type.Optional(Type.Number()),
 			limit: Type.Optional(Type.Number()),
-			options: Type.Optional(Type.Array(Type.String())),
+			options: Type.Optional(Type.Array(Type.Union([Type.String(), Type.Object({ title: Type.String(), description: Type.Optional(Type.String()) })]))),
 			options_mode: Type.Optional(Type.String()),
 			selected: Type.Optional(Type.Array(Type.String())),
 			live: Type.Optional(Type.Boolean()),
@@ -721,6 +751,7 @@ export function registerDomainTools(pi: ExtensionAPI): void {
 				]);
 				await resolveNameArrayField(params, "blocks_task_names", "blocks_task_ids", "tasks.list", taskScope);
 				if (action === "open" || action === "reply") {
+					normalizeDiscussOptions(params);
 					const operation = action === "open" ? "discuss.open" : "discuss.reply";
 					const result = await callService<Record<string, unknown>, DiscussionAndRounds>(operation, params);
 					const fallback = action === "open"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danypops/papyrus",
-  "version": "0.27.14",
+  "version": "0.28.0",
   "description": "Daemon-backed graph artifacts, evidence-bearing tasks, rules, skills, and native TUI workflows for Pi",
   "type": "module",
   "keywords": ["pi-package"],

package/src/adapters/sqlite-discussion-round-store.ts

@@ -21,6 +21,7 @@ interface DiscussionRoundRow {
 	options: string | null;
 	options_mode: string | null;
 	selected: string | null;
+	option_descriptions: string | null;
 }
 
 function mapRow(row: DiscussionRoundRow): DiscussionRound {
@@ -34,6 +35,7 @@ function mapRow(row: DiscussionRoundRow): DiscussionRound {
 		...(row.options !== null ? { options: JSON.parse(row.options) as string[] } : {}),
 		...(row.options_mode !== null ? { optionsMode: row.options_mode as DiscussionOptionsMode } : {}),
 		...(row.selected !== null ? { selected: JSON.parse(row.selected) as string[] } : {}),
+		...(row.option_descriptions !== null ? { optionDescriptions: JSON.parse(row.option_descriptions) as string[] } : {}),
 	};
 }
 
@@ -47,16 +49,17 @@ export class SQLiteDiscussionRoundStore implements DiscussionRoundStore {
 		// currently pending options (extra.discussion), which this store, deliberately scoped to
 		// the rounds table alone, has no access to. discussion-service.ts validates it beforehand.
 		const posed = round.options !== undefined || round.optionsMode !== undefined
-			? validateDiscussionOptions(round.options ?? [], round.optionsMode ?? "")
+			? validateDiscussionOptions(round.options ?? [], round.optionsMode ?? "", round.optionDescriptions)
 			: undefined;
 		const result = this.db.prepare(`
-			INSERT INTO discussion_rounds (discussion_id, round_number, actor, content, occurred_at, event_schema_version, options, options_mode, selected)
-			VALUES (?, ?, ?, ?, ?, 1, ?, ?, ?)
+			INSERT INTO discussion_rounds (discussion_id, round_number, actor, content, occurred_at, event_schema_version, options, options_mode, selected, option_descriptions)
+			VALUES (?, ?, ?, ?, ?, 1, ?, ?, ?, ?)
 		`).run(
 			round.discussionId, round.roundNumber, actor, content, occurredAt,
 			posed ? JSON.stringify(posed.options) : null,
 			posed ? posed.mode : null,
 			round.selected !== undefined ? JSON.stringify(round.selected) : null,
+			posed?.optionDescriptions ? JSON.stringify(posed.optionDescriptions) : null,
 		);
 		return {
 			id: Number(result.lastInsertRowid),
@@ -66,6 +69,7 @@ export class SQLiteDiscussionRoundStore implements DiscussionRoundStore {
 			content,
 			occurredAt,
 			...(posed ? { options: posed.options, optionsMode: posed.mode } : {}),
+			...(posed?.optionDescriptions ? { optionDescriptions: posed.optionDescriptions } : {}),
 			...(round.selected !== undefined ? { selected: [...round.selected] } : {}),
 		};
 	}
@@ -73,7 +77,7 @@ export class SQLiteDiscussionRoundStore implements DiscussionRoundStore {
 	list(query: DiscussionRoundQuery): DiscussionRound[] {
 		const limit = Math.min(DISCUSSION_ROUNDS_MAX_LIMIT, Math.max(1, Math.floor(query.limit ?? DISCUSSION_ROUNDS_DEFAULT_LIMIT)));
 		const rows = this.db.prepare(`
-			SELECT id, discussion_id, round_number, actor, content, occurred_at, options, options_mode, selected
+			SELECT id, discussion_id, round_number, actor, content, occurred_at, options, options_mode, selected, option_descriptions
 			FROM discussion_rounds
 			WHERE discussion_id = ? AND round_number > ?
 			ORDER BY round_number ASC

package/src/cli.ts

@@ -128,8 +128,8 @@ const USAGE = `Usage:
   papyrus log append --source <id> --level <debug|info|warning|error> --message <text> --operation-id <id> [--source-label <text>] [--fields-json <json>] [--session-id <id>] [--occurred-at <iso>] [--global] [--json]
   papyrus session register --session-id <id> [--json]
   papyrus session release --session-id <id> [--session-secret <secret>] [--json]
-  papyrus discuss open --title <t> --actor <a> --content <c> [--body <b>] [--labels-json <json>] [--blocks-json <json>] [--options-json <json>] [--options-mode single|multi] [--json]
-  papyrus discuss reply <id> --actor <a> --content <c> [--selected-json <json>] [--options-json <json>] [--options-mode single|multi] [--json]
+  papyrus discuss open --title <t> --actor <a> --content <c> [--body <b>] [--labels-json <json>] [--blocks-json <json>] [--options-json <json>] [--options-mode single|multi] [--option-descriptions-json <json>] [--json]
+  papyrus discuss reply <id> --actor <a> --content <c> [--selected-json <json>] [--options-json <json>] [--options-mode single|multi] [--option-descriptions-json <json>] [--json]
   papyrus discuss defer <id> [--reason <text>] [--json]
   papyrus discuss resume <id> [--json]
   papyrus discuss settle <id> --settlement <text> [--json]
@@ -1134,6 +1134,7 @@ export async function runDiscussCli(args: string[], client: TaskCliClient): Prom
 	let limit: number | undefined;
 	let options: string[] | undefined;
 	let optionsMode: string | undefined;
+	let optionDescriptions: string[] | undefined;
 	let selected: string[] | undefined;
 	for (let index = 0; index < args.length; index++) {
 		const argument = args[index]!;
@@ -1147,6 +1148,7 @@ export async function runDiscussCli(args: string[], client: TaskCliClient): Prom
 		if (argument === "--task-id") { taskId = args[++index]; if (!taskId) throw new Error("--task-id requires a value"); continue; }
 		if (argument === "--options-json") { options = parseJsonStringArrayFlag(args[++index], "--options-json"); continue; }
 		if (argument === "--options-mode") { optionsMode = args[++index]; if (!optionsMode) throw new Error("--options-mode requires a value"); continue; }
+		if (argument === "--option-descriptions-json") { optionDescriptions = parseJsonStringArrayFlag(args[++index], "--option-descriptions-json"); continue; }
 		if (argument === "--selected-json") { selected = parseJsonStringArrayFlag(args[++index], "--selected-json"); continue; }
 		if (argument === "--reason") { reason = args[++index]; if (reason === undefined) throw new Error("--reason requires a value"); continue; }
 		if (argument === "--settlement") { settlement = args[++index]; if (!settlement) throw new Error("--settlement requires a value"); continue; }
@@ -1170,12 +1172,12 @@ export async function runDiscussCli(args: string[], client: TaskCliClient): Prom
 	switch (action) {
 		case "open": {
 			if (id) throw new Error("discuss open accepts no positional arguments");
-			const result = await client.call<Record<string, unknown>, unknown>("discuss.open", { title, actor, content, body, labels, blocks_task_ids: blocksTaskIds, options, options_mode: optionsMode });
+			const result = await client.call<Record<string, unknown>, unknown>("discuss.open", { title, actor, content, body, labels, blocks_task_ids: blocksTaskIds, options, options_mode: optionsMode, option_descriptions: optionDescriptions });
 			return json ? JSON.stringify(result) : JSON.stringify(result, null, 2);
 		}
 		case "reply": {
 			if (!id) throw new Error("discuss reply requires exactly one discussion id");
-			const result = await client.call<Record<string, unknown>, unknown>("discuss.reply", { id, actor, content, selected, options, options_mode: optionsMode });
+			const result = await client.call<Record<string, unknown>, unknown>("discuss.reply", { id, actor, content, selected, options, options_mode: optionsMode, option_descriptions: optionDescriptions });
 			return json ? JSON.stringify(result) : JSON.stringify(result, null, 2);
 		}
 		case "defer": {

package/src/constants.ts

@@ -7,7 +7,7 @@ export const DAEMON_PROBE_TIMEOUT_MS = 800;
 export const DAEMON_UNIT_NAME = "papyrus.service";
 export const DAEMON_DIR_ENV = "PAPYRUS_DAEMON_DIR";
 export const SQLITE_BUSY_TIMEOUT_MS = 5_000;
-export const SQLITE_SCHEMA_VERSION = 18;
+export const SQLITE_SCHEMA_VERSION = 19;
 export const SERVICE_MAX_BODY_BYTES = 1_048_576;
 
 export const WAL_CHECKPOINT_INTERVAL_MS = 60_000;
@@ -175,6 +175,10 @@ export const DISCUSSION_ACTOR_MAX_LENGTH = 128;
 export const DISCUSSION_OPTIONS_MIN_COUNT = 2;
 export const DISCUSSION_OPTIONS_MAX_COUNT = 10;
 export const DISCUSSION_OPTION_MAX_LENGTH = 200;
+// Deliberately much shorter than DISCUSSION_ROUND_CONTENT_MAX_CHARACTERS -- a per-option
+// description is meant to be a one-line tradeoff/consequence, not a restatement of the whole
+// question. Long enough for a real pro/con, short enough to force conciseness.
+export const DISCUSSION_OPTION_DESCRIPTION_MAX_LENGTH = 240;
 /** Bounds for the generic graph projection protocol (external bounded contexts). */
 export const GRAPH_PROJECTION_MAX_ARTIFACTS_PER_BATCH = 500;
 export const GRAPH_PROJECTION_MAX_EDGES_PER_BATCH = 1_000;

package/src/db.ts

@@ -238,6 +238,7 @@ CREATE TABLE IF NOT EXISTS discussion_rounds (
 	options       TEXT,
 	options_mode  TEXT,
 	selected      TEXT,
+	option_descriptions TEXT,
 	UNIQUE (discussion_id, round_number)
 );
 CREATE INDEX IF NOT EXISTS discussion_rounds_discussion_idx ON discussion_rounds(discussion_id, round_number, id);
@@ -524,6 +525,17 @@ const FUTURE_MIGRATIONS: ReadonlyArray<PapyrusMigration> = [
 			`);
 		},
 	},
+	{
+		version: 19,
+		name: "discuss-option-descriptions",
+		// See domain/discussion.ts's pendingOptionDescriptions. Nullable, purely additive column, same
+		// pattern as version 16's discuss-options -- a round with no per-option description (every
+		// round before this feature existed, and any that simply doesn't need one) stores NULL.
+		up: (db) => {
+			const existing = new Set((db.prepare("PRAGMA table_info(discussion_rounds)").all() as Array<{ name: string }>).map((row) => row.name));
+			if (!existing.has("option_descriptions")) db.exec("ALTER TABLE discussion_rounds ADD COLUMN option_descriptions TEXT");
+		},
+	},
 ];
 
 /**

package/src/discussion-service.ts

@@ -35,6 +35,8 @@ export interface OpenDiscussionInput {
 	/** Poses a choice on round 1 -- both or neither; see domain/discussion.ts's DiscussionOptionsMode. */
 	options?: string[];
 	optionsMode?: DiscussionOptionsMode;
+	/** Index-aligned with options -- see domain/discussion.ts's pendingOptionDescriptions. */
+	optionDescriptions?: string[];
 }
 
 export interface ReplyInput {
@@ -45,6 +47,7 @@ export interface ReplyInput {
 	/** Poses a new choice on this same round, replacing whatever was previously pending. */
 	options?: string[];
 	optionsMode?: DiscussionOptionsMode;
+	optionDescriptions?: string[];
 }
 
 export interface DiscussionAndRounds {
@@ -69,15 +72,15 @@ export class Discussions {
 	}
 
 	/** Validates a freshly-posed choice; undefined when neither field is given (nothing posed), since both/neither is the only valid shape. */
-	private validatePosedOptions(options: string[] | undefined, optionsMode: DiscussionOptionsMode | undefined): { options: string[]; mode: DiscussionOptionsMode } | undefined {
+	private validatePosedOptions(options: string[] | undefined, optionsMode: DiscussionOptionsMode | undefined, optionDescriptions: string[] | undefined): { options: string[]; mode: DiscussionOptionsMode; optionDescriptions?: string[] } | undefined {
 		if (options === undefined && optionsMode === undefined) return undefined;
-		return validateDiscussionOptions(options ?? [], optionsMode ?? "");
+		return validateDiscussionOptions(options ?? [], optionsMode ?? "", optionDescriptions);
 	}
 
 	open(input: OpenDiscussionInput, context?: ArtifactEventContext): DiscussionAndRounds {
 		const actor = validateDiscussionActor(input.actor);
 		const content = validateDiscussionContent(input.content);
-		const posed = this.validatePosedOptions(input.options, input.optionsMode);
+		const posed = this.validatePosedOptions(input.options, input.optionsMode, input.optionDescriptions);
 		return this.artifacts.atomic(() => {
 			const discussion = this.artifacts.create({
 				kind: "task",
@@ -90,13 +93,13 @@ export class Discussions {
 					discussion: {
 						state: "active",
 						roundCount: 1,
-						...(posed ? { pendingOptions: posed.options, pendingOptionsMode: posed.mode } : {}),
+						...(posed ? { pendingOptions: posed.options, pendingOptionsMode: posed.mode, ...(posed.optionDescriptions ? { pendingOptionDescriptions: posed.optionDescriptions } : {}) } : {}),
 					},
 				},
 			}, context);
 			const round = this.rounds.append({
 				discussionId: discussion.id, roundNumber: 1, actor, content,
-				...(posed ? { options: posed.options, optionsMode: posed.mode } : {}),
+				...(posed ? { options: posed.options, optionsMode: posed.mode, ...(posed.optionDescriptions ? { optionDescriptions: posed.optionDescriptions } : {}) } : {}),
 			}, new Date().toISOString());
 			for (const taskId of input.blocksTaskIds ?? []) this.block(discussion.id, taskId, context);
 			return { discussion: this.artifacts.get(discussion.id)!, rounds: [round] };
@@ -106,7 +109,7 @@ export class Discussions {
 	reply(discussionId: string, input: ReplyInput, context?: ArtifactEventContext): DiscussionAndRounds {
 		const validActor = validateDiscussionActor(input.actor);
 		const validContent = validateDiscussionContent(input.content);
-		const posed = this.validatePosedOptions(input.options, input.optionsMode);
+		const posed = this.validatePosedOptions(input.options, input.optionsMode, input.optionDescriptions);
 		return this.artifacts.atomic(() => {
 			const discussion = requireDiscussion(this.artifacts.get(discussionId), discussionId);
 			const state = this.extra(discussion);
@@ -116,14 +119,19 @@ export class Discussions {
 			const nextRound = state.roundCount + 1;
 			const round = this.rounds.append({
 				discussionId, roundNumber: nextRound, actor: validActor, content: validContent,
-				...(posed ? { options: posed.options, optionsMode: posed.mode } : {}),
+				...(posed ? { options: posed.options, optionsMode: posed.mode, ...(posed.optionDescriptions ? { optionDescriptions: posed.optionDescriptions } : {}) } : {}),
 				...(selected ? { selected } : {}),
 			}, new Date().toISOString());
-			const { pendingOptions: _clearedOptions, pendingOptionsMode: _clearedMode, ...answered } = state;
+			// Whenever this round answers the pending choice OR poses a new one, the base must drop ALL
+			// three pending* fields first -- otherwise a re-pose that omits descriptions this time would
+			// leave a stale pendingOptionDescriptions array (sized for the OLD options) spread through
+			// unchanged, no longer aligned 1:1 with the new pendingOptions. Only a plain reply that
+			// neither answers nor re-poses leaves the existing pending state untouched.
+			const { pendingOptions: _clearedOptions, pendingOptionsMode: _clearedMode, pendingOptionDescriptions: _clearedDescriptions, ...withoutPending } = state;
 			const nextState = {
-				...(selected ? answered : state),
+				...(selected || posed ? withoutPending : state),
 				roundCount: nextRound,
-				...(posed ? { pendingOptions: posed.options, pendingOptionsMode: posed.mode } : {}),
+				...(posed ? { pendingOptions: posed.options, pendingOptionsMode: posed.mode, ...(posed.optionDescriptions ? { pendingOptionDescriptions: posed.optionDescriptions } : {}) } : {}),
 			};
 			const updated = this.artifacts.setExtra(discussionId, { ...discussion.extra, discussion: nextState }, context)!;
 			return { discussion: updated, rounds: [round] };

package/src/domain/discussion.ts

@@ -20,6 +20,7 @@
 import {
 	DISCUSSION_ACTOR_MAX_LENGTH,
 	DISCUSSION_DEFER_REASON_MAX_CHARACTERS,
+	DISCUSSION_OPTION_DESCRIPTION_MAX_LENGTH,
 	DISCUSSION_OPTION_MAX_LENGTH,
 	DISCUSSION_OPTIONS_MAX_COUNT,
 	DISCUSSION_OPTIONS_MIN_COUNT,
@@ -49,6 +50,10 @@ export interface DiscussionExtra {
 	settledAt?: string;
 	pendingOptions?: string[];
 	pendingOptionsMode?: DiscussionOptionsMode;
+	/** Index-aligned with pendingOptions when present -- one entry per option, empty string meaning
+	 * "no description for this one". Purely descriptive metadata: selection/validation only ever
+	 * matches against pendingOptions itself, never against this array. */
+	pendingOptionDescriptions?: string[];
 }
 
 /** One append-only round of a Discussion -- opening statement is round 1. options/optionsMode/selected are the historical record of what was posed/picked in this specific round (extra.discussion.pendingOptions is the separate, mutable "what's unanswered right now" cache). */
@@ -61,6 +66,8 @@ export interface DiscussionRound {
 	occurredAt: string;
 	options?: string[];
 	optionsMode?: DiscussionOptionsMode;
+	/** Index-aligned with options -- see DiscussionExtra.pendingOptionDescriptions. */
+	optionDescriptions?: string[];
 	selected?: string[];
 }
 
@@ -71,6 +78,7 @@ export interface AppendDiscussionRound {
 	content: string;
 	options?: string[];
 	optionsMode?: DiscussionOptionsMode;
+	optionDescriptions?: string[];
 	selected?: string[];
 }
 
@@ -101,8 +109,8 @@ export function validateSettlement(settlement: string): string {
 	return boundedString(settlement, "settlement", DISCUSSION_SETTLEMENT_MAX_CHARACTERS);
 }
 
-/** Validates a freshly-posed choice: 2..DISCUSSION_OPTIONS_MAX_COUNT unique, bounded-length options and a real mode. */
-export function validateDiscussionOptions(options: string[], mode: string): { options: string[]; mode: DiscussionOptionsMode } {
+/** Validates a freshly-posed choice: 2..DISCUSSION_OPTIONS_MAX_COUNT unique, bounded-length options, a real mode, and -- if given -- one description per option (empty string means "none for this one"). */
+export function validateDiscussionOptions(options: string[], mode: string, optionDescriptions?: string[]): { options: string[]; mode: DiscussionOptionsMode; optionDescriptions?: string[] } {
 	if (!(DISCUSSION_OPTIONS_MODES as readonly string[]).includes(mode)) {
 		throw new Error(`options_mode must be one of ${DISCUSSION_OPTIONS_MODES.join(", ")}`);
 	}
@@ -111,7 +119,13 @@ export function validateDiscussionOptions(options: string[], mode: string): { op
 	}
 	for (const option of options) boundedString(option, "option", DISCUSSION_OPTION_MAX_LENGTH);
 	if (new Set(options).size !== options.length) throw new Error("options must not repeat an entry");
-	return { options: [...options], mode: mode as DiscussionOptionsMode };
+	if (optionDescriptions !== undefined) {
+		if (optionDescriptions.length !== options.length) throw new Error("option_descriptions must have exactly one entry per option (use an empty string for none)");
+		for (const description of optionDescriptions) {
+			if (description.length > DISCUSSION_OPTION_DESCRIPTION_MAX_LENGTH) throw new Error(`option description must be at most ${DISCUSSION_OPTION_DESCRIPTION_MAX_LENGTH} characters`);
+		}
+	}
+	return { options: [...options], mode: mode as DiscussionOptionsMode, ...(optionDescriptions !== undefined ? { optionDescriptions: [...optionDescriptions] } : {}) };
 }
 
 /** Validates an answer against the Discussion's currently pending posed choice, if any. */
@@ -153,6 +167,15 @@ export function readDiscussionExtra(extra: Record<string, unknown>): DiscussionE
 	if (pendingOptionsMode !== undefined && !(DISCUSSION_OPTIONS_MODES as readonly unknown[]).includes(pendingOptionsMode)) {
 		throw new Error("invalid Discussion pendingOptionsMode");
 	}
+	const pendingOptionDescriptions = record["pendingOptionDescriptions"];
+	if (pendingOptionDescriptions !== undefined) {
+		if (!Array.isArray(pendingOptionDescriptions) || pendingOptionDescriptions.some((entry) => typeof entry !== "string")) {
+			throw new Error("invalid Discussion pendingOptionDescriptions");
+		}
+		if (!Array.isArray(pendingOptions) || pendingOptionDescriptions.length !== pendingOptions.length) {
+			throw new Error("invalid Discussion pendingOptionDescriptions: must align 1:1 with pendingOptions");
+		}
+	}
 	return {
 		state: state as DiscussionState,
 		roundCount,
@@ -161,5 +184,6 @@ export function readDiscussionExtra(extra: Record<string, unknown>): DiscussionE
 		...(typeof record["settledAt"] === "string" ? { settledAt: record["settledAt"] } : {}),
 		...(pendingOptions !== undefined ? { pendingOptions: pendingOptions as string[] } : {}),
 		...(pendingOptionsMode !== undefined ? { pendingOptionsMode: pendingOptionsMode as DiscussionOptionsMode } : {}),
+		...(pendingOptionDescriptions !== undefined ? { pendingOptionDescriptions: pendingOptionDescriptions as string[] } : {}),
 	};
 }

package/src/modules/discuss.ts

@@ -77,6 +77,7 @@ export function discussOperations(discussions: Discussions): OperationDefinition
 			blocksTaskIds: optionalStringArray(input, "blocks_task_ids") ?? optionalStringArray(input, "blocksTaskIds"),
 			options: optionalStringArray(input, "options"),
 			optionsMode: optionsMode(input),
+			optionDescriptions: optionalStringArray(input, "option_descriptions") ?? optionalStringArray(input, "optionDescriptions"),
 		}, eventContext(input))),
 		define("discuss.reply", (input: OperationInput) => discussions.reply(string(input, "id"), {
 			actor: string(input, "actor"),
@@ -84,6 +85,7 @@ export function discussOperations(discussions: Discussions): OperationDefinition
 			selected: optionalStringArray(input, "selected"),
 			options: optionalStringArray(input, "options"),
 			optionsMode: optionsMode(input),
+			optionDescriptions: optionalStringArray(input, "option_descriptions") ?? optionalStringArray(input, "optionDescriptions"),
 		}, eventContext(input))),
 		define("discuss.defer", (input: OperationInput) => discussions.defer(string(input, "id"), optionalString(input, "reason"), eventContext(input))),
 		define("discuss.resume", (input: OperationInput) => discussions.resume(string(input, "id"), eventContext(input))),