@danypops/papyrus 0.17.2 → 0.19.0

package/README.md

@@ -100,6 +100,12 @@ papyrus skills run <skill-id> \
 
 The existing `artifact-template` skill subtype remains a compatibility mechanism for one-artifact templates with metadata `{targetKind, defaults, required}`. Instantiate it through `papyrus_create` with `template_id`; defaults merge recursively, explicit arrays replace defaults, required paths such as `extra.owner` are validated, and target-kind mismatches are rejected.
 
+### Removing an artifact
+
+Artifacts are never hard-deleted on request: every artifact gets a permanent, immutable `created` row in the mutation event log the moment it exists, so removal is a real, time-gated trash rather than a status flip. `remove` (any of the `tasks`/`docs`/`rules`/`skills` domain tools, or `papyrus artifact remove <id> [--reason <text>]`) moves an artifact to the trash: it is immediately excluded from every list/query, still directly reachable by id, and fully recoverable via `restore` until its purge deadline (30 days later) passes. `remove` refuses a Task that is the live Task Focus in any scope.
+
+Once the deadline passes, the daemon's periodic sweep performs a real, cascading, irreversible deletion — the one deliberate, narrow exception to Papyrus's otherwise-absolute append-only history, enforced by the database itself (not merely application code) via a trigger condition checked at delete time.
+
 ## Tools
 
 The `papyrus_*` tools are the low-level graph-store API:
@@ -148,6 +154,23 @@ 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."
+
+```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/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";
@@ -31,6 +33,26 @@ function artifactLine(artifact: Artifact): string {
 	return `${artifact.id} [${artifact.status}] ${artifact.title}`;
 }
 
+/**
+ * Shared "remove"/"restore" dispatch for every domain tool (tasks/docs/rules/skills) --
+ * artifact.remove/restore are kind-agnostic composition-root operations (see service.ts),
+ * not owned by any one domain module, so every domain tool exposes the same two actions
+ * over the same two operations rather than reinventing trash semantics four times.
+ * Returns null when action is neither, so callers fall through to their own dispatch.
+ */
+async function handleArtifactRemoveRestore(action: unknown, params: Record<string, unknown>): Promise<ReturnType<typeof text> | null> {
+	if (action === "remove") {
+		const record = await callService<Record<string, unknown>, { artifactId: string; trashedAt: string; purgeAfter: string; reason?: string }>("artifact.remove", params);
+		return text(`Trashed ${record.artifactId}, eligible for purge at ${record.purgeAfter}.`, createPreviewDetails("artifact.remove", "Trashed", record.artifactId));
+	}
+	if (action === "restore") {
+		const outcome = await callService<Record<string, unknown>, { restored: boolean }>("artifact.restore", params);
+		const output = outcome.restored ? `Restored ${params["id"]}.` : `${params["id"]} was not trashed.`;
+		return text(output, createPreviewDetails("artifact.restore", "Restored", output));
+	}
+	return null;
+}
+
 const proofReferenceSchema = Type.Object({
 	type: Type.Union(PROOF_TYPES.map((type) => Type.Literal(type))),
 	target: Type.String(),
@@ -45,7 +67,7 @@ export function registerDomainTools(pi: ExtensionAPI): void {
 	pi.registerTool({
 		name: "tasks",
 		label: "Tasks",
-		description: "Task domain tool. ACTIONS: create, update, list, show, history, scope, set_scope, assign_project, graph, plan, active, focused, focus, pause, unpause, clear_focus, start, submit, complete, reject, retry, cancel, run_gates, set_checklist, depend, undepend, contain, uncontain. Lifecycle is todo → in-progress → review → done, with review failure → rejected and retry → in-progress; canceled is terminal. update can recover a Task accidentally created terminal by setting status=todo with a reason, but cannot rewrite legitimate lifecycle history. Active focus is independent and identifies the one task auto-drive continues. Completion runs gates and checklist-proof review, then focuses one deterministic ready successor without claiming effort. Dependency cycles are rejected. undepend/uncontain are idempotent for an already-absent relationship and never start, complete, or focus work merely because an edge disappeared; uncontain removes both contains and part_of edges atomically. Prefer this over low-level papyrus_* tools for task work.",
+		description: "Task domain tool. ACTIONS: create, update, list, show, history, scope, set_scope, assign_project, graph, plan, active, focused, focus, pause, unpause, clear_focus, start, submit, complete, reject, retry, cancel, run_gates, set_checklist, depend, undepend, contain, uncontain, remove, restore. Lifecycle is todo → in-progress → review → done, with review failure → rejected and retry → in-progress; canceled is terminal. update can recover a Task accidentally created terminal by setting status=todo with a reason, but cannot rewrite legitimate lifecycle history. Active focus is independent and identifies the one task auto-drive continues. Completion runs gates and checklist-proof review, then focuses one deterministic ready successor without claiming effort. Dependency cycles are rejected. undepend/uncontain are idempotent for an already-absent relationship and never start, complete, or focus work merely because an edge disappeared; uncontain removes both contains and part_of edges atomically. remove moves a Task to a time-gated trash (restorable via restore until the purge deadline; refuses if it is the live Task Focus). Prefer this over low-level papyrus_* tools for task work.",
 		parameters: Type.Object({
 			action: Type.String(),
 			id: Type.Optional(Type.String()),
@@ -181,6 +203,8 @@ export function registerDomainTools(pi: ExtensionAPI): void {
 						}))),
 					);
 				}
+				const trashResult = await handleArtifactRemoveRestore(action, params);
+				if (trashResult) return trashResult;
 				const operations = {
 					focus: "tasks.focus",
 					start: "tasks.start",
@@ -257,7 +281,7 @@ export function registerDomainTools(pi: ExtensionAPI): void {
 	pi.registerTool({
 		name: "docs",
 		label: "Documents",
-		description: "Document domain tool. ACTIONS: create, list, show, activate, archive, reopen, link, assign_project. project_root is optional at creation (omitted = unscoped); assign_project reassigns it later, or unscopes when project_root is omitted. Prefer this over low-level papyrus_* tools for document work.",
+		description: "Document domain tool. ACTIONS: create, list, show, activate, archive, reopen, link, assign_project, remove, restore. project_root is optional at creation (omitted = unscoped); assign_project reassigns it later, or unscopes when project_root is omitted. remove moves a Doc to a time-gated trash, excluded from list/query but still directly showable, restorable via restore until the purge deadline. Prefer this over low-level papyrus_* tools for document work.",
 		parameters: Type.Object({
 			action: Type.String(),
 			id: Type.Optional(Type.String()),
@@ -273,6 +297,7 @@ export function registerDomainTools(pi: ExtensionAPI): void {
 			relation: Type.Optional(Type.String()),
 			target_id: Type.Optional(Type.String()),
 			project_root: Type.Optional(Type.String()),
+			reason: Type.Optional(Type.String()),
 		}),
 		renderCall(args, theme) { return renderPapyrusToolCall("Documents", args, theme); },
 		renderResult(result, options, theme, context) { return renderPapyrusToolResult(result, options, theme, context); },
@@ -291,6 +316,8 @@ export function registerDomainTools(pi: ExtensionAPI): void {
 					const artifact = await callService<Record<string, unknown>, Artifact>("docs.show", params);
 					return text(`${artifactLine(artifact)}\n\n${artifact.body}`, createArtifactDetails("docs.show", artifact));
 				}
+				const trashResult = await handleArtifactRemoveRestore(action, params);
+				if (trashResult) return trashResult;
 				const operations = { activate: "docs.activate", archive: "docs.archive", reopen: "docs.reopen", link: "docs.link", assign_project: "docs.assign_project" } as const;
 				const operation = operations[action as keyof typeof operations];
 				if (!operation) throw new Error(`unknown docs action: ${action}`);
@@ -305,14 +332,14 @@ export function registerDomainTools(pi: ExtensionAPI): void {
 	pi.registerTool({
 		name: "rules",
 		label: "Rules",
-		description: "Rule domain tool. ACTIONS: create, list, show, preview, enable, disable, gate, assign_project. project_root is optional at creation (omitted = unscoped); assign_project reassigns it later, or unscopes when project_root is omitted. Active rules inject into the agent system prompt.",
+		description: "Rule domain tool. ACTIONS: create, list, show, preview, enable, disable, gate, assign_project, remove, restore. project_root is optional at creation (omitted = unscoped); assign_project reassigns it later, or unscopes when project_root is omitted. Active rules inject into the agent system prompt. remove moves a Rule to a time-gated trash, excluded from list/query but still directly showable, restorable via restore until the purge deadline.",
 		parameters: Type.Object({
 			action: Type.String(), id: Type.Optional(Type.String()), title: Type.Optional(Type.String()),
 			body: Type.Optional(Type.String()), condition: Type.Optional(Type.String()), rule_action: Type.Optional(Type.String()),
 			severity: Type.Optional(Type.String()), labels: Type.Optional(Type.Array(Type.String())),
 			extra: Type.Optional(Type.Record(Type.String(), Type.Unknown())), status: Type.Optional(Type.String()),
 			text: Type.Optional(Type.String()), limit: Type.Optional(Type.Number()), task_id: Type.Optional(Type.String()),
-			project_root: Type.Optional(Type.String()),
+			project_root: Type.Optional(Type.String()), reason: Type.Optional(Type.String()),
 		}),
 		renderCall(args, theme) { return renderPapyrusToolCall("Rules", args, theme); },
 		renderResult(result, options, theme, context) { return renderPapyrusToolResult(result, options, theme, context); },
@@ -331,6 +358,8 @@ export function registerDomainTools(pi: ExtensionAPI): void {
 					const preview = await callService<Record<string, unknown>, string>("rules.preview", params);
 					return text(preview, createPreviewDetails("rules.preview", "Rule preview", preview));
 				}
+				const trashResult = await handleArtifactRemoveRestore(action, params);
+				if (trashResult) return trashResult;
 				const operations = { show: "rules.show", enable: "rules.enable", disable: "rules.disable", gate: "rules.gate", assign_project: "rules.assign_project" } as const;
 				const operation = operations[action as keyof typeof operations];
 				if (!operation) throw new Error(`unknown rules action: ${action}`);
@@ -345,7 +374,7 @@ export function registerDomainTools(pi: ExtensionAPI): void {
 	pi.registerTool({
 		name: "skills",
 		label: "Skills",
-		description: "Papyrus Skill workflow and compatibility-template domain tool. Papyrus Skills are parameterized Task/Rule/Doc bundles, distinct from prompt-only skills. ACTIONS: create, create_template, list, show, invoke, run, enable, disable, instantiate, assign_project. run validates arguments and atomically creates one scoped workflow run. project_root is optional at creation (omitted = unscoped) for create/create_template; assign_project reassigns it later, or unscopes when project_root is omitted.",
+		description: "Papyrus Skill workflow and compatibility-template domain tool. Papyrus Skills are parameterized Task/Rule/Doc bundles, distinct from prompt-only skills. ACTIONS: create, create_template, list, show, invoke, run, enable, disable, instantiate, assign_project, remove, restore. run validates arguments and atomically creates one scoped workflow run. project_root is optional at creation (omitted = unscoped) for create/create_template; assign_project reassigns it later, or unscopes when project_root is omitted. remove moves a Skill to a time-gated trash, excluded from list/query but still directly showable, restorable via restore until the purge deadline.",
 		parameters: Type.Object({
 			action: Type.String(), id: Type.Optional(Type.String()), title: Type.Optional(Type.String()),
 			body: Type.Optional(Type.String()), trigger: Type.Optional(Type.String()), steps: Type.Optional(Type.Array(Type.String())),
@@ -356,7 +385,7 @@ export function registerDomainTools(pi: ExtensionAPI): void {
 			text: Type.Optional(Type.String()), limit: Type.Optional(Type.Number()), template_id: Type.Optional(Type.String()),
 			target_kind: Type.Optional(Type.String()), defaults: Type.Optional(Type.Record(Type.String(), Type.Unknown())),
 			required: Type.Optional(Type.Array(Type.String())), kind: Type.Optional(Type.String()), subtype: Type.Optional(Type.String()),
-			project_root: Type.Optional(Type.String()),
+			project_root: Type.Optional(Type.String()), reason: Type.Optional(Type.String()),
 		}),
 		renderCall(args, theme) { return renderPapyrusToolCall("Skills", args, theme); },
 		renderResult(result, options, theme, context) { return renderPapyrusToolResult(result, options, theme, context); },
@@ -393,6 +422,8 @@ export function registerDomainTools(pi: ExtensionAPI): void {
 						roots: run.rootTaskIds,
 					}));
 				}
+				const trashResult = await handleArtifactRemoveRestore(action, params);
+				if (trashResult) return trashResult;
 				const operations = { show: "skills.show", enable: "skills.enable", disable: "skills.disable", instantiate: "skills.instantiate", assign_project: "skills.assign_project" } as const;
 				const operation = operations[action as keyof typeof operations];
 				if (!operation) throw new Error(`unknown skills action: ${action}`);
@@ -403,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/package.json

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

package/src/adapters/sqlite-artifact-store.ts

@@ -12,7 +12,23 @@ import type {
 	UpdateArtifactInput,
 } from "../domain/artifact.ts";
 import type { ArtifactEventContext, ArtifactEventPage, ArtifactEventQuery } from "../domain/artifact-event.ts";
-import { createArtifact, getArtifact, linkArtifacts, queryArtifactEvents, queryArtifacts, unlinkArtifacts, updateArtifactContent, updateExtra, updateStatus } from "../ops.ts";
+import type { ArtifactTrashRecord } from "../domain/artifact-trash.ts";
+import {
+	createArtifact,
+	getArtifact,
+	getArtifactTrash,
+	linkArtifacts,
+	listArtifactTrash,
+	purgeDueArtifacts,
+	queryArtifactEvents,
+	queryArtifacts,
+	restoreArtifact,
+	trashArtifact,
+	unlinkArtifacts,
+	updateArtifactContent,
+	updateExtra,
+	updateStatus,
+} from "../ops.ts";
 
 export class SQLiteArtifactStore implements AtomicArtifactStore {
 	constructor(private readonly db: Db) {}
@@ -57,6 +73,26 @@ export class SQLiteArtifactStore implements AtomicArtifactStore {
 		return queryArtifactEvents(this.db, query);
 	}
 
+	trash(id: string, options?: { reason?: string; context?: ArtifactEventContext }): ArtifactTrashRecord {
+		return trashArtifact(this.db, id, { reason: options?.reason, context: options?.context });
+	}
+
+	restore(id: string, context?: ArtifactEventContext): { restored: boolean } {
+		return restoreArtifact(this.db, id, context);
+	}
+
+	trashStatus(id: string): ArtifactTrashRecord | null {
+		return getArtifactTrash(this.db, id);
+	}
+
+	listTrash(): ArtifactTrashRecord[] {
+		return listArtifactTrash(this.db);
+	}
+
+	purgeDueTrash(): number {
+		return purgeDueArtifacts(this.db);
+	}
+
 	relationships(filter: RelationshipQuery = {}): ArtifactEdge[] {
 		if (filter.artifactIds?.length === 0) return [];
 		const conditions: string[] = [];

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

@@ -82,6 +82,10 @@ const USAGE = `Usage:
   papyrus artifact create --kind <kind> [--title <title>] [--status <status>] [--subtype <subtype>] [--body <body>] [--labels-json <json>] [--extra-json <json>] [--template-id <id>] [--json]
   papyrus artifact query [--kind <kind>] [--status <status>] [--text <query>] [--limit <count>] [--json]
   papyrus artifact show <id> [--depth <n>] [--max-nodes <n>] [--json]
+  papyrus artifact remove <id> [--reason <text>] [--json]
+  papyrus artifact restore <id> [--json]
+  papyrus artifact trash-status <id> [--json]
+  papyrus artifact trash-list [--json]
   papyrus docs create --title <title> [--body <body>] [--subtype <subtype>] [--labels-json <json>] [--extra-json <json>] [--template-id <id>] [--project-root <path>] [--json]
   papyrus docs list [--status <status>] [--text <query>] [--limit <count>] [--project-root <path>] [--json]
   papyrus docs show <id> [--json]
@@ -114,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]
@@ -738,6 +752,7 @@ export async function runArtifactCli(args: string[], client: TaskCliClient, proj
 	let labels: string[] | undefined;
 	let extra: Record<string, unknown> | undefined;
 	let templateId: string | undefined;
+	let reason: string | undefined;
 	let text: string | undefined;
 	let limit: number | undefined;
 	let depth: number | undefined;
@@ -753,6 +768,7 @@ export async function runArtifactCli(args: string[], client: TaskCliClient, proj
 		if (argument === "--labels-json") { labels = parseJsonStringArrayFlag(args[++index], "--labels-json"); continue; }
 		if (argument === "--extra-json") { extra = parseJsonObjectFlag(args[++index], "--extra-json"); continue; }
 		if (argument === "--template-id") { templateId = args[++index]; if (!templateId) throw new Error("--template-id requires a value"); continue; }
+		if (argument === "--reason") { reason = args[++index]; if (reason === undefined) throw new Error("--reason requires a value"); continue; }
 		if (argument === "--text") { text = args[++index]; if (text === undefined) throw new Error("--text requires a value"); continue; }
 		if (argument === "--limit") {
 			const value = args[++index];
@@ -804,8 +820,36 @@ export async function runArtifactCli(args: string[], client: TaskCliClient, proj
 			human = `${artifactLabel(artifact)}\n\n${artifact.body ?? ""}`;
 			break;
 		}
+		case "remove": {
+			if (!id) throw new Error("artifact remove requires exactly one artifact id");
+			const record = await client.call<Record<string, unknown>, { artifactId: string; trashedAt: string; purgeAfter: string; reason?: string }>("artifact.remove", { id, reason });
+			result = record;
+			human = `Trashed ${record.artifactId}: eligible for purge at ${record.purgeAfter}`;
+			break;
+		}
+		case "restore": {
+			if (!id) throw new Error("artifact restore requires exactly one artifact id");
+			const outcome = await client.call<Record<string, unknown>, { restored: boolean }>("artifact.restore", { id });
+			result = outcome;
+			human = outcome.restored ? `Restored ${id}` : `${id} was not trashed`;
+			break;
+		}
+		case "trash-status": {
+			if (!id) throw new Error("artifact trash-status requires exactly one artifact id");
+			const record = await client.call<Record<string, unknown>, { artifactId: string; trashedAt: string; purgeAfter: string; reason?: string } | null>("artifact.trash_status", { id });
+			result = record;
+			human = record ? `${record.artifactId}: trashed at ${record.trashedAt}, purge eligible at ${record.purgeAfter}` : `${id} is not trashed`;
+			break;
+		}
+		case "trash-list": {
+			if (id) throw new Error("artifact trash-list accepts no positional arguments");
+			const rows = await client.call<Record<string, unknown>, Array<{ artifactId: string; trashedAt: string; purgeAfter: string; reason?: string }>>("artifact.trash_list", {});
+			result = rows;
+			human = rows.length === 0 ? "Trash is empty." : rows.map((row) => `${row.artifactId}: purge eligible at ${row.purgeAfter}`).join("\n");
+			break;
+		}
 		default:
-			throw new Error("artifact action must be create, query, or show");
+			throw new Error("artifact action must be create, query, show, remove, restore, trash-status, or trash-list");
 	}
 	return json ? JSON.stringify(result) : human;
 }
@@ -940,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[] = [];
@@ -1361,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 = 13;
+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;
@@ -159,6 +180,15 @@ export const TASK_FOCUS_MAX_SCOPES = 500;
 export const TASK_FOCUS_STALE_AFTER_MS = 30 * 24 * 60 * 60 * 1000;
 /** Hard cap on registered session_identities rows (see domain/session-identity.ts); oldest-seen identity is evicted beyond this, mirroring TASK_FOCUS_MAX_SCOPES. */
 export const SESSION_IDENTITY_MAX_ROWS = 2_000;
+/**
+ * Grace period between artifact.remove (trash) and artifact purge eligibility -- see
+ * domain/artifact-trash.ts. 30 days, matching TASK_FOCUS_STALE_AFTER_MS's convention: long
+ * enough that a mistaken removal is still recoverable via artifact.restore, short enough to
+ * actually bound trash accumulation. Enforced twice: the daemon's periodic sweep only
+ * selects rows past this deadline, and the SQLite triggers that otherwise forbid deleting
+ * artifact_events/task_events independently re-check the same deadline at delete time.
+ */
+export const ARTIFACT_TRASH_RETENTION_MS = 30 * 24 * 60 * 60 * 1000;
 /** Persisted project and focused-graph Task view bounds. */
 export const TASK_SCOPE_MAX_TASKS = 1_000;
 /** Docs/Rules/Skills project scope listing bound, mirroring TASK_SCOPE_MAX_TASKS. */

package/src/daemon.ts

@@ -34,6 +34,14 @@ export function serveMain(): void {
 			if (removed > 0) logEvent("info", "stale_focus_reaped", { removed });
 		} catch (error) { logEvent("error", "reap_stale_focus_failed", { message: error instanceof Error ? error.message : String(error) }); }
 	}, DB_OPTIMIZE_INTERVAL_MS);
+	// Same daily cadence: ARTIFACT_TRASH_RETENTION_MS is 30 days, so a daily sweep finds newly
+	// due artifacts promptly without needing its own tighter interval -- see domain/artifact-trash.ts.
+	const purgeTrashTimer = setInterval(() => {
+		try {
+			const purged = service.purgeDueTrash();
+			if (purged > 0) logEvent("info", "artifact_trash_purged", { purged });
+		} catch (error) { logEvent("error", "purge_trash_failed", { message: error instanceof Error ? error.message : String(error) }); }
+	}, DB_OPTIMIZE_INTERVAL_MS);
 	let stopping = false;
 	const shutdown = () => {
 		if (stopping) return;
@@ -41,6 +49,7 @@ export function serveMain(): void {
 		clearInterval(checkpointTimer);
 		clearInterval(optimizeTimer);
 		clearInterval(reapFocusTimer);
+		clearInterval(purgeTrashTimer);
 		clearDaemonPort(stateDir);
 		service.close();
 		void server.stop(true).finally(() => process.exit(0));