@danypops/papyrus 0.41.0 → 0.42.1

package/src/ops.ts

@@ -3,36 +3,40 @@
  * Enforces the schema protocol (kinds, statuses, relations) via FK + app validation.
  */
 import { createRequire } from "node:module";
+import { ARTIFACT_TRASH_RETENTION_MS, DEFAULT_STATUS_BY_KIND } from "./constants.ts";
 import type { Db } from "./db.ts";
 import { inTransaction } from "./db.ts";
-import { ARTIFACT_TRASH_RETENTION_MS, DEFAULT_STATUS_BY_KIND } from "./constants.ts";
 import type { Artifact, ArtifactQuery, CreateArtifactInput, UpdateArtifactInput } from "./domain/artifact.ts";
 import type { ArtifactTrashRecord } from "./domain/artifact-trash.ts";
+
 export type { ArtifactTrashRecord } from "./domain/artifact-trash.ts";
-import type { Gate, GateResult, GateRunOptions } from "./domain/gate.ts";
+
 import {
-	normalizeArtifactEventQuery,
-	resolveArtifactEvent,
 	type AppendArtifactEvent,
 	type ArtifactEvent,
 	type ArtifactEventContext,
 	type ArtifactEventPage,
 	type ArtifactEventQuery,
 	type ArtifactEventType,
+	normalizeArtifactEventQuery,
+	resolveArtifactEvent,
 } from "./domain/artifact-event.ts";
+import type { Gate, GateResult, GateRunOptions } from "./domain/gate.ts";
+
 export type { Artifact } from "./domain/artifact.ts";
 export type { Gate, GateResult } from "./domain/gate.ts";
 export type CreateInput = CreateArtifactInput;
+
 import {
 	DEFAULT_GRAPH_DEPTH,
 	DEFAULT_GRAPH_MAX_NODES,
-	MAX_GRAPH_DEPTH,
-	MAX_GRAPH_NODES,
 	GATE_COMMAND_TIMEOUT_MS,
-	GATE_TEST_TIMEOUT_MS,
-	GATE_OUTPUT_LIMIT,
-	GATE_MAX_BUFFER_BYTES,
 	GATE_FILE_MAX_BYTES,
+	GATE_MAX_BUFFER_BYTES,
+	GATE_OUTPUT_LIMIT,
+	GATE_TEST_TIMEOUT_MS,
+	MAX_GRAPH_DEPTH,
+	MAX_GRAPH_NODES,
 } from "./constants.ts";
 
 const require_ = createRequire(import.meta.url);
@@ -58,8 +62,7 @@ function deepMerge(base: unknown, override: unknown): unknown {
 }
 
 function valueAtPath(value: unknown, path: string): unknown {
-	return path.split(".").reduce<unknown>((current, segment) =>
-		isRecord(current) ? current[segment] : undefined, value);
+	return path.split(".").reduce<unknown>((current, segment) => (isRecord(current) ? current[segment] : undefined), value);
 }
 
 function isPresent(value: unknown): boolean {
@@ -75,11 +78,13 @@ function resolveCreateInput(db: Db, input: CreateInput): ResolvedCreateInput {
 
 	const template = getArtifact(db, input.templateId);
 	if (!template) throw new Error(`template "${input.templateId}" not found`);
-	if (template.kind !== "skill" || template.subtype !== "artifact-template") {
+	// A template is any artifact carrying subtype=artifact-template metadata -- its own kind is
+	// irrelevant to its function as a defaults/required carrier for the *target* kind.
+	if (template.subtype !== "artifact-template") {
 		throw new Error(`artifact "${input.templateId}" is not an artifact template`);
 	}
 
-	const targetKind = template.extra["targetKind"];
+	const targetKind = template.extra.targetKind;
 	if (typeof targetKind !== "string" || targetKind.length === 0) {
 		throw new Error(`template "${input.templateId}" has no targetKind`);
 	}
@@ -87,13 +92,13 @@ function resolveCreateInput(db: Db, input: CreateInput): ResolvedCreateInput {
 		throw new Error(`template "${input.templateId}" targets kind "${targetKind}", not "${input.kind}"`);
 	}
 
-	const defaults = isRecord(template.extra["defaults"]) ? template.extra["defaults"] : {};
+	const defaults = isRecord(template.extra.defaults) ? template.extra.defaults : {};
 	const { templateId: _templateId, ...overrides } = input;
 	const merged = deepMerge(defaults, overrides) as CreateInput;
 	merged.kind = targetKind;
 
-	const required = Array.isArray(template.extra["required"])
-		? template.extra["required"].filter((field): field is string => typeof field === "string")
+	const required = Array.isArray(template.extra.required)
+		? template.extra.required.filter((field): field is string => typeof field === "string")
 		: ["title"];
 	for (const field of required) {
 		if (!isPresent(valueAtPath(merged, field))) {
@@ -116,16 +121,16 @@ function defaultStatusFor(db: Db, kind: string): string {
 
 function rowToArtifact(row: Record<string, unknown>): Artifact {
 	return {
-		id: row["id"] as string,
-		kind: row["kind"] as string,
-		title: row["title"] as string,
-		status: row["status"] as string,
-		subtype: (row["subtype"] as string) ?? "",
-		body: (row["body"] as string) ?? "",
-		labels: JSON.parse((row["labels"] as string) ?? "[]"),
-		extra: JSON.parse((row["extra"] as string) ?? "{}"),
-		created_at: row["created_at"] as string,
-		updated_at: row["updated_at"] as string,
+		id: row.id as string,
+		kind: row.kind as string,
+		title: row.title as string,
+		status: row.status as string,
+		subtype: (row.subtype as string) ?? "",
+		body: (row.body as string) ?? "",
+		labels: JSON.parse((row.labels as string) ?? "[]"),
+		extra: JSON.parse((row.extra as string) ?? "{}"),
+		created_at: row.created_at as string,
+		updated_at: row.updated_at as string,
 	};
 }
 
@@ -141,23 +146,25 @@ export function appendArtifactEvent(db: Db, input: AppendArtifactEvent): Artifac
 	const now = new Date().toISOString();
 	let id: number | bigint = 0;
 	inTransaction(db, () => {
-		const result = db.prepare(`
+		const result = db
+			.prepare(`
 			INSERT INTO artifact_events (
 				artifact_id, occurred_at, event_type, actor, source, session_id,
 				from_status, to_status, relation, related_id, event_schema_version
 			) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 1)
-		`).run(
-			event.artifactId,
-			now,
-			event.type,
-			event.actor,
-			event.source,
-			event.sessionId ?? null,
-			event.fromStatus ?? null,
-			event.toStatus ?? null,
-			event.relation ?? null,
-			event.relatedId ?? null,
-		);
+		`)
+			.run(
+				event.artifactId,
+				now,
+				event.type,
+				event.actor,
+				event.source,
+				event.sessionId ?? null,
+				event.fromStatus ?? null,
+				event.toStatus ?? null,
+				event.relation ?? null,
+				event.relatedId ?? null,
+			);
 		id = result.lastInsertRowid;
 	});
 	return {
@@ -213,19 +220,36 @@ export function queryArtifactEvents(db: Db, query: ArtifactEventQuery): Artifact
 	const { artifactId, actor, sessionId, since, limit, direction, cursor } = normalizeArtifactEventQuery(query);
 	const conditions: string[] = [];
 	const params: unknown[] = [];
-	if (artifactId) { conditions.push("(artifact_id = ? OR related_id = ?)"); params.push(artifactId, artifactId); }
-	if (actor) { conditions.push("actor = ?"); params.push(actor); }
-	if (sessionId) { conditions.push("session_id = ?"); params.push(sessionId); }
-	if (since) { conditions.push("occurred_at >= ?"); params.push(since); }
+	if (artifactId) {
+		conditions.push("(artifact_id = ? OR related_id = ?)");
+		params.push(artifactId, artifactId);
+	}
+	if (actor) {
+		conditions.push("actor = ?");
+		params.push(actor);
+	}
+	if (sessionId) {
+		conditions.push("session_id = ?");
+		params.push(sessionId);
+	}
+	if (since) {
+		conditions.push("occurred_at >= ?");
+		params.push(since);
+	}
 	const comparator = direction === "desc" ? "<" : ">";
-	if (cursor !== undefined) { conditions.push(`id ${comparator} ?`); params.push(cursor); }
+	if (cursor !== undefined) {
+		conditions.push(`id ${comparator} ?`);
+		params.push(cursor);
+	}
 	const order = direction === "desc" ? "DESC" : "ASC";
-	const rows = db.prepare(`
+	const rows = db
+		.prepare(`
 		SELECT * FROM artifact_events
 		WHERE ${conditions.join(" AND ")}
 		ORDER BY occurred_at ${order}, id ${order}
 		LIMIT ?
-	`).all(...params, limit + 1) as ArtifactEventRow[];
+	`)
+		.all(...params, limit + 1) as ArtifactEventRow[];
 	const hasMore = rows.length > limit;
 	const events = rows.slice(0, limit).map(mapArtifactEventRow);
 	return { events, ...(hasMore ? { nextCursor: events.at(-1)!.id } : {}) };
@@ -260,7 +284,11 @@ export function getArtifact(db: Db, id: string, opts?: { tree?: boolean; depth?:
 		const depthLimit = Math.min(MAX_GRAPH_DEPTH, Math.max(0, Math.floor(opts.depth ?? DEFAULT_GRAPH_DEPTH)));
 		const nodeLimit = Math.min(MAX_GRAPH_NODES, Math.max(1, Math.floor(opts.maxNodes ?? DEFAULT_GRAPH_MAX_NODES)));
 		const queue: Array<{ id: string; depth: number }> = [{ id, depth: 0 }];
-		const allEdges = db.prepare('SELECT from_id AS "from", relation, to_id AS "to" FROM edges').all() as { from: string; relation: string; to: string }[];
+		const allEdges = db.prepare('SELECT from_id AS "from", relation, to_id AS "to" FROM edges').all() as {
+			from: string;
+			relation: string;
+			to: string;
+		}[];
 		const reachable = new Set<string>([id]);
 		const adj = new Map<string, { from: string; relation: string; to: string }[]>();
 		for (const edge of allEdges) {
@@ -295,16 +323,31 @@ export function queryArtifacts(db: Db, filter: ArtifactQuery): Artifact[] {
 		conditions.push(`id IN (${filter.ids.map(() => "?").join(", ")})`);
 		params.push(...filter.ids);
 	}
-	if (filter.kind) { conditions.push("kind = ?"); params.push(filter.kind); }
-	if (filter.status) { conditions.push("status = ?"); params.push(filter.status); }
+	if (filter.kind) {
+		conditions.push("kind = ?");
+		params.push(filter.kind);
+	}
+	if (filter.status) {
+		conditions.push("status = ?");
+		params.push(filter.status);
+	}
 	if (filter.statuses) {
 		if (filter.statuses.length === 0) return [];
 		conditions.push(`status IN (${filter.statuses.map(() => "?").join(", ")})`);
 		params.push(...filter.statuses);
 	}
-	if (filter.subtype) { conditions.push("subtype = ?"); params.push(filter.subtype); }
-	if (filter.excludeSubtype) { conditions.push("subtype != ?"); params.push(filter.excludeSubtype); }
-	if (filter.text) { conditions.push("(title LIKE ? OR body LIKE ?)"); params.push(`%${filter.text}%`, `%${filter.text}%`); }
+	if (filter.subtype) {
+		conditions.push("subtype = ?");
+		params.push(filter.subtype);
+	}
+	if (filter.excludeSubtype) {
+		conditions.push("subtype != ?");
+		params.push(filter.excludeSubtype);
+	}
+	if (filter.text) {
+		conditions.push("(title LIKE ? OR body LIKE ?)");
+		params.push(`%${filter.text}%`, `%${filter.text}%`);
+	}
 	for (const label of filter.labels ?? []) {
 		conditions.push("EXISTS (SELECT 1 FROM json_each(artifacts.labels) WHERE value = ?)");
 		params.push(label);
@@ -314,7 +357,7 @@ export function queryArtifacts(db: Db, filter: ArtifactQuery): Artifact[] {
 		conditions.push("json_extract(extra, ?) = ?");
 		params.push(`$.${key}`, value);
 	}
-	if (conditions.length) sql += " WHERE " + conditions.join(" AND ");
+	if (conditions.length) sql += ` WHERE ${conditions.join(" AND ")}`;
 	sql += " ORDER BY updated_at DESC";
 	if (filter.limit !== undefined) {
 		if (!Number.isInteger(filter.limit) || filter.limit < 1) throw new Error("artifact query limit must be a positive integer");
@@ -327,20 +370,25 @@ export function queryArtifacts(db: Db, filter: ArtifactQuery): Artifact[] {
 
 function rowToTrashRecord(row: Record<string, unknown>): ArtifactTrashRecord {
 	return {
-		artifactId: row["artifact_id"] as string,
-		trashedAt: row["trashed_at"] as string,
-		purgeAfter: row["purge_after"] as string,
-		...(row["reason"] == null ? {} : { reason: row["reason"] as string }),
+		artifactId: row.artifact_id as string,
+		trashedAt: row.trashed_at as string,
+		purgeAfter: row.purge_after as string,
+		...(row.reason == null ? {} : { reason: row.reason as string }),
 	};
 }
 
 export function getArtifactTrash(db: Db, id: string): ArtifactTrashRecord | null {
-	const row = db.prepare("SELECT artifact_id, trashed_at, purge_after, reason FROM artifact_trash WHERE artifact_id = ?").get(id) as Record<string, unknown> | null;
+	const row = db.prepare("SELECT artifact_id, trashed_at, purge_after, reason FROM artifact_trash WHERE artifact_id = ?").get(id) as Record<
+		string,
+		unknown
+	> | null;
 	return row ? rowToTrashRecord(row) : null;
 }
 
 export function listArtifactTrash(db: Db): ArtifactTrashRecord[] {
-	const rows = db.prepare("SELECT artifact_id, trashed_at, purge_after, reason FROM artifact_trash ORDER BY purge_after ASC").all() as Record<string, unknown>[];
+	const rows = db
+		.prepare("SELECT artifact_id, trashed_at, purge_after, reason FROM artifact_trash ORDER BY purge_after ASC")
+		.all() as Record<string, unknown>[];
 	return rows.map(rowToTrashRecord);
 }
 
@@ -357,11 +405,16 @@ export function listArtifactTrash(db: Db): ArtifactTrashRecord[] {
  * caller is not necessarily looking at right now. No other kind has an analogous "currently
  * in use" signal to check.
  */
-export function trashArtifact(db: Db, id: string, options?: { reason?: string; now?: () => string; context?: ArtifactEventContext }): ArtifactTrashRecord {
+export function trashArtifact(
+	db: Db,
+	id: string,
+	options?: { reason?: string; now?: () => string; context?: ArtifactEventContext },
+): ArtifactTrashRecord {
 	const artifact = getArtifact(db, id);
 	if (!artifact) throw new Error(`artifact "${id}" not found`);
 	const focusedScope = db.prepare("SELECT scope FROM task_focus WHERE task_id = ? LIMIT 1").get(id) as { scope: string } | null;
-	if (focusedScope) throw new Error(`artifact "${id}" is the active Task Focus in scope "${focusedScope.scope}"; clear focus before removing it`);
+	if (focusedScope)
+		throw new Error(`artifact "${id}" is the active Task Focus in scope "${focusedScope.scope}"; clear focus before removing it`);
 	const now = options?.now ?? (() => new Date().toISOString());
 	const trashedAt = now();
 	const purgeAfter = new Date(new Date(trashedAt).getTime() + ARTIFACT_TRASH_RETENTION_MS).toISOString();
@@ -407,7 +460,9 @@ export function restoreArtifact(db: Db, id: string, context?: ArtifactEventConte
  */
 export function purgeDueArtifacts(db: Db, now: () => string = () => new Date().toISOString()): number {
 	const nowIso = now();
-	const due = (db.prepare("SELECT artifact_id FROM artifact_trash WHERE purge_after <= ?").all(nowIso) as Array<{ artifact_id: string }>).map((row) => row.artifact_id);
+	const due = (
+		db.prepare("SELECT artifact_id FROM artifact_trash WHERE purge_after <= ?").all(nowIso) as Array<{ artifact_id: string }>
+	).map((row) => row.artifact_id);
 	let purged = 0;
 	for (const id of due) {
 		inTransaction(db, () => {
@@ -500,7 +555,10 @@ export function updateExtra(db: Db, id: string, extra: Record<string, unknown>,
 
 /** Active rules with inject metadata — for before_agent_start system prompt injection. */
 export function injectableRules(db: Db): Array<{ id: string; title: string; body: string; extra: Record<string, unknown> }> {
-	const rows = db.prepare("SELECT * FROM artifacts WHERE kind = 'rule' AND status = 'active' ORDER BY updated_at DESC").all() as Record<string, unknown>[];
+	const rows = db.prepare("SELECT * FROM artifacts WHERE kind = 'rule' AND status = 'active' ORDER BY updated_at DESC").all() as Record<
+		string,
+		unknown
+	>[];
 	return rows.map((row) => {
 		const art = rowToArtifact(row);
 		return { id: art.id, title: art.title, body: art.body, extra: art.extra };
@@ -536,15 +594,19 @@ function runProcessGateSync(gate: Gate, cwd?: string): GateResult {
 	if (result.error) return { gate, passed: false, output: result.error.message.slice(0, GATE_OUTPUT_LIMIT) };
 	const combined = `${result.stdout ?? ""}${result.stderr ?? ""}`.trim();
 	const passed = result.status === 0 && (gate.expect ? combined.includes(gate.expect) : true);
-	return { gate, passed, output: combined.slice(0, GATE_OUTPUT_LIMIT) || (result.status === 0 ? "ok" : `command exited with code ${result.status}`) };
+	return {
+		gate,
+		passed,
+		output: combined.slice(0, GATE_OUTPUT_LIMIT) || (result.status === 0 ? "ok" : `command exited with code ${result.status}`),
+	};
 }
 
 export function runGates(db: Db, artifactId: string, options: GateRunOptions = {}): GateResult[] {
 	const art = getArtifact(db, artifactId);
 	if (!art) throw new Error("artifact not found");
-	const gates = (art.extra["gates"] as Gate[]) ?? [];
+	const gates = (art.extra.gates as Gate[]) ?? [];
 	const cwd = options.cwd;
-	return gates.map((gate) => (gate.type === "command" || gate.type === "test") ? runProcessGateSync(gate, cwd) : runNonProcessGate(gate));
+	return gates.map((gate) => (gate.type === "command" || gate.type === "test" ? runProcessGateSync(gate, cwd) : runNonProcessGate(gate)));
 }
 
 /**
@@ -558,7 +620,11 @@ export function runGates(db: Db, artifactId: string, options: GateRunOptions = {
  *      indefinitely after Papyrus considers the gate "timed out". Spawning detached (its own
  *      process group) and killing the negated pid on our own timer reaches the whole tree.
  */
-function executeGateCommand(command: string, timeout: number, cwd?: string): Promise<{ passed: boolean; output: string; matchable: string }> {
+function executeGateCommand(
+	command: string,
+	timeout: number,
+	cwd?: string,
+): Promise<{ passed: boolean; output: string; matchable: string }> {
 	// `spawn(..., { shell: true, detached: true })` instead of the `exec()` convenience wrapper:
 	// `detached` (needed to make the shell the leader of its own process group, so the negated pid
 	// below reaches every descendant, not just the shell) is not part of Node's `exec()`/
@@ -634,7 +700,7 @@ function runNonProcessGate(gate: Gate): GateResult {
 export async function runGatesAsync(db: Db, artifactId: string, options: GateRunOptions = {}): Promise<GateResult[]> {
 	const art = getArtifact(db, artifactId);
 	if (!art) throw new Error("artifact not found");
-	const gates = (art.extra["gates"] as Gate[]) ?? [];
+	const gates = (art.extra.gates as Gate[]) ?? [];
 	const results: GateResult[] = [];
 	for (const gate of gates) {
 		const remainingMs = options.deadlineMs === undefined ? undefined : options.deadlineMs - Date.now();
@@ -657,4 +723,3 @@ export async function runGatesAsync(db: Db, artifactId: string, options: GateRun
 	}
 	return results;
 }
-

package/src/playbook-definition.ts

@@ -1,19 +1,22 @@
 /**
  * playbook-definition.ts — compiles a Playbook's own steps/trigger/tools/arguments, plus its
- * `contains` (nested) and `depends_on` (prerequisite) composition tree, into an in-memory
- * SkillDefinition. This is the "recycle Papyrus Skills -> Playbooks" half of the redesign:
- * rather than a second graph-materialization engine, a Playbook becomes prose that compiles
- * down to the exact blueprint shape workflow Skills already use, then hands off to
- * workflow-execution.ts's shared materializeWorkflowDefinition for the actual Task creation.
+ * `contains` (nested) and `depends_on` (prerequisite) whole-artifact composition tree, into
+ * an in-memory BlueprintDefinition. Rather than a second graph-materialization engine, a
+ * Playbook becomes a definition that compiles down to the exact Blueprint shape a
+ * workflow-definition target already uses, then hands off to workflow-execution.ts's shared
+ * materializeWorkflowDefinition for the actual artifact creation.
  *
  * One task blueprint per playbook-node root (a container, never itself gated) plus one per
  * step (chained by sequential dependsOn); `contains`-linked playbooks nest their own root
  * under the parent root and continue the parent's own step chain ("run as part of this one",
  * after the parent's own steps); `depends_on`-linked playbooks compile as independent
- * subtrees whose tails gate this node's first step ("complete this FIRST"). No SkillCallBlueprint
- * indirection is used -- everything is inlined into one flat definition, since a Playbook's
- * composition tree is fully known and owned at compile time, unlike a workflow Skill's nested
- * pipeline step (which references another SKILL by id, resolved and executed independently).
+ * subtrees whose tails gate this node's first step ("complete this FIRST"). That whole-artifact
+ * composition tree is fully known and owned at compile time and is always inlined directly
+ * (no CallBlueprint indirection). A step-level `call` (one step within a single playbook
+ * node, not the composition tree above) is the one place this compiler DOES emit a
+ * CallBlueprint -- a finer-grained, in-blueprint nested-run reference resolved and executed
+ * independently by workflow-execution.ts, exactly like a workflow-definition target's own
+ * nested pipeline step, since its target's own definition is not knowable at this compile time.
  */
 import {
 	PLAYBOOK_INVOCATION_MAX_CALL_DEPTH,
@@ -21,9 +24,16 @@ import {
 	PLAYBOOK_INVOCATION_MAX_LINKED_ARTIFACTS,
 } from "./constants.ts";
 import type { Artifact } from "./domain/artifact.ts";
-import type { SkillDefinition, SkillInputDefinition, SkillTaskBlueprint } from "./domain/skill-definition.ts";
-import { validateSkillDefinition } from "./domain/skill-definition.ts";
-import type { PlaybookArgument } from "./domain-services.ts";
+import type {
+	BlueprintDefinition,
+	BlueprintInputDefinition,
+	CallBlueprint,
+	DocBlueprint,
+	RuleBlueprint,
+	TaskBlueprint,
+} from "./domain/blueprint-definition.ts";
+import { validateBlueprintDefinition } from "./domain/blueprint-definition.ts";
+import type { PlaybookArgument, PlaybookStep } from "./domain-services.ts";
 import type { ArtifactStore } from "./ports/artifact-store.ts";
 
 /** A non-composing edge touching a playbook node, to be mirrored onto that node's generated root task once real task ids exist -- e.g. a Rule `gates` this playbook, or this playbook `references`/`documents` a Doc. Direction is preserved exactly: `from`/`to` name whichever side is NOT the playbook, and `ownerIsFrom` says which side the playbook (now the generated root task) occupies. */
@@ -36,7 +46,7 @@ export interface PlaybookExternalLink {
 }
 
 export interface CompiledPlaybook {
-	definition: SkillDefinition;
+	definition: BlueprintDefinition;
 	/** The very first real leaf task in the whole tree's reading order -- what a caller should focus once materialized. */
 	entryRef: string;
 	externalLinks: PlaybookExternalLink[];
@@ -56,21 +66,21 @@ function requirePlaybook(artifacts: ArtifactStore, id: string): Artifact {
 	return playbook;
 }
 
-function stepsOf(playbook: Artifact): string[] {
-	return Array.isArray(playbook.extra["steps"]) ? playbook.extra["steps"].filter((step): step is string => typeof step === "string") : [];
+function stepsOf(playbook: Artifact): PlaybookStep[] {
+	return Array.isArray(playbook.extra.steps) ? (playbook.extra.steps as PlaybookStep[]) : [];
 }
 
 function toolsOf(playbook: Artifact): string[] {
-	return Array.isArray(playbook.extra["tools"]) ? playbook.extra["tools"].filter((tool): tool is string => typeof tool === "string") : [];
+	return Array.isArray(playbook.extra.tools) ? playbook.extra.tools.filter((tool): tool is string => typeof tool === "string") : [];
 }
 
 function argumentsOf(playbook: Artifact): PlaybookArgument[] {
-	return Array.isArray(playbook.extra["arguments"]) ? (playbook.extra["arguments"] as PlaybookArgument[]) : [];
+	return Array.isArray(playbook.extra.arguments) ? (playbook.extra.arguments as PlaybookArgument[]) : [];
 }
 
 /** The generated container task's own body -- purpose and context only. Steps are separate child tasks, so they are not re-listed here (that was the old text-dump shape). */
 function rootTaskBody(playbook: Artifact): string {
-	const trigger = typeof playbook.extra["trigger"] === "string" ? playbook.extra["trigger"] : "manual invocation";
+	const trigger = typeof playbook.extra.trigger === "string" ? playbook.extra.trigger : "manual invocation";
 	const tools = toolsOf(playbook);
 	return [
 		`Playbook "${playbook.title}".`,
@@ -87,8 +97,11 @@ function stepTitle(step: string): string {
 }
 
 interface CompileContext {
-	tasks: SkillTaskBlueprint[];
-	inputs: Record<string, SkillInputDefinition>;
+	docs: DocBlueprint[];
+	rules: RuleBlueprint[];
+	tasks: TaskBlueprint[];
+	skills: CallBlueprint[];
+	inputs: Record<string, BlueprintInputDefinition>;
 	externalLinks: PlaybookExternalLink[];
 	refCounter: { n: number };
 }
@@ -101,9 +114,20 @@ interface CompileNodeResult {
 	tailRef: string;
 }
 
-function mergeArgument(inputs: Record<string, SkillInputDefinition>, argument: PlaybookArgument): void {
+/** A composition tree can declare the same argument name from more than one node (e.g. two prerequisite playbooks both need a `target`); required OR-accumulates the same way it always did, but the type must agree everywhere -- silently picking one node's type over another's would compile a definition whose placeholder substitution disagrees with what one of the two authors actually declared. */
+function mergeArgument(inputs: Record<string, BlueprintInputDefinition>, argument: PlaybookArgument): void {
 	const existing = inputs[argument.name];
-	inputs[argument.name] = { type: "string", required: (existing?.required ?? false) || argument.required };
+	if (existing && existing.type !== argument.type) {
+		throw new Error(
+			`playbook composition declares conflicting types for argument "${argument.name}" (${existing.type} vs ${argument.type})`,
+		);
+	}
+	inputs[argument.name] = {
+		type: argument.type,
+		required: (existing?.required ?? false) || argument.required,
+		...(argument.enum ? { enum: argument.enum } : {}),
+		...(argument.default !== undefined ? { default: argument.default } : {}),
+	};
 }
 
 function compileNode(
@@ -116,28 +140,44 @@ function compileNode(
 	incomingPrecedingRefs: string[],
 ): CompileNodeResult {
 	if (ancestorIds.has(playbookId)) throw new Error(`playbook composition cycle includes "${playbookId}"`);
-	if (depth > PLAYBOOK_INVOCATION_MAX_CALL_DEPTH) throw new Error(`playbook composition exceeds ${PLAYBOOK_INVOCATION_MAX_CALL_DEPTH} levels`);
+	if (depth > PLAYBOOK_INVOCATION_MAX_CALL_DEPTH)
+		throw new Error(`playbook composition exceeds ${PLAYBOOK_INVOCATION_MAX_CALL_DEPTH} levels`);
 	const nextAncestors = new Set([...ancestorIds, playbookId]);
 
 	const playbook = requirePlaybook(artifacts, playbookId);
 	for (const argument of argumentsOf(playbook)) mergeArgument(ctx.inputs, argument);
 
 	const rootRef = `pb${ctx.refCounter.n++}`;
-	const rootBlueprint: SkillTaskBlueprint = { ref: rootRef, title: playbook.title, body: rootTaskBody(playbook), ...(parentRef ? { parent: parentRef } : {}) };
+	const rootBlueprint: TaskBlueprint = {
+		ref: rootRef,
+		title: playbook.title,
+		body: rootTaskBody(playbook),
+		...(parentRef ? { parent: parentRef } : {}),
+	};
 	ctx.tasks.push(rootBlueprint);
-	if (ctx.tasks.length > PLAYBOOK_INVOCATION_MAX_CREATED_TASKS) throw new Error(`playbook invocation exceeds ${PLAYBOOK_INVOCATION_MAX_CREATED_TASKS} tasks`);
+	if (ctx.tasks.length > PLAYBOOK_INVOCATION_MAX_CREATED_TASKS)
+		throw new Error(`playbook invocation exceeds ${PLAYBOOK_INVOCATION_MAX_CREATED_TASKS} tasks`);
 
 	const edges = artifacts.relationships({ artifactIds: [playbookId] }).slice(0, PLAYBOOK_INVOCATION_MAX_LINKED_ARTIFACTS);
-	const composablePlaybookIds = nonTrashedPlaybookIds(artifacts, edges.filter((edge) => edge.from === playbookId).map((edge) => edge.to));
-	const prerequisiteIds = edges.filter((edge) => edge.from === playbookId && edge.relation === "depends_on").map((edge) => edge.to)
+	const composablePlaybookIds = nonTrashedPlaybookIds(
+		artifacts,
+		edges.filter((edge) => edge.from === playbookId).map((edge) => edge.to),
+	);
+	const prerequisiteIds = edges
+		.filter((edge) => edge.from === playbookId && edge.relation === "depends_on")
+		.map((edge) => edge.to)
 		.filter((id) => composablePlaybookIds.has(id));
-	const nestedIds = edges.filter((edge) => edge.from === playbookId && edge.relation === "contains").map((edge) => edge.to)
+	const nestedIds = edges
+		.filter((edge) => edge.from === playbookId && edge.relation === "contains")
+		.map((edge) => edge.to)
 		.filter((id) => composablePlaybookIds.has(id));
 	for (const edge of edges) {
-		const isComposingFrom = edge.from === playbookId && (edge.relation === "contains" || edge.relation === "depends_on") && composablePlaybookIds.has(edge.to);
+		const isComposingFrom =
+			edge.from === playbookId && (edge.relation === "contains" || edge.relation === "depends_on") && composablePlaybookIds.has(edge.to);
 		if (isComposingFrom) continue;
 		if (edge.from === playbookId) ctx.externalLinks.push({ rootRef, relation: edge.relation, otherArtifactId: edge.to, ownerIsFrom: true });
-		else if (edge.to === playbookId) ctx.externalLinks.push({ rootRef, relation: edge.relation, otherArtifactId: edge.from, ownerIsFrom: false });
+		else if (edge.to === playbookId)
+			ctx.externalLinks.push({ rootRef, relation: edge.relation, otherArtifactId: edge.from, ownerIsFrom: false });
 	}
 
 	const prerequisiteTailRefs: string[] = [];
@@ -148,15 +188,60 @@ function compileNode(
 		if (headRef === undefined) headRef = result.headRef;
 	}
 
+	// Doc/rule steps are not gated tasks (DocBlueprint/RuleBlueprint have no dependsOn/parent of
+	// their own -- workflow-execution.ts always creates them unconditionally alongside the run)
+	// -- they do not touch cursorPrecedingRefs/headRef/tailRef at all. A task or call step DOES
+	// occupy a position in the sequential chain, exactly as a plain-string step always did.
 	let cursorPrecedingRefs = [...incomingPrecedingRefs, ...prerequisiteTailRefs];
 	let tailRef = rootRef;
 	for (const [index, step] of stepsOf(playbook).entries()) {
-		const stepRef = `${rootRef}-s${index}`;
-		ctx.tasks.push({ ref: stepRef, title: stepTitle(step), body: step, parent: rootRef, dependsOn: cursorPrecedingRefs });
-		if (ctx.tasks.length > PLAYBOOK_INVOCATION_MAX_CREATED_TASKS) throw new Error(`playbook invocation exceeds ${PLAYBOOK_INVOCATION_MAX_CREATED_TASKS} tasks`);
-		if (headRef === undefined) headRef = stepRef;
-		cursorPrecedingRefs = [stepRef];
-		tailRef = stepRef;
+		if (typeof step === "string" || step.kind === "task") {
+			const body = typeof step === "string" ? step : step.body;
+			const title = typeof step === "string" ? stepTitle(step) : (step.title ?? stepTitle(body));
+			const stepRef = `${rootRef}-s${index}`;
+			ctx.tasks.push({ ref: stepRef, title, body, parent: rootRef, dependsOn: cursorPrecedingRefs });
+			if (ctx.tasks.length > PLAYBOOK_INVOCATION_MAX_CREATED_TASKS)
+				throw new Error(`playbook invocation exceeds ${PLAYBOOK_INVOCATION_MAX_CREATED_TASKS} tasks`);
+			if (headRef === undefined) headRef = stepRef;
+			cursorPrecedingRefs = [stepRef];
+			tailRef = stepRef;
+		} else if (step.kind === "doc") {
+			const stepRef = `${rootRef}-d${index}`;
+			ctx.docs.push({
+				ref: stepRef,
+				title: step.title,
+				...(step.body ? { body: step.body } : {}),
+				...(step.subtype ? { subtype: step.subtype } : {}),
+				...(step.labels ? { labels: step.labels } : {}),
+			});
+		} else if (step.kind === "rule") {
+			const stepRef = `${rootRef}-r${index}`;
+			ctx.rules.push({
+				ref: stepRef,
+				title: step.title,
+				...(step.body ? { body: step.body } : {}),
+				...(step.condition ? { condition: step.condition } : {}),
+				...(step.action ? { action: step.action } : {}),
+				...(step.severity ? { severity: step.severity } : {}),
+				...(step.labels ? { labels: step.labels } : {}),
+			});
+		} else {
+			// kind === "call": nests another Playbook's (or a workflow-definition target's) run as
+			// a pipeline step -- shares the same dependsOn chain as a task step, resolved
+			// polymorphically at execution time by workflow-execution.ts based on the target's kind.
+			const stepRef = `${rootRef}-c${index}`;
+			ctx.skills.push({
+				ref: stepRef,
+				title: step.title,
+				targetId: step.playbookId,
+				...(step.arguments ? { arguments: step.arguments } : {}),
+				parent: rootRef,
+				dependsOn: cursorPrecedingRefs,
+			});
+			if (headRef === undefined) headRef = stepRef;
+			cursorPrecedingRefs = [stepRef];
+			tailRef = stepRef;
+		}
 	}
 
 	for (const nestedId of nestedIds) {
@@ -172,12 +257,12 @@ function compileNode(
 
 /** Pure and read-only: creates no artifacts. Cycle/depth-bounded exactly like playbookInvocation's own traversal, but a composition cycle here is a hard error (real Tasks would be created, unlike a text render degrading to a marker). */
 export function compilePlaybookDefinition(artifacts: ArtifactStore, playbookId: string): CompiledPlaybook {
-	const ctx: CompileContext = { tasks: [], inputs: {}, externalLinks: [], refCounter: { n: 0 } };
+	const ctx: CompileContext = { docs: [], rules: [], tasks: [], skills: [], inputs: {}, externalLinks: [], refCounter: { n: 0 } };
 	const { headRef } = compileNode(artifacts, playbookId, ctx, new Set(), 0, undefined, []);
-	const definition = validateSkillDefinition({
+	const definition = validateBlueprintDefinition({
 		version: 1,
 		inputs: ctx.inputs,
-		blueprints: { docs: [], rules: [], tasks: ctx.tasks, skills: [] },
+		blueprints: { docs: ctx.docs, rules: ctx.rules, tasks: ctx.tasks, skills: ctx.skills },
 		links: [],
 	});
 	return { definition, entryRef: headRef, externalLinks: ctx.externalLinks };