@danypops/papyrus 0.40.0 → 0.42.0

package/src/domain-services.ts

@@ -9,14 +9,19 @@ import {
 	PLAYBOOK_ARGUMENT_NAME_MAX_LENGTH,
 	PLAYBOOK_INVOCATION_MAX_CALL_DEPTH,
 	PLAYBOOK_INVOCATION_MAX_LINKED_ARTIFACTS,
+	PLAYBOOK_MAX_STEPS,
 	RULE_TEXT_HARD_LIMIT_CHARACTERS,
-	SKILL_INVOCATION_MAX_CALL_DEPTH,
-	SKILL_INVOCATION_MAX_LINKED_ARTIFACTS,
+	SKILL_MAX_ENUM_VALUES,
 } from "./constants.ts";
 import { requireLocallyOwnedContent, type Artifact, type CreateArtifactInput } from "./domain/artifact.ts";
 import type { ArtifactEventContext } from "./domain/artifact-event.ts";
 import { normalizeProjectRoot } from "./domain/task-scope.ts";
-import { validateSkillDefinition } from "./domain/skill-definition.ts";
+import {
+	BLUEPRINT_INPUT_TYPES,
+	validateArgumentValue,
+	type BlueprintArgumentValue,
+	type BlueprintInputType,
+} from "./domain/blueprint-definition.ts";
 import type { ArtifactStore } from "./ports/artifact-store.ts";
 import type { ArtifactScopeStore } from "./ports/artifact-scope-store.ts";
 import { NOTE_SUBTYPE } from "./note-service.ts";
@@ -61,7 +66,7 @@ export interface ListFilter {
 }
 
 /**
- * Shared by listDocuments/listRules/listSkills: when filter.projectRoot is given, resolve
+ * Shared by listDocuments/listRules/listPlaybooks: when filter.projectRoot is given, resolve
  * via ArtifactScopeStore first and post-filter by kind/status/text (mirrors Tasks.list's
  * established scoped-listing shape); otherwise fall back to the existing unscoped query
  * path unchanged, so every caller that predates project scoping keeps working exactly as
@@ -85,7 +90,7 @@ function listScoped(artifacts: ArtifactStore, scopes: ArtifactScopeStore, kind:
 		.slice(0, limit);
 }
 
-/** Shared by assignDocumentProject/assignRuleProject/assignSkillProject. */
+/** Shared by assignDocumentProject/assignRuleProject/assignPlaybookProject. */
 function assignArtifactProject(artifacts: ArtifactStore, scopes: ArtifactScopeStore, id: string, kind: string, projectRoot: string | undefined): Artifact {
 	requireKind(artifacts, id, kind);
 	scopes.assign(id, projectRoot === undefined ? undefined : normalizeProjectRoot(projectRoot), projectRoot === undefined ? "unscoped" : "explicit");
@@ -287,14 +292,21 @@ export function assignRuleProject(artifacts: ArtifactStore, scopes: ArtifactScop
 	return assignArtifactProject(artifacts, scopes, id, "rule", projectRoot);
 }
 
-/** Global rules always apply; scoped workflow rules apply only while their run owns active focus. */
+/**
+ * Global rules always apply; scoped workflow-run rules apply only while their run owns active
+ * focus. Both a workflow-definition target's own run scope ("skill-run", written by
+ * workflow-execution.ts's runWorkflowSteps for that target kind) and a Playbook's own run scope
+ * ("playbook-run", same call for a Playbook target) are recognized -- confirmed live that only
+ * "skill-run" was ever checked here, silently breaking Playbook-run-scoped rule injection since
+ * Playbook gained its own doc/rule structured steps.
+ */
 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;
+		if ((value["type"] !== "skill-run" && value["type"] !== "playbook-run") || !Array.isArray(value["taskIds"])) return false;
 		return activeTaskId !== undefined && value["taskIds"].some((id) => id === activeTaskId);
 	});
 }
@@ -344,191 +356,11 @@ export function gateTaskWithRule(artifacts: ArtifactStore, ruleId: string, taskI
 	return showRule(artifacts, ruleId);
 }
 
-export interface CreateSkillInput {
-	title: string;
-	body?: string;
-	trigger?: string;
-	steps?: string[];
-	tools?: string[];
-	definition?: unknown;
-	labels?: string[];
-	extra?: Record<string, unknown>;
-	projectRoot?: string;
-}
-
-export interface CreateArtifactTemplateInput {
-	title: string;
-	targetKind: string;
-	defaults?: Record<string, unknown>;
-	required?: string[];
-	body?: string;
-	labels?: string[];
-	projectRoot?: string;
-}
-
-export type SkillTransition = "enable" | "disable";
-
-export function createSkill(artifacts: ArtifactStore, scopes: ArtifactScopeStore, input: CreateSkillInput, authority: AuthorityRegistry, context?: ArtifactEventContext): 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);
-	if (definition?.blueprints.docs.some((document) => document.subtype === NOTE_SUBTYPE)) requireNotesFacade(authority, "skills");
-	const projectRoot = input.projectRoot === undefined ? undefined : normalizeProjectRoot(input.projectRoot);
-	const skill = artifacts.create({
-		kind: "skill",
-		status: "active", // explicit; see createDocument for why defaultStatusFor is not trusted here
-		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 } : {}),
-		},
-	}, context);
-	scopes.assign(skill.id, projectRoot, projectRoot === undefined ? "unscoped" : "explicit");
-	return skill;
-}
-
-export function createArtifactTemplate(artifacts: ArtifactStore, scopes: ArtifactScopeStore, input: CreateArtifactTemplateInput, authority: AuthorityRegistry, context?: ArtifactEventContext): Artifact {
-	if (input.targetKind === "doc" && input.defaults?.["subtype"] === NOTE_SUBTYPE) requireNotesFacade(authority, "skills");
-	const projectRoot = input.projectRoot === undefined ? undefined : normalizeProjectRoot(input.projectRoot);
-	const template = artifacts.create({
-		kind: "skill",
-		status: "active", // explicit; see createDocument for why defaultStatusFor is not trusted here
-		subtype: "artifact-template",
-		title: input.title,
-		body: input.body,
-		labels: input.labels,
-		extra: {
-			targetKind: input.targetKind,
-			defaults: input.defaults ?? {},
-			required: input.required ?? ["title"],
-		},
-	}, context);
-	scopes.assign(template.id, projectRoot, projectRoot === undefined ? "unscoped" : "explicit");
-	return template;
-}
-
-export function instantiateTemplate(artifacts: ArtifactStore, templateId: string, input: CreateArtifactInput, authority: AuthorityRegistry, context?: ArtifactEventContext): Artifact {
-	if (rejectsNoteTemplate(artifacts, templateId, input.subtype)) requireNotesFacade(authority, "skills");
-	return artifacts.create({ ...input, templateId }, context);
-}
-
-export function listSkills(artifacts: ArtifactStore, scopes: ArtifactScopeStore, filter: ListFilter): Artifact[] {
-	return listScoped(artifacts, scopes, "skill", filter);
-}
-
-export function assignSkillProject(artifacts: ArtifactStore, scopes: ArtifactScopeStore, id: string, projectRoot: string | undefined): Artifact {
-	return assignArtifactProject(artifacts, scopes, id, "skill", projectRoot);
-}
-
-export function showSkill(artifacts: ArtifactStore, id: string): Artifact {
-	requireKind(artifacts, id, "skill");
-	return artifacts.get(id, { tree: true })!;
-}
-
-export type UpdateSkillInput = UpdateContentInput;
-
-export function updateSkill(artifacts: ArtifactStore, id: string, input: UpdateSkillInput, context?: ArtifactEventContext): Artifact {
-	requireContentUpdateFields(input);
-	assertTitleBounds(input.title);
-	assertBodyBounds(input.body);
-	assertLabelsBounds(input.labels);
-	const skill = requireLocallyOwnedContent(requireKind(artifacts, id, "skill"));
-	const updated = artifacts.updateContent(skill.id, input, context);
-	if (!updated) throw new Error(`skill "${id}" not found`);
-	return updated;
-}
-
-function skillInvocationBody(skill: Artifact): string {
-	if (skill.subtype === "artifact-template") {
-		return `Create an artifact using Papyrus template "${skill.title}".\ntemplate_name: ${skill.title}\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}".`,
-			`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") : [];
-	return [
-		`Apply Papyrus skill "${skill.title}".`,
-		`Trigger: ${trigger}`,
-		...(skill.body ? [`Context: ${skill.body}`] : []),
-		...(steps.length ? ["Steps:", ...steps.map((step, index) => `${index + 1}. ${step}`)] : []),
-		...(tools.length ? [`Tools: ${tools.join(", ")}`] : []),
-	].join("\n");
-}
-
 /**
- * Skills are special: invoking one queries Papyrus for the skill's real outgoing graph edges
- * -- not just its own static body/extra fields -- so a Skill linked to existing Tasks, Rules,
- * or Docs surfaces that linked context on invocation. A Skill can also link to and invoke
- * OTHER Skills (any relation whose target is itself a Skill, e.g. the same "triggers" relation
- * workflow execution already uses for skill-to-task edges): invoking the parent recursively
- * composes the linked skill's own invocation. Bounded and cycle-safe -- a skill-calls-skill
- * edge cycle degrades to a marker instead of infinite-looping, matching the cycle-safety
- * discipline established by task dependency graphs and the (since-removed; see Doc
- * "ConversationJournal design record") ConversationJournal domain's own reply chains.
- * `visited` and `depth` are recursion-internal; callers should not pass them.
- */
-export function skillInvocation(artifacts: ArtifactStore, id: string, visited: Set<string> = new Set(), depth = 0): string {
-	const skill = requireKind(artifacts, id, "skill");
-	visited.add(id);
-	const sections = [skillInvocationBody(skill)];
-
-	const edges = artifacts.relationships({ artifactIds: [id] }).filter((edge) => edge.from === id).slice(0, SKILL_INVOCATION_MAX_LINKED_ARTIFACTS);
-	const linkedArtifactLines: string[] = [];
-	const linkedSkillSections: string[] = [];
-	for (const edge of edges) {
-		const target = artifacts.get(edge.to);
-		if (!target) continue; // dangling edge -- defensive, should not happen
-		if (target.kind !== "skill") {
-			linkedArtifactLines.push(`- ${edge.relation} ${target.kind} "${target.title}"`);
-			continue;
-		}
-		if (visited.has(target.id)) {
-			linkedSkillSections.push(`Also linked via ${edge.relation} to skill "${target.title}" -- already invoked above in this chain, not repeated.`);
-		} else if (depth + 1 > SKILL_INVOCATION_MAX_CALL_DEPTH) {
-			linkedSkillSections.push(`Also linked via ${edge.relation} to skill "${target.title}" -- call depth limit reached, invoke it separately.`);
-		} else {
-			const nested = skillInvocation(artifacts, target.id, visited, depth + 1);
-			linkedSkillSections.push(`Also invoke linked skill (${edge.relation}) "${target.title}":\n${nested}`);
-		}
-	}
-	if (linkedArtifactLines.length > 0) {
-		sections.push(["Linked context (query Papyrus for full detail before proceeding):", ...linkedArtifactLines].join("\n"));
-	}
-	for (const section of linkedSkillSections) sections.push(section);
-	return sections.join("\n\n");
-}
-
-export function transitionSkill(artifacts: ArtifactStore, id: string, action: SkillTransition, context?: ArtifactEventContext): Artifact {
-	const skill = requireLocallyOwnedContent(requireKind(artifacts, id, "skill"));
-	const expected = action === "enable" ? "deprecated" : "active";
-	const target = action === "enable" ? "active" : "deprecated";
-	if (skill.status !== expected) throw new Error(`cannot ${action} skill from ${skill.status}`);
-	return artifacts.setStatus(id, target, context)!;
-}
-
-/**
- * Playbooks: a trigger and an ordered list of steps -- authored as prose, a completely
- * different beast from Skills at that level. But playbooks.invoke (playbook-execution.ts)
- * recycles the exact same materialization engine workflow Skills use: it compiles a Playbook
- * into a SkillDefinition and mechanically instantiates real Tasks from it, same as a Skill's
- * own artifact-template/workflow blueprint. `playbookInvocation` below is the OTHER, older
+ * Playbooks: a trigger and an ordered list of steps -- authored as prose. But playbooks.invoke
+ * (playbook-execution.ts) recycles the shared blueprint materialization engine: it compiles a
+ * Playbook into a BlueprintDefinition and mechanically instantiates real Tasks from it.
+ * `playbookInvocation` below is the OTHER, older
  * path -- rendered text with no side effects, now exposed as the `preview` action for a human
  * who wants to just read a playbook before invoking it, not the primary way of running one.
  * Like Tasks, a Playbook can be nested or chained with another Playbook: `contains`/`part_of`
@@ -546,6 +378,10 @@ export interface PlaybookArgument {
 	description?: string;
 	/** Defaults true: naming an argument at all is a signal it matters, so an author must opt out explicitly to make one optional. */
 	required: boolean;
+	/** Defaults "string" (unchanged behavior for every argument declared before typed arguments existed). Validated the exact same way a workflow-definition target's own BlueprintInputDefinition is (domain/blueprint-definition.ts), not re-derived here. */
+	type: BlueprintInputType;
+	enum?: BlueprintArgumentValue[];
+	default?: BlueprintArgumentValue;
 }
 
 /** Rejects malformed input rather than silently dropping a bad entry -- the same posture creation validation already takes everywhere else. */
@@ -569,7 +405,98 @@ function validatePlaybookArguments(value: unknown): PlaybookArgument[] | undefin
 		}
 		const required = record["required"];
 		if (required !== undefined && typeof required !== "boolean") throw new Error(`argument "${name}" required must be a boolean`);
-		return { name, ...(description !== undefined ? { description: description as string } : {}), required: required !== false };
+		const type = record["type"] === undefined ? "string" : record["type"];
+		if (!BLUEPRINT_INPUT_TYPES.has(type as BlueprintInputType)) throw new Error(`argument "${name}" has unsupported type`);
+		const result: PlaybookArgument = { name, required: required !== false, type: type as BlueprintInputType };
+		if (description !== undefined) result.description = description as string;
+		if (record["default"] !== undefined) result.default = validateArgumentValue(name, result.type, record["default"]);
+		if (record["enum"] !== undefined) {
+			const values = record["enum"];
+			if (!Array.isArray(values) || values.length === 0 || values.length > SKILL_MAX_ENUM_VALUES) {
+				throw new Error(`argument "${name}" enum must contain 1-${SKILL_MAX_ENUM_VALUES} values`);
+			}
+			result.enum = values.map((entry_) => validateArgumentValue(name, result.type, entry_));
+			if (result.default !== undefined && !result.enum.includes(result.default)) {
+				throw new Error(`argument "${name}" default must be one of its enum values`);
+			}
+		}
+		return result;
+	});
+}
+
+/** A plain string step is an ordinary prose task -- unchanged since Playbooks first existed. A structured step declares one of the other three Blueprint kinds (domain/blueprint-definition.ts): a Doc, a Rule, or a nested pipeline call into another Playbook (or a workflow-definition target). No `ref` field -- refs are compiler-assigned (playbook-definition.ts); a Playbook author never sees them, keeping the common case exactly as prose-simple as a plain string. */
+export type PlaybookStep =
+	| string
+	| { kind: "task"; title?: string; body: string }
+	| { kind: "doc"; title: string; body?: string; subtype?: string; labels?: string[] }
+	| { kind: "rule"; title: string; body?: string; condition?: string; action?: string; severity?: "block" | "warn" | "info"; labels?: string[] }
+	| { kind: "call"; title: string; playbookId: string; arguments?: Record<string, unknown> };
+
+function validateStructuredStep(value: Record<string, unknown>, index: number): PlaybookStep {
+	const kind = value["kind"];
+	const title = value["title"];
+	if (kind === "task") {
+		const body = value["body"];
+		if (typeof body !== "string" || body.trim().length === 0) throw new Error(`step ${index} (task) requires a non-empty body`);
+		return { kind: "task", body, ...(typeof title === "string" && title.length > 0 ? { title } : {}) };
+	}
+	if (typeof title !== "string" || title.trim().length === 0 || title.length > ARTIFACT_TITLE_MAX_LENGTH) {
+		throw new Error(`step ${index} (${String(kind)}) requires a title between 1 and ${ARTIFACT_TITLE_MAX_LENGTH} characters`);
+	}
+	if (kind === "doc" || kind === "rule") {
+		const body = value["body"];
+		if (body !== undefined && typeof body !== "string") throw new Error(`step ${index} (${kind}) body must be a string`);
+		const labels = value["labels"];
+		if (labels !== undefined && (!Array.isArray(labels) || labels.some((label) => typeof label !== "string"))) {
+			throw new Error(`step ${index} (${kind}) labels must be a string array`);
+		}
+		if (kind === "doc") {
+			const subtype = value["subtype"];
+			if (subtype !== undefined && typeof subtype !== "string") throw new Error(`step ${index} (doc) subtype must be a string`);
+			return { kind: "doc", title, ...(body !== undefined ? { body: body as string } : {}), ...(subtype !== undefined ? { subtype: subtype as string } : {}), ...(labels !== undefined ? { labels: labels as string[] } : {}) };
+		}
+		const condition = value["condition"];
+		const action = value["action"];
+		const severity = value["severity"];
+		if (condition !== undefined && typeof condition !== "string") throw new Error(`step ${index} (rule) condition must be a string`);
+		if (action !== undefined && typeof action !== "string") throw new Error(`step ${index} (rule) action must be a string`);
+		if (severity !== undefined && severity !== "block" && severity !== "warn" && severity !== "info") {
+			throw new Error(`step ${index} (rule) severity must be block, warn, or info`);
+		}
+		return {
+			kind: "rule",
+			title,
+			...(body !== undefined ? { body: body as string } : {}),
+			...(condition !== undefined ? { condition: condition as string } : {}),
+			...(action !== undefined ? { action: action as string } : {}),
+			...(severity !== undefined ? { severity: severity as "block" | "warn" | "info" } : {}),
+			...(labels !== undefined ? { labels: labels as string[] } : {}),
+		};
+	}
+	if (kind === "call") {
+		const playbookId = value["playbookId"];
+		if (typeof playbookId !== "string" || playbookId.trim().length === 0) throw new Error(`step ${index} (call) requires a playbookId`);
+		const callArguments = value["arguments"];
+		if (callArguments !== undefined && (typeof callArguments !== "object" || callArguments === null || Array.isArray(callArguments))) {
+			throw new Error(`step ${index} (call) arguments must be an object`);
+		}
+		return { kind: "call", title, playbookId, ...(callArguments !== undefined ? { arguments: callArguments as Record<string, unknown> } : {}) };
+	}
+	throw new Error(`step ${index} has unknown kind "${String(kind)}"`);
+}
+
+/** A plain string passes through unchanged (the entire authoring surface before this extension); an object is validated against one of the three structured step kinds. Rejects malformed input rather than silently dropping it, matching validatePlaybookArguments' own posture. */
+function validatePlaybookSteps(value: unknown): PlaybookStep[] | undefined {
+	if (value === undefined) return undefined;
+	if (!Array.isArray(value)) throw new Error("playbook steps must be an array");
+	if (value.length > PLAYBOOK_MAX_STEPS) throw new Error(`playbook steps cannot exceed ${PLAYBOOK_MAX_STEPS} entries`);
+	return value.map((entry, index) => {
+		if (typeof entry === "string") {
+			if (entry.trim().length === 0) throw new Error(`step ${index} must not be empty`);
+			return entry;
+		}
+		if (typeof entry !== "object" || entry === null || Array.isArray(entry)) throw new Error(`step ${index} must be a string or a structured step object`);
+		return validateStructuredStep(entry as Record<string, unknown>, index);
 	});
 }
 
@@ -577,7 +504,7 @@ export interface CreatePlaybookInput {
 	title: string;
 	body?: string;
 	trigger?: string;
-	steps?: string[];
+	steps?: unknown;
 	tools?: string[];
 	/** Declares named arguments this Playbook needs -- see playbookInvocation for how a missing required one surfaces. */
 	arguments?: unknown;
@@ -592,6 +519,7 @@ export type UpdatePlaybookInput = UpdateContentInput;
 export function createPlaybook(artifacts: ArtifactStore, scopes: ArtifactScopeStore, input: CreatePlaybookInput, context?: ArtifactEventContext): Artifact {
 	const projectRoot = input.projectRoot === undefined ? undefined : normalizeProjectRoot(input.projectRoot);
 	const declaredArguments = validatePlaybookArguments(input.arguments);
+	const declaredSteps = validatePlaybookSteps(input.steps);
 	const playbook = artifacts.create({
 		kind: "playbook",
 		status: "active", // explicit; see createDocument for why defaultStatusFor is not trusted here
@@ -601,7 +529,7 @@ export function createPlaybook(artifacts: ArtifactStore, scopes: ArtifactScopeSt
 		extra: {
 			...(input.extra ?? {}),
 			...(input.trigger ? { trigger: input.trigger } : {}),
-			...(input.steps ? { steps: input.steps } : {}),
+			...(declaredSteps ? { steps: declaredSteps } : {}),
 			...(input.tools ? { tools: input.tools } : {}),
 			...(declaredArguments ? { arguments: declaredArguments } : {}),
 		},
@@ -678,19 +606,34 @@ export function undependPlaybook(artifacts: ArtifactStore, id: string, dependenc
 	return showPlaybook(artifacts, id);
 }
 
+/** Text rendering for one preview step, covering all four Blueprint kinds -- distinct from playbook-definition.ts's stepTitle (a compiled Task's title), since a preview is read by a human/agent deciding whether to invoke, not turned into a real artifact. */
+function stepText(step: PlaybookStep, index: number): string {
+	if (typeof step === "string") return `${index + 1}. ${step}`;
+	if (step.kind === "task") return `${index + 1}. ${step.title ? `${step.title} -- ` : ""}${step.body}`;
+	if (step.kind === "doc") return `${index + 1}. [creates Doc] "${step.title}"${step.subtype ? ` (${step.subtype})` : ""}`;
+	if (step.kind === "rule") return `${index + 1}. [creates Rule] "${step.title}"${step.condition ? ` -- when: ${step.condition}` : ""}`;
+	return `${index + 1}. [calls playbook] "${step.title}" -> ${step.playbookId}`;
+}
+
+function argumentQualifier(argument: PlaybookArgument): string {
+	const qualifier = argument.required ? "required" : "optional";
+	const type = argument.type === "string" ? "" : `, ${argument.type}`;
+	const options = argument.enum ? `, one of: ${argument.enum.join(", ")}` : "";
+	return `${qualifier}${type}${options}`;
+}
+
 /** Renders trigger/body/arguments/steps/tools into readable guidance -- the flat, non-recursive part of a Playbook's own invocation, shared by the top-level render and by a nested composed call. */
-function playbookInvocationBody(playbook: Artifact, provided: Record<string, string>): string {
+function playbookInvocationBody(playbook: Artifact, provided: Record<string, unknown>): string {
 	const trigger = typeof playbook.extra["trigger"] === "string" ? playbook.extra["trigger"] : "manual invocation";
-	const steps = Array.isArray(playbook.extra["steps"]) ? playbook.extra["steps"].filter((step): step is string => typeof step === "string") : [];
+	const steps = Array.isArray(playbook.extra["steps"]) ? (playbook.extra["steps"] as PlaybookStep[]) : [];
 	const tools = Array.isArray(playbook.extra["tools"]) ? playbook.extra["tools"].filter((tool): tool is string => typeof tool === "string") : [];
 	const declaredArguments = Array.isArray(playbook.extra["arguments"]) ? (playbook.extra["arguments"] as PlaybookArgument[]) : [];
 	const argumentLines = declaredArguments.map((argument) => {
 		const value = provided[argument.name];
-		if (value !== undefined) return `- ${argument.name}: ${value}`;
-		const qualifier = argument.required ? "required" : "optional";
-		return `- ${argument.name} (${qualifier}${argument.description ? `: ${argument.description}` : ""}) -- not yet provided`;
+		if (value !== undefined) return `- ${argument.name}: ${String(value)}`;
+		return `- ${argument.name} (${argumentQualifier(argument)}${argument.description ? `: ${argument.description}` : ""}) -- not yet provided`;
 	});
-	const missingRequired = declaredArguments.filter((argument) => argument.required && provided[argument.name] === undefined);
+	const missingRequired = declaredArguments.filter((argument) => argument.required && provided[argument.name] === undefined && argument.default === undefined);
 	return [
 		`Apply Papyrus playbook "${playbook.title}".`,
 		`Trigger: ${trigger}`,
@@ -699,7 +642,7 @@ function playbookInvocationBody(playbook: Artifact, provided: Record<string, str
 		...(missingRequired.length > 0
 			? [`Missing required argument(s): ${missingRequired.map((argument) => argument.name).join(", ")}. Ask the human for these directly -- the discuss tool with live:true asks synchronously and gets a real answer in this same turn -- before proceeding with the steps below. Do not guess or invent a value.`]
 			: []),
-		...(steps.length ? ["Steps:", ...steps.map((step, index) => `${index + 1}. ${step}`)] : []),
+		...(steps.length ? ["Steps:", ...steps.map((step, index) => stepText(step, index))] : []),
 		...(tools.length ? [`Tools: ${tools.join(", ")}`] : []),
 	].join("\n");
 }
@@ -711,14 +654,14 @@ function playbookInvocationBody(playbook: Artifact, provided: Record<string, str
  * "run as part of this one". `depends_on` chains a prerequisite -- its full steps render BEFORE
  * this playbook's own, as "complete this first". Every other relation (references, relates_to,
  * etc.) still gets the flat one-line "Linked context" pointer, unchanged. Bounded and
- * cycle-safe -- a composition cycle degrades to a marker instead of infinite-looping, matching
- * skillInvocation's own cycle-safety discipline.
+ * cycle-safe -- a composition cycle degrades to a marker instead of infinite-looping, the same
+ * cycle-safety discipline task dependency graphs already established.
  * `provided` is the caller's already-known argument values (e.g. from the conversation so far);
  * any declared *required* argument missing from it is called out explicitly, directing the agent
  * to discuss (live:true) rather than guess or silently proceed. `visited` and `depth` are
  * recursion-internal; callers should not pass them.
  */
-export function playbookInvocation(artifacts: ArtifactStore, id: string, provided: Record<string, string> = {}, visited: Set<string> = new Set(), depth = 0): string {
+export function playbookInvocation(artifacts: ArtifactStore, id: string, provided: Record<string, unknown> = {}, visited: Set<string> = new Set(), depth = 0): string {
 	const playbook = requireKind(artifacts, id, "playbook");
 	visited.add(id);
 

package/src/modules/logs.ts

@@ -1,7 +1,7 @@
 /**
  * modules/logs.ts — the `log` domain as a registered Papyrus-native module.
  *
- * Deliberately self-contained: does not import artifact/task/rule/skill infrastructure --
+ * Deliberately self-contained: does not import artifact/task/rule/playbook infrastructure --
  * logs never touch the Artifact graph directly (see src/domain/log-entry.ts's own module
  * comment on why `log` is not an Artifact kind).
  */

package/src/modules/playbooks.ts

@@ -1,11 +1,11 @@
 /**
  * modules/playbooks.ts — Playbooks as a Papyrus-native registered module.
  *
- * A Playbook (trigger + ordered steps, contains/depends_on composition, predefined
- * rules/docs) is a completely different beast from a Skill (a mechanically instantiated
- * artifact-template or workflow blueprint) at the AUTHORING level -- but playbooks.invoke
- * recycles the exact same materialization engine workflow Skills use (playbook-execution.ts
- * compiles a Playbook's composition tree into a SkillDefinition, then hands off to
+ * A Playbook is prose-first, whole-artifact composition (contains/depends_on between real
+ * Playbook artifacts) rather than a raw JSON blueprint -- but its own step list can also
+ * declare Doc/Rule blueprints and typed arguments and nested pipeline calls. playbooks.invoke
+ * recycles the shared blueprint materialization engine (playbook-execution.ts compiles a
+ * Playbook's steps and composition tree into a BlueprintDefinition, then hands off to
  * workflow-execution.ts's shared core). See domain-services.ts's Playbook section and
  * playbook-definition.ts for the full rationale.
  */
@@ -98,14 +98,14 @@ export function playbooksOperations({ artifacts, events, scopes, artifactScopes,
 	return [
 		define("playbooks.create", (input: OperationInput) => createPlaybook(artifacts, artifactScopes, {
 			title: string(input, "title"), body: optionalString(input, "body"), trigger: optionalString(input, "trigger"),
-			steps: input["steps"] as string[] | undefined, tools: input["tools"] as string[] | undefined,
+			steps: input["steps"], tools: input["tools"] as string[] | undefined,
 			arguments: input["arguments"],
 			labels: input["labels"] as string[] | undefined, extra: input["extra"] as Record<string, unknown> | undefined,
 			projectRoot: optionalString(input, "project_root"),
 		}, eventContext(input))),
 		define("playbooks.list", (input: OperationInput) => listPlaybooks(artifacts, artifactScopes, artifactFilter(input))),
 		define("playbooks.show", (input: OperationInput) => showPlaybook(artifacts, string(input, "id"))),
-		define("playbooks.preview", (input: OperationInput) => playbookInvocation(artifacts, string(input, "id"), input["arguments"] as Record<string, string> | undefined)),
+		define("playbooks.preview", (input: OperationInput) => playbookInvocation(artifacts, string(input, "id"), input["arguments"] as Record<string, unknown> | undefined)),
 		define("playbooks.invoke", (input: OperationInput) => {
 			const result = invokePlaybook(artifacts, string(input, "id"), {
 				runId: optionalString(input, "run_id") ?? optionalString(input, "runId"),
@@ -129,3 +129,5 @@ export function playbooksOperations({ artifacts, events, scopes, artifactScopes,
 		define("playbooks.undepend", (input: OperationInput) => undependPlaybook(artifacts, string(input, "id"), string(input, "dependency_id"), eventContext(input))),
 	];
 }
+
+

package/src/ops.ts

@@ -75,7 +75,9 @@ 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`);
 	}