@danypops/papyrus 0.3.0 → 0.4.0

package/README.md

@@ -62,11 +62,20 @@ Each kind has an enforced status vocabulary. Every edge endpoint must exist, and
 
 ### Hierarchy and traversal
 
-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 may activate several successors. 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.
+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
 
-A Papyrus Skill is distinct from a conventional prompt-only skill: its input API and templates define a connected Task/Rule/Doc workflow. Task dependencies and gates provide deterministic execution; Rules provide scoped governance; Docs provide invocation context and provenance. The versioned workflow-instantiation API is tracked as active Papyrus work.
+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 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.
+
+```bash
+papyrus skills run <skill-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 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.
 
@@ -84,7 +93,7 @@ Agent-facing domain tools own lifecycle invariants and sit above this store API:
 - **`tasks`** — create/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
 - **`rules`** — create/list/show/preview, enable/disable, and attach governance gates to tasks
-- **`skills`** — create/list/show/invoke, enable/disable, create templates, and instantiate templates
+- **`skills`** — create/list/show/invoke/run, enable/disable, create compatibility templates, and atomically instantiate parameterized workflow runs
 
 Every tool operation is registered in the daemon’s `/api/v1/ops` registry; parity is verified in tests. The task consumer uses the `tasks.graph` operation, which returns task nodes with explicit parent, child, and dependency IDs rather than leaking SQLite rows or asking the UI to reconstruct relationships.
 
@@ -105,6 +114,7 @@ Run `/tasks` for the interactive task panel:
 
 - `/` filters; arrow keys navigate; Enter opens task actions
 - `g` opens the programmatic Unicode graph; Tab switches dependency/composition views and arrow keys pan
+- routed graph layouts are bounded to 48 nodes/96 edges; larger graphs use a deterministic, box-drawn line fallback, and renderer failures are contained inside the viewport rather than escaping Pi
 - advance the `todo → in-progress → review → done` lifecycle; failed review becomes `rejected`, retry returns to `in-progress`, and `canceled` is terminal
 - use **active** only as the independent singleton focus that auto-drive continues; focusing a task never changes its lifecycle
 - starting nested effort moves todo ancestors to in-progress; submitting enters review; completing review checks both typed checklist proofs and executable gates
@@ -118,6 +128,7 @@ Run `/tasks` for the interactive task panel:
 Authenticated CLI parity covers the changed lifecycle and focus operations:
 
 ```bash
+papyrus tasks graph --json
 papyrus tasks active --json
 papyrus tasks focus <id> --json
 papyrus tasks start <id> --json

package/extension/src/beautiful-mermaid-renderer.ts

@@ -1,6 +1,9 @@
 import { renderMermaidASCII } from "beautiful-mermaid";
 import {
 	GRAPH_RENDER_BOX_PADDING,
+	GRAPH_RENDER_MAX_FALLBACK_LINES,
+	GRAPH_RENDER_MAX_ROUTED_EDGES,
+	GRAPH_RENDER_MAX_ROUTED_NODES,
 	GRAPH_RENDER_PADDING_X,
 	GRAPH_RENDER_PADDING_Y,
 } from "../../src/constants.ts";
@@ -30,9 +33,29 @@ export function mermaidSource(graph: DisplayGraph): string {
 	return lines.join("\n");
 }
 
+function boundedLineFallback(graph: DisplayGraph): RenderedGraph {
+	const candidates = [
+		"┌─ Task graph ─",
+		`│ ${graph.nodes.length} nodes · ${graph.edges.length} edges · routed layout skipped above ${GRAPH_RENDER_MAX_ROUTED_NODES} nodes`,
+		"├─ Nodes",
+		...graph.nodes.map((node) => `│ ${node.label}`),
+		"├─ Edges",
+		...graph.edges.map((edge) => `│ ${edge.from} ─${edge.label ? `${edge.label}─` : ""}→ ${edge.to}`),
+	];
+	const contentLimit = Math.max(1, GRAPH_RENDER_MAX_FALLBACK_LINES - 1);
+	const lines = candidates.slice(0, contentLimit);
+	const omitted = candidates.length - lines.length;
+	if (omitted > 0) lines[lines.length - 1] = `│ … ${omitted + 1} lines omitted`;
+	lines.push("└─");
+	return { lines };
+}
+
 export class BeautifulMermaidRenderer implements GraphRenderer {
 	render(graph: DisplayGraph): RenderedGraph {
 		if (graph.nodes.length === 0) return { lines: [] };
+		if (graph.nodes.length > GRAPH_RENDER_MAX_ROUTED_NODES || graph.edges.length > GRAPH_RENDER_MAX_ROUTED_EDGES) {
+			return boundedLineFallback(graph);
+		}
 		const output = renderMermaidASCII(mermaidSource(graph), {
 			useAscii: false,
 			paddingX: GRAPH_RENDER_PADDING_X,

package/extension/src/domain-tools.ts

@@ -4,7 +4,8 @@ import type { Artifact } from "../../src/domain/artifact.ts";
 import { PROOF_TYPES } from "../../src/domain/checklist.ts";
 import type { GateResult } from "../../src/domain/gate.ts";
 import type { TaskExecutionPlan } from "../../src/task-execution.ts";
-import type { TaskCompletion } from "../../src/task-service.ts";
+import type { TaskCompletion, TaskGraph } from "../../src/task-service.ts";
+import type { SkillWorkflowRunResult } from "../../src/skill-execution.ts";
 import { callService } from "./service-client.ts";
 
 function text(message: string, details: Record<string, unknown> = {}) {
@@ -29,7 +30,7 @@ export function registerDomainTools(pi: ExtensionAPI): void {
 	pi.registerTool({
 		name: "tasks",
 		label: "Tasks",
-		description: "Task domain tool. ACTIONS: create, list, show, plan, active, focus, start, submit, complete, reject, retry, cancel, run_gates, set_checklist, depend, contain. Lifecycle is todo → in-progress → review → done, with review failure → rejected and retry → in-progress; canceled is terminal. 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. Prefer this over low-level papyrus_* tools for task work.",
+		description: "Task domain tool. ACTIONS: create, list, show, graph, plan, active, focus, start, submit, complete, reject, retry, cancel, run_gates, set_checklist, depend, contain. Lifecycle is todo → in-progress → review → done, with review failure → rejected and retry → in-progress; canceled is terminal. 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. Prefer this over low-level papyrus_* tools for task work.",
 		parameters: Type.Object({
 			action: Type.String(),
 			id: Type.Optional(Type.String()),
@@ -67,6 +68,12 @@ export function registerDomainTools(pi: ExtensionAPI): void {
 					const artifact = await callService<Record<string, unknown>, Artifact | null>("tasks.active", params);
 					return text(artifact ? `Active: ${artifactLine(artifact)}` : "No active task.", { artifact });
 				}
+				if (action === "graph") {
+					const graph = await callService<Record<string, unknown>, TaskGraph>("tasks.graph", params);
+					const dependencies = graph.nodes.reduce((count, node) => count + node.dependencyIds.length, 0);
+					const containment = graph.nodes.reduce((count, node) => count + node.childIds.length, 0);
+					return text(`Task graph: ${graph.nodes.length} nodes, ${graph.rootIds.length} roots, ${dependencies} dependencies, ${containment} containment edges.`, { graph });
+				}
 				if (action === "plan") {
 					const plan = await callService<Record<string, unknown>, TaskExecutionPlan>("tasks.plan", params);
 					const byId = new Map(plan.nodes.map((node) => [node.id, node]));
@@ -203,11 +210,13 @@ 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, enable, disable, instantiate.",
+		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. run validates arguments and atomically creates one scoped workflow run.",
 		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())),
-			tools: Type.Optional(Type.Array(Type.String())), labels: Type.Optional(Type.Array(Type.String())),
+			tools: Type.Optional(Type.Array(Type.String())), definition: Type.Optional(Type.Record(Type.String(), Type.Unknown())),
+			arguments: Type.Optional(Type.Record(Type.String(), Type.Unknown())), run_id: 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()), template_id: Type.Optional(Type.String()),
 			target_kind: Type.Optional(Type.String()), defaults: Type.Optional(Type.Record(Type.String(), Type.Unknown())),
@@ -229,6 +238,17 @@ export function registerDomainTools(pi: ExtensionAPI): void {
 					const invocation = await callService<Record<string, unknown>, string>("skills.invoke", params);
 					return text(invocation, { invocation });
 				}
+				if (action === "run") {
+					const run = await callService<Record<string, unknown>, SkillWorkflowRunResult>("skills.run", params);
+					const execution = run.execution.nodes.map((node) => `  [${node.state}] ${node.id} ${node.title}`).join("\n");
+					return text([
+						`Created Skill run ${run.runId}: ${run.created.tasks.length} tasks, ${run.created.rules.length} rules, ${run.created.docs.length} docs.`,
+						`Ready roots: ${run.rootTaskIds.join(", ") || "none"}.`,
+						`Context docs: ${run.created.docs.join(", ") || "none"}.`,
+						`Scoped rules: ${run.created.rules.join(", ") || "none"}.`,
+						...(execution ? ["Execution:", execution] : []),
+					].join("\n"), { run });
+				}
 				const operations = { show: "skills.show", enable: "skills.enable", disable: "skills.disable", instantiate: "skills.instantiate" } as const;
 				const operation = operations[action as keyof typeof operations];
 				if (!operation) return text(`Unknown skills action: ${action}`);

package/extension/src/index.ts

@@ -21,7 +21,7 @@ import { callService } from "./service-client.ts";
 import { registerDomainTools } from "./domain-tools.ts";
 import type { TaskGraph, TaskStatus } from "../../src/task-service.ts";
 import { ActiveTaskContinuation, type ActiveTaskMarker } from "./active-task-continuation.ts";
-import { buildTaskWidgetProjection } from "./task-widget.ts";
+import { buildTaskWidgetProjection, type TaskWidgetProjection } from "./task-widget.ts";
 import { TASK_STATUS_PRESENTATION, taskTreeConnector } from "./task-presentation.ts";
 
 function text(t: string, details: Record<string, unknown> = {}) {
@@ -34,6 +34,21 @@ function text(t: string, details: Record<string, unknown> = {}) {
 
 const WIDGET_KEY = "pi-papyrus";
 
+export function renderTaskWidgetLines(theme: Theme, projection: TaskWidgetProjection, width: number): string[] {
+	if (projection.openTotal === 0) return [];
+	const lines: string[] = [];
+	for (let index = 0; index < projection.rows.length; index++) {
+		const row = projection.rows[index]!;
+		const laterSibling = projection.rows.slice(index + 1).some((candidate) => candidate.depth === row.depth);
+		const hierarchy = taskTreeConnector({ depth: row.depth, hasChildren: row.hasOpenChildren, hasLaterSibling: laterSibling });
+		const focus = row.active ? theme.fg("accent", "▶") : " ";
+		const presentation = TASK_STATUS_PRESENTATION[row.task.status as TaskStatus];
+		const glyph = presentation ? theme.fg(presentation.color, presentation.glyph) : theme.fg("muted", "?");
+		lines.push(truncateToWidth(`${focus} ${hierarchy} ${glyph} ${row.task.title}`, width, "…"));
+	}
+	return lines;
+}
+
 class TaskOverlay {
 	private uiCtx: ExtensionUIContext | undefined;
 	private registered = false;
@@ -93,31 +108,7 @@ class TaskOverlay {
 	}
 
 	private renderLines(theme: Theme, width: number): string[] {
-		const projection = buildTaskWidgetProjection(this.snapshot);
-		if (projection.total === 0) return [];
-
-		if (projection.openTotal === 0) {
-			return [truncateToWidth(theme.bold("Tasks · no open tasks · /tasks"), width, "…")];
-		}
-
-		const active = projection.rows.find((row) => row.active);
-		const lines = [
-			truncateToWidth(
-				theme.bold(`Tasks · ${active ? theme.fg("accent", "▶ active") : "no active focus"} · ${projection.openTotal} open`),
-				width,
-				"…",
-			),
-		];
-		for (let index = 0; index < projection.rows.length; index++) {
-			const row = projection.rows[index]!;
-			const laterSibling = projection.rows.slice(index + 1).some((candidate) => candidate.depth === row.depth);
-			const hierarchy = taskTreeConnector({ depth: row.depth, hasChildren: row.hasOpenChildren, hasLaterSibling: laterSibling });
-			const focus = row.active ? theme.fg("accent", "▶") : " ";
-			const presentation = TASK_STATUS_PRESENTATION[row.task.status as TaskStatus];
-			const glyph = presentation ? theme.fg(presentation.color, presentation.glyph) : theme.fg("muted", "?");
-			lines.push(truncateToWidth(`${focus} ${hierarchy} ${glyph} ${row.task.title}`, width, "…"));
-		}
-		return lines;
+		return renderTaskWidgetLines(theme, buildTaskWidgetProjection(this.snapshot), width);
 	}
 
 	dispose(): void {

package/extension/src/skills.ts

@@ -1,7 +1,10 @@
 import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
 import type { Artifact } from "../../src/domain/artifact.ts";
+import type { SkillWorkflowRunResult } from "../../src/skill-execution.ts";
+import type { TaskGraph } from "../../src/task-service.ts";
 import { showArtifactBrowser, showArtifactDetails } from "./artifact-browser.ts";
 import { callService } from "./service-client.ts";
+import { showTaskGraph } from "./task-graph.ts";
 
 const SKILL_GLYPHS: Record<string, string> = { active: "●", deprecated: "○" };
 
@@ -14,6 +17,15 @@ export function skillRowMeta(skill: Artifact): string {
 		const target = typeof skill.extra["targetKind"] === "string" ? skill.extra["targetKind"] : "artifact";
 		return `template → ${target}`;
 	}
+	if (skill.subtype === "workflow") {
+		const definition = skill.extra["definition"] as Record<string, unknown> | undefined;
+		const inputs = definition?.["inputs"] && typeof definition["inputs"] === "object"
+			? Object.keys(definition["inputs"] as Record<string, unknown>).length
+			: 0;
+		const blueprints = definition?.["blueprints"] as Record<string, unknown> | undefined;
+		const tasks = Array.isArray(blueprints?.["tasks"]) ? blueprints["tasks"].length : 0;
+		return `workflow · ${inputs} inputs · ${tasks} tasks`;
+	}
 	const trigger = typeof skill.extra["trigger"] === "string" ? `when ${skill.extra["trigger"]}` : "manual";
 	const tools = strings(skill.extra["tools"]);
 	return [trigger, tools.join(", ")].filter(Boolean).join(" · ");
@@ -23,6 +35,12 @@ export function skillInvocationPrompt(skill: Artifact): string {
 	if (skill.subtype === "artifact-template") {
 		return [`Create an artifact using Papyrus template \"${skill.title}\".`, `template_id: ${skill.id}`, "Ask for or infer the title and all required template fields, then call papyrus_create."].join("\n");
 	}
+	if (skill.subtype === "workflow") {
+		return [
+			`Run Papyrus workflow Skill \"${skill.title}\" (${skill.id}).`,
+			"Collect its required arguments, then call the skills domain tool with action=run.",
+		].join("\n");
+	}
 	const trigger = typeof skill.extra["trigger"] === "string" ? skill.extra["trigger"] : "manual invocation";
 	const steps = strings(skill.extra["steps"]);
 	const tools = strings(skill.extra["tools"]);
@@ -35,6 +53,20 @@ export function skillInvocationPrompt(skill: Artifact): string {
 	].join("\n");
 }
 
+export function skillRunTaskGraph(run: SkillWorkflowRunResult, taskArtifacts: Artifact[]): TaskGraph {
+	const executionById = new Map(run.execution.nodes.map((node) => [node.id, node]));
+	return {
+		nodes: taskArtifacts.map((task) => ({
+			task,
+			active: executionById.get(task.id)?.active === true,
+			parentIds: [],
+			childIds: [],
+			dependencyIds: executionById.get(task.id)?.prerequisiteIds ?? [],
+		})),
+		rootIds: run.rootTaskIds,
+	};
+}
+
 export async function showSkills(ctx: ExtensionCommandContext): Promise<void> {
 	await showArtifactBrowser(ctx, {
 		kind: "skill",
@@ -43,10 +75,37 @@ export async function showSkills(ctx: ExtensionCommandContext): Promise<void> {
 		statusOrder: ["active", "deprecated"],
 		glyphs: SKILL_GLYPHS,
 		rowMeta: skillRowMeta,
-		actions: (skill) => ["Show details", skill.subtype === "artifact-template" ? "Use template" : "Invoke skill", skill.status === "active" ? "Disable" : "Enable"],
+		actions: (skill) => [
+			"Show details",
+			skill.subtype === "artifact-template" ? "Use template" : skill.subtype === "workflow" ? "Run workflow" : "Invoke skill",
+			skill.status === "active" ? "Disable" : "Enable",
+		],
 		handleAction: async (choice, skill, commandCtx) => {
 			if (choice === "Show details") await showArtifactDetails(commandCtx, skill.id, "skills.show");
-			else if (choice === "Invoke skill" || choice === "Use template") {
+			else if (choice === "Run workflow") {
+				const source = await commandCtx.ui.input("Workflow arguments JSON:", "{}");
+				if (source === undefined) return;
+				try {
+					const arguments_ = JSON.parse(source) as unknown;
+					if (typeof arguments_ !== "object" || arguments_ === null || Array.isArray(arguments_)) {
+						throw new Error("arguments must be a JSON object");
+					}
+					const run = await callService<Record<string, unknown>, SkillWorkflowRunResult>("skills.run", {
+						id: skill.id,
+						arguments: arguments_ as Record<string, unknown>,
+					});
+					commandCtx.ui.notify([
+						`Created ${run.runId} · ${run.created.tasks.length} tasks · ${run.rootTaskIds.length} ready roots`,
+						`Context docs: ${run.created.docs.join(", ") || "none"}`,
+						`Scoped rules: ${run.created.rules.join(", ") || "none"}`,
+					].join("\n"), "info");
+					const taskArtifacts = await Promise.all(run.execution.nodes.map((node) =>
+						callService<Record<string, unknown>, Artifact>("tasks.show", { id: node.id })));
+					await showTaskGraph(commandCtx, skillRunTaskGraph(run, taskArtifacts));
+				} catch (error) {
+					commandCtx.ui.notify(`Workflow run failed: ${error instanceof Error ? error.message : error}`, "error");
+				}
+			} else if (choice === "Invoke skill" || choice === "Use template") {
 				const invocation = await callService<Record<string, unknown>, string>("skills.invoke", { id: skill.id });
 				commandCtx.ui.setEditorText(invocation);
 				commandCtx.ui.notify("Invocation placed in the editor", "info");

package/extension/src/task-graph.ts

@@ -86,8 +86,17 @@ export class TaskGraphViewport {
 
 	private rebuild(): void {
 		const view = GRAPH_VIEWS[this.viewIndex]!;
-		this.graphLines = this.renderer.render(projectTaskGraph(this.graph, view)).lines;
-		if (this.graphLines.length === 0) this.graphLines = [`No task ${view} relationships`];
+		try {
+			this.graphLines = this.renderer.render(projectTaskGraph(this.graph, view)).lines;
+			if (this.graphLines.length === 0) this.graphLines = [`No task ${view} relationships`];
+		} catch {
+			this.graphLines = [
+				"┌─ Task graph ─",
+				`│ Graph rendering failed for ${view} view.`,
+				"│ Press Tab for another view or Esc to close.",
+				"└─",
+			];
+		}
 		this.offsetY = Math.min(this.offsetY, Math.max(0, this.graphLines.length - this.viewportHeight));
 	}
 }

package/package.json

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

@@ -1,5 +1,6 @@
 import type { Db } from "../db.ts";
-import type { ArtifactStore } from "../ports/artifact-store.ts";
+import { inTransaction } from "../db.ts";
+import type { AtomicArtifactStore } from "../ports/atomic-artifact-store.ts";
 import type {
 	Artifact,
 	ArtifactEdge,
@@ -11,9 +12,13 @@ import type {
 } from "../domain/artifact.ts";
 import { createArtifact, getArtifact, linkArtifacts, queryArtifacts, updateExtra, updateStatus } from "../ops.ts";
 
-export class SQLiteArtifactStore implements ArtifactStore {
+export class SQLiteArtifactStore implements AtomicArtifactStore {
 	constructor(private readonly db: Db) {}
 
+	atomic<T>(operation: () => T): T {
+		return inTransaction(this.db, operation);
+	}
+
 	create(input: CreateArtifactInput): Artifact {
 		return createArtifact(this.db, input);
 	}

package/src/cli.ts

@@ -5,7 +5,7 @@ import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { connectPapyrusClient, type PapyrusClient } from "./client.ts";
-import { DAEMON_UNIT_NAME } from "./constants.ts";
+import { DAEMON_UNIT_NAME, TASK_EXECUTION_MAX_NODES } from "./constants.ts";
 import { serveMain } from "./daemon.ts";
 import type { GateResult } from "./domain/gate.ts";
 import type { TaskExecutionPlan } from "./task-execution.ts";
@@ -57,7 +57,9 @@ const USAGE = `Usage:
   papyrus serve
   papyrus service <install|start|stop|restart|status>
   papyrus migrate task-lifecycle [--json]
+  papyrus skills run <id> [--arguments-json <json>] [--run-id <id>] [--json]
   papyrus tasks plan [--json]
+  papyrus tasks graph [--json]
   papyrus tasks active [--json]
   papyrus tasks focus <id> [--json]
   papyrus tasks complete <id> [--json]
@@ -113,6 +115,51 @@ export async function runMigrationCli(args: string[], client: TaskCliClient): Pr
 	return `Migrated schema ${result.from} → ${result.to}: ${result.applied.join(", ")}`;
 }
 
+export async function runSkillCli(args: string[], client: TaskCliClient): Promise<string> {
+	const json = args.includes("--json");
+	const positional: string[] = [];
+	let runId: string | undefined;
+	let arguments_: Record<string, unknown> = {};
+	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") {
+			const source = args[++index];
+			if (!source) throw new Error("--arguments-json requires a JSON object");
+			const parsed = JSON.parse(source) as unknown;
+			if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+				throw new Error("--arguments-json must be a JSON object");
+			}
+			arguments_ = parsed as Record<string, unknown>;
+			continue;
+		}
+		if (argument.startsWith("--")) throw new Error(`unknown skills option ${argument}`);
+		positional.push(argument);
+	}
+	if (positional.length !== 2 || positional[0] !== "run") throw new Error("skills requires `run <id>`");
+	const input: Record<string, unknown> = { id: positional[1], arguments: arguments_ };
+	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");
+}
+
 export async function runTaskCli(args: string[], client: TaskCliClient): Promise<string> {
 	const json = args.includes("--json");
 	const positional = args.filter((arg) => arg !== "--json");
@@ -134,6 +181,18 @@ export async function runTaskCli(args: string[], client: TaskCliClient): Promise
 			human = `Active: ${artifactLabel(active)}`;
 			break;
 		}
+		case "graph": {
+			if (id) throw new Error("tasks graph accepts no positional arguments");
+			const graph = await client.call<{ limit: number }, {
+				nodes: Array<{ dependencyIds: string[]; childIds: string[] }>;
+				rootIds: string[];
+			}>("tasks.graph", { limit: TASK_EXECUTION_MAX_NODES + 1 });
+			result = graph;
+			const dependencies = graph.nodes.reduce((count, node) => count + node.dependencyIds.length, 0);
+			const children = graph.nodes.reduce((count, node) => count + node.childIds.length, 0);
+			human = `Task graph: ${graph.nodes.length} nodes, ${graph.rootIds.length} roots, ${dependencies} dependencies, ${children} containment edges`;
+			break;
+		}
 		case "plan": {
 			if (id) throw new Error("tasks plan accepts no positional arguments");
 			const plan = await client.call<Record<string, never>, TaskExecutionPlan>("tasks.plan", {});
@@ -183,7 +242,7 @@ export async function runTaskCli(args: string[], client: TaskCliClient): Promise
 			break;
 		}
 		default:
-			throw new Error("tasks action must be active, focus, plan, complete, start, submit, reject, retry, cancel, or depend");
+			throw new Error("tasks action must be active, focus, graph, plan, complete, start, submit, reject, retry, cancel, or depend");
 	}
 	return json ? JSON.stringify(result) : human;
 }
@@ -196,6 +255,11 @@ 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 === "migrate") {
 		const client = await connectPapyrusClient();
 		console.log(await runMigrationCli(args.slice(1), client));

package/src/constants.ts

@@ -32,12 +32,23 @@ export const TASK_GRAPH_HORIZONTAL_PAN_COLUMNS = 4;
 export const TASK_EXECUTION_MAX_NODES = 1_000;
 export const TASK_EXECUTION_MAX_EDGES = 10_000;
 export const TASK_EXECUTION_MAX_DEGREE = 100;
+/** Bounded parameterized Skill definitions and rendered workflow runs. */
+export const SKILL_MAX_INPUTS = 32;
+export const SKILL_MAX_ENUM_VALUES = 32;
+export const SKILL_MAX_BLUEPRINTS = 100;
+export const SKILL_MAX_LINKS = 500;
+export const SKILL_MAX_RENDERED_BYTES = 1_048_576;
+export const SKILL_RUN_ID_MAX_LENGTH = 64;
 /** Bounded automatic Pi continuations while a focused Papyrus Task remains. */
 export const TASK_DRIVER_MAX_TURNS = 20;
 export const TASK_DRIVER_MAX_UNCHANGED_TURNS = 6;
 export const GRAPH_RENDER_PADDING_X = 2;
 export const GRAPH_RENDER_PADDING_Y = 1;
 export const GRAPH_RENDER_BOX_PADDING = 0;
+/** beautiful-mermaid routed layouts become unsafe on larger task graphs; use bounded line fallback. */
+export const GRAPH_RENDER_MAX_ROUTED_NODES = 48;
+export const GRAPH_RENDER_MAX_ROUTED_EDGES = 96;
+export const GRAPH_RENDER_MAX_FALLBACK_LINES = 200;
 
 /** Safe defaults and hard ceilings for graph expansion. */
 export const DEFAULT_GRAPH_DEPTH = 4;

package/src/db.ts

@@ -29,15 +29,38 @@ export interface Db {
 	close(): void;
 }
 
+const TRANSACTION_DEPTH = new WeakMap<object, number>();
+
 export function inTransaction<T>(db: Db, fn: () => T): T {
+	const depth = TRANSACTION_DEPTH.get(db as object) ?? 0;
+	if (depth > 0) {
+		const savepoint = `papyrus_nested_${depth}`;
+		db.exec(`SAVEPOINT ${savepoint}`);
+		TRANSACTION_DEPTH.set(db as object, depth + 1);
+		try {
+			const result = fn();
+			db.exec(`RELEASE SAVEPOINT ${savepoint}`);
+			return result;
+		} catch (error) {
+			db.exec(`ROLLBACK TO SAVEPOINT ${savepoint}`);
+			db.exec(`RELEASE SAVEPOINT ${savepoint}`);
+			throw error;
+		} finally {
+			TRANSACTION_DEPTH.set(db as object, depth);
+		}
+	}
+
 	db.exec("BEGIN IMMEDIATE");
+	TRANSACTION_DEPTH.set(db as object, 1);
 	try {
 		const result = fn();
 		db.exec("COMMIT");
 		return result;
-	} catch (e) {
+	} catch (error) {
 		db.exec("ROLLBACK");
-		throw e;
+		throw error;
+	} finally {
+		TRANSACTION_DEPTH.delete(db as object);
 	}
 }
 

package/src/domain/skill-definition.ts

@@ -1,4 +1,10 @@
-import { SEED_RELATIONS } from "../constants.ts";
+import {
+	SEED_RELATIONS,
+	SKILL_MAX_BLUEPRINTS,
+	SKILL_MAX_ENUM_VALUES,
+	SKILL_MAX_INPUTS,
+	SKILL_MAX_LINKS,
+} from "../constants.ts";
 
 export type SkillArgumentValue = string | number | boolean;
 export type SkillInputType = "string" | "number" | "boolean";
@@ -59,13 +65,10 @@ export interface SkillDefinition {
 	links: SkillBlueprintLink[];
 }
 
-const MAX_INPUTS = 32;
-const MAX_ENUM_VALUES = 32;
-const MAX_BLUEPRINTS = 100;
-const MAX_LINKS = 500;
 const NAME_PATTERN = /^[A-Za-z][A-Za-z0-9_-]{0,63}$/;
 const PLACEHOLDER_PATTERN = /{{\s*([A-Za-z][A-Za-z0-9_-]{0,63})\s*}}/g;
 const INPUT_TYPES = new Set<SkillInputType>(["string", "number", "boolean"]);
+const RESERVED_KEYS = new Set(["__proto__", "constructor", "prototype"]);
 const RELATIONS = new Set<string>(SEED_RELATIONS);
 
 function record(value: unknown, label: string): Record<string, unknown> {
@@ -93,9 +96,10 @@ function validateArgumentValue(name: string, type: SkillInputType, value: unknow
 function validateInputs(value: unknown): Record<string, SkillInputDefinition> {
 	const source = record(value ?? {}, "skill inputs");
 	const entries = Object.entries(source);
-	if (entries.length > MAX_INPUTS) throw new Error(`skill inputs exceed ${MAX_INPUTS}`);
+	if (entries.length > SKILL_MAX_INPUTS) throw new Error(`skill inputs exceed ${SKILL_MAX_INPUTS}`);
 	const result: Record<string, SkillInputDefinition> = {};
 	for (const [name, raw] of entries) {
+		if (RESERVED_KEYS.has(name)) throw new Error(`reserved skill input name "${name}"`);
 		if (!NAME_PATTERN.test(name)) throw new Error(`invalid skill input name "${name}"`);
 		const input = record(raw, `skill input "${name}"`);
 		if (!INPUT_TYPES.has(input["type"] as SkillInputType)) throw new Error(`skill input "${name}" has unsupported type`);
@@ -108,7 +112,7 @@ function validateInputs(value: unknown): Record<string, SkillInputDefinition> {
 		if (input["default"] !== undefined) normalized.default = validateArgumentValue(name, type, input["default"]);
 		if (input["enum"] !== undefined) {
 			const values = array(input["enum"], `skill input "${name}" enum`);
-			if (values.length === 0 || values.length > MAX_ENUM_VALUES) throw new Error(`skill input "${name}" enum must contain 1-${MAX_ENUM_VALUES} values`);
+			if (values.length === 0 || values.length > SKILL_MAX_ENUM_VALUES) throw new Error(`skill input "${name}" enum must contain 1-${SKILL_MAX_ENUM_VALUES} values`);
 			normalized.enum = values.map((entry) => validateArgumentValue(name, type, entry));
 			if (normalized.default !== undefined && !normalized.enum.includes(normalized.default)) {
 				throw new Error(`skill input "${name}" default must be one of its enum values`);
@@ -162,7 +166,7 @@ export function validateSkillDefinition(value: unknown): SkillDefinition {
 	const rules = array(rawBlueprints["rules"] ?? [], "skill rule blueprints").map((entry) => validateBlueprint<SkillRuleBlueprint>(entry, "rule"));
 	const tasks = array(rawBlueprints["tasks"] ?? [], "skill task blueprints").map((entry) => validateBlueprint<SkillTaskBlueprint>(entry, "task"));
 	const all = [...docs, ...rules, ...tasks];
-	if (all.length === 0 || all.length > MAX_BLUEPRINTS) throw new Error(`skill blueprints must contain 1-${MAX_BLUEPRINTS} artifacts`);
+	if (all.length === 0 || all.length > SKILL_MAX_BLUEPRINTS) throw new Error(`skill blueprints must contain 1-${SKILL_MAX_BLUEPRINTS} artifacts`);
 	const refs = new Set<string>();
 	for (const blueprint of all) {
 		if (refs.has(blueprint.ref)) throw new Error(`duplicate skill blueprint ref "${blueprint.ref}"`);
@@ -179,7 +183,7 @@ export function validateSkillDefinition(value: unknown): SkillDefinition {
 	}
 	assertAcyclic(tasks);
 	for (const name of placeholders(all)) {
-		if (!(name in inputs)) throw new Error(`unknown skill input placeholder "${name}"`);
+		if (!Object.hasOwn(inputs, name)) throw new Error(`unknown skill input placeholder "${name}"`);
 	}
 	const links = array(source["links"] ?? [], "skill links").map((entry) => {
 		const link = record(entry, "skill link");
@@ -191,14 +195,14 @@ export function validateSkillDefinition(value: unknown): SkillDefinition {
 		if (!RELATIONS.has(relation)) throw new Error(`unknown skill link relation "${relation}"`);
 		return { from, relation, to };
 	});
-	if (links.length > MAX_LINKS) throw new Error(`skill links exceed ${MAX_LINKS}`);
+	if (links.length > SKILL_MAX_LINKS) throw new Error(`skill links exceed ${SKILL_MAX_LINKS}`);
 	return { version: 1, inputs, blueprints: { docs, rules, tasks }, links };
 }
 
 export function resolveSkillArguments(definition: SkillDefinition, value: unknown): Record<string, SkillArgumentValue> {
 	const source = record(value ?? {}, "skill arguments");
 	for (const name of Object.keys(source)) {
-		if (!(name in definition.inputs)) throw new Error(`unknown skill argument "${name}"`);
+		if (!Object.hasOwn(definition.inputs, name)) throw new Error(`unknown skill argument "${name}"`);
 	}
 	const result: Record<string, SkillArgumentValue> = {};
 	for (const [name, input] of Object.entries(definition.inputs)) {

package/src/domain-services.ts

@@ -1,4 +1,5 @@
 import type { Artifact, CreateArtifactInput } from "./domain/artifact.ts";
+import { validateSkillDefinition } from "./domain/skill-definition.ts";
 import type { ArtifactStore } from "./ports/artifact-store.ts";
 
 export interface ListFilter {
@@ -98,6 +99,18 @@ export function listRules(artifacts: ArtifactStore, filter: ListFilter): Artifac
 	return artifacts.query({ kind: "rule", ...filter });
 }
 
+/** Global rules always apply; scoped workflow rules apply only while their run owns active focus. */
+export function listInjectableRules(artifacts: ArtifactStore, activeTaskId?: string): Artifact[] {
+	return artifacts.query({ kind: "rule", status: "active" }).filter((rule) => {
+		const scope = rule.extra["scope"];
+		if (scope === undefined) return true;
+		if (typeof scope !== "object" || scope === null || Array.isArray(scope)) return false;
+		const value = scope as Record<string, unknown>;
+		if (value["type"] !== "skill-run" || !Array.isArray(value["taskIds"])) return false;
+		return activeTaskId !== undefined && value["taskIds"].some((id) => id === activeTaskId);
+	});
+}
+
 export function showRule(artifacts: ArtifactStore, id: string): Artifact {
 	requireKind(artifacts, id, "rule");
 	return artifacts.get(id, { tree: true })!;
@@ -131,6 +144,7 @@ export interface CreateSkillInput {
 	trigger?: string;
 	steps?: string[];
 	tools?: string[];
+	definition?: unknown;
 	labels?: string[];
 	extra?: Record<string, unknown>;
 }
@@ -147,13 +161,19 @@ export interface CreateArtifactTemplateInput {
 export type SkillTransition = "enable" | "disable";
 
 export function createSkill(artifacts: ArtifactStore, input: CreateSkillInput): Artifact {
+	if (input.definition !== undefined && (input.trigger !== undefined || input.steps !== undefined || input.tools !== undefined)) {
+		throw new Error("workflow Skill definition cannot be mixed with legacy trigger, steps, or tools");
+	}
+	const definition = input.definition === undefined ? undefined : validateSkillDefinition(input.definition);
 	return artifacts.create({
 		kind: "skill",
+		subtype: definition ? "workflow" : undefined,
 		title: input.title,
 		body: input.body,
 		labels: input.labels,
 		extra: {
 			...(input.extra ?? {}),
+			...(definition ? { definition } : {}),
 			...(input.trigger ? { trigger: input.trigger } : {}),
 			...(input.steps ? { steps: input.steps } : {}),
 			...(input.tools ? { tools: input.tools } : {}),
@@ -194,6 +214,17 @@ export function skillInvocation(artifacts: ArtifactStore, id: string): string {
 	if (skill.subtype === "artifact-template") {
 		return `Create an artifact using Papyrus template "${skill.title}".\ntemplate_id: ${skill.id}\nAsk for or infer all required template fields, then call the skills domain tool instantiate action.`;
 	}
+	if (skill.subtype === "workflow") {
+		const definition = validateSkillDefinition(skill.extra["definition"]);
+		const required = Object.entries(definition.inputs)
+			.filter(([, input]) => input.required && input.default === undefined)
+			.map(([name]) => name);
+		return [
+			`Run Papyrus workflow Skill "${skill.title}" (${skill.id}).`,
+			`Required arguments: ${required.length > 0 ? required.join(", ") : "none"}.`,
+			"Call the skills domain tool with action=run and arguments after collecting required values.",
+		].join("\n");
+	}
 	const trigger = typeof skill.extra["trigger"] === "string" ? skill.extra["trigger"] : "manual invocation";
 	const steps = Array.isArray(skill.extra["steps"]) ? skill.extra["steps"].filter((step): step is string => typeof step === "string") : [];
 	const tools = Array.isArray(skill.extra["tools"]) ? skill.extra["tools"].filter((tool): tool is string => typeof tool === "string") : [];

package/src/ports/atomic-artifact-store.ts

@@ -0,0 +1,13 @@
+import type { ArtifactStore } from "./artifact-store.ts";
+
+/** Artifact store boundary for domain operations that must commit as one graph mutation. */
+export interface AtomicArtifactStore extends ArtifactStore {
+	atomic<T>(operation: () => T): T;
+}
+
+export function requireAtomicArtifactStore(store: ArtifactStore): AtomicArtifactStore {
+	if (!("atomic" in store) || typeof store.atomic !== "function") {
+		throw new Error("artifact store does not support atomic workflow runs");
+	}
+	return store as AtomicArtifactStore;
+}

package/src/service.ts

@@ -20,6 +20,7 @@ import {
 	instantiateTemplate,
 	listDocuments,
 	listRules,
+	listInjectableRules,
 	listSkills,
 	previewRule,
 	showDocument,
@@ -32,6 +33,7 @@ import {
 	type DocumentRelation,
 } from "./domain-services.ts";
 import { taskContext } from "./task-context.ts";
+import { instantiateSkillWorkflow } from "./skill-execution.ts";
 
 export const EXPECTED_OPERATION_NAMES = [
 	"system.migrate",
@@ -80,6 +82,7 @@ export const EXPECTED_OPERATION_NAMES = [
 	"skills.list",
 	"skills.show",
 	"skills.invoke",
+	"skills.run",
 	"skills.enable",
 	"skills.disable",
 	"skills.instantiate",
@@ -171,7 +174,7 @@ function handlers(
 		}),
 		"graph.status": (input) => artifacts.setStatus(string(input, "id"), string(input, "status")),
 		"gates.run": (input) => gates.runAsync(string(input, "id")),
-		"rules.injectable": () => artifacts.query({ kind: "rule", status: "active" })
+		"rules.injectable": () => listInjectableRules(artifacts, tasks.active()?.id)
 			.map(({ id, title, body, extra }) => ({ id, title, body, extra })),
 		"tasks.create": (input) => tasks.create({
 			title: string(input, "title"),
@@ -228,6 +231,7 @@ function handlers(
 		"skills.create": (input) => createSkill(artifacts, {
 			title: string(input, "title"), body: optionalString(input, "body"), trigger: optionalString(input, "trigger"),
 			steps: input["steps"] as string[] | undefined, tools: input["tools"] as string[] | undefined,
+			definition: input["definition"],
 			labels: input["labels"] as string[] | undefined, extra: input["extra"] as Record<string, unknown> | undefined,
 		}),
 		"skills.create_template": (input) => createArtifactTemplate(artifacts, {
@@ -237,6 +241,10 @@ function handlers(
 		"skills.list": (input) => listSkills(artifacts, taskFilter(input)),
 		"skills.show": (input) => showSkill(artifacts, string(input, "id")),
 		"skills.invoke": (input) => skillInvocation(artifacts, string(input, "id")),
+		"skills.run": (input) => instantiateSkillWorkflow(artifacts, string(input, "id"), {
+			runId: optionalString(input, "run_id") ?? optionalString(input, "runId"),
+			arguments: input["arguments"] as Record<string, unknown> | undefined,
+		}),
 		"skills.enable": (input) => transitionSkill(artifacts, string(input, "id"), "enable"),
 		"skills.disable": (input) => transitionSkill(artifacts, string(input, "id"), "disable"),
 		"skills.instantiate": (input) => instantiateTemplate(artifacts, string(input, "template_id"), normalizeCreateInput(input)),

package/src/skill-execution.ts

@@ -0,0 +1,204 @@
+import { randomUUID } from "node:crypto";
+import { SKILL_MAX_RENDERED_BYTES, SKILL_RUN_ID_MAX_LENGTH, TASK_EXECUTION_MAX_EDGES } from "./constants.ts";
+import type { Artifact } from "./domain/artifact.ts";
+import { validateChecklist } from "./domain/checklist.ts";
+import {
+	resolveSkillArguments,
+	validateSkillDefinition,
+	type SkillArgumentValue,
+	type SkillDefinition,
+} from "./domain/skill-definition.ts";
+import type { ArtifactStore } from "./ports/artifact-store.ts";
+import { requireAtomicArtifactStore } from "./ports/atomic-artifact-store.ts";
+import { projectTaskExecution, type TaskExecutionPlan } from "./task-execution.ts";
+import type { TaskGraph, TaskNode } from "./task-service.ts";
+
+const RUN_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_-]*$/;
+const EXACT_PLACEHOLDER_PATTERN = /^{{\s*([A-Za-z][A-Za-z0-9_-]{0,63})\s*}}$/;
+const PLACEHOLDER_PATTERN = /{{\s*([A-Za-z][A-Za-z0-9_-]{0,63})\s*}}/g;
+const UNSAFE_KEYS = new Set(["__proto__", "constructor", "prototype"]);
+
+export interface InstantiateSkillWorkflowInput {
+	runId?: string;
+	arguments?: Record<string, unknown>;
+}
+
+export interface SkillWorkflowRunResult {
+	skillId: string;
+	runId: string;
+	arguments: Record<string, SkillArgumentValue>;
+	created: {
+		docs: string[];
+		rules: string[];
+		tasks: string[];
+	};
+	rootTaskIds: string[];
+	execution: TaskExecutionPlan;
+}
+
+function requireWorkflowSkill(artifacts: ArtifactStore, skillId: string): { skill: Artifact; definition: SkillDefinition } {
+	const skill = artifacts.get(skillId);
+	if (!skill) throw new Error(`skill artifact "${skillId}" not found`);
+	if (skill.kind !== "skill" || skill.subtype !== "workflow") {
+		throw new Error(`artifact "${skillId}" is not a workflow Skill`);
+	}
+	if (skill.status !== "active") throw new Error(`cannot run workflow Skill from ${skill.status}`);
+	return { skill, definition: validateSkillDefinition(skill.extra["definition"]) };
+}
+
+function normalizeRunId(skillId: string, requested: string | undefined): string {
+	const runId = requested ?? `${skillId.slice(0, 40)}-${randomUUID().replaceAll("-", "").slice(0, 12)}`;
+	if (runId.length > SKILL_RUN_ID_MAX_LENGTH || !RUN_ID_PATTERN.test(runId)) {
+		throw new Error(`skill run id must match ${RUN_ID_PATTERN} and contain at most ${SKILL_RUN_ID_MAX_LENGTH} characters`);
+	}
+	return runId;
+}
+
+function renderValue(value: unknown, arguments_: Record<string, SkillArgumentValue>): unknown {
+	if (typeof value === "string") {
+		const exact = value.match(EXACT_PLACEHOLDER_PATTERN);
+		if (exact) {
+			const name = exact[1]!;
+			if (!(name in arguments_)) throw new Error(`skill input placeholder "${name}" has no argument value`);
+			return arguments_[name]!;
+		}
+		return value.replace(PLACEHOLDER_PATTERN, (_placeholder, name: string) => {
+			if (!(name in arguments_)) throw new Error(`skill input placeholder "${name}" has no argument value`);
+			return String(arguments_[name]!);
+		});
+	}
+	if (Array.isArray(value)) return value.map((entry) => renderValue(entry, arguments_));
+	if (typeof value !== "object" || value === null) return value;
+	const rendered: Record<string, unknown> = {};
+	for (const [key, entry] of Object.entries(value)) {
+		if (UNSAFE_KEYS.has(key)) throw new Error(`unsafe skill blueprint key "${key}"`);
+		rendered[key] = renderValue(entry, arguments_);
+	}
+	return rendered;
+}
+
+function renderDefinition(definition: SkillDefinition, arguments_: Record<string, SkillArgumentValue>): SkillDefinition {
+	const rendered = renderValue(definition, arguments_) as SkillDefinition;
+	const bytes = new TextEncoder().encode(JSON.stringify(rendered)).byteLength;
+	if (bytes > SKILL_MAX_RENDERED_BYTES) throw new Error(`rendered skill workflow exceeds ${SKILL_MAX_RENDERED_BYTES} bytes`);
+	for (const task of rendered.blueprints.tasks) {
+		if (task.extra?.["checklist"] !== undefined) {
+			task.extra["checklist"] = validateChecklist(task.extra["checklist"]);
+		}
+	}
+	return validateSkillDefinition(rendered);
+}
+
+function withRunLabel(labels: string[] | undefined, runId: string): string[] {
+	return [...new Set([...(labels ?? []), `skill-run:${runId}`])];
+}
+
+function executionGraph(tasks: Artifact[], definition: SkillDefinition, ids: Map<string, string>): TaskGraph {
+	const byRef = new Map(definition.blueprints.tasks.map((task) => [task.ref, task]));
+	const nodes: TaskNode[] = tasks.map((task) => {
+		const ref = task.extra["skillRun"] && typeof task.extra["skillRun"] === "object"
+			? (task.extra["skillRun"] as Record<string, unknown>)["ref"] as string
+			: "";
+		const blueprint = byRef.get(ref)!;
+		return {
+			task,
+			active: false,
+			parentIds: blueprint.parent ? [ids.get(blueprint.parent)!] : [],
+			childIds: definition.blueprints.tasks.filter((candidate) => candidate.parent === ref).map((candidate) => ids.get(candidate.ref)!),
+			dependencyIds: (blueprint.dependsOn ?? []).map((dependency) => ids.get(dependency)!),
+		};
+	});
+	return { nodes, rootIds: nodes.filter((node) => node.parentIds.length === 0).map((node) => node.task.id) };
+}
+
+export function instantiateSkillWorkflow(
+	artifacts: ArtifactStore,
+	skillId: string,
+	input: InstantiateSkillWorkflowInput = {},
+): SkillWorkflowRunResult {
+	const { definition } = requireWorkflowSkill(artifacts, skillId);
+	const arguments_ = resolveSkillArguments(definition, input.arguments);
+	const rendered = renderDefinition(definition, arguments_);
+	const runId = normalizeRunId(skillId, input.runId);
+	const refs = [
+		...rendered.blueprints.docs.map(({ ref }) => ref),
+		...rendered.blueprints.rules.map(({ ref }) => ref),
+		...rendered.blueprints.tasks.map(({ ref }) => ref),
+	];
+	const ids = new Map(refs.map((ref) => [ref, `${runId}-${ref}`]));
+	const taskIds = rendered.blueprints.tasks.map(({ ref }) => ids.get(ref)!);
+	const rootTaskIds = rendered.blueprints.tasks
+		.filter((task) => (task.dependsOn?.length ?? 0) === 0)
+		.map((task) => ids.get(task.ref)!);
+	const relationshipCount = rendered.links.length
+		+ rendered.blueprints.tasks.reduce((count, task) => count + (task.dependsOn?.length ?? 0) + (task.parent ? 2 : 0), 0)
+		+ rootTaskIds.length;
+	if (relationshipCount > TASK_EXECUTION_MAX_EDGES) {
+		throw new Error(`skill workflow run exceeds ${TASK_EXECUTION_MAX_EDGES} relationships`);
+	}
+
+	const atomic = requireAtomicArtifactStore(artifacts);
+	return atomic.atomic(() => {
+		const docs = rendered.blueprints.docs.map((blueprint) => artifacts.create({
+			id: ids.get(blueprint.ref),
+			kind: "doc",
+			title: blueprint.title,
+			body: blueprint.body,
+			subtype: blueprint.subtype,
+			labels: withRunLabel(blueprint.labels, runId),
+			extra: { ...(blueprint.extra ?? {}), skillRun: { id: runId, skillId, ref: blueprint.ref } },
+		}));
+		const rules = rendered.blueprints.rules.map((blueprint) => artifacts.create({
+			id: ids.get(blueprint.ref),
+			kind: "rule",
+			title: blueprint.title,
+			body: blueprint.body,
+			labels: withRunLabel(blueprint.labels, runId),
+			extra: {
+				...(blueprint.extra ?? {}),
+				...(blueprint.condition ? { condition: blueprint.condition } : {}),
+				...(blueprint.action ? { action: blueprint.action } : {}),
+				...(blueprint.severity ? { severity: blueprint.severity } : {}),
+				skillRun: { id: runId, skillId, ref: blueprint.ref },
+				scope: { type: "skill-run", runId, taskIds },
+			},
+		}));
+		const tasks = rendered.blueprints.tasks.map((blueprint) => artifacts.create({
+			id: ids.get(blueprint.ref),
+			kind: "task",
+			title: blueprint.title,
+			body: blueprint.body,
+			labels: withRunLabel(blueprint.labels, runId),
+			extra: { ...(blueprint.extra ?? {}), skillRun: { id: runId, skillId, ref: blueprint.ref } },
+		}));
+
+		for (const blueprint of rendered.blueprints.tasks) {
+			const id = ids.get(blueprint.ref)!;
+			for (const dependency of blueprint.dependsOn ?? []) {
+				artifacts.link({ from: id, relation: "depends_on", to: ids.get(dependency)! });
+			}
+			if (blueprint.parent) {
+				const parentId = ids.get(blueprint.parent)!;
+				artifacts.link({ from: parentId, relation: "contains", to: id });
+				artifacts.link({ from: id, relation: "part_of", to: parentId });
+			}
+		}
+		for (const link of rendered.links) {
+			artifacts.link({ from: ids.get(link.from)!, relation: link.relation, to: ids.get(link.to)! });
+		}
+		for (const rootTaskId of rootTaskIds) artifacts.link({ from: skillId, relation: "triggers", to: rootTaskId });
+
+		return {
+			skillId,
+			runId,
+			arguments: arguments_,
+			created: {
+				docs: docs.map(({ id }) => id),
+				rules: rules.map(({ id }) => id),
+				tasks: tasks.map(({ id }) => id),
+			},
+			rootTaskIds,
+			execution: projectTaskExecution(executionGraph(tasks, rendered, ids)),
+		};
+	});
+}