@danypops/papyrus 0.9.0 → 0.10.0

package/README.md

@@ -9,7 +9,7 @@ Artifacts are rows in SQLite. Edges are typed relations. Kinds and relations are
 ```text
 Pi tools + TUI
       ↓
-tasks / docs / rules / skills domain tools
+tasks / notes / docs / rules / skills domain tools
       ↓
 Papyrus client → authenticated loopback daemon
       ↓
@@ -40,6 +40,10 @@ papyrus tasks focus <task-id>
 papyrus tasks pause
 papyrus tasks unpause
 papyrus tasks complete <task-id>
+
+# Deferred human-intent inbox
+papyrus notes capture "Review release provenance later"
+papyrus notes list --json
 ```
 
 For repository work, install the versioned ownership guard once:
@@ -94,7 +98,8 @@ The `papyrus_*` tools are the low-level graph-store API:
 Agent-facing domain tools own lifecycle invariants and sit above this store API:
 
 - **`tasks`** — create/update/list/show/plan, manage the singleton active focus, replace evidence-bearing checklists, hierarchy/dependencies, lifecycle transitions, non-blocking gates, and review completion that focuses one deterministic ready successor without claiming effort
-- **`docs`** — create/list/show, activate/archive/reopen, and document-safe graph links
+- **`notes`** — capture/list/show deferred human intent, mark it consumed, promote it to an existing Task/Doc/Rule/Skill, or archive it with an explicit disposition
+- **`docs`** — create/list/show, activate/archive/reopen, and document-safe graph links; Note mutations remain behind the Notes facade
 - **`rules`** — create/list/show/preview, enable/disable, and attach governance gates to tasks
 - **`skills`** — create/list/show/invoke/run, enable/disable, create compatibility templates, and atomically instantiate parameterized workflow runs
 
@@ -105,11 +110,29 @@ Internally, application services depend on the `ArtifactStore` and `GateRunner`
 ## Interactive frontends
 
 - `/tasks` — project/focused-graph scope, task lifecycle, append-only history, gates, dependencies, and nested metadata
-- `/docs` — searchable documents, lifecycle, details, and graph links
+- `/note <request>` — directly capture one project-scoped deferred request without creating a Task
+- `/notes` — searchable project Notes inbox with consume, promote, and disposition-aware archive actions
+- `/docs` — searchable non-Note documents, lifecycle, details, and graph links
 - `/rules` — severity/condition rows, exact injection preview, enable/disable, and task gating
 - `/skills` — trigger/tools rows, invocation into the editor, and artifact templates
 
-All four use daemon-backed domain operations; none opens SQLite from the Pi process.
+All frontends use daemon-backed domain operations; none opens SQLite from the Pi process.
+
+## Notes
+
+Notes are project-scoped `doc/note` artifacts for human requests that should be considered later. Capturing a Note does not create work, inject the entire inbox into prompts, or imply acceptance. The agent can use the `notes` domain tool to list and consume open Notes, decide whether to create a Task, Doc, Rule, or Skill through its owning domain tool, then promote the Note by linking that artifact. Archive requires one of `completed`, `duplicate`, `declined`, or `superseded`; promote archives with a `promoted` disposition and target ID. Capture, consumption, and disposition provenance remain in bounded Note history.
+
+The default inbox contains draft and consumed/active Notes, is bounded to 50 rows, and has a hard limit of 200. Bodies are capped at 10,000 characters. Generic document and graph lifecycle operations reject Note mutations so they cannot bypass disposition provenance.
+
+```bash
+papyrus notes capture "Investigate the retry policy" --json
+papyrus notes list --limit 25 --json
+papyrus notes show <note-id> --json
+papyrus notes consume <note-id> --json
+# Create the resulting artifact with tasks/docs/rules/skills first, then:
+papyrus notes promote <note-id> <target-id> --reason "Converted to tracked work" --json
+papyrus notes archive <note-id> declined --reason "No longer relevant" --json
+```
 
 ## Tasks
 

package/extension/src/artifact-browser.ts

@@ -18,6 +18,7 @@ export interface ArtifactBrowserConfig {
 	statusOrder: string[];
 	glyphs: Record<string, string>;
 	listOperation?: OperationName;
+	listInput?: Record<string, unknown>;
 	rowMeta(row: Artifact): string;
 	actions(row: Artifact): string[];
 	handleAction(choice: string, row: Artifact, ctx: ExtensionCommandContext): Promise<void>;
@@ -46,6 +47,7 @@ async function loadArtifacts(config: ArtifactBrowserConfig): Promise<Artifact[]>
 	return callService<Record<string, unknown>, Artifact[]>(config.listOperation ?? "artifact.query", {
 		kind: config.kind,
 		limit: BROWSER_QUERY_LIMIT,
+		...(config.listInput ?? {}),
 	});
 }
 
@@ -53,9 +55,11 @@ export async function showArtifactDetails(
 	ctx: ExtensionCommandContext,
 	id: string,
 	operation: OperationName = "artifact.show",
+	input: Record<string, unknown> = {},
 ): Promise<void> {
 	const artifact = await callService<Record<string, unknown>, Artifact | null>(operation, {
 		id,
+		...input,
 		tree: true,
 		depth: DETAIL_GRAPH_DEPTH,
 		max_nodes: DETAIL_GRAPH_NODES,

package/extension/src/domain-tools.ts

@@ -7,6 +7,7 @@ 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 { NOTE_DISPOSITIONS } from "../../src/note-service.ts";
 import { callService } from "./service-client.ts";
 
 function text(message: string, details: Record<string, unknown> = {}) {
@@ -159,6 +160,51 @@ export function registerDomainTools(pi: ExtensionAPI): void {
 		},
 	});
 
+	pi.registerTool({
+		name: "notes",
+		label: "Notes",
+		description: "Deferred human-intent inbox. ACTIONS: capture, list, show, consume, promote, archive. Capture stores a request without creating work. Consume marks it considered. To promote, first create the resulting Task, Doc, Rule, or Skill through its domain tool, then link it with target_id. Archive requires an explicit disposition.",
+		parameters: Type.Object({
+			action: Type.String(),
+			id: Type.Optional(Type.String()),
+			body: Type.Optional(Type.String()),
+			title: Type.Optional(Type.String()),
+			status: Type.Optional(Type.Union([Type.Literal("draft"), Type.Literal("active"), Type.Literal("archived")])),
+			text: Type.Optional(Type.String()),
+			limit: Type.Optional(Type.Number()),
+			target_id: Type.Optional(Type.String()),
+			disposition: Type.Optional(Type.Union(NOTE_DISPOSITIONS.map((value) => Type.Literal(value)))),
+			reason: Type.Optional(Type.String()),
+			session_id: Type.Optional(Type.String()),
+			project_root: Type.Optional(Type.String()),
+		}),
+		async execute(_id, params, _signal, _onUpdate, ctx) {
+			try {
+				const action = params.action;
+				const request = { ...params, project_root: params.project_root ?? ctx.cwd, actor: "agent", source: "notes-tool" };
+				if (action === "capture") {
+					const artifact = await callService<Record<string, unknown>, Artifact>("notes.capture", request);
+					return text(`Captured note ${artifactLine(artifact)}`, { artifact });
+				}
+				if (action === "list") {
+					const rows = await callService<Record<string, unknown>, Artifact[]>("notes.list", request);
+					return text(rows.length ? rows.map(artifactLine).join("\n") : "No open notes.", { rows });
+				}
+				if (action === "show") {
+					const artifact = await callService<Record<string, unknown>, Artifact>("notes.show", request);
+					return text(`${artifactLine(artifact)}\n\n${artifact.body}`, { artifact });
+				}
+				const operations = { consume: "notes.consume", promote: "notes.promote", archive: "notes.archive" } as const;
+				const operation = operations[action as keyof typeof operations];
+				if (!operation) return text(`Unknown notes action: ${action}`);
+				const artifact = await callService<Record<string, unknown>, Artifact>(operation, request);
+				return text(`${action}: ${artifactLine(artifact)}`, { artifact });
+			} catch (error) {
+				return text(`notes failed: ${error instanceof Error ? error.message : error}`);
+			}
+		},
+	});
+
 	pi.registerTool({
 		name: "docs",
 		label: "Documents",

package/extension/src/index.ts

@@ -318,9 +318,10 @@ export default async function (pi: ExtensionAPI) {
 	// ── Interactive artifact browsers ──────────────────────────────────
 
 	// Lazy imports keep TUI components out of non-interactive startup paths.
-	const [tasksModule, docsModule, rulesModule, skillsModule] = await Promise.all([
+	const [tasksModule, docsModule, notesModule, rulesModule, skillsModule] = await Promise.all([
 		import("./tasks.ts"),
 		import("./docs.ts"),
+		import("./notes.ts"),
 		import("./rules.ts"),
 		import("./skills.ts"),
 	]);
@@ -338,6 +339,14 @@ export default async function (pi: ExtensionAPI) {
 		description: "Browse and manage Papyrus documents (interactive)",
 		handler: async (_args, ctx) => { await docsModule.showDocs(ctx); },
 	});
+	pi.registerCommand("note", {
+		description: "Capture a deferred request directly in Papyrus",
+		handler: async (args, ctx) => { await notesModule.captureNote(args, ctx); },
+	});
+	pi.registerCommand("notes", {
+		description: "Browse and triage the project Notes inbox",
+		handler: async (_args, ctx) => { await notesModule.showNotes(ctx); },
+	});
 	pi.registerCommand("rules", {
 		description: "Browse, preview, and toggle Papyrus rules (interactive)",
 		handler: async (_args, ctx) => { await rulesModule.showRules(ctx); },

package/extension/src/notes.ts

@@ -0,0 +1,90 @@
+import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { NOTE_DISPOSITIONS } from "../../src/note-service.ts";
+import type { Artifact } from "../../src/domain/artifact.ts";
+import { showArtifactBrowser, showArtifactDetails } from "./artifact-browser.ts";
+import { callService } from "./service-client.ts";
+
+const NOTE_GLYPHS: Record<string, string> = { draft: "○", active: "●", archived: "■" };
+
+export function noteRowMeta(note: Artifact): string {
+	const history = Array.isArray(note.extra["noteHistory"]) ? note.extra["noteHistory"].length : 0;
+	return `${history} event${history === 1 ? "" : "s"}`;
+}
+
+export function noteCaptureInput(request: string, projectRoot: string): Record<string, unknown> | null {
+	const body = request.trim();
+	if (!body) return null;
+	return { body, project_root: projectRoot, actor: "human", source: "note-command" };
+}
+
+export async function captureNote(request: string, ctx: ExtensionCommandContext): Promise<Artifact | null> {
+	const input = noteCaptureInput(request, ctx.cwd);
+	if (!input) {
+		ctx.ui.notify("Usage: /note <request for later>", "warning");
+		return null;
+	}
+	try {
+		const note = await callService<Record<string, unknown>, Artifact>("notes.capture", input);
+		ctx.ui.notify(`Captured note: ${note.title}`, "info");
+		return note;
+	} catch (error) {
+		ctx.ui.notify(`Note capture failed: ${error instanceof Error ? error.message : error}`, "error");
+		return null;
+	}
+}
+
+export async function showNotes(ctx: ExtensionCommandContext): Promise<void> {
+	await showArtifactBrowser(ctx, {
+		kind: "note",
+		title: "Notes inbox",
+		listOperation: "notes.list",
+		listInput: { project_root: ctx.cwd },
+		statusOrder: ["draft", "active", "archived"],
+		glyphs: NOTE_GLYPHS,
+		rowMeta: noteRowMeta,
+		actions: (note) => [
+			"Show details",
+			...(note.status === "draft" ? ["Consume"] : []),
+			"Promote",
+			"Archive",
+		],
+		handleAction: async (choice, note, commandCtx) => {
+			if (choice === "Show details") {
+				await showArtifactDetails(commandCtx, note.id, "notes.show", { project_root: commandCtx.cwd });
+				return;
+			}
+			if (choice === "Consume") {
+				await callService("notes.consume", { id: note.id, project_root: commandCtx.cwd, actor: "human", source: "notes-tui" });
+				commandCtx.ui.notify(`Consumed ${note.title}`, "info");
+				return;
+			}
+			if (choice === "Promote") {
+				const targetId = await commandCtx.ui.input("Resulting artifact id:", "");
+				if (!targetId) return;
+				const reason = await commandCtx.ui.input("Disposition note (optional):", "");
+				await callService("notes.promote", {
+					id: note.id,
+					target_id: targetId,
+					project_root: commandCtx.cwd,
+					actor: "human",
+					source: "notes-tui",
+					...(reason ? { reason } : {}),
+				});
+				commandCtx.ui.notify(`Promoted ${note.title} → ${targetId}`, "info");
+				return;
+			}
+			const disposition = await commandCtx.ui.select("Archive disposition", [...NOTE_DISPOSITIONS]);
+			if (!disposition) return;
+			const reason = await commandCtx.ui.input("Reason (optional):", "");
+			await callService("notes.archive", {
+				id: note.id,
+				disposition,
+				project_root: commandCtx.cwd,
+				actor: "human",
+				source: "notes-tui",
+				...(reason ? { reason } : {}),
+			});
+			commandCtx.ui.notify(`Archived ${note.title} · ${disposition}`, "info");
+		},
+	});
+}

package/package.json

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

package/src/cli.ts

@@ -58,6 +58,12 @@ const USAGE = `Usage:
   papyrus service <install|start|stop|restart|status>
   papyrus migrate task-focus [--json]
   papyrus skills run <id> [--arguments-json <json>] [--run-id <id>] [--json]
+  papyrus notes capture <request> [--title <title>] [--json]
+  papyrus notes list [--status <draft|active|archived>] [--text <query>] [--limit <count>] [--json]
+  papyrus notes show <id> [--json]
+  papyrus notes consume <id> [--reason <reason>] [--json]
+  papyrus notes promote <id> <target-id> [--reason <reason>] [--json]
+  papyrus notes archive <id> <completed|duplicate|declined|superseded> [--reason <reason>] [--json]
   papyrus tasks plan [--json]
   papyrus tasks graph [--json]
   papyrus tasks active [--json]
@@ -85,7 +91,7 @@ function usage(): never {
 
 type TaskCliClient = Pick<PapyrusClient, "call">;
 type MigrationResult = { from: number; to: number; applied: string[] };
-type CliArtifact = { id: string; title: string; status: string };
+type CliArtifact = { id: string; title: string; status: string; body?: string };
 type CliCompletion = Omit<TaskCompletion, "artifact" | "blocked"> & {
 	artifact: CliArtifact;
 	blocked: Array<Omit<TaskBlockage, "artifact"> & { artifact: CliArtifact }>;
@@ -168,6 +174,66 @@ export async function runSkillCli(args: string[], client: TaskCliClient, project
 	].join("\n");
 }
 
+export async function runNoteCli(args: string[], client: TaskCliClient, projectRoot: string = process.cwd()): Promise<string> {
+	const json = args.includes("--json");
+	const positional: string[] = [];
+	let title: string | undefined;
+	let status: string | undefined;
+	let text: string | undefined;
+	let reason: string | undefined;
+	let limit: number | undefined;
+	for (let index = 0; index < args.length; index++) {
+		const argument = args[index]!;
+		if (argument === "--json") continue;
+		if (["--title", "--status", "--text", "--reason", "--limit"].includes(argument)) {
+			const value = args[++index];
+			if (value === undefined) throw new Error(`${argument} requires a value`);
+			if (argument === "--title") title = value;
+			else if (argument === "--status") status = value;
+			else if (argument === "--text") text = value;
+			else if (argument === "--reason") reason = value;
+			else {
+				limit = Number(value);
+				if (!Number.isInteger(limit)) throw new Error("--limit requires an integer");
+			}
+			continue;
+		}
+		if (argument.startsWith("--")) throw new Error(`unknown notes option ${argument}`);
+		positional.push(argument);
+	}
+	const [action, id, target] = positional;
+	let result: CliArtifact | CliArtifact[];
+	let human: string;
+	if (action === "capture") {
+		if (!id || target) throw new Error("notes capture requires exactly one request argument");
+		result = await client.call("notes.capture", { body: id, ...(title ? { title } : {}), project_root: projectRoot, actor: "human", source: "cli" }) as CliArtifact;
+		human = `Captured: ${artifactLabel(result)}`;
+	} else if (action === "list") {
+		if (id) throw new Error("notes list accepts no positional arguments");
+		result = await client.call("notes.list", { project_root: projectRoot, ...(status ? { status } : {}), ...(text ? { text } : {}), ...(limit === undefined ? {} : { limit }) }) as CliArtifact[];
+		human = result.length > 0 ? result.map((note) => `[${note.status}] ${artifactLabel(note)}`).join("\n") : "No open notes.";
+	} else if (action === "show") {
+		if (!id || target) throw new Error("notes show requires exactly one note id");
+		result = await client.call("notes.show", { id, project_root: projectRoot }) as CliArtifact;
+		human = `${artifactLabel(result)}\n\n${result.body ?? ""}`.trimEnd();
+	} else if (action === "consume") {
+		if (!id || target) throw new Error("notes consume requires exactly one note id");
+		result = await client.call("notes.consume", { id, project_root: projectRoot, actor: "agent", source: "cli", ...(reason ? { reason } : {}) }) as CliArtifact;
+		human = `Consumed: ${artifactLabel(result)}`;
+	} else if (action === "promote") {
+		if (!id || !target || positional.length !== 3) throw new Error("notes promote requires a note id and target artifact id");
+		result = await client.call("notes.promote", { id, target_id: target, project_root: projectRoot, actor: "agent", source: "cli", ...(reason ? { reason } : {}) }) as CliArtifact;
+		human = `Promoted: ${artifactLabel(result)} → ${target}`;
+	} else if (action === "archive") {
+		if (!id || !target || positional.length !== 3) throw new Error("notes archive requires a note id and disposition");
+		result = await client.call("notes.archive", { id, disposition: target, project_root: projectRoot, actor: "human", source: "cli", ...(reason ? { reason } : {}) }) as CliArtifact;
+		human = `Archived: ${artifactLabel(result)} · ${target}`;
+	} else {
+		throw new Error("notes action must be capture, list, show, consume, promote, or archive");
+	}
+	return json ? JSON.stringify(result) : human;
+}
+
 export async function runTaskCli(args: string[], client: TaskCliClient, projectRoot: string = process.cwd()): Promise<string> {
 	const json = args.includes("--json");
 	const positional: string[] = [];
@@ -357,6 +423,11 @@ export async function main(args: string[] = process.argv.slice(2)): Promise<void
 		console.log(await runSkillCli(args.slice(1), client));
 		return;
 	}
+	if (command === "notes") {
+		const client = await connectPapyrusClient();
+		console.log(await runNoteCli(args.slice(1), client));
+		return;
+	}
 	if (command === "migrate") {
 		const client = await connectPapyrusClient();
 		console.log(await runMigrationCli(args.slice(1), client));

package/src/constants.ts

@@ -58,6 +58,14 @@ export const TASK_HISTORY_MAX_LIMIT = 100;
 export const TASK_EVENT_MAX_EVIDENCE_BYTES = 65_536;
 export const TASK_EVENT_ACTOR_MAX_LENGTH = 128;
 export const TASK_EVENT_REASON_MAX_LENGTH = 2_000;
+/** Deferred human Note payload, inbox, and provenance bounds. */
+export const NOTE_BODY_MAX_CHARACTERS = 10_000;
+export const NOTE_TITLE_MAX_CHARACTERS = 80;
+export const NOTE_LIST_DEFAULT_LIMIT = 50;
+export const NOTE_LIST_MAX_LIMIT = 200;
+export const NOTE_HISTORY_MAX_EVENTS = 20;
+export const NOTE_PROVENANCE_MAX_LENGTH = 128;
+export const NOTE_REASON_MAX_CHARACTERS = 2_000;
 /** Persisted project and focused-graph Task view bounds. */
 export const TASK_SCOPE_MAX_TASKS = 1_000;
 export const TASK_PROJECT_ROOT_MAX_LENGTH = 4_096;

package/src/domain/artifact.ts

@@ -39,8 +39,12 @@ export interface UpdateArtifactInput {
 export interface ArtifactQuery {
 	kind?: string;
 	status?: string;
+	statuses?: string[];
+	subtype?: string;
+	excludeSubtype?: string;
 	text?: string;
 	labels?: string[];
+	extraEquals?: Record<string, string | number | boolean>;
 	limit?: number;
 }
 

package/src/domain-services.ts

@@ -1,6 +1,7 @@
 import type { Artifact, CreateArtifactInput } from "./domain/artifact.ts";
 import { validateSkillDefinition } from "./domain/skill-definition.ts";
 import type { ArtifactStore } from "./ports/artifact-store.ts";
+import { NOTE_SUBTYPE } from "./note-service.ts";
 
 export interface ListFilter {
 	status?: string;
@@ -15,6 +16,19 @@ function requireKind(artifacts: ArtifactStore, id: string, kind: string): Artifa
 	return artifact;
 }
 
+function rejectsNoteTemplate(artifacts: ArtifactStore, templateId: string | undefined, subtype: string | undefined): boolean {
+	if (subtype === NOTE_SUBTYPE) return true;
+	if (!templateId) return false;
+	const template = artifacts.get(templateId);
+	const defaults = template?.extra["defaults"];
+	return typeof defaults === "object" && defaults !== null && !Array.isArray(defaults)
+		&& (defaults as Record<string, unknown>)["subtype"] === NOTE_SUBTYPE;
+}
+
+function requireNotesFacade(): never {
+	throw new Error("note creation requires notes.capture");
+}
+
 export interface CreateDocumentInput {
 	title: string;
 	body?: string;
@@ -34,6 +48,7 @@ const DOCUMENT_TRANSITIONS: Record<DocumentTransition, { from: string[]; to: str
 };
 
 export function createDocument(artifacts: ArtifactStore, input: CreateDocumentInput): Artifact {
+	if (rejectsNoteTemplate(artifacts, input.templateId, input.subtype)) requireNotesFacade();
 	return artifacts.create({
 		kind: "doc",
 		title: input.title,
@@ -46,23 +61,29 @@ export function createDocument(artifacts: ArtifactStore, input: CreateDocumentIn
 }
 
 export function listDocuments(artifacts: ArtifactStore, filter: ListFilter): Artifact[] {
-	return artifacts.query({ kind: "doc", ...filter });
+	return artifacts.query({ kind: "doc", excludeSubtype: NOTE_SUBTYPE, ...filter });
+}
+
+function requireDocument(artifacts: ArtifactStore, id: string): Artifact {
+	const document = requireKind(artifacts, id, "doc");
+	if (document.subtype === NOTE_SUBTYPE) throw new Error("note access requires a notes.* operation");
+	return document;
 }
 
 export function showDocument(artifacts: ArtifactStore, id: string): Artifact {
-	requireKind(artifacts, id, "doc");
+	requireDocument(artifacts, id);
 	return artifacts.get(id, { tree: true })!;
 }
 
 export function transitionDocument(artifacts: ArtifactStore, id: string, action: DocumentTransition): Artifact {
-	const document = requireKind(artifacts, id, "doc");
+	const document = requireDocument(artifacts, id);
 	const transition = DOCUMENT_TRANSITIONS[action];
 	if (!transition.from.includes(document.status)) throw new Error(`cannot ${action} document from ${document.status}`);
 	return artifacts.setStatus(id, transition.to)!;
 }
 
 export function linkDocument(artifacts: ArtifactStore, id: string, relation: DocumentRelation, targetId: string): Artifact {
-	requireKind(artifacts, id, "doc");
+	requireDocument(artifacts, id);
 	if (!artifacts.get(targetId)) throw new Error(`target artifact "${targetId}" not found`);
 	artifacts.link({ from: id, relation, to: targetId });
 	return showDocument(artifacts, id);
@@ -165,6 +186,7 @@ export function createSkill(artifacts: ArtifactStore, input: CreateSkillInput):
 		throw new Error("workflow Skill definition cannot be mixed with legacy trigger, steps, or tools");
 	}
 	const definition = input.definition === undefined ? undefined : validateSkillDefinition(input.definition);
+	if (definition?.blueprints.docs.some((document) => document.subtype === NOTE_SUBTYPE)) requireNotesFacade();
 	return artifacts.create({
 		kind: "skill",
 		subtype: definition ? "workflow" : undefined,
@@ -182,6 +204,7 @@ export function createSkill(artifacts: ArtifactStore, input: CreateSkillInput):
 }
 
 export function createArtifactTemplate(artifacts: ArtifactStore, input: CreateArtifactTemplateInput): Artifact {
+	if (input.targetKind === "doc" && input.defaults?.["subtype"] === NOTE_SUBTYPE) requireNotesFacade();
 	return artifacts.create({
 		kind: "skill",
 		subtype: "artifact-template",
@@ -197,6 +220,7 @@ export function createArtifactTemplate(artifacts: ArtifactStore, input: CreateAr
 }
 
 export function instantiateTemplate(artifacts: ArtifactStore, templateId: string, input: CreateArtifactInput): Artifact {
+	if (rejectsNoteTemplate(artifacts, templateId, input.subtype)) requireNotesFacade();
 	return artifacts.create({ ...input, templateId });
 }
 

package/src/note-service.ts

@@ -0,0 +1,205 @@
+import {
+	NOTE_BODY_MAX_CHARACTERS,
+	NOTE_HISTORY_MAX_EVENTS,
+	NOTE_LIST_DEFAULT_LIMIT,
+	NOTE_LIST_MAX_LIMIT,
+	NOTE_PROVENANCE_MAX_LENGTH,
+	NOTE_REASON_MAX_CHARACTERS,
+	NOTE_TITLE_MAX_CHARACTERS,
+	TASK_PROJECT_ROOT_MAX_LENGTH,
+} from "./constants.ts";
+import type { Artifact } from "./domain/artifact.ts";
+import { requireAtomicArtifactStore } from "./ports/atomic-artifact-store.ts";
+import type { ArtifactStore } from "./ports/artifact-store.ts";
+
+export const NOTE_SUBTYPE = "note";
+export const NOTE_DISPOSITIONS = ["completed", "duplicate", "declined", "superseded"] as const;
+export type NoteDisposition = typeof NOTE_DISPOSITIONS[number];
+
+export interface NoteProvenance {
+	actor?: string;
+	source?: string;
+	sessionId?: string;
+	reason?: string;
+}
+
+export interface CaptureNoteInput extends NoteProvenance {
+	body: string;
+	title?: string;
+	projectRoot: string;
+}
+
+export interface ListNotesInput {
+	projectRoot: string;
+	status?: "draft" | "active" | "archived";
+	text?: string;
+	limit?: number;
+}
+
+export interface ArchiveNoteInput extends NoteProvenance {
+	projectRoot: string;
+	disposition: NoteDisposition;
+}
+
+interface NoteHistoryEvent {
+	action: "captured" | "consumed" | "promoted" | "archived";
+	at: string;
+	actor: string;
+	source: string;
+	sessionId?: string;
+	reason?: string;
+	targetId?: string;
+	disposition?: NoteDisposition | "promoted";
+}
+
+function requiredBounded(value: string, field: string, maximum: number): string {
+	const normalized = value.trim();
+	if (!normalized) throw new Error(`${field} is required`);
+	if (normalized.length > maximum) throw new Error(`${field} exceeds ${maximum} characters`);
+	return normalized;
+}
+
+function optionalBounded(value: string | undefined, field: string, maximum: number): string | undefined {
+	if (value === undefined) return undefined;
+	return requiredBounded(value, field, maximum);
+}
+
+function noteTitle(body: string, requested?: string): string {
+	if (requested !== undefined) return requiredBounded(requested, "note title", NOTE_TITLE_MAX_CHARACTERS);
+	const firstLine = body.split(/\r?\n/, 1)[0]!.replace(/\s+/g, " ").trim();
+	return firstLine.slice(0, NOTE_TITLE_MAX_CHARACTERS) || "Deferred note";
+}
+
+function provenance(input: NoteProvenance, defaults: { actor: string; source: string }): Omit<NoteHistoryEvent, "action" | "at"> {
+	return {
+		actor: optionalBounded(input.actor, "note actor", NOTE_PROVENANCE_MAX_LENGTH) ?? defaults.actor,
+		source: optionalBounded(input.source, "note source", NOTE_PROVENANCE_MAX_LENGTH) ?? defaults.source,
+		...(input.sessionId ? { sessionId: requiredBounded(input.sessionId, "note session id", NOTE_PROVENANCE_MAX_LENGTH) } : {}),
+		...(input.reason ? { reason: requiredBounded(input.reason, "note reason", NOTE_REASON_MAX_CHARACTERS) } : {}),
+	};
+}
+
+function history(artifact: Artifact): NoteHistoryEvent[] {
+	const value = artifact.extra["noteHistory"];
+	if (!Array.isArray(value)) return [];
+	return value.filter((entry): entry is NoteHistoryEvent => typeof entry === "object" && entry !== null && !Array.isArray(entry));
+}
+
+function appendHistory(artifact: Artifact, event: NoteHistoryEvent): Record<string, unknown> {
+	return {
+		...artifact.extra,
+		noteHistory: [...history(artifact), event].slice(-NOTE_HISTORY_MAX_EVENTS),
+	};
+}
+
+function event(action: NoteHistoryEvent["action"], input: NoteProvenance, extra: Partial<NoteHistoryEvent> = {}): NoteHistoryEvent {
+	return {
+		action,
+		at: new Date().toISOString(),
+		...provenance(input, { actor: action === "captured" ? "human" : "agent", source: "notes" }),
+		...extra,
+	};
+}
+
+export class Notes {
+	constructor(private readonly artifacts: ArtifactStore) {}
+
+	capture(input: CaptureNoteInput): Artifact {
+		const projectRoot = requiredBounded(input.projectRoot, "project_root", TASK_PROJECT_ROOT_MAX_LENGTH);
+		const body = requiredBounded(input.body, "note body", NOTE_BODY_MAX_CHARACTERS);
+		const captured = event("captured", input);
+		return this.artifacts.create({
+			kind: "doc",
+			subtype: NOTE_SUBTYPE,
+			status: "draft",
+			title: noteTitle(body, input.title),
+			body,
+			labels: ["note", "inbox"],
+			extra: { projectRoot, noteHistory: [captured] },
+		});
+	}
+
+	list(input: ListNotesInput): Artifact[] {
+		const projectRoot = requiredBounded(input.projectRoot, "project_root", TASK_PROJECT_ROOT_MAX_LENGTH);
+		const limit = input.limit ?? NOTE_LIST_DEFAULT_LIMIT;
+		if (!Number.isInteger(limit) || limit < 1 || limit > NOTE_LIST_MAX_LIMIT) {
+			throw new Error(`note limit must be an integer from 1 to ${NOTE_LIST_MAX_LIMIT}`);
+		}
+		return this.artifacts.query({
+			kind: "doc",
+			subtype: NOTE_SUBTYPE,
+			...(input.status ? { status: input.status } : { statuses: ["draft", "active"] }),
+			...(input.text ? { text: input.text } : {}),
+			extraEquals: { projectRoot },
+			limit,
+		});
+	}
+
+	show(id: string, projectRoot: string): Artifact {
+		const note = this.requireNote(id);
+		this.requireProject(note, projectRoot);
+		return this.artifacts.get(id, { tree: true })!;
+	}
+
+	consume(id: string, input: NoteProvenance & { projectRoot: string }): Artifact {
+		const atomic = requireAtomicArtifactStore(this.artifacts);
+		return atomic.atomic(() => {
+			const note = this.requireNote(id);
+			this.requireProject(note, input.projectRoot);
+			if (note.status === "archived") throw new Error("cannot consume an archived note");
+			if (note.status === "active") return this.artifacts.get(id, { tree: true })!;
+			this.artifacts.setExtra(id, appendHistory(note, event("consumed", input)));
+			this.artifacts.setStatus(id, "active");
+			return this.artifacts.get(id, { tree: true })!;
+		});
+	}
+
+	promote(id: string, targetId: string, input: NoteProvenance & { projectRoot: string }): Artifact {
+		const atomic = requireAtomicArtifactStore(this.artifacts);
+		return atomic.atomic(() => {
+			const note = this.requireNote(id);
+			this.requireProject(note, input.projectRoot);
+			if (note.status === "archived") throw new Error("cannot promote an archived note");
+			if (targetId === id) throw new Error("a note cannot promote to itself");
+			if (!this.artifacts.get(targetId)) throw new Error(`promotion target "${targetId}" not found`);
+			const promoted = event("promoted", input, { disposition: "promoted", targetId });
+			const disposition = { kind: "promoted", targetId, ...(promoted.reason ? { reason: promoted.reason } : {}) };
+			this.artifacts.link({ from: id, relation: "relates_to", to: targetId });
+			this.artifacts.setExtra(id, {
+				...appendHistory(note, promoted),
+				disposition,
+			});
+			this.artifacts.setStatus(id, "archived");
+			return this.artifacts.get(id, { tree: true })!;
+		});
+	}
+
+	archive(id: string, input: ArchiveNoteInput): Artifact {
+		if (!NOTE_DISPOSITIONS.includes(input.disposition)) throw new Error("note disposition must be completed, duplicate, declined, or superseded");
+		const atomic = requireAtomicArtifactStore(this.artifacts);
+		return atomic.atomic(() => {
+			const note = this.requireNote(id);
+			this.requireProject(note, input.projectRoot);
+			if (note.status === "archived") throw new Error("note is already archived");
+			const archived = event("archived", input, { disposition: input.disposition });
+			const details = { kind: input.disposition, ...(archived.reason ? { reason: archived.reason } : {}) };
+			this.artifacts.setExtra(id, {
+				...appendHistory(note, archived),
+				disposition: details,
+			});
+			this.artifacts.setStatus(id, "archived");
+			return this.artifacts.get(id, { tree: true })!;
+		});
+	}
+
+	private requireNote(id: string): Artifact {
+		const artifact = this.artifacts.get(id);
+		if (!artifact || artifact.kind !== "doc" || artifact.subtype !== NOTE_SUBTYPE) throw new Error(`note "${id}" not found`);
+		return artifact;
+	}
+
+	private requireProject(note: Artifact, projectRoot: string): void {
+		const requested = requiredBounded(projectRoot, "project_root", TASK_PROJECT_ROOT_MAX_LENGTH);
+		if (note.extra["projectRoot"] !== requested) throw new Error(`note "${note.id}" is outside project scope`);
+	}
+}

package/src/ops.ts

@@ -6,7 +6,7 @@ import { createRequire } from "node:module";
 import { exec } from "node:child_process";
 import type { Db } from "./db.ts";
 import { inTransaction } from "./db.ts";
-import type { Artifact, CreateArtifactInput, UpdateArtifactInput } from "./domain/artifact.ts";
+import type { Artifact, ArtifactQuery, CreateArtifactInput, UpdateArtifactInput } from "./domain/artifact.ts";
 import type { Gate, GateResult, GateRunOptions } from "./domain/gate.ts";
 export type { Artifact } from "./domain/artifact.ts";
 export type { Gate, GateResult } from "./domain/gate.ts";
@@ -172,22 +172,36 @@ export function getArtifact(db: Db, id: string, opts?: { tree?: boolean; depth?:
 	return art;
 }
 
-export function queryArtifacts(db: Db, filter: {
-	kind?: string;
-	status?: string;
-	text?: string;
-	labels?: string[];
-	limit?: number;
-}): Artifact[] {
+export function queryArtifacts(db: Db, filter: ArtifactQuery): Artifact[] {
 	let sql = "SELECT * FROM artifacts";
 	const conditions: string[] = [];
 	const params: unknown[] = [];
 	if (filter.kind) { conditions.push("kind = ?"); params.push(filter.kind); }
 	if (filter.status) { conditions.push("status = ?"); params.push(filter.status); }
+	if (filter.statuses) {
+		if (filter.statuses.length === 0) return [];
+		conditions.push(`status IN (${filter.statuses.map(() => "?").join(", ")})`);
+		params.push(...filter.statuses);
+	}
+	if (filter.subtype) { conditions.push("subtype = ?"); params.push(filter.subtype); }
+	if (filter.excludeSubtype) { conditions.push("subtype != ?"); params.push(filter.excludeSubtype); }
 	if (filter.text) { conditions.push("(title LIKE ? OR body LIKE ?)"); params.push(`%${filter.text}%`, `%${filter.text}%`); }
+	for (const label of filter.labels ?? []) {
+		conditions.push("EXISTS (SELECT 1 FROM json_each(artifacts.labels) WHERE value = ?)");
+		params.push(label);
+	}
+	for (const [key, value] of Object.entries(filter.extraEquals ?? {})) {
+		if (!/^[A-Za-z][A-Za-z0-9_]*$/.test(key)) throw new Error(`invalid extra query key "${key}"`);
+		conditions.push("json_extract(extra, ?) = ?");
+		params.push(`$.${key}`, value);
+	}
 	if (conditions.length) sql += " WHERE " + conditions.join(" AND ");
 	sql += " ORDER BY updated_at DESC";
-	if (filter.limit) sql += ` LIMIT ${Math.floor(filter.limit)}`;
+	if (filter.limit !== undefined) {
+		if (!Number.isInteger(filter.limit) || filter.limit < 1) throw new Error("artifact query limit must be a positive integer");
+		sql += " LIMIT ?";
+		params.push(filter.limit);
+	}
 	const rows = db.prepare(sql).all(...params) as Record<string, unknown>[];
 	return rows.map(rowToArtifact);
 }

package/src/service.ts

@@ -40,6 +40,7 @@ import {
 } from "./domain-services.ts";
 import { taskContext } from "./task-context.ts";
 import { instantiateSkillWorkflow } from "./skill-execution.ts";
+import { Notes, type NoteDisposition } from "./note-service.ts";
 
 export const EXPECTED_OPERATION_NAMES = [
 	"system.migrate",
@@ -85,6 +86,12 @@ export const EXPECTED_OPERATION_NAMES = [
 	"docs.archive",
 	"docs.reopen",
 	"docs.link",
+	"notes.capture",
+	"notes.list",
+	"notes.show",
+	"notes.consume",
+	"notes.promote",
+	"notes.archive",
 	"rules.create",
 	"rules.list",
 	"rules.show",
@@ -162,6 +169,7 @@ function handlers(
 	artifacts: ArtifactStore,
 	gates: GateRunner,
 	tasks: Tasks,
+	notes: Notes,
 	events: TaskEventStore,
 	scopes: TaskScopeStore,
 	migrate: () => unknown,
@@ -191,6 +199,7 @@ function handlers(
 		"system.migrate": () => migrate(),
 		"artifact.create": (input) => {
 			const normalized = normalizeCreateInput(input);
+			if (normalized.kind === "doc" && normalized.subtype === "note") throw new Error("note creation requires notes.capture");
 			if (normalized.kind !== "task") return artifacts.create(normalized);
 			return tasks.create({
 				id: normalized.id,
@@ -229,7 +238,9 @@ function handlers(
 		}),
 		"graph.status": (input) => {
 			const id = string(input, "id");
-			if (artifacts.get(id)?.kind === "task") throw new Error("task lifecycle changes require a tasks.* operation so history and review invariants are preserved");
+			const artifact = artifacts.get(id);
+			if (artifact?.kind === "task") throw new Error("task lifecycle changes require a tasks.* operation so history and review invariants are preserved");
+			if (artifact?.kind === "doc" && artifact.subtype === "note") throw new Error("note lifecycle changes require a notes.* operation so disposition provenance is preserved");
 			return artifacts.setStatus(id, string(input, "status"));
 		},
 		"gates.run": (input) => {
@@ -307,6 +318,28 @@ function handlers(
 		"docs.archive": (input) => transitionDocument(artifacts, string(input, "id"), "archive"),
 		"docs.reopen": (input) => transitionDocument(artifacts, string(input, "id"), "reopen"),
 		"docs.link": (input) => linkDocument(artifacts, string(input, "id"), string(input, "relation") as DocumentRelation, string(input, "target_id")),
+		"notes.capture": (input) => notes.capture({
+			body: string(input, "body"), title: optionalString(input, "title"), projectRoot: string(input, "project_root"),
+			actor: optionalString(input, "actor"), source: optionalString(input, "source"), sessionId: optionalString(input, "session_id"),
+		}),
+		"notes.list": (input) => notes.list({
+			projectRoot: string(input, "project_root"), status: optionalString(input, "status") as "draft" | "active" | "archived" | undefined,
+			text: optionalString(input, "text"), limit: optionalNumber(input, "limit"),
+		}),
+		"notes.show": (input) => notes.show(string(input, "id"), string(input, "project_root")),
+		"notes.consume": (input) => notes.consume(string(input, "id"), {
+			projectRoot: string(input, "project_root"), actor: optionalString(input, "actor"), source: optionalString(input, "source"),
+			sessionId: optionalString(input, "session_id"), reason: optionalString(input, "reason"),
+		}),
+		"notes.promote": (input) => notes.promote(string(input, "id"), string(input, "target_id"), {
+			projectRoot: string(input, "project_root"), actor: optionalString(input, "actor"), source: optionalString(input, "source"),
+			sessionId: optionalString(input, "session_id"), reason: optionalString(input, "reason"),
+		}),
+		"notes.archive": (input) => notes.archive(string(input, "id"), {
+			projectRoot: string(input, "project_root"), disposition: string(input, "disposition") as NoteDisposition,
+			actor: optionalString(input, "actor"), source: optionalString(input, "source"), sessionId: optionalString(input, "session_id"),
+			reason: optionalString(input, "reason"),
+		}),
 		"rules.create": (input) => createRule(artifacts, {
 			title: string(input, "title"), body: optionalString(input, "body"), condition: optionalString(input, "condition"),
 			action: optionalString(input, "rule_action") ?? optionalString(input, "governance_action"),
@@ -364,7 +397,8 @@ export function createPapyrusService(path: string): PapyrusService {
 	const events = new SQLiteTaskEventStore(db);
 	const scopes = new SQLiteTaskScopeStore(db);
 	const tasks = new Tasks(artifacts, gates, focus, events, scopes);
-	const registry = handlers(artifacts, gates, tasks, events, scopes, () => migrateDb(db));
+	const notes = new Notes(artifacts);
+	const registry = handlers(artifacts, gates, tasks, notes, events, scopes, () => migrateDb(db));
 	const state = (): SchemaState => {
 		const current = schemaVersion(db);
 		return { current, required: SQLITE_SCHEMA_VERSION, migrationRequired: current !== SQLITE_SCHEMA_VERSION };