@danypops/papyrus 0.27.15 → 0.28.1

package/extension/src/discuss.ts

@@ -89,7 +89,7 @@ export async function showDiscussions(ctx: ExtensionCommandContext): Promise<voi
 				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, subtitle, options: pending.pendingOptions.map((title) => ({ title })), allowMultiple: pending.pendingOptionsMode === "multi" })
+					? 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 });

package/extension/src/domain-tools.ts

@@ -39,6 +39,35 @@ 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; } })();
@@ -52,7 +81,7 @@ async function liveAnswer(ctx: ExtensionContext, discussion: Artifact, latestCon
 		return askQuestion(ctx, {
 			question,
 			subtitle,
-			options: pending.pendingOptions.map((title) => ({ title })),
+			options: pending.pendingOptions.map((title, index) => ({ title, description: pending.pendingOptionDescriptions?.[index] || undefined })),
 			allowMultiple: pending.pendingOptionsMode === "multi",
 			onUpdate,
 			signal,
@@ -681,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 or {title, description}; description is optional for exactly 2 options (a self-evident yes/no) but REQUIRED and non-empty for every option once there are 3 or more -- rejected otherwise. One line: the real pro/con/risk/consequence, never padding that just restates the title. 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()),
@@ -700,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()),
@@ -722,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.15",
+  "version": "0.28.1",
   "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,12 @@ 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;
+// Below this, a binary yes/no choice is often self-evident and a description would just pad it.
+export const DISCUSSION_OPTION_DESCRIPTION_REQUIRED_FROM_COUNT = 3;
 /** 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,8 @@
 import {
 	DISCUSSION_ACTOR_MAX_LENGTH,
 	DISCUSSION_DEFER_REASON_MAX_CHARACTERS,
+	DISCUSSION_OPTION_DESCRIPTION_MAX_LENGTH,
+	DISCUSSION_OPTION_DESCRIPTION_REQUIRED_FROM_COUNT,
 	DISCUSSION_OPTION_MAX_LENGTH,
 	DISCUSSION_OPTIONS_MAX_COUNT,
 	DISCUSSION_OPTIONS_MIN_COUNT,
@@ -49,6 +51,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 +67,8 @@ export interface DiscussionRound {
 	occurredAt: string;
 	options?: string[];
 	optionsMode?: DiscussionOptionsMode;
+	/** Index-aligned with options -- see DiscussionExtra.pendingOptionDescriptions. */
+	optionDescriptions?: string[];
 	selected?: string[];
 }
 
@@ -71,6 +79,7 @@ export interface AppendDiscussionRound {
 	content: string;
 	options?: string[];
 	optionsMode?: DiscussionOptionsMode;
+	optionDescriptions?: string[];
 	selected?: string[];
 }
 
@@ -101,8 +110,10 @@ 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 a non-empty description for every option once
+ * DISCUSSION_OPTION_DESCRIPTION_REQUIRED_FROM_COUNT or more are posed. */
+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 +122,17 @@ 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 };
+	const descriptionsRequired = options.length >= DISCUSSION_OPTION_DESCRIPTION_REQUIRED_FROM_COUNT;
+	if (descriptionsRequired && (optionDescriptions === undefined || optionDescriptions.some((description) => description.trim().length === 0))) {
+		throw new Error(`option_descriptions is required, with a non-empty entry for every option, once ${DISCUSSION_OPTION_DESCRIPTION_REQUIRED_FROM_COUNT} or more options are posed`);
+	}
+	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 +174,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 +191,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))),