@danypops/papyrus 0.18.0 → 0.19.1

package/README.md

@@ -154,6 +154,25 @@ papyrus notes promote <note-id> <target-id> --reason "Converted to tracked work"
 papyrus notes archive <note-id> declined --reason "No longer relevant" --json
 ```
 
+## Discuss
+
+Discuss is a native, persistent deliberation, distinct from a one-shot ask: it survives across turns and sessions, takes multiple rounds, and can genuinely block a Task's completion until settled or deferred. A Discussion is a `doc` artifact with `subtype: "discussion"` -- real graph citizenship (edges, show/list) without a fifth enforced artifact kind. Its fine-grained lifecycle (`active`/`deferred`/`settled`) lives in `extra.discussion`, since Papyrus enforces status vocabulary per kind, not per subtype.
+
+Rounds are a dedicated append-only child table (mirroring Task history's own shape): `open` records round 1, `reply` appends further rounds, refused once the Discussion is `deferred` or `settled` -- resume first. `defer` is explicitly non-blocking (paused, reason optional, resumable); `settle` is terminal, records an outcome, and archives the Doc. `block`/`unblock` manage the blocking relationship to a Task independently of `open`.
+
+Blocking is real: `tasks.complete` is refused while any `active` Discussion has a `blocks` edge to that Task. A `deferred` Discussion does not block -- "we will get back to this" is distinct from "resolved."
+
+Run `/discuss` for the interactive panel: browse every Discussion (the real `active`/`deferred`/`settled` state shown per row, not just the shared Doc status glyph), open a scrollable transcript, and reply/defer/resume/settle or block/unblock a task without leaving the TUI. Opening a *new* Discussion is left to the agent (same as Docs/Rules/Skills) -- `/discuss` browses and drives existing ones.
+
+```bash
+papyrus discuss open --title "Naming" --actor alice --content "Should we rename this?" --blocks-json '["task-id"]' --json
+papyrus discuss reply <discussion-id> --actor bob --content "I think so, here's why..." --json
+papyrus discuss defer <discussion-id> --reason "Waiting on design review" --json
+papyrus discuss resume <discussion-id> --json
+papyrus discuss settle <discussion-id> --settlement "Agreed: renaming to X" --json
+papyrus discuss show <discussion-id> --json
+```
+
 ## Tasks
 
 Run `/tasks` for the interactive task panel:

package/extension/src/artifact-status-presentation.ts

@@ -36,6 +36,19 @@ export const SKILL_STATUS_PRESENTATION: Record<string, StatusPresentation> = {
 	deprecated: { label: "deprecated", glyph: "○", color: "muted" },
 };
 
+/**
+ * Keyed by extra.discussion.state, not the shared Doc status column -- a settled Discussion's
+ * doc.status becomes "archived", but a deferred one stays "active" at the doc level (see
+ * domain/discussion.ts's header comment). Reusing DOC_STATUS_PRESENTATION here would render
+ * "deferred" and "active" Discussions with the identical glyph, silently losing the one piece
+ * of state this feature exists to distinguish.
+ */
+export const DISCUSSION_STATE_PRESENTATION: Record<string, StatusPresentation> = {
+	active: { label: "active", glyph: "●", color: "accent" },
+	deferred: { label: "deferred", glyph: "⏸", color: "warning" },
+	settled: { label: "settled", glyph: "✓", color: "success" },
+};
+
 /** Rule severity gets its own color independent of status -- block is the loudest, info the quietest. */
 export const RULE_SEVERITY_PRESENTATION: Record<string, ThemeColor> = {
 	block: "error",

package/extension/src/discuss.ts

@@ -0,0 +1,96 @@
+/**
+ * discuss.ts — /discuss interactive panel.
+ * Reuses the generic artifact browser (artifact-browser.ts), same as docs.ts/rules.ts/notes.ts:
+ * a Discussion is a `doc` artifact, so the browser's list/filter/refresh/select-action loop
+ * applies unchanged. The one real wrinkle is that Discuss's meaningful lifecycle state
+ * (active/deferred/settled) lives in extra.discussion, not the shared doc status column the
+ * browser colors its row glyph by (see artifact-status-presentation.ts's DISCUSSION_STATE_PRESENTATION
+ * comment) -- so the real state is surfaced in rowMeta text instead, the same way rules.ts
+ * surfaces severity and notes.ts surfaces history count, both also not the row glyph.
+ *
+ * Creating a new Discussion is left to the agent (the discuss tool), matching docs.ts/rules.ts/
+ * skills.ts precedent -- Notes is the one kind with a human-facing creation command (/note),
+ * because Notes exists specifically as a human-authored inbox.
+ */
+import type { ExtensionCommandContext, Theme } from "@earendil-works/pi-coding-agent";
+import type { Artifact } from "../../src/domain/artifact.ts";
+import type { DiscussionAndRounds } from "../../src/discussion-service.ts";
+import { showArtifactBrowser } from "./artifact-browser.ts";
+import { DISCUSSION_STATE_PRESENTATION, DOC_STATUS_PRESENTATION } from "./artifact-status-presentation.ts";
+import { discussionRoundCountOf, discussionStateOf, showDiscussionDetailView } from "./discussion-detail-view.ts";
+import { callService } from "./service-client.ts";
+
+const SOURCE = "discuss-tui";
+const ACTOR = "human";
+
+export function discussionRowMeta(discussion: Artifact, theme: Theme): string {
+	const state = discussionStateOf(discussion);
+	const presentation = DISCUSSION_STATE_PRESENTATION[state];
+	const stateText = presentation ? theme.fg(presentation.color, `${presentation.glyph} ${presentation.label}`) : theme.fg("muted", "state unknown");
+	const rounds = discussionRoundCountOf(discussion);
+	return `${stateText} · ${rounds} round${rounds === 1 ? "" : "s"}`;
+}
+
+function discussionActions(discussion: Artifact): string[] {
+	const state = discussionStateOf(discussion);
+	if (state === "active") return ["Show transcript", "Reply", "Defer", "Settle", "Block a task", "Unblock a task"];
+	if (state === "deferred") return ["Show transcript", "Resume", "Settle"];
+	return ["Show transcript"]; // settled, or an unrecognized/corrupt state -- read-only either way
+}
+
+export async function showDiscussions(ctx: ExtensionCommandContext): Promise<void> {
+	await showArtifactBrowser(ctx, {
+		kind: "doc",
+		title: "Discussions",
+		listOperation: "discuss.list",
+		statusOrder: ["draft", "active", "archived"],
+		presentation: DOC_STATUS_PRESENTATION,
+		rowMeta: discussionRowMeta,
+		actions: discussionActions,
+		handleAction: async (choice, discussion, commandCtx) => {
+			if (choice === "Show transcript") {
+				const result = await callService<Record<string, unknown>, DiscussionAndRounds>("discuss.show", { id: discussion.id });
+				await showDiscussionDetailView(commandCtx, result.discussion, result.rounds);
+				return;
+			}
+			if (choice === "Reply") {
+				const content = await commandCtx.ui.input("Reply:", "");
+				if (!content) return;
+				await callService("discuss.reply", { id: discussion.id, actor: ACTOR, content, source: SOURCE });
+				commandCtx.ui.notify("Round added.", "info");
+				return;
+			}
+			if (choice === "Defer") {
+				const reason = await commandCtx.ui.input("Defer reason (optional):", "");
+				await callService("discuss.defer", { id: discussion.id, ...(reason ? { reason } : {}), actor: ACTOR, source: SOURCE });
+				commandCtx.ui.notify("Deferred.", "info");
+				return;
+			}
+			if (choice === "Resume") {
+				await callService("discuss.resume", { id: discussion.id, actor: ACTOR, source: SOURCE });
+				commandCtx.ui.notify("Resumed.", "info");
+				return;
+			}
+			if (choice === "Settle") {
+				const settlement = await commandCtx.ui.input("Settlement:", "");
+				if (!settlement) return;
+				await callService("discuss.settle", { id: discussion.id, settlement, actor: ACTOR, source: SOURCE });
+				commandCtx.ui.notify("Settled.", "info");
+				return;
+			}
+			if (choice === "Block a task") {
+				const taskId = await commandCtx.ui.input("Task artifact id to block:", "");
+				if (!taskId) return;
+				await callService("discuss.block", { id: discussion.id, task_id: taskId, actor: ACTOR, source: SOURCE });
+				commandCtx.ui.notify(`${discussion.id} now blocks ${taskId}`, "info");
+				return;
+			}
+			if (choice === "Unblock a task") {
+				const taskId = await commandCtx.ui.input("Task artifact id to unblock:", "");
+				if (!taskId) return;
+				const result = await callService<Record<string, unknown>, { unblocked: boolean }>("discuss.unblock", { id: discussion.id, task_id: taskId, actor: ACTOR, source: SOURCE });
+				commandCtx.ui.notify(result.unblocked ? `${discussion.id} no longer blocks ${taskId}` : "No such blocking relationship.", "info");
+			}
+		},
+	});
+}

package/extension/src/discussion-detail-view.ts

@@ -0,0 +1,130 @@
+/**
+ * discussion-detail-view.ts — the transcript view for a single Discussion.
+ *
+ * The generic artifact detail view (artifact-detail-view.ts) formats an artifact's own
+ * fields (title, body, extra as JSON, edges); it has no way to show a Discussion's rounds,
+ * since those live in a dedicated child table fetched separately (discuss.show / discuss.rounds),
+ * not in the artifact row itself. Tasks needed the same kind of dedicated view for the same
+ * underlying reason (task-detail-view.ts) -- this mirrors that scrolling-viewport idiom rather
+ * than inventing a new one.
+ */
+import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { matchesKey, truncateToWidth, type TUI } from "@earendil-works/pi-tui";
+import {
+	ARTIFACT_DETAIL_MAX_VISIBLE_LINES,
+	ARTIFACT_DETAIL_MIN_VISIBLE_LINES,
+	ARTIFACT_DETAIL_RESERVED_ROWS,
+} from "../../src/constants.ts";
+import type { Artifact } from "../../src/domain/artifact.ts";
+import { readDiscussionExtra, type DiscussionRound } from "../../src/domain/discussion.ts";
+import { renderMarkdownBody, type ActiveTheme } from "./markdown.ts";
+import { DISCUSSION_STATE_PRESENTATION } from "./artifact-status-presentation.ts";
+
+interface TranscriptLine {
+	text: string;
+}
+
+/** Reads state defensively for display -- a corrupt/foreign extra.discussion shape shows as "unknown" rather than crashing the whole panel over one bad row. */
+export function discussionStateOf(discussion: Artifact): string {
+	try {
+		return readDiscussionExtra(discussion.extra).state;
+	} catch {
+		return "unknown";
+	}
+}
+
+export function discussionRoundCountOf(discussion: Artifact): number {
+	try {
+		return readDiscussionExtra(discussion.extra).roundCount;
+	} catch {
+		return 0;
+	}
+}
+
+class DiscussionTranscriptViewport {
+	private offsetY = 0;
+	private renderedWidth = 0;
+	private lines: TranscriptLine[] = [];
+	private readonly visibleLines: number;
+
+	constructor(
+		private readonly tui: TUI,
+		private readonly activeTheme: ActiveTheme,
+		private readonly discussion: Artifact,
+		private readonly rounds: DiscussionRound[],
+		private readonly close: () => void,
+	) {
+		this.visibleLines = Math.max(
+			ARTIFACT_DETAIL_MIN_VISIBLE_LINES,
+			Math.min(ARTIFACT_DETAIL_MAX_VISIBLE_LINES, tui.terminal.rows - ARTIFACT_DETAIL_RESERVED_ROWS),
+		);
+	}
+
+	invalidate(): void { this.renderedWidth = 0; }
+
+	render(width: number): string[] {
+		const contentWidth = Math.max(1, width - 2);
+		this.buildLines(contentWidth);
+		this.offsetY = Math.min(this.offsetY, Math.max(0, this.lines.length - this.visibleLines));
+		const end = Math.min(this.lines.length, this.offsetY + this.visibleLines);
+		const theme = this.activeTheme();
+		const border = theme.fg("borderMuted", "─".repeat(Math.max(1, width)));
+		const footer = [
+			this.lines.length > this.visibleLines ? `↑/↓ scroll · ${this.offsetY + 1}-${end}/${this.lines.length}` : "",
+			"Esc back",
+		].filter(Boolean).join(" · ");
+		return [
+			border,
+			truncateToWidth(theme.fg("accent", theme.bold("Discussion transcript")), width, ""),
+			border,
+			...this.lines.slice(this.offsetY, end).map((line) => truncateToWidth(` ${line.text}`, width, "")),
+			truncateToWidth(theme.fg("dim", footer), width, ""),
+			border,
+		];
+	}
+
+	handleInput(data: string): void {
+		if (matchesKey(data, "escape") || matchesKey(data, "ctrl+c")) { this.close(); return; }
+		if (matchesKey(data, "up")) this.offsetY = Math.max(0, this.offsetY - 1);
+		else if (matchesKey(data, "down")) this.offsetY = Math.min(Math.max(0, this.lines.length - this.visibleLines), this.offsetY + 1);
+		else if (matchesKey(data, "pageDown")) this.offsetY = Math.min(Math.max(0, this.lines.length - this.visibleLines), this.offsetY + this.visibleLines);
+		else if (matchesKey(data, "pageUp")) this.offsetY = Math.max(0, this.offsetY - this.visibleLines);
+		else return;
+		this.tui.requestRender();
+	}
+
+	private buildLines(width: number): void {
+		if (this.renderedWidth === width) return;
+		this.renderedWidth = width;
+		const theme = this.activeTheme();
+		const extra = (() => { try { return readDiscussionExtra(this.discussion.extra); } catch { return undefined; } })();
+		const presentation = extra ? DISCUSSION_STATE_PRESENTATION[extra.state] : undefined;
+		const stateLine = presentation
+			? theme.fg(presentation.color, `${presentation.glyph} ${presentation.label}`)
+			: theme.fg("muted", "state unknown");
+		const header: TranscriptLine[] = [
+			{ text: theme.bold(this.discussion.title) },
+			{ text: `${stateLine}${theme.fg("dim", ` · ${this.discussion.id}`)}` },
+			...(extra?.deferredReason ? [{ text: theme.fg("muted", `Deferred: ${extra.deferredReason}`) }] : []),
+			...(extra?.settlement ? [{ text: theme.fg("success", `Settled: ${extra.settlement}`) }] : []),
+			{ text: "" },
+		];
+		const transcript: TranscriptLine[] = this.rounds.flatMap((round, index) => {
+			const roundHeader = theme.fg("accent", `[round ${round.roundNumber}] `) + theme.bold(round.actor) + theme.fg("dim", ` · ${round.occurredAt}`);
+			const body = renderMarkdownBody(round.content, width - 2, this.activeTheme).map((line) => ({ text: `  ${line}` }));
+			return [{ text: roundHeader }, ...body, ...(index < this.rounds.length - 1 ? [{ text: "" }] : [])];
+		});
+		this.lines = [...header, ...(transcript.length > 0 ? transcript : [{ text: theme.fg("muted", "No rounds recorded.") }])];
+		this.offsetY = Math.min(this.offsetY, Math.max(0, this.lines.length - this.visibleLines));
+	}
+}
+
+export async function showDiscussionDetailView(ctx: ExtensionCommandContext, discussion: Artifact, rounds: DiscussionRound[]): Promise<void> {
+	if (ctx.mode !== "tui") {
+		const lines = rounds.map((round) => `[round ${round.roundNumber}] ${round.actor}: ${round.content}`);
+		ctx.ui.notify([discussion.title, ...lines].join("\n"), "info");
+		return;
+	}
+	await ctx.ui.custom<void>((tui, theme, _keybindings, done) =>
+		new DiscussionTranscriptViewport(tui, () => ctx.ui.theme ?? theme, discussion, rounds, done));
+}

package/extension/src/domain-tools.ts

@@ -7,6 +7,8 @@ import type { TaskExecutionPlan } from "../../src/task-execution.ts";
 import type { TaskHistoryPage } from "../../src/domain/task-event.ts";
 import type { TaskCompletion, TaskGraph } from "../../src/task-service.ts";
 import type { SkillWorkflowRunResult } from "../../src/skill-execution.ts";
+import type { DiscussionAndRounds } from "../../src/discussion-service.ts";
+import type { DiscussionRound } from "../../src/domain/discussion.ts";
 import { emitTaskFocusEvent } from "./task-focus-events.ts";
 import { sessionSecretField } from "./session-identity.ts";
 import { NOTE_DISPOSITIONS } from "../../src/note-service.ts";
@@ -432,4 +434,72 @@ 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.",
+		parameters: Type.Object({
+			action: Type.String(),
+			id: Type.Optional(Type.String()),
+			title: Type.Optional(Type.String()),
+			actor: Type.Optional(Type.String()),
+			content: Type.Optional(Type.String()),
+			body: Type.Optional(Type.String()),
+			labels: Type.Optional(Type.Array(Type.String())),
+			blocks_task_ids: Type.Optional(Type.Array(Type.String())),
+			task_id: Type.Optional(Type.String()),
+			reason: Type.Optional(Type.String()),
+			settlement: Type.Optional(Type.String()),
+			state: Type.Optional(Type.String()),
+			after_round: Type.Optional(Type.Number()),
+			limit: Type.Optional(Type.Number()),
+		}),
+		renderCall(args, theme) { return renderPapyrusToolCall("Discuss", args, theme); },
+		renderResult(result, options, theme, context) { return renderPapyrusToolResult(result, options, theme, context); },
+		async execute(_id, params) {
+			try {
+				const action = params.action;
+				if (action === "open") {
+					const result = await callService<Record<string, unknown>, DiscussionAndRounds>("discuss.open", params);
+					return text(`Opened discussion ${artifactLine(result.discussion)}`, createArtifactDetails("discuss.open", result.discussion));
+				}
+				if (action === "reply") {
+					const result = await callService<Record<string, unknown>, DiscussionAndRounds>("discuss.reply", params);
+					return text(`Round ${result.rounds[0]?.roundNumber} added to ${result.discussion.id}`, createArtifactDetails("discuss.reply", result.discussion));
+				}
+				if (action === "block") {
+					await callService<Record<string, unknown>, { blocked: boolean }>("discuss.block", params);
+					const message = `${params.id} now blocks ${params.task_id}`;
+					return text(message, createPreviewDetails("discuss.block", "Blocked", message));
+				}
+				if (action === "unblock") {
+					const result = await callService<Record<string, unknown>, { unblocked: boolean }>("discuss.unblock", params);
+					const message = result.unblocked ? `${params.id} no longer blocks ${params.task_id}` : "No such blocking relationship.";
+					return text(message, createPreviewDetails("discuss.unblock", "Unblocked", message));
+				}
+				if (action === "show") {
+					const result = await callService<Record<string, unknown>, DiscussionAndRounds>("discuss.show", params);
+					const rounds = result.rounds.map((round) => `  [round ${round.roundNumber}] ${round.actor}: ${round.content}`).join("\n");
+					return text(`${artifactLine(result.discussion)}\n\n${rounds}`, createArtifactDetails("discuss.show", result.discussion));
+				}
+				if (action === "rounds") {
+					const rounds = await callService<Record<string, unknown>, DiscussionRound[]>("discuss.rounds", params);
+					const output = rounds.map((round) => `[round ${round.roundNumber}] ${round.actor}: ${round.content}`).join("\n") || "No rounds.";
+					return text(output, createPreviewDetails("discuss.rounds", "Discussion rounds", output));
+				}
+				if (action === "list") {
+					const rows = await callService<Record<string, unknown>, Artifact[]>("discuss.list", params);
+					return text(rows.length ? rows.map(artifactLine).join("\n") : "No discussions found.", createArtifactListDetails("discuss.list", rows));
+				}
+				const operations = { defer: "discuss.defer", resume: "discuss.resume", settle: "discuss.settle" } as const;
+				const operation = operations[action as keyof typeof operations];
+				if (!operation) throw new Error(`unknown discuss action: ${action}`);
+				const artifact = await callService<Record<string, unknown>, Artifact>(operation, params);
+				return text(artifactLine(artifact), createArtifactDetails(operation, artifact));
+			} catch (error) {
+				throw new Error(`discuss failed: ${error instanceof Error ? error.message : error}`);
+			}
+		},
+	});
 }

package/extension/src/index.ts

@@ -416,12 +416,13 @@ export default async function (pi: ExtensionAPI) {
 	// ── Interactive artifact browsers ──────────────────────────────────
 
 	// Lazy imports keep TUI components out of non-interactive startup paths.
-	const [tasksModule, docsModule, notesModule, rulesModule, skillsModule] = await Promise.all([
+	const [tasksModule, docsModule, notesModule, rulesModule, skillsModule, discussModule] = await Promise.all([
 		import("./tasks.ts"),
 		import("./docs.ts"),
 		import("./notes.ts"),
 		import("./rules.ts"),
 		import("./skills.ts"),
+		import("./discuss.ts"),
 	]);
 	let overlay: TaskOverlay | undefined;
 
@@ -454,6 +455,10 @@ export default async function (pi: ExtensionAPI) {
 		description: "Browse and invoke Papyrus skills and templates (interactive)",
 		handler: async (_args, ctx) => { await skillsModule.showSkills(ctx); },
 	});
+	pi.registerCommand("discuss", {
+		description: "Browse Papyrus Discussions and reply, defer, resume, settle, or block/unblock a task (interactive)",
+		handler: async (_args, ctx) => { await discussModule.showDiscussions(ctx); },
+	});
 	pi.registerCommand("context", {
 		description: "Structured, per-segment breakdown of the context window: real usage against the model's window, drilling into Papyrus Rules and the Pi-native skill catalog",
 		handler: async (_args, ctx) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danypops/papyrus",
-  "version": "0.18.0",
+  "version": "0.19.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

@@ -0,0 +1,61 @@
+import type { Db } from "../db.ts";
+import { DISCUSSION_ROUNDS_DEFAULT_LIMIT, DISCUSSION_ROUNDS_MAX_LIMIT } from "../constants.ts";
+import { validateDiscussionActor, validateDiscussionContent, type AppendDiscussionRound, type DiscussionRound, type DiscussionRoundQuery } from "../domain/discussion.ts";
+import type { DiscussionRoundStore } from "../ports/discussion-round-store.ts";
+
+interface DiscussionRoundRow {
+	id: number;
+	discussion_id: string;
+	round_number: number;
+	actor: string;
+	content: string;
+	occurred_at: string;
+}
+
+function mapRow(row: DiscussionRoundRow): DiscussionRound {
+	return {
+		id: row.id,
+		discussionId: row.discussion_id,
+		roundNumber: row.round_number,
+		actor: row.actor,
+		content: row.content,
+		occurredAt: row.occurred_at,
+	};
+}
+
+export class SQLiteDiscussionRoundStore implements DiscussionRoundStore {
+	constructor(private readonly db: Db) {}
+
+	append(round: AppendDiscussionRound, occurredAt: string): DiscussionRound {
+		const content = validateDiscussionContent(round.content);
+		const actor = validateDiscussionActor(round.actor);
+		const result = this.db.prepare(`
+			INSERT INTO discussion_rounds (discussion_id, round_number, actor, content, occurred_at, event_schema_version)
+			VALUES (?, ?, ?, ?, ?, 1)
+		`).run(round.discussionId, round.roundNumber, actor, content, occurredAt);
+		return {
+			id: Number(result.lastInsertRowid),
+			discussionId: round.discussionId,
+			roundNumber: round.roundNumber,
+			actor,
+			content,
+			occurredAt,
+		};
+	}
+
+	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
+			FROM discussion_rounds
+			WHERE discussion_id = ? AND round_number > ?
+			ORDER BY round_number ASC
+			LIMIT ?
+		`).all(query.discussionId, query.afterRound ?? 0, limit) as DiscussionRoundRow[];
+		return rows.map(mapRow);
+	}
+
+	count(discussionId: string): number {
+		return (this.db.prepare("SELECT COUNT(*) AS c FROM discussion_rounds WHERE discussion_id = ?").get(discussionId) as { c: number }).c;
+	}
+}

package/src/cli.ts

@@ -118,6 +118,16 @@ 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>] [--json]
+  papyrus discuss reply <id> --actor <a> --content <c> [--json]
+  papyrus discuss defer <id> [--reason <text>] [--json]
+  papyrus discuss resume <id> [--json]
+  papyrus discuss settle <id> --settlement <text> [--json]
+  papyrus discuss block <id> --task-id <task-id> [--json]
+  papyrus discuss unblock <id> --task-id <task-id> [--json]
+  papyrus discuss show <id> [--json]
+  papyrus discuss rounds <id> [--after-round <n>] [--limit <n>] [--json]
+  papyrus discuss list [--state active|deferred|settled] [--limit <n>] [--json]
   papyrus log query --source <id> [--since <iso>] [--level <debug|info|warning|error>] [--limit <count>] [--json]
   papyrus tasks plan [--session-id <id>] [--json]
   papyrus tasks graph [--session-id <id>] [--json]
@@ -974,6 +984,106 @@ export async function runSessionIdentityCli(args: string[], client: TaskCliClien
 	throw new Error("session action must be register or release");
 }
 
+export async function runDiscussCli(args: string[], client: TaskCliClient): Promise<string> {
+	const json = args.includes("--json");
+	const positional: string[] = [];
+	let title: string | undefined;
+	let actor: string | undefined;
+	let content: string | undefined;
+	let body: string | undefined;
+	let labels: string[] | undefined;
+	let blocksTaskIds: string[] | undefined;
+	let taskId: string | undefined;
+	let reason: string | undefined;
+	let settlement: string | undefined;
+	let state: string | undefined;
+	let afterRound: number | undefined;
+	let limit: number | undefined;
+	for (let index = 0; index < args.length; index++) {
+		const argument = args[index]!;
+		if (argument === "--json") continue;
+		if (argument === "--title") { title = args[++index]; if (!title) throw new Error("--title requires a value"); continue; }
+		if (argument === "--actor") { actor = args[++index]; if (!actor) throw new Error("--actor requires a value"); continue; }
+		if (argument === "--content") { content = args[++index]; if (content === undefined) throw new Error("--content requires a value"); continue; }
+		if (argument === "--body") { body = args[++index]; if (body === undefined) throw new Error("--body requires a value"); continue; }
+		if (argument === "--labels-json") { labels = parseJsonStringArrayFlag(args[++index], "--labels-json"); continue; }
+		if (argument === "--blocks-json") { blocksTaskIds = parseJsonStringArrayFlag(args[++index], "--blocks-json"); continue; }
+		if (argument === "--task-id") { taskId = args[++index]; if (!taskId) throw new Error("--task-id requires a value"); 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; }
+		if (argument === "--state") { state = args[++index]; if (!state) throw new Error("--state requires a value"); continue; }
+		if (argument === "--after-round") {
+			const value = args[++index];
+			if (!value || Number.isNaN(Number(value))) throw new Error("--after-round requires a numeric value");
+			afterRound = Number(value);
+			continue;
+		}
+		if (argument === "--limit") {
+			const value = args[++index];
+			if (!value || Number.isNaN(Number(value))) throw new Error("--limit requires a numeric value");
+			limit = Number(value);
+			continue;
+		}
+		if (argument.startsWith("--")) throw new Error(`unknown discuss option ${argument}`);
+		positional.push(argument);
+	}
+	const [action, id] = positional;
+	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 });
+			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 });
+			return json ? JSON.stringify(result) : JSON.stringify(result, null, 2);
+		}
+		case "defer": {
+			if (!id) throw new Error("discuss defer requires exactly one discussion id");
+			const result = await client.call<Record<string, unknown>, unknown>("discuss.defer", { id, reason });
+			return json ? JSON.stringify(result) : JSON.stringify(result, null, 2);
+		}
+		case "resume": {
+			if (!id) throw new Error("discuss resume requires exactly one discussion id");
+			const result = await client.call<Record<string, unknown>, unknown>("discuss.resume", { id });
+			return json ? JSON.stringify(result) : JSON.stringify(result, null, 2);
+		}
+		case "settle": {
+			if (!id) throw new Error("discuss settle requires exactly one discussion id");
+			const result = await client.call<Record<string, unknown>, unknown>("discuss.settle", { id, settlement });
+			return json ? JSON.stringify(result) : JSON.stringify(result, null, 2);
+		}
+		case "block": {
+			if (!id) throw new Error("discuss block requires exactly one discussion id");
+			const result = await client.call<Record<string, unknown>, unknown>("discuss.block", { id, task_id: taskId });
+			return json ? JSON.stringify(result) : JSON.stringify(result, null, 2);
+		}
+		case "unblock": {
+			if (!id) throw new Error("discuss unblock requires exactly one discussion id");
+			const result = await client.call<Record<string, unknown>, unknown>("discuss.unblock", { id, task_id: taskId });
+			return json ? JSON.stringify(result) : JSON.stringify(result, null, 2);
+		}
+		case "show": {
+			if (!id) throw new Error("discuss show requires exactly one discussion id");
+			const result = await client.call<Record<string, unknown>, unknown>("discuss.show", { id });
+			return json ? JSON.stringify(result) : JSON.stringify(result, null, 2);
+		}
+		case "rounds": {
+			if (!id) throw new Error("discuss rounds requires exactly one discussion id");
+			const result = await client.call<Record<string, unknown>, unknown>("discuss.rounds", { id, after_round: afterRound, limit });
+			return json ? JSON.stringify(result) : JSON.stringify(result, null, 2);
+		}
+		case "list": {
+			if (id) throw new Error("discuss list accepts no positional arguments");
+			const result = await client.call<Record<string, unknown>, unknown>("discuss.list", { state, limit });
+			return json ? JSON.stringify(result) : JSON.stringify(result, null, 2);
+		}
+		default:
+			throw new Error("discuss action must be open, reply, defer, resume, settle, block, unblock, show, rounds, or list");
+	}
+}
+
 export async function runNoteCli(args: string[], client: TaskCliClient, projectRoot: string = process.cwd()): Promise<string> {
 	const json = args.includes("--json");
 	const positional: string[] = [];
@@ -1395,6 +1505,11 @@ export async function main(args: string[] = process.argv.slice(2)): Promise<void
 		console.log(await runSessionIdentityCli(args.slice(1), client));
 		return;
 	}
+	if (command === "discuss") {
+		const client = await connectPapyrusClient();
+		console.log(await runDiscussCli(args.slice(1), client));
+		return;
+	}
 	if (command === "migrate") {
 		const client = await connectPapyrusClient();
 		console.log(await runMigrationCli(args.slice(1), client));

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 = 14;
+export const SQLITE_SCHEMA_VERSION = 15;
 export const SERVICE_MAX_BODY_BYTES = 1_048_576;
 
 export const WAL_CHECKPOINT_INTERVAL_MS = 60_000;
@@ -137,6 +137,27 @@ export const NOTE_REASON_MAX_CHARACTERS = 2_000;
 export const ARTIFACT_EVENT_ACTOR_MAX_LENGTH = 128;
 export const ARTIFACT_EVENT_HISTORY_DEFAULT_LIMIT = 25;
 export const ARTIFACT_EVENT_HISTORY_MAX_LIMIT = 200;
+/**
+ * Discuss: a native, blocking-capable deliberation, distinct from Discourse's forum (kept
+ * fully standalone, no dependency here) and from the removed ConversationJournal (see Doc
+ * 285681a7-bd44-4f33-93b1-1e10198d6d16 -- that domain never had a forcing real caller; a
+ * Discussion's ability to block a Task's completion is exactly that forcing caller).
+ * A Discussion is a `doc` with subtype "discussion"; its fine-grained lifecycle
+ * (active/deferred/settled) lives in extra.discussion, not the shared doc status
+ * vocabulary, since Papyrus enforces status per-kind, not per-subtype. Rounds are a
+ * dedicated append-only child table, mirroring task_events' proven shape -- a round
+ * carries substantive content, unlike the generic artifact_events log's transition markers.
+ */
+export const DISCUSSION_ROUND_CONTENT_MAX_CHARACTERS = 10_000;
+export const DISCUSSION_ROUNDS_DEFAULT_LIMIT = 25;
+export const DISCUSSION_ROUNDS_MAX_LIMIT = 200;
+/** Hard ceiling on total rounds a single Discussion can ever accumulate -- forces settlement or deferral rather than an unbounded back-and-forth. */
+export const DISCUSSION_MAX_ROUNDS = 200;
+export const DISCUSSION_LIST_DEFAULT_LIMIT = 50;
+export const DISCUSSION_LIST_MAX_LIMIT = 200;
+export const DISCUSSION_SETTLEMENT_MAX_CHARACTERS = 4_000;
+export const DISCUSSION_DEFER_REASON_MAX_CHARACTERS = 2_000;
+export const DISCUSSION_ACTOR_MAX_LENGTH = 128;
 /** 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

@@ -227,6 +227,22 @@ CREATE TABLE IF NOT EXISTS artifact_trash (
 	reason       TEXT
 );
 CREATE INDEX IF NOT EXISTS artifact_trash_purge_idx ON artifact_trash(purge_after);
+CREATE TABLE IF NOT EXISTS discussion_rounds (
+	id            INTEGER PRIMARY KEY AUTOINCREMENT,
+	discussion_id TEXT NOT NULL REFERENCES artifacts(id),
+	round_number  INTEGER NOT NULL,
+	actor         TEXT NOT NULL,
+	content       TEXT NOT NULL,
+	occurred_at   TEXT NOT NULL,
+	event_schema_version INTEGER NOT NULL DEFAULT 1,
+	UNIQUE (discussion_id, round_number)
+);
+CREATE INDEX IF NOT EXISTS discussion_rounds_discussion_idx ON discussion_rounds(discussion_id, round_number, id);
+CREATE TRIGGER IF NOT EXISTS discussion_rounds_no_update BEFORE UPDATE ON discussion_rounds
+BEGIN SELECT RAISE(ABORT, 'discussion_rounds are append-only'); END;
+CREATE TRIGGER IF NOT EXISTS discussion_rounds_no_delete BEFORE DELETE ON discussion_rounds
+WHEN NOT EXISTS (SELECT 1 FROM artifact_trash WHERE artifact_id = OLD.discussion_id AND purge_after <= strftime('%Y-%m-%dT%H:%M:%fZ','now'))
+BEGIN SELECT RAISE(ABORT, 'discussion_rounds are append-only except during an explicit, elapsed-grace-period artifact trash purge'); END;
 `;
 
 const SEED_SQL = `
@@ -252,7 +268,7 @@ INSERT OR IGNORE INTO relation_names VALUES ('implements','This work satisfies t
 INSERT OR IGNORE INTO relation_names VALUES ('follows','This work obeys that (task→rule, task→skill)');
 INSERT OR IGNORE INTO relation_names VALUES ('depends_on','DAG ordering (task→task)');
 INSERT OR IGNORE INTO relation_names VALUES ('documents','Describes (doc→task, doc→rule, doc→skill)');
-INSERT OR IGNORE INTO relation_names VALUES ('blocks','Blocking relationship (task→task)');
+INSERT OR IGNORE INTO relation_names VALUES ('blocks','Blocking relationship (task→task, or an active Discussion doc→task)');
 INSERT OR IGNORE INTO relation_names VALUES ('supersedes','Replaces (doc→doc, rule→rule)');
 INSERT OR IGNORE INTO relation_names VALUES ('relates_to','Catch-all (any→any)');
 INSERT OR IGNORE INTO relation_names VALUES ('gates','This rule gates that task (rule→task)');
@@ -306,6 +322,7 @@ const CORE_LEDGER_VERSIONS: ReadonlyArray<{ version: number; name: string; check
 	{ version: 4, name: "remove-discourse", checksum: "b923f41c44460f0aaeb2f4e60e28f8b8e1425d03f527955bd991434b46de4c82" },
 	{ version: 5, name: "session-identity", checksum: "1c6a165bbe37f82a100fd34762db70c3f8ab15ff20c3a53c2e60448edc815a5e" },
 	{ version: 6, name: "artifact-trash", checksum: "4a75dbec2892deb54bcc1afdf0d51d81f03a8d10861787d083784a29e5c7e8f9" },
+	{ version: 7, name: "discuss-native", checksum: "ab7bdd04824bd93681917807b817d6e08b9825af90161e3ccd6d6663021dc6a0" },
 ];
 
 export function migrationLedger(db: Db): ModuleMigrationRow[] {
@@ -425,6 +442,34 @@ const FUTURE_MIGRATIONS: ReadonlyArray<PapyrusMigration> = [
 			`);
 		},
 	},
+	{
+		version: 15,
+		name: "discuss-native",
+		// See domain/discussion.ts. discussion_rounds mirrors task_events' proven shape (append-only,
+		// with the identical trash-purge trigger carve-out); the blocks relation's description is
+		// widened to reflect that an active Discussion doc can now block a task too.
+		up: (db) => {
+			db.exec(`
+				CREATE TABLE IF NOT EXISTS discussion_rounds (
+					id            INTEGER PRIMARY KEY AUTOINCREMENT,
+					discussion_id TEXT NOT NULL REFERENCES artifacts(id),
+					round_number  INTEGER NOT NULL,
+					actor         TEXT NOT NULL,
+					content       TEXT NOT NULL,
+					occurred_at   TEXT NOT NULL,
+					event_schema_version INTEGER NOT NULL DEFAULT 1,
+					UNIQUE (discussion_id, round_number)
+				);
+				CREATE INDEX IF NOT EXISTS discussion_rounds_discussion_idx ON discussion_rounds(discussion_id, round_number, id);
+				CREATE TRIGGER IF NOT EXISTS discussion_rounds_no_update BEFORE UPDATE ON discussion_rounds
+				BEGIN SELECT RAISE(ABORT, 'discussion_rounds are append-only'); END;
+				CREATE TRIGGER IF NOT EXISTS discussion_rounds_no_delete BEFORE DELETE ON discussion_rounds
+				WHEN NOT EXISTS (SELECT 1 FROM artifact_trash WHERE artifact_id = OLD.discussion_id AND purge_after <= strftime('%Y-%m-%dT%H:%M:%fZ','now'))
+				BEGIN SELECT RAISE(ABORT, 'discussion_rounds are append-only except during an explicit, elapsed-grace-period artifact trash purge'); END;
+				UPDATE relation_names SET description = 'Blocking relationship (task→task, or an active Discussion doc→task)' WHERE name = 'blocks';
+			`);
+		},
+	},
 ];
 
 /**

package/src/discussion-service.ts

@@ -0,0 +1,162 @@
+/**
+ * Discuss: application service composing the Discussion Doc (via ArtifactStore) with its
+ * append-only rounds (via DiscussionRoundStore). See domain/discussion.ts for the full
+ * design rationale.
+ */
+import { DISCUSSION_LIST_DEFAULT_LIMIT, DISCUSSION_LIST_MAX_LIMIT, DISCUSSION_MAX_ROUNDS } from "./constants.ts";
+import {
+	DISCUSSION_SUBTYPE,
+	isDiscussionArtifact,
+	readDiscussionExtra,
+	validateDeferReason,
+	validateDiscussionActor,
+	validateDiscussionContent,
+	validateSettlement,
+	type DiscussionExtra,
+	type DiscussionRound,
+} from "./domain/discussion.ts";
+import type { Artifact } from "./domain/artifact.ts";
+import type { ArtifactEventContext } from "./domain/artifact-event.ts";
+import type { AtomicArtifactStore } from "./ports/atomic-artifact-store.ts";
+import type { DiscussionRoundStore } from "./ports/discussion-round-store.ts";
+
+export class DiscussionError extends Error {}
+
+export interface OpenDiscussionInput {
+	title: string;
+	actor: string;
+	content: string;
+	body?: string;
+	labels?: string[];
+	blocksTaskIds?: string[];
+}
+
+export interface DiscussionAndRounds {
+	discussion: Artifact;
+	rounds: DiscussionRound[];
+}
+
+function requireDiscussion(artifact: Artifact | null, id: string): Artifact {
+	if (!artifact) throw new DiscussionError(`discussion "${id}" not found`);
+	if (!isDiscussionArtifact(artifact)) throw new DiscussionError(`artifact "${id}" is not a Discussion`);
+	return artifact;
+}
+
+export class Discussions {
+	constructor(
+		private readonly artifacts: AtomicArtifactStore,
+		private readonly rounds: DiscussionRoundStore,
+	) {}
+
+	private extra(discussion: Artifact): DiscussionExtra {
+		return readDiscussionExtra(discussion.extra);
+	}
+
+	open(input: OpenDiscussionInput, context?: ArtifactEventContext): DiscussionAndRounds {
+		const actor = validateDiscussionActor(input.actor);
+		const content = validateDiscussionContent(input.content);
+		return this.artifacts.atomic(() => {
+			const discussion = this.artifacts.create({
+				kind: "doc",
+				subtype: DISCUSSION_SUBTYPE,
+				title: input.title,
+				body: input.body ?? "",
+				status: "active",
+				labels: input.labels,
+				extra: { discussion: { state: "active", roundCount: 1 } },
+			}, context);
+			const round = this.rounds.append({ discussionId: discussion.id, roundNumber: 1, actor, content }, new Date().toISOString());
+			for (const taskId of input.blocksTaskIds ?? []) this.block(discussion.id, taskId, context);
+			return { discussion: this.artifacts.get(discussion.id)!, rounds: [round] };
+		});
+	}
+
+	reply(discussionId: string, actor: string, content: string, context?: ArtifactEventContext): DiscussionAndRounds {
+		const validActor = validateDiscussionActor(actor);
+		const validContent = validateDiscussionContent(content);
+		return this.artifacts.atomic(() => {
+			const discussion = requireDiscussion(this.artifacts.get(discussionId), discussionId);
+			const state = this.extra(discussion);
+			if (state.state !== "active") throw new DiscussionError(`discussion "${discussionId}" is ${state.state}; resume it before replying`);
+			if (state.roundCount >= DISCUSSION_MAX_ROUNDS) throw new DiscussionError(`discussion "${discussionId}" has reached its ${DISCUSSION_MAX_ROUNDS}-round limit; settle or defer it`);
+			const nextRound = state.roundCount + 1;
+			const round = this.rounds.append({ discussionId, roundNumber: nextRound, actor: validActor, content: validContent }, new Date().toISOString());
+			const updated = this.artifacts.setExtra(discussionId, { ...discussion.extra, discussion: { ...state, roundCount: nextRound } }, context)!;
+			return { discussion: updated, rounds: [round] };
+		});
+	}
+
+	defer(discussionId: string, reason?: string, context?: ArtifactEventContext): Artifact {
+		const validReason = reason === undefined ? undefined : validateDeferReason(reason);
+		return this.artifacts.atomic(() => {
+			const discussion = requireDiscussion(this.artifacts.get(discussionId), discussionId);
+			const state = this.extra(discussion);
+			if (state.state !== "active") throw new DiscussionError(`discussion "${discussionId}" is ${state.state}; only an active Discussion can be deferred`);
+			return this.artifacts.setExtra(discussionId, {
+				...discussion.extra,
+				discussion: { ...state, state: "deferred", ...(validReason === undefined ? {} : { deferredReason: validReason }) },
+			}, context)!;
+		});
+	}
+
+	resume(discussionId: string, context?: ArtifactEventContext): Artifact {
+		return this.artifacts.atomic(() => {
+			const discussion = requireDiscussion(this.artifacts.get(discussionId), discussionId);
+			const state = this.extra(discussion);
+			if (state.state !== "deferred") throw new DiscussionError(`discussion "${discussionId}" is ${state.state}; only a deferred Discussion can be resumed`);
+			const { deferredReason: _deferredReason, ...rest } = state;
+			return this.artifacts.setExtra(discussionId, { ...discussion.extra, discussion: { ...rest, state: "active" } }, context)!;
+		});
+	}
+
+	settle(discussionId: string, settlement: string, context?: ArtifactEventContext): Artifact {
+		const validSettlement = validateSettlement(settlement);
+		return this.artifacts.atomic(() => {
+			const discussion = requireDiscussion(this.artifacts.get(discussionId), discussionId);
+			const state = this.extra(discussion);
+			if (state.state === "settled") throw new DiscussionError(`discussion "${discussionId}" is already settled`);
+			const updated = this.artifacts.setExtra(discussionId, {
+				...discussion.extra,
+				discussion: { ...state, state: "settled", settlement: validSettlement, settledAt: new Date().toISOString() },
+			}, context)!;
+			return this.artifacts.setStatus(discussionId, "archived", context) ?? updated;
+		});
+	}
+
+	/** Links an existing active Discussion to a Task it blocks; refuses a non-task target or an already-settled Discussion. */
+	block(discussionId: string, taskId: string, context?: ArtifactEventContext): void {
+		const discussion = requireDiscussion(this.artifacts.get(discussionId), discussionId);
+		if (this.extra(discussion).state === "settled") throw new DiscussionError(`discussion "${discussionId}" is settled; it can no longer block anything`);
+		const task = this.artifacts.get(taskId);
+		if (!task) throw new DiscussionError(`task "${taskId}" not found`);
+		if (task.kind !== "task") throw new DiscussionError(`artifact "${taskId}" is not a task`);
+		this.artifacts.link({ from: discussionId, relation: "blocks", to: taskId }, context);
+	}
+
+	/** Idempotent: unblocking an already-absent relationship is a no-op. */
+	unblock(discussionId: string, taskId: string, context?: ArtifactEventContext): boolean {
+		return this.artifacts.unlink({ from: discussionId, relation: "blocks", to: taskId }, context);
+	}
+
+	show(discussionId: string): DiscussionAndRounds {
+		const discussion = requireDiscussion(this.artifacts.get(discussionId), discussionId);
+		return { discussion, rounds: this.rounds.list({ discussionId }) };
+	}
+
+	listRounds(discussionId: string, afterRound?: number, limit?: number): DiscussionRound[] {
+		requireDiscussion(this.artifacts.get(discussionId), discussionId);
+		return this.rounds.list({ discussionId, afterRound, limit });
+	}
+
+	list(filter: { state?: string; limit?: number } = {}): Artifact[] {
+		// DISCUSSION_LIST_MAX_LIMIT/DEFAULT_LIMIT exist specifically so an unqualified discuss.list
+		// (limit omitted) can never fall through to queryArtifacts' own unbounded default -- the same
+		// class of gap notes.ts's noteListInput comment documents fixing for Notes.
+		const limit = Math.min(DISCUSSION_LIST_MAX_LIMIT, Math.max(1, Math.floor(filter.limit ?? DISCUSSION_LIST_DEFAULT_LIMIT)));
+		const rows = this.artifacts.query({ kind: "doc", subtype: DISCUSSION_SUBTYPE, limit });
+		if (!filter.state) return rows;
+		return rows.filter((row) => {
+			try { return this.extra(row).state === filter.state; } catch { return false; }
+		});
+	}
+}

package/src/domain/discussion.ts

@@ -0,0 +1,107 @@
+/**
+ * Discuss: a native Papyrus deliberation with a real lifecycle, distinct from a one-shot
+ * "ask" (see the design discussion this implements) and from Discourse's forum (kept fully
+ * standalone by design -- no dependency here, Discuss reuses none of its storage or wire
+ * shape). A Discussion is a `doc` artifact with subtype "discussion": real graph citizenship
+ * (edges, show/list) without a fifth enforced artifact kind. Its fine-grained lifecycle
+ * lives in extra.discussion rather than the shared doc status vocabulary, since Papyrus
+ * enforces status per-kind, not per-subtype -- "deferred" has no equivalent among a plain
+ * doc's draft/active/archived. The doc's own status column follows loosely: "active" while
+ * extra.discussion.state is active or deferred, "archived" once settled.
+ *
+ * Blocking is the forcing, load-bearing behavior a Discussion adds over a passive record:
+ * an "active" Discussion that `blocks` a Task refuses that Task's completion (see
+ * task-service.ts's blockingDiscussions) until the Discussion is settled or deferred.
+ * Deferred is explicitly non-blocking -- "we will get back to this," not "resolved".
+ */
+import {
+	DISCUSSION_ACTOR_MAX_LENGTH,
+	DISCUSSION_DEFER_REASON_MAX_CHARACTERS,
+	DISCUSSION_ROUND_CONTENT_MAX_CHARACTERS,
+	DISCUSSION_SETTLEMENT_MAX_CHARACTERS,
+} from "../constants.ts";
+
+export const DISCUSSION_SUBTYPE = "discussion";
+
+export const DISCUSSION_STATES = ["active", "deferred", "settled"] as const;
+export type DiscussionState = typeof DISCUSSION_STATES[number];
+
+/** Persisted in a discussion Doc's `extra.discussion`. */
+export interface DiscussionExtra {
+	state: DiscussionState;
+	roundCount: number;
+	deferredReason?: string;
+	settlement?: string;
+	settledAt?: string;
+}
+
+/** One append-only round of a Discussion -- opening statement is round 1. */
+export interface DiscussionRound {
+	id: number;
+	discussionId: string;
+	roundNumber: number;
+	actor: string;
+	content: string;
+	occurredAt: string;
+}
+
+export interface AppendDiscussionRound {
+	discussionId: string;
+	roundNumber: number;
+	actor: string;
+	content: string;
+}
+
+export interface DiscussionRoundQuery {
+	discussionId: string;
+	afterRound?: number;
+	limit?: number;
+}
+
+function boundedString(value: string, field: string, maximum: number): string {
+	if (value.length === 0 || value.length > maximum) throw new Error(`${field} must be between 1 and ${maximum} characters`);
+	return value;
+}
+
+export function validateDiscussionContent(content: string): string {
+	return boundedString(content, "content", DISCUSSION_ROUND_CONTENT_MAX_CHARACTERS);
+}
+
+export function validateDiscussionActor(actor: string): string {
+	return boundedString(actor, "actor", DISCUSSION_ACTOR_MAX_LENGTH);
+}
+
+export function validateDeferReason(reason: string): string {
+	return boundedString(reason, "reason", DISCUSSION_DEFER_REASON_MAX_CHARACTERS);
+}
+
+export function validateSettlement(settlement: string): string {
+	return boundedString(settlement, "settlement", DISCUSSION_SETTLEMENT_MAX_CHARACTERS);
+}
+
+/** True for any artifact (already fetched) that is a Discussion, regardless of its current lifecycle state. */
+export function isDiscussionArtifact(artifact: { kind: string; subtype: string }): boolean {
+	return artifact.kind === "doc" && artifact.subtype === DISCUSSION_SUBTYPE;
+}
+
+/** Reads and defensively validates the extra.discussion shape; throws on a corrupt/foreign shape rather than silently treating it as some default state. */
+export function readDiscussionExtra(extra: Record<string, unknown>): DiscussionExtra {
+	const raw = extra["discussion"];
+	if (typeof raw !== "object" || raw === null) throw new Error("artifact is not a Discussion (missing extra.discussion)");
+	const record = raw as Record<string, unknown>;
+	const state = record["state"];
+	if (typeof state !== "string" || !(DISCUSSION_STATES as readonly string[]).includes(state)) {
+		throw new Error(`invalid Discussion state "${String(state)}"`);
+	}
+	const roundCount = record["roundCount"];
+	if (typeof roundCount !== "number" || !Number.isInteger(roundCount) || roundCount < 0) {
+		throw new Error("invalid Discussion roundCount");
+	}
+	return {
+		state: state as DiscussionState,
+		roundCount,
+		...(typeof record["deferredReason"] === "string" ? { deferredReason: record["deferredReason"] } : {}),
+		...(typeof record["settlement"] === "string" ? { settlement: record["settlement"] } : {}),
+		...(typeof record["settledAt"] === "string" ? { settledAt: record["settledAt"] } : {}),
+	};
+}

package/src/modules/discuss.ts

@@ -0,0 +1,87 @@
+/**
+ * modules/discuss.ts — Discuss as a Papyrus-native registered module. See
+ * domain/discussion.ts and discussion-service.ts for the full design.
+ */
+import type { ArtifactEventContext } from "../domain/artifact-event.ts";
+import type { Discussions } from "../discussion-service.ts";
+import type { OperationDefinition } from "../module-registry.ts";
+
+const MODULE_ID = "discuss";
+
+type OperationInput = Record<string, unknown>;
+
+function string(input: OperationInput, key: string): string {
+	const value = input[key];
+	if (typeof value !== "string" || value.length === 0) throw new Error(`${key} is required`);
+	return value;
+}
+
+function optionalString(input: OperationInput, key: string): string | undefined {
+	const value = input[key];
+	if (value === undefined) return undefined;
+	if (typeof value !== "string") throw new Error(`${key} must be a string`);
+	return value;
+}
+
+function optionalStringArray(input: OperationInput, key: string): string[] | undefined {
+	const value = input[key];
+	if (value === undefined) return undefined;
+	if (!Array.isArray(value) || value.some((entry) => typeof entry !== "string")) throw new Error(`${key} must be an array of strings`);
+	return value as string[];
+}
+
+function optionalNumber(input: OperationInput, key: string): number | undefined {
+	const value = input[key];
+	if (value === undefined) return undefined;
+	if (typeof value !== "number" || !Number.isFinite(value)) throw new Error(`${key} must be a number`);
+	return value;
+}
+
+const eventContext = (input: OperationInput): ArtifactEventContext => ({
+	actor: optionalString(input, "actor"),
+	source: optionalString(input, "source"),
+	sessionId: optionalString(input, "session_id") ?? optionalString(input, "sessionId"),
+});
+
+function taskId(input: OperationInput): string {
+	const value = optionalString(input, "task_id") ?? optionalString(input, "taskId");
+	if (!value) throw new Error("task_id is required");
+	return value;
+}
+
+/** This module's own operation names, the single source of truth src/service.ts's EXPECTED_OPERATION_NAMES spreads in rather than re-listing by hand. */
+export const DISCUSS_OPERATION_NAMES = [
+	"discuss.open", "discuss.reply", "discuss.defer", "discuss.resume", "discuss.settle",
+	"discuss.block", "discuss.unblock", "discuss.show", "discuss.rounds", "discuss.list",
+] as const;
+
+/** Registers every discuss.* operation against one Discussions instance. */
+export function discussOperations(discussions: Discussions): OperationDefinition[] {
+	const define = <Input, Output>(name: string, execute: (input: Input) => Output): OperationDefinition<Input, Output> => ({
+		name, moduleId: MODULE_ID, execute,
+	});
+	return [
+		define("discuss.open", (input: OperationInput) => discussions.open({
+			title: string(input, "title"),
+			actor: string(input, "actor"),
+			content: string(input, "content"),
+			body: optionalString(input, "body"),
+			labels: optionalStringArray(input, "labels"),
+			blocksTaskIds: optionalStringArray(input, "blocks_task_ids") ?? optionalStringArray(input, "blocksTaskIds"),
+		}, eventContext(input))),
+		define("discuss.reply", (input: OperationInput) => discussions.reply(string(input, "id"), string(input, "actor"), string(input, "content"), 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))),
+		define("discuss.settle", (input: OperationInput) => discussions.settle(string(input, "id"), string(input, "settlement"), eventContext(input))),
+		define("discuss.block", (input: OperationInput) => {
+			discussions.block(string(input, "id"), taskId(input), eventContext(input));
+			return { blocked: true };
+		}),
+		define("discuss.unblock", (input: OperationInput) => ({
+			unblocked: discussions.unblock(string(input, "id"), taskId(input), eventContext(input)),
+		})),
+		define("discuss.show", (input: OperationInput) => discussions.show(string(input, "id"))),
+		define("discuss.rounds", (input: OperationInput) => discussions.listRounds(string(input, "id"), optionalNumber(input, "after_round") ?? optionalNumber(input, "afterRound"), optionalNumber(input, "limit"))),
+		define("discuss.list", (input: OperationInput) => discussions.list({ state: optionalString(input, "state"), limit: optionalNumber(input, "limit") })),
+	];
+}

package/src/ports/discussion-round-store.ts

@@ -0,0 +1,8 @@
+import type { AppendDiscussionRound, DiscussionRound, DiscussionRoundQuery } from "../domain/discussion.ts";
+
+/** Persistence port for a Discussion's append-only rounds (see domain/discussion.ts). */
+export interface DiscussionRoundStore {
+	append(round: AppendDiscussionRound, occurredAt: string): DiscussionRound;
+	list(query: DiscussionRoundQuery): DiscussionRound[];
+	count(discussionId: string): number;
+}

package/src/service.ts

@@ -34,7 +34,10 @@ import { notesOperations, NOTES_OPERATION_NAMES } from "./modules/notes.ts";
 import { rulesOperations, RULES_OPERATION_NAMES } from "./modules/rules.ts";
 import { skillsOperations, SKILLS_OPERATION_NAMES } from "./modules/skills.ts";
 import { sessionIdentityOperations, SESSION_IDENTITY_OPERATION_NAMES } from "./modules/session-identity.ts";
+import { discussOperations, DISCUSS_OPERATION_NAMES } from "./modules/discuss.ts";
 import { tasksOperations, TASKS_OPERATION_NAMES } from "./modules/tasks.ts";
+import { Discussions } from "./discussion-service.ts";
+import { SQLiteDiscussionRoundStore } from "./adapters/sqlite-discussion-round-store.ts";
 
 /**
  * Operations with no registered module: the generic, cross-cutting kernel surface
@@ -73,6 +76,7 @@ export const EXPECTED_OPERATION_NAMES = [
 	...GRAPH_PROJECTION_OPERATION_NAMES,
 	...LOGS_OPERATION_NAMES,
 	...SESSION_IDENTITY_OPERATION_NAMES,
+	...DISCUSS_OPERATION_NAMES,
 ] as const;
 
 export type OperationName = typeof EXPECTED_OPERATION_NAMES[number];
@@ -383,6 +387,16 @@ function handlers(
 		"logs.query": forwardToModule("logs.query"),
 		"session.register": forwardToModule("session.register"),
 		"session.release": forwardToModule("session.release"),
+		"discuss.open": forwardToModule("discuss.open"),
+		"discuss.reply": forwardToModule("discuss.reply"),
+		"discuss.defer": forwardToModule("discuss.defer"),
+		"discuss.resume": forwardToModule("discuss.resume"),
+		"discuss.settle": forwardToModule("discuss.settle"),
+		"discuss.block": forwardToModule("discuss.block"),
+		"discuss.unblock": forwardToModule("discuss.unblock"),
+		"discuss.show": forwardToModule("discuss.show"),
+		"discuss.rounds": forwardToModule("discuss.rounds"),
+		"discuss.list": forwardToModule("discuss.list"),
 	};
 }
 
@@ -399,11 +413,13 @@ export function createPapyrusService(path: string): PapyrusService {
 	const artifactScopes = new SQLiteArtifactScopeStore(db);
 	const logs = new Logs(new SQLiteLogStore(db));
 	const sessionIdentity = new SessionIdentity(new SQLiteSessionIdentityStore(db));
+	const discussions = new Discussions(artifacts, new SQLiteDiscussionRoundStore(db));
 	const authority = createAuthorityRegistry();
 	const moduleRegistry = new OperationRegistry();
 	moduleRegistry.registerAll(notesOperations(notes));
 	moduleRegistry.registerAll(logsOperations(logs));
 	moduleRegistry.registerAll(sessionIdentityOperations(sessionIdentity));
+	moduleRegistry.registerAll(discussOperations(discussions));
 	moduleRegistry.registerAll(tasksOperations(tasks, artifacts, sessionIdentity));
 	moduleRegistry.registerAll(docsOperations(artifacts, artifactScopes, authority));
 	moduleRegistry.registerAll(rulesOperations(artifacts, artifactScopes));

package/src/task-service.ts

@@ -11,6 +11,7 @@ import {
 } from "./constants.ts";
 import type { Artifact } from "./domain/artifact.ts";
 import { checklistEntries, validateChecklist, type Checklist, type ProofReference } from "./domain/checklist.ts";
+import { isDiscussionArtifact, readDiscussionExtra } from "./domain/discussion.ts";
 import type { Gate, GateResult } from "./domain/gate.ts";
 import type { AppendTaskEvent, TaskEventContext, TaskHistoryPage, TaskHistoryQuery, TaskLifecycleStatus } from "./domain/task-event.ts";
 import { normalizeProjectRoot, taskScopeLabel, type TaskScopeSource, type TaskViewMode, type TaskViewSelection } from "./domain/task-scope.ts";
@@ -419,6 +420,7 @@ export class Tasks {
 
 	complete(id: string, context: TaskEventContext = {}, options: TaskCompletionOptions = {}): TaskCompletion {
 		const task = this.requireReview(id);
+		this.requireNotBlocked(id);
 		const attemptId = crypto.randomUUID();
 		this.events.atomic(() => this.appendEvent({ taskId: id, type: "completion_attempted", fromStatus: "review", toStatus: "review", attemptId }, context));
 		const checklist = this.reviewChecklist(task);
@@ -428,6 +430,7 @@ export class Tasks {
 
 	async completeAsync(id: string, context: TaskEventContext = {}, options: TaskCompletionOptions = {}): Promise<TaskCompletion> {
 		const task = this.requireReview(id);
+		this.requireNotBlocked(id);
 		const attemptId = crypto.randomUUID();
 		this.events.atomic(() => this.appendEvent({ taskId: id, type: "completion_attempted", fromStatus: "review", toStatus: "review", attemptId }, context));
 		const checklist = this.reviewChecklist(task);
@@ -678,4 +681,28 @@ export class Tasks {
 		if (task.status !== "review") throw new Error(`cannot complete task from ${task.status}`);
 		return task;
 	}
+
+	/**
+	 * Discuss's forcing behavior (see domain/discussion.ts): an active Discussion doc that
+	 * `blocks` this task refuses its completion until settled or deferred. A discussion whose
+	 * extra.discussion shape is missing or corrupt is treated as non-blocking rather than
+	 * crashing completion -- the same fail-open posture Task Focus's opt-in armor uses for an
+	 * unrecognized shape.
+	 */
+	private blockingDiscussions(id: string): Artifact[] {
+		return this.artifacts.relationships({ artifactIds: [id] })
+			.filter((edge) => edge.relation === "blocks" && edge.to === id)
+			.map((edge) => this.artifacts.get(edge.from))
+			.filter((source): source is Artifact => source !== null && isDiscussionArtifact(source))
+			.filter((discussion) => {
+				try { return readDiscussionExtra(discussion.extra).state === "active"; } catch { return false; }
+			});
+	}
+
+	private requireNotBlocked(id: string): void {
+		const blockers = this.blockingDiscussions(id);
+		if (blockers.length > 0) {
+			throw new Error(`task "${id}" is blocked by ${blockers.length} active Discussion(s): ${blockers.map((discussion) => discussion.id).join(", ")}`);
+		}
+	}
 }