@danypops/papyrus 0.40.0 → 0.42.0

package/README.md

@@ -42,7 +42,7 @@ The daemon uses WAL, foreign keys, a bounded busy timeout, versioned migrations,
 
 `artifacts` is the shared graph-identity supertype, not a second copy of every application's database. `edges` references that single identity table at both endpoints, preserving foreign-key integrity for cross-domain links. Domain extension tables exist only where application invariants require indexed relational state: Task chronology/focus/scope and Discourse posts/events/session cursors/projection checkpoints. This is a class-table/table-per-type variant with explicit child-to-parent foreign keys; Papyrus does not use SQLite table inheritance or orphan-prone `(target_type, target_id)` links.
 
-The owning application remains the mutation authority. Discourse commits its extension rows and `context-thread`/`context-message` Doc projections atomically through `discourse.store`; generic artifact, document, Skill-template, lifecycle, and graph-link operations reject those owned subtypes and the `reply_to`/`discusses` relations. SQLite triggers additionally verify that each extension row references the expected Doc subtype. Domain tables are canonical for domain invariants; graph bodies and metadata are read-oriented projections committed in the same transaction.
+The owning application remains the mutation authority. Discourse commits its extension rows and `context-thread`/`context-message` Doc projections atomically through `discourse.store`; generic artifact, document, lifecycle, and graph-link operations reject those owned subtypes and the `reply_to`/`discusses` relations. SQLite triggers additionally verify that each extension row references the expected Doc subtype. Domain tables are canonical for domain invariants; graph bodies and metadata are read-oriented projections committed in the same transaction.
 
 The authenticated CLI exposes the same operation for diagnostics and adapter parity:
 
@@ -59,7 +59,7 @@ Papyrus enforces four artifact kinds:
 - `doc` — knowledge: specifications, decisions, and research
 - `task` — work: desired outcomes, gates, checklists, and dependencies
 - `rule` — governance injected into the Pi system prompt
-- `skill` — a parameterized workflow bundle whose validated arguments render a connected collection of deterministic Tasks plus contextual Rules and Docs
+- `playbook` — a trigger and an ordered list of steps whose validated arguments render a connected collection of deterministic Tasks plus contextual Rules and Docs
 
 Each kind has an enforced status vocabulary. Every edge endpoint must exist, and every edge relation must be registered in `relation_names`. Relations are universal: any artifact kind can link to any other kind.
 
@@ -67,34 +67,31 @@ Each kind has an enforced status vocabulary. Every edge endpoint must exist, and
 
 Use `contains` and `part_of` for explicit parent/child structure; use `depends_on` for execution ordering. Dependency edges form an executable DAG: self-dependencies and cycles are rejected, fan-in waits for every prerequisite, and fan-out can expose several ready successors while active focus remains singular. Graph reads are cycle-safe and bounded by `depth` and `max_nodes` (defaults: depth 4, 100 nodes; hard ceilings: depth 20, 1,000 nodes). Executable task plans are additionally bounded to 1,000 tasks and 10,000 relationships.
 
-### Skills and compatibility templates
+### Playbooks
 
-A Papyrus Skill is distinct from a conventional prompt-only skill: its input API and blueprints define a connected Task/Rule/Doc workflow. `skills.run` validates and normalizes all arguments, safely renders placeholders in memory, validates the complete graph, then persists artifacts and edges in one transaction. Task dependencies, containment, gates, checklists, and context survive rendering. Run Rules are injected only while active focus belongs to that run. Docs retain invocation context and provenance; missing evidence references remain unknown and no gate runs during instantiation.
+A Playbook's steps are a plain prose string (a Task), or a structured object: `{kind:'doc',...}` creates a Doc, `{kind:'rule',...}` creates a Rule, `{kind:'call',...}` nests another Playbook's own run as a pipeline step. `playbooks.invoke` validates and normalizes all arguments, safely renders placeholders in memory, validates the complete graph, then persists artifacts and edges in one transaction. Task dependencies, containment, gates, checklists, and context survive rendering. Run Rules are injected only while active focus belongs to that run. Docs retain invocation context and provenance; missing evidence references remain unknown and no gate runs during instantiation.
 
-A run result has a stable schema: Skill ID, run ID, normalized arguments, created IDs grouped by kind, ready root task IDs, and the bounded execution plan. Explicit run IDs produce deterministic artifact IDs (`<run-id>-<blueprint-ref>`); collisions roll back the entire run.
+A run result has a stable schema: Playbook ID, run ID, normalized arguments, created IDs grouped by kind, ready root task IDs, and the bounded execution plan. Explicit run IDs produce deterministic artifact IDs (`<run-id>-<blueprint-ref>`); collisions roll back the entire run.
 
 ```bash
-papyrus skills run <skill-id> \
+papyrus playbooks invoke <playbook-id> \
   --arguments-json '{"project":"Papyrus"}' \
-  --run-id papyrus-001 \
   --json
 ```
 
-The existing `artifact-template` skill subtype remains a compatibility mechanism for one-artifact templates with metadata `{targetKind, defaults, required}`. Instantiate it via the `skills.instantiate` operation 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.
+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` (the shared `artifact.remove`/`artifact.remove_subtree` operations every agent-facing domain routes through, 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.
 
 ### Naming vs. ids
 
-Every agent domain tool (tasks, docs, rules, skills, notes, discuss) addresses its artifacts by `name` (the exact title) wherever `id` would otherwise be required -- `dependency_name`/`parent_name`/`child_name`/`root_task_name`/`depends_on_names` (tasks), `target_name` (docs link, searches every kind since a link target can be any of them), `task_name` (rules gate, discuss block/unblock), `template_name` (skills instantiate), and `blocks_task_names` (discuss open) are the name-based equivalents of their `*_id` counterparts. Resolution is an exact, case-insensitive, trimmed title match scoped like a plain list call; an unmatched or ambiguous name fails with a clear error (ambiguous names list the real ids, since that's the one point disambiguation genuinely needs them). Results returned to the agent likewise lead with name and status, never id, unless two artifacts in the same result share a title -- id is a backend implementation detail, not a conversational handle. `id` itself still works exactly as before for every action, in every tool.
+Every agent domain tool (tasks, docs, rules, playbooks, notes, discuss) addresses its artifacts by `name` (the exact title) wherever `id` would otherwise be required -- `dependency_name`/`parent_name`/`child_name`/`root_task_name`/`depends_on_names` (tasks), `target_name` (docs link, searches every kind since a link target can be any of them), `task_name` (rules gate, discuss block/unblock), and `blocks_task_names` (discuss open) are the name-based equivalents of their `*_id` counterparts. Resolution is an exact, case-insensitive, trimmed title match scoped like a plain list call; an unmatched or ambiguous name fails with a clear error (ambiguous names list the real ids, since that's the one point disambiguation genuinely needs them). Results returned to the agent likewise lead with name and status, never id, unless two artifacts in the same result share a title -- id is a backend implementation detail, not a conversational handle. `id` itself still works exactly as before for every action, in every tool.
 
 ### Mutability
 
-Tasks, Docs, Rules, and Skills all support first-class `update` (title/body/labels, at least one required) alongside creation -- a Doc's body is no longer immutable once created. Every update is bounded the same way creation is (Rules keep their own stricter combined condition+action+body ceiling; Docs/Skills share Tasks' own length bounds) and recorded on the artifact's append-only mutation history, queryable via `graph.history`. An artifact carrying a `source:<system>` label (e.g. `source:web-spider` on an ingested page) is a read-only projection from a system Papyrus doesn't own the source of; updating one is refused with a clear error rather than silently forking it -- capture a correction as a new linked Doc instead until a write-back capability to that system exists. Notes stay behind their own facade for any content change, same as every other Notes mutation.
+Tasks, Docs, Rules, and Playbooks all support first-class `update` (title/body/labels, at least one required) alongside creation -- a Doc's body is no longer immutable once created. Every update is bounded the same way creation is (Rules keep their own stricter combined condition+action+body ceiling; Docs/Playbooks share Tasks' own length bounds) and recorded on the artifact's append-only mutation history, queryable via `graph.history`. An artifact carrying a `source:<system>` label (e.g. `source:web-spider` on an ingested page) is a read-only projection from a system Papyrus doesn't own the source of; updating one is refused with a clear error rather than silently forking it -- capture a correction as a new linked Doc instead until a write-back capability to that system exists. Notes stay behind their own facade for any content change, same as every other Notes mutation.
 
 Internally, application services depend on the `ArtifactStore` and `GateRunner` ports. SQLite and subprocess execution are adapters composed only by the daemon; task behavior is unit-tested against fakes without a database. Task visualization projects the same `TaskGraph` into semantic display graphs and sends them through a `GraphRenderer` port -- the Pi adapter (in `@danypops/pi-papyrus`) uses `beautiful-mermaid` for terminal Unicode output without leaking Mermaid syntax into the task domain.
 

package/package.json

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

package/src/artifact-relationship-view.ts

@@ -4,7 +4,7 @@ import { fallbackLabel } from "./task-relationship-view.ts";
 
 /**
  * The generic-artifact counterpart to projectTaskRelationships: unlike a Task, which already
- * has its containing TaskGraph's real titles in memory, a generic Doc/Rule/Skill/Playbook only
+ * has its containing TaskGraph's real titles in memory, a generic Doc/Rule/Playbook only
  * has raw edge id pairs (artifact.show's tree fetch never resolves neighbor titles -- see
  * ops.ts getArtifact). Reuses the same fallbackLabel heuristic rather than adding a network
  * round-trip per neighbor, which would turn a rendering concern into a new daemon-adjacent one.

package/src/cli.ts

@@ -118,18 +118,8 @@ const USAGE = `Usage:
   papyrus rules injectable [--json]
   papyrus rules assign-project <id> [project-root] [--json]
   papyrus rules update <id> [--title <title>] [--body <body>] [--labels-json <json>] [--json]
-  papyrus skills run <id> [--arguments-json <json>] [--run-id <id>] [--json]
-  papyrus skills create --title <title> [--body <body>] [--trigger <text>] [--steps-json <json>] [--tools-json <json>] [--definition-json <json>] [--labels-json <json>] [--extra-json <json>] [--project-root <path>] [--json]
-  papyrus skills create-template --title <title> --target-kind <kind> [--defaults-json <json>] [--required-json <json>] [--body <body>] [--labels-json <json>] [--project-root <path>] [--json]
-  papyrus skills list [--status <status>] [--text <query>] [--limit <count>] [--project-root <path>] [--json]
-  papyrus skills show <id> [--json]
-  papyrus skills invoke <id> [--json]
-  papyrus skills enable|disable <id> [--json]
-  papyrus skills instantiate <template-id> [--title <title>] [--body <body>] [--status <status>] [--labels-json <json>] [--extra-json <json>] [--json]
-  papyrus skills assign-project <id> [project-root] [--json]
-  papyrus skills update <id> [--title <title>] [--body <body>] [--labels-json <json>] [--json]
-  papyrus playbooks create --title <title> [--body <body>] [--trigger <text>] [--steps-json <json>] [--tools-json <json>] [--labels-json <json>] [--extra-json <json>] [--arguments-json <json array>] [--project-root <path>] [--json]
-  papyrus playbooks invoke <id> [--arguments-json <json object>] [--project-root <path>] [--json]  # materializes real tasks (contains/depends_on-wired) and focuses the entry task
+  papyrus playbooks create --title <title> [--body <body>] [--trigger <text>] [--steps-json <json array of strings and/or {kind:'doc'|'rule'|'call'|'task',...} objects>] [--tools-json <json>] [--labels-json <json>] [--extra-json <json>] [--arguments-json <json array, each optionally {type,enum,default}>] [--project-root <path>] [--json]
+  papyrus playbooks invoke <id> [--arguments-json <json object>] [--run-id <id>] [--project-root <path>] [--json]  # materializes real tasks (contains/depends_on-wired) and focuses the entry task
   papyrus playbooks preview <id> [--arguments-json <json object>] [--json]  # renders text only, creates nothing
   papyrus playbooks list [--status <status>] [--text <query>] [--limit <count>] [--project-root <path>] [--json]
   papyrus playbooks show <id> [--json]
@@ -231,10 +221,11 @@ function parseJsonStringArrayFlag(value: string | undefined, flag: string): stri
 }
 
 /**
- * No shape assertion here -- unlike every other JSON flag, playbooks --arguments-json is genuinely
- * polymorphic (an array on create, a {name: value} map on invoke), and the two actions share one
- * flag-parsing pass in runPlaybooksCli. The service validates the shape for whichever operation
- * actually receives it.
+ * No shape assertion here -- playbooks --arguments-json is genuinely polymorphic (an array on
+ * create, a {name: value} map on invoke, sharing one flag-parsing pass in runPlaybooksCli), and
+ * --steps-json accepts a mix of plain prose strings and structured step objects (doc/rule/call/
+ * task) that a single string-array assertion would wrongly reject. The service validates the
+ * real shape for whichever operation actually receives it.
  */
 function parseJsonAnyFlag(value: string | undefined, flag: string): unknown {
 	if (value === undefined) throw new Error(`${flag} requires a value`);
@@ -376,160 +367,6 @@ export function runIdMigrationCli(args: string[]): string {
 	throw new Error("migrate-ids requires one of: mirror, validate, promote");
 }
 
-export async function runSkillCli(args: string[], client: TaskCliClient, projectRoot: string = process.cwd()): Promise<string> {
-	const json = args.includes("--json");
-	const positional: string[] = [];
-	let runId: string | undefined;
-	let arguments_: Record<string, unknown> = {};
-	let title: string | undefined;
-	let body: string | undefined;
-	let trigger: string | undefined;
-	let steps: string[] | undefined;
-	let tools: string[] | undefined;
-	let definition: unknown;
-	let labels: string[] | undefined;
-	let extra: Record<string, unknown> | undefined;
-	let targetKind: string | undefined;
-	let defaults: Record<string, unknown> | undefined;
-	let required: string[] | undefined;
-	let status: string | undefined;
-	let text: string | undefined;
-	let limit: number | undefined;
-	let skillProjectRoot: string | undefined;
-	for (let index = 0; index < args.length; index++) {
-		const argument = args[index]!;
-		if (argument === "--json") continue;
-		if (argument === "--run-id") { runId = args[++index]; if (!runId) throw new Error("--run-id requires a value"); continue; }
-		if (argument === "--arguments-json") { arguments_ = parseJsonObjectFlag(args[++index], "--arguments-json"); continue; }
-		if (argument === "--title") { title = args[++index]; if (title === undefined) throw new Error("--title requires a value"); continue; }
-		if (argument === "--body") { body = args[++index]; if (body === undefined) throw new Error("--body requires a value"); continue; }
-		if (argument === "--trigger") { trigger = args[++index]; if (trigger === undefined) throw new Error("--trigger requires a value"); continue; }
-		if (argument === "--steps-json") { steps = parseJsonStringArrayFlag(args[++index], "--steps-json"); continue; }
-		if (argument === "--tools-json") { tools = parseJsonStringArrayFlag(args[++index], "--tools-json"); continue; }
-		if (argument === "--definition-json") {
-			const value = args[++index];
-			if (!value) throw new Error("--definition-json requires a value");
-			definition = JSON.parse(value);
-			continue;
-		}
-		if (argument === "--labels-json") { labels = parseJsonStringArrayFlag(args[++index], "--labels-json"); continue; }
-		if (argument === "--extra-json") { extra = parseJsonObjectFlag(args[++index], "--extra-json"); continue; }
-		if (argument === "--target-kind") { targetKind = args[++index]; if (!targetKind) throw new Error("--target-kind requires a value"); continue; }
-		if (argument === "--defaults-json") { defaults = parseJsonObjectFlag(args[++index], "--defaults-json"); continue; }
-		if (argument === "--required-json") { required = parseJsonStringArrayFlag(args[++index], "--required-json"); continue; }
-		if (argument === "--status") { status = args[++index]; if (!status) throw new Error("--status requires a value"); continue; }
-		if (argument === "--text") { text = args[++index]; if (text === undefined) throw new Error("--text requires a value"); continue; }
-		if (argument === "--project-root") { skillProjectRoot = args[++index]; if (!skillProjectRoot) throw new Error("--project-root requires a 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 skills option ${argument}`);
-		positional.push(argument);
-	}
-	const [action, id, second] = positional;
-	if (action === "run") {
-		if (positional.length !== 2) throw new Error("skills requires `run <id>`");
-		const input: Record<string, unknown> = { id, arguments: arguments_, project_root: projectRoot };
-		if (runId) input["run_id"] = runId;
-		const result = await client.call<Record<string, unknown>, {
-			runId: string;
-			created: { tasks: string[]; rules: string[]; docs: string[] };
-			rootTaskIds: string[];
-			execution: TaskExecutionPlan;
-		}>("skills.run", input);
-		if (json) return JSON.stringify(result);
-		return [
-			`Created Skill run ${result.runId}: ${result.created.tasks.length} tasks, ${result.created.rules.length} rules, ${result.created.docs.length} docs`,
-			`Ready roots: ${result.rootTaskIds.join(", ") || "none"}`,
-			`Context docs: ${result.created.docs.join(", ") || "none"}`,
-			`Scoped rules: ${result.created.rules.join(", ") || "none"}`,
-			...result.execution.nodes.map((node) => `[${node.state}] ${node.id} ${node.title}`),
-		].join("\n");
-	}
-	let result: unknown;
-	let human: string;
-	switch (action) {
-		case "create": {
-			if (id) throw new Error("skills create accepts no positional arguments");
-			if (!title) throw new Error("skills create requires --title");
-			const artifact = await client.call<Record<string, unknown>, CliArtifact>("skills.create", { title, body, trigger, steps, tools, definition, labels, extra, project_root: skillProjectRoot });
-			result = artifact;
-			human = `Created skill: ${artifactLabel(artifact)}`;
-			break;
-		}
-		case "create-template": {
-			if (id) throw new Error("skills create-template accepts no positional arguments");
-			if (!title || !targetKind) throw new Error("skills create-template requires --title and --target-kind");
-			const artifact = await client.call<Record<string, unknown>, CliArtifact>("skills.create_template", {
-				title, target_kind: targetKind, defaults, required, body, labels, project_root: skillProjectRoot,
-			});
-			result = artifact;
-			human = `Created template: ${artifactLabel(artifact)}`;
-			break;
-		}
-		case "list": {
-			if (id) throw new Error("skills list accepts no positional arguments");
-			const rows = await client.call<Record<string, unknown>, CliArtifact[]>("skills.list", { status, text, limit, project_root: skillProjectRoot });
-			result = rows;
-			human = rows.length === 0 ? "No skills found." : rows.map((row) => artifactLabel(row)).join("\n");
-			break;
-		}
-		case "assign-project": {
-			if (!id) throw new Error("skills assign-project requires <id> [project-root]");
-			const artifact = await client.call<Record<string, unknown>, CliArtifact>("skills.assign_project", { id, project_root: second });
-			result = artifact;
-			human = second ? `Assigned ${id} to ${second}` : `Unscoped ${id}`;
-			break;
-		}
-		case "show": {
-			if (!id) throw new Error("skills show requires exactly one skill id");
-			const artifact = await client.call<Record<string, unknown>, CliArtifact>("skills.show", { id });
-			result = artifact;
-			human = `${artifactLabel(artifact)}\n\n${artifact.body ?? ""}`;
-			break;
-		}
-		case "invoke": {
-			if (!id) throw new Error("skills invoke requires exactly one skill id");
-			const invocation = await client.call<Record<string, unknown>, string>("skills.invoke", { id });
-			result = invocation;
-			human = invocation;
-			break;
-		}
-		case "enable":
-		case "disable": {
-			if (!id) throw new Error(`skills ${action} requires exactly one skill id`);
-			const operation = action === "enable" ? "skills.enable" : "skills.disable";
-			const artifact = await client.call<Record<string, unknown>, CliArtifact>(operation, { id });
-			result = artifact;
-			human = `${artifactLabel(artifact)}`;
-			break;
-		}
-		case "instantiate": {
-			if (!id) throw new Error("skills instantiate requires exactly one template id");
-			const artifact = await client.call<Record<string, unknown>, CliArtifact>("skills.instantiate", {
-				template_id: id, title, body, status, labels, extra, project_root: projectRoot,
-			});
-			result = artifact;
-			human = `Created: ${artifactLabel(artifact)}`;
-			break;
-		}
-		case "update": {
-			if (!id || second) throw new Error("skills update requires exactly one skill id");
-			if (title === undefined && body === undefined && labels === undefined) throw new Error("skills update requires --title, --body, or --labels-json");
-			const artifact = await client.call<Record<string, unknown>, CliArtifact>("skills.update", { id, title, body, labels });
-			result = artifact;
-			human = `${artifactLabel(artifact)}`;
-			break;
-		}
-		default:
-			throw new Error("skills action must be run, create, create-template, list, show, invoke, enable, disable, instantiate, assign-project, or update");
-	}
-	return json ? JSON.stringify(result) : human;
-}
-
 export async function runGraphCli(args: string[], client: TaskCliClient): Promise<string> {
 	const json = args.includes("--json");
 	const positional: string[] = [];
@@ -822,11 +659,12 @@ export async function runPlaybooksCli(args: string[], client: TaskCliClient): Pr
 	let title: string | undefined;
 	let body: string | undefined;
 	let trigger: string | undefined;
-	let steps: string[] | undefined;
+	let steps: unknown;
 	let tools: string[] | undefined;
 	let labels: string[] | undefined;
 	let extra: Record<string, unknown> | undefined;
 	let playbookArguments: unknown;
+	let runId: string | undefined;
 	let status: string | undefined;
 	let text: string | undefined;
 	let limit: number | undefined;
@@ -837,11 +675,12 @@ export async function runPlaybooksCli(args: string[], client: TaskCliClient): Pr
 		if (argument === "--title") { title = args[++index]; if (title === undefined) throw new Error("--title requires a value"); continue; }
 		if (argument === "--body") { body = args[++index]; if (body === undefined) throw new Error("--body requires a value"); continue; }
 		if (argument === "--trigger") { trigger = args[++index]; if (trigger === undefined) throw new Error("--trigger requires a value"); continue; }
-		if (argument === "--steps-json") { steps = parseJsonStringArrayFlag(args[++index], "--steps-json"); continue; }
+		if (argument === "--steps-json") { steps = parseJsonAnyFlag(args[++index], "--steps-json"); continue; }
 		if (argument === "--tools-json") { tools = parseJsonStringArrayFlag(args[++index], "--tools-json"); continue; }
 		if (argument === "--labels-json") { labels = parseJsonStringArrayFlag(args[++index], "--labels-json"); continue; }
 		if (argument === "--extra-json") { extra = parseJsonObjectFlag(args[++index], "--extra-json"); continue; }
 		if (argument === "--arguments-json") { playbookArguments = parseJsonAnyFlag(args[++index], "--arguments-json"); continue; }
+		if (argument === "--run-id") { runId = args[++index]; if (!runId) throw new Error("--run-id requires a value"); continue; }
 		if (argument === "--status") { status = args[++index]; if (!status) throw new Error("--status requires a value"); continue; }
 		if (argument === "--text") { text = args[++index]; if (text === undefined) throw new Error("--text requires a value"); continue; }
 		if (argument === "--project-root") { playbookProjectRoot = args[++index]; if (!playbookProjectRoot) throw new Error("--project-root requires a value"); continue; }
@@ -889,7 +728,7 @@ export async function runPlaybooksCli(args: string[], client: TaskCliClient): Pr
 		}
 		case "invoke": {
 			if (!id || second) throw new Error("playbooks invoke requires exactly one playbook id");
-			const invocation = await client.call<Record<string, unknown>, { entryTaskId: string; missingArguments?: string[] }>("playbooks.invoke", { id, arguments: playbookArguments, project_root: playbookProjectRoot });
+			const invocation = await client.call<Record<string, unknown>, { entryTaskId: string; missingArguments?: string[] }>("playbooks.invoke", { id, arguments: playbookArguments, run_id: runId, project_root: playbookProjectRoot });
 			result = invocation;
 			human = invocation.missingArguments
 				? `Missing required argument(s): ${invocation.missingArguments.join(", ")}.`
@@ -1803,11 +1642,6 @@ export async function main(args: string[] = process.argv.slice(2)): Promise<void
 		console.log(await runTaskCli(args.slice(1), client));
 		return;
 	}
-	if (command === "skills") {
-		const client = await connectPapyrusClient();
-		console.log(await runSkillCli(args.slice(1), client));
-		return;
-	}
 	if (command === "playbooks") {
 		const client = await connectPapyrusClient();
 		console.log(await runPlaybooksCli(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 = 21;
+export const SQLITE_SCHEMA_VERSION = 23;
 export const SERVICE_MAX_BODY_BYTES = 1_048_576;
 
 export const WAL_CHECKPOINT_INTERVAL_MS = 60_000;
@@ -97,22 +97,22 @@ export const SKILL_MAX_LINKS = 500;
 export const SKILL_MAX_RENDERED_BYTES = 1_048_576;
 
 /**
- * Skills are special: invoking one queries Papyrus for whatever it's actually graph-linked
- * to (existing Tasks/Rules/Docs via ordinary edges, not just its own static body/extra
- * fields), and a Skill can link to and invoke other Skills. Both traversals are bounded and
- * cycle-safe -- a skill-calls-skill edge cycle must not infinite-loop invocation, matching
- * the same cycle-safety discipline established by task dependency graphs and the
+ * Invoking a Playbook queries Papyrus for whatever it's actually graph-linked to (existing
+ * Tasks/Rules/Docs via ordinary edges, not just its own static body/extra fields), and a
+ * Playbook can link to and invoke other Playbooks. Both traversals are bounded and
+ * cycle-safe -- a playbook-calls-playbook edge cycle must not infinite-loop invocation,
+ * matching the same cycle-safety discipline established by task dependency graphs and the
  * (since-removed; see Doc "ConversationJournal design record") ConversationJournal domain's
  * own reply chains.
  */
-export const SKILL_INVOCATION_MAX_LINKED_ARTIFACTS = 20;
-export const SKILL_INVOCATION_MAX_CALL_DEPTH = 4;
 export const PLAYBOOK_INVOCATION_MAX_LINKED_ARTIFACTS = 20;
-/** Mirrors SKILL_INVOCATION_MAX_CALL_DEPTH: a playbook-calls-playbook edge chain is bounded the same way a skill-calls-skill chain is. */
 export const PLAYBOOK_INVOCATION_MAX_CALL_DEPTH = 4;
 export const PLAYBOOK_ARGUMENT_MAX_COUNT = 20;
 export const PLAYBOOK_ARGUMENT_NAME_MAX_LENGTH = 64;
 export const PLAYBOOK_ARGUMENT_DESCRIPTION_MAX_LENGTH = 500;
+/** A Playbook argument's enum/default validation reuses SKILL_MAX_ENUM_VALUES directly (same value shape, no reason for a second bound). */
+/** One playbook's own steps array, before composition with any contained/depended-on playbook -- mirrors SKILL_MAX_BLUEPRINTS' role for a workflow Skill's flat blueprint list. */
+export const PLAYBOOK_MAX_STEPS = 100;
 /**
  * playbooks.invoke materializes a real Task per step (plus one container Task per playbook
  * node in the contains/depends_on composition tree) instead of rendering text -- this bounds
@@ -293,53 +293,20 @@ export function dbPath(): string {
 	return `${xdg}/papyrus/papyrus.db`;
 }
 
-/**
- * Four purpose-built kinds — the enforced vocabulary.
- *
- * doc   = Knowledge — descriptive ("here is what the architecture looks like")
- * task  = Work — prescriptive action items with gates and checklists
- * rule  = Governance — context injection ("when doing X, follow Y").
- *         Maps to AGENTS.md semantics: active rules with inject:true are
- *         appended to the system prompt on before_agent_start.
- * skill = Parameterized workflow bundle — validated inputs render connected Task, Rule, and Doc collections.
- */
-export const SEED_KINDS = [
-	{ name: "doc", description: "Knowledge — descriptive reference (specs, decisions, research, designs)" },
-	{ name: "task", description: "Work — action items with gates, checklists, and dependencies" },
-	{ name: "rule", description: "Governance — context injection (when doing X, follow Y). Maps to AGENTS.md" },
-	{ name: "skill", description: "Parameterized workflow bundle — inputs and templates load deterministic tasks plus contextual rules and docs" },
-] as const;
-
-export const SEED_STATUSES = [
-	{ name: "draft", kind: "doc" },
-	{ name: "active", kind: "doc" },
-	{ name: "archived", kind: "doc" },
-	{ name: "todo", kind: "task" },
-	{ name: "in-progress", kind: "task" },
-	{ name: "review", kind: "task" },
-	{ name: "rejected", kind: "task" },
-	{ name: "done", kind: "task" },
-	{ name: "canceled", kind: "task" },
-	{ name: "active", kind: "rule" },
-	{ name: "deprecated", kind: "rule" },
-	{ name: "active", kind: "skill" },
-	{ name: "deprecated", kind: "skill" },
-] as const;
-
 /**
  * The initial status a newly created artifact of a kind gets when no caller-supplied
  * status is given. This must be an explicit, named mapping — never derived from row order
- * in the `statuses` table (SEED_STATUSES' listed order, or a migration's insertion order,
- * is not a semantic guarantee; a migrated database can freely have a different physical
- * row order for the same logical status set). Deriving "the default" from "whichever row
- * happens to be first by rowid" was the root cause of a real production defect where
- * migrated databases created new Tasks as done instead of todo.
+ * in the `statuses` table (a migration's insertion order is not a semantic guarantee; a
+ * migrated database can freely have a different physical row order for the same logical
+ * status set). Deriving "the default" from "whichever row happens to be first by rowid"
+ * was the root cause of a real production defect where migrated databases created new
+ * Tasks as done instead of todo.
  */
 export const DEFAULT_STATUS_BY_KIND: Readonly<Record<string, string>> = {
 	doc: "draft",
 	task: "todo",
 	rule: "active",
-	skill: "active",
+	playbook: "active",
 };
 
 /**
@@ -347,14 +314,14 @@ export const DEFAULT_STATUS_BY_KIND: Readonly<Record<string, string>> = {
  *
  * references:  source material (doc→doc, doc→task, doc→rule)
  * implements:  this work satisfies that (task→doc, task→rule)
- * follows:     this work obeys that (task→rule, task→skill)
- * depends_on:  DAG ordering (task→task)
- * documents:   describes (doc→task, doc→rule, doc→skill)
+ * follows:     this work obeys that (task→rule, task→playbook)
+ * depends_on:  DAG ordering (task→task, playbook→playbook)
+ * documents:   describes (doc→task, doc→rule, doc→playbook)
  * blocks:      blocking relationship (task→task)
  * supersedes:  replaces (doc→doc, rule→rule)
  * relates_to:  catch-all (any→any)
  * gates:       this rule gates that task (rule→task)
- * triggers:    this skill applies to that work (skill→task)
+ * triggers:    this playbook run applies to that work (playbook→task)
  */
 export const SEED_RELATIONS = [
 	"references", "implements", "follows", "depends_on",

package/src/db.ts

@@ -291,7 +291,6 @@ const SEED_SQL = `
 INSERT OR IGNORE INTO kinds VALUES ('doc','Knowledge — what we know (specs, decisions, research, designs)');
 INSERT OR IGNORE INTO kinds VALUES ('task','Work — what we are doing (objectives, steps, checklists)');
 INSERT OR IGNORE INTO kinds VALUES ('rule','Governance — when doing X, follow Y');
-INSERT OR IGNORE INTO kinds VALUES ('skill','Parameterized workflow bundle — inputs and templates load tasks, rules, and docs');
 INSERT OR IGNORE INTO kinds VALUES ('playbook','Reusable procedure — a trigger and an ordered list of steps an agent reads and follows, not a mechanically instantiated blueprint');
 INSERT OR IGNORE INTO statuses VALUES ('draft','doc');
 INSERT OR IGNORE INTO statuses VALUES ('active','doc');
@@ -304,20 +303,18 @@ INSERT OR IGNORE INTO statuses VALUES ('done','task');
 INSERT OR IGNORE INTO statuses VALUES ('canceled','task');
 INSERT OR IGNORE INTO statuses VALUES ('active','rule');
 INSERT OR IGNORE INTO statuses VALUES ('deprecated','rule');
-INSERT OR IGNORE INTO statuses VALUES ('active','skill');
-INSERT OR IGNORE INTO statuses VALUES ('deprecated','skill');
 INSERT OR IGNORE INTO statuses VALUES ('active','playbook');
 INSERT OR IGNORE INTO statuses VALUES ('deprecated','playbook');
 INSERT OR IGNORE INTO relation_names VALUES ('references','Source material (doc→doc, doc→task, doc→rule)');
 INSERT OR IGNORE INTO relation_names VALUES ('implements','This work satisfies that (task→doc, task→rule)');
-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 ('follows','This work obeys that (task→rule, task→playbook)');
+INSERT OR IGNORE INTO relation_names VALUES ('depends_on','DAG ordering (task→task, playbook→playbook)');
+INSERT OR IGNORE INTO relation_names VALUES ('documents','Describes (doc→task, doc→rule, doc→playbook)');
 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)');
-INSERT OR IGNORE INTO relation_names VALUES ('triggers','This skill applies to that work (skill→task)');
+INSERT OR IGNORE INTO relation_names VALUES ('triggers','This playbook run applies to that work (playbook→task)');
 INSERT OR IGNORE INTO relation_names VALUES ('contains','Parent contains a nested artifact (any→any)');
 INSERT OR IGNORE INTO relation_names VALUES ('part_of','Artifact belongs to a parent artifact (any→any)');
 CREATE INDEX IF NOT EXISTS edges_to_id_idx ON edges(to_id);
@@ -656,6 +653,36 @@ const FUTURE_MIGRATIONS: ReadonlyArray<PapyrusMigration> = [
 			}
 		},
 	},
+	{
+		version: 22,
+		name: "skill-to-playbook-data-migration",
+		// Part of the Skill→Playbook consolidation. Migration 18 already moved subtype-less Skill
+		// rows to kind=playbook; this moves everything still left under kind=skill (workflow and
+		// artifact-template rows alike, plus any bare stragglers), preserving subtype and status so
+		// a later task can still tell which authoring shape each migrated row came from. The
+		// 'skill'/'artifact-template' kinds/statuses type rows themselves are deliberately NOT
+		// dropped here: src/modules/skills.ts's createSkill (and the CLI/Vehicle/TUI surfaces still
+		// wired to it) still writes kind='skill' rows in its own live, not-yet-retired test suite --
+		// dropping the kinds row now would break that FK-enforced write path before its own
+		// retirement task removes it. Dropping the type rows is that later task's job.
+		up: (db) => {
+			db.exec(`UPDATE artifacts SET kind = 'playbook' WHERE kind = 'skill'`);
+		},
+	},
+	{
+		version: 23,
+		name: "retire-skill-kind",
+		// Final step of the Skill→Playbook consolidation. Every module/CLI/Vehicle/TUI surface
+		// that wrote kind='skill' is now retired (confirmed live: zero real callers anywhere), and
+		// migration 22 already moved every existing row off kind=skill. The type rows themselves
+		// are now genuinely dead -- safe to drop.
+		up: (db) => {
+			db.exec(`
+				DELETE FROM statuses WHERE kind = 'skill';
+				DELETE FROM kinds WHERE name = 'skill';
+			`);
+		},
+	},
 ];
 
 /**

package/src/domain/artifact-event.ts

@@ -1,6 +1,6 @@
 /**
  * Generic, kind-agnostic mutation event log — the "who did what, when" answer
- * shared by every artifact kind (doc, task, rule, skill), not reinvented per domain.
+ * shared by every artifact kind (doc, task, rule, playbook), not reinvented per domain.
  *
  * Modeled after scribe's parchment.Event/EventFilter/GetEvents shape, but avoids its
  * known gap: there, the Actor column is defined and filterable yet never populated by