@danypops/papyrus 0.2.1 → 0.4.0

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);
 	}
 }
 
@@ -74,6 +97,11 @@ CREATE TABLE IF NOT EXISTS relation_names (
 	name        TEXT PRIMARY KEY,
 	description TEXT
 );
+CREATE TABLE IF NOT EXISTS task_focus (
+	scope       TEXT PRIMARY KEY CHECK (scope = 'global'),
+	task_id     TEXT NOT NULL UNIQUE REFERENCES artifacts(id),
+	updated_at  TEXT NOT NULL
+);
 `;
 
 const SEED_SQL = `
@@ -84,10 +112,12 @@ INSERT OR IGNORE INTO kinds VALUES ('skill','Parameterized workflow bundle — i
 INSERT OR IGNORE INTO statuses VALUES ('draft','doc');
 INSERT OR IGNORE INTO statuses VALUES ('active','doc');
 INSERT OR IGNORE INTO statuses VALUES ('archived','doc');
-INSERT OR IGNORE INTO statuses VALUES ('pending','task');
-INSERT OR IGNORE INTO statuses VALUES ('active','task');
+INSERT OR IGNORE INTO statuses VALUES ('todo','task');
+INSERT OR IGNORE INTO statuses VALUES ('in-progress','task');
+INSERT OR IGNORE INTO statuses VALUES ('review','task');
+INSERT OR IGNORE INTO statuses VALUES ('rejected','task');
 INSERT OR IGNORE INTO statuses VALUES ('done','task');
-INSERT OR IGNORE INTO statuses VALUES ('failed','task');
+INSERT OR IGNORE INTO statuses VALUES ('canceled','task');
 INSERT OR IGNORE INTO statuses VALUES ('active','rule');
 INSERT OR IGNORE INTO statuses VALUES ('deprecated','rule');
 INSERT OR IGNORE INTO statuses VALUES ('active','skill');
@@ -107,23 +137,64 @@ INSERT OR IGNORE INTO relation_names VALUES ('part_of','Artifact belongs to a pa
 CREATE INDEX IF NOT EXISTS edges_to_id_idx ON edges(to_id);
 `;
 
-function migrate(db: Db): void {
-	const row = db.prepare("PRAGMA user_version").get() as { user_version: number };
-	let version = row.user_version;
-	if (version > SQLITE_SCHEMA_VERSION) {
-		throw new Error(`database schema ${version} is newer than supported ${SQLITE_SCHEMA_VERSION}`);
-	}
-	if (version < 1) {
-		inTransaction(db, () => {
-			db.exec(SCHEMA);
-			db.exec(SEED_SQL);
-			db.exec("PRAGMA user_version = 1");
-		});
-		version = 1;
-	}
-	if (version !== SQLITE_SCHEMA_VERSION) {
-		throw new Error(`missing migration from schema ${version} to ${SQLITE_SCHEMA_VERSION}`);
+export interface MigrationResult {
+	from: number;
+	to: number;
+	applied: string[];
+}
+
+export function schemaVersion(db: Db): number {
+	return (db.prepare("PRAGMA user_version").get() as { user_version: number }).user_version;
+}
+
+function bootstrapEmptyDatabase(db: Db): void {
+	const existing = db
+		.prepare("SELECT name FROM sqlite_master WHERE type = 'table' AND name NOT LIKE 'sqlite_%' LIMIT 1")
+		.get();
+	if (existing) throw new Error("database schema is unversioned; refusing to migrate existing data during boot");
+	inTransaction(db, () => {
+		db.exec(SCHEMA);
+		db.exec(SEED_SQL);
+		db.exec(`PRAGMA user_version = ${SQLITE_SCHEMA_VERSION}`);
+	});
+}
+
+export function migrateDb(db: Db): MigrationResult {
+	const from = schemaVersion(db);
+	if (from > SQLITE_SCHEMA_VERSION) {
+		throw new Error(`database schema ${from} is newer than supported ${SQLITE_SCHEMA_VERSION}`);
 	}
+	if (from === SQLITE_SCHEMA_VERSION) return { from, to: from, applied: [] };
+	if (from !== 1) throw new Error(`no explicit migration path from database schema ${from}`);
+
+	inTransaction(db, () => {
+		db.exec(`
+			INSERT OR IGNORE INTO statuses VALUES ('todo','task');
+			INSERT OR IGNORE INTO statuses VALUES ('in-progress','task');
+			INSERT OR IGNORE INTO statuses VALUES ('review','task');
+			INSERT OR IGNORE INTO statuses VALUES ('rejected','task');
+			INSERT OR IGNORE INTO statuses VALUES ('done','task');
+			INSERT OR IGNORE INTO statuses VALUES ('canceled','task');
+			CREATE TABLE task_focus (
+				scope TEXT PRIMARY KEY CHECK (scope = 'global'),
+				task_id TEXT NOT NULL UNIQUE REFERENCES artifacts(id),
+				updated_at TEXT NOT NULL
+			);
+			INSERT INTO task_focus (scope, task_id, updated_at)
+			SELECT 'global', id, strftime('%Y-%m-%dT%H:%M:%fZ','now')
+			FROM artifacts WHERE kind = 'task' AND status = 'active'
+			ORDER BY updated_at DESC, id ASC LIMIT 1;
+			UPDATE artifacts SET status = CASE status
+				WHEN 'pending' THEN 'todo'
+				WHEN 'active' THEN 'in-progress'
+				WHEN 'failed' THEN 'rejected'
+				ELSE status END
+			WHERE kind = 'task';
+			DELETE FROM statuses WHERE kind = 'task' AND name IN ('pending', 'active', 'failed');
+			PRAGMA user_version = 2;
+		`);
+	});
+	return { from, to: SQLITE_SCHEMA_VERSION, applied: ["task-lifecycle-and-focus"] };
 }
 
 export function openDb(path: string): Db {
@@ -132,7 +203,12 @@ export function openDb(path: string): Db {
 	db.exec("PRAGMA foreign_keys = ON");
 	db.exec(`PRAGMA busy_timeout = ${SQLITE_BUSY_TIMEOUT_MS}`);
 	if (path !== ":memory:") db.exec("PRAGMA journal_mode = WAL");
-	migrate(db);
+	const current = schemaVersion(db);
+	if (current > SQLITE_SCHEMA_VERSION) {
+		db.close();
+		throw new Error(`database schema ${current} is newer than supported ${SQLITE_SCHEMA_VERSION}`);
+	}
+	if (current === 0) bootstrapEmptyDatabase(db);
 	db.exec("PRAGMA optimize=0x10002");
 	return db;
 }

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/ports/task-focus-store.ts

@@ -0,0 +1,21 @@
+export interface TaskFocusStore {
+	get(): string | undefined;
+	set(taskId: string): void;
+	clear(taskId?: string): void;
+}
+
+export class InMemoryTaskFocusStore implements TaskFocusStore {
+	private taskId: string | undefined;
+
+	get(): string | undefined {
+		return this.taskId;
+	}
+
+	set(taskId: string): void {
+		this.taskId = taskId;
+	}
+
+	clear(taskId?: string): void {
+		if (taskId === undefined || taskId === this.taskId) this.taskId = undefined;
+	}
+}

package/src/service.ts

@@ -1,14 +1,15 @@
-import { SERVICE_MAX_BODY_BYTES } from "./constants.ts";
+import { SERVICE_MAX_BODY_BYTES, SQLITE_SCHEMA_VERSION } from "./constants.ts";
 import { VERSION } from "./version.ts";
-import { openDb } from "./db.ts";
+import { migrateDb, openDb, schemaVersion } from "./db.ts";
 import { SQLiteArtifactStore } from "./adapters/sqlite-artifact-store.ts";
 import { SQLiteGateRunner } from "./adapters/sqlite-gate-runner.ts";
+import { SQLiteTaskFocusStore } from "./adapters/sqlite-task-focus-store.ts";
 import type { CreateArtifactInput } from "./domain/artifact.ts";
 import type { Checklist } from "./domain/checklist.ts";
 import type { ArtifactStore } from "./ports/artifact-store.ts";
 import type { GateRunner } from "./ports/gate-runner.ts";
 import { projectTaskExecution } from "./task-execution.ts";
-import { Tasks } from "./task-service.ts";
+import { Tasks, type TaskStatus } from "./task-service.ts";
 import {
 	createArtifactTemplate,
 	createDocument,
@@ -19,6 +20,7 @@ import {
 	instantiateTemplate,
 	listDocuments,
 	listRules,
+	listInjectableRules,
 	listSkills,
 	previewRule,
 	showDocument,
@@ -31,8 +33,10 @@ 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",
 	"artifact.create",
 	"artifact.query",
 	"artifact.show",
@@ -46,13 +50,17 @@ export const EXPECTED_OPERATION_NAMES = [
 	"tasks.graph",
 	"tasks.plan",
 	"tasks.show",
+	"tasks.active",
+	"tasks.focus",
 	"tasks.start",
+	"tasks.submit",
 	"tasks.complete",
 	"tasks.run_gates",
 	"tasks.set_checklist",
 	"tasks.context",
-	"tasks.fail",
+	"tasks.reject",
 	"tasks.retry",
+	"tasks.cancel",
 	"tasks.depend",
 	"tasks.contain",
 	"docs.create",
@@ -74,6 +82,7 @@ export const EXPECTED_OPERATION_NAMES = [
 	"skills.list",
 	"skills.show",
 	"skills.invoke",
+	"skills.run",
 	"skills.enable",
 	"skills.disable",
 	"skills.instantiate",
@@ -84,6 +93,7 @@ type OperationInput = Record<string, unknown>;
 type OperationHandler = (input: OperationInput) => unknown;
 
 export class UnknownOperationError extends Error {}
+export class MigrationRequiredError extends Error {}
 export class PayloadTooLargeError extends Error {}
 
 function string(input: OperationInput, key: string): string {
@@ -111,21 +121,34 @@ function normalizeCreateInput(input: OperationInput): CreateArtifactInput {
 	return { ...rest, templateId: typeof template_id === "string" ? template_id : undefined } as CreateArtifactInput;
 }
 
+export interface SchemaState {
+	current: number;
+	required: number;
+	migrationRequired: boolean;
+}
+
 export interface PapyrusService {
 	operationNames(): OperationName[];
+	schemaState(): SchemaState;
 	execute(operation: string, input?: OperationInput): Promise<unknown>;
 	checkpoint(): void;
 	optimize(): void;
 	close(): void;
 }
 
-function handlers(artifacts: ArtifactStore, gates: GateRunner, tasks: Tasks): Record<OperationName, OperationHandler> {
+function handlers(
+	artifacts: ArtifactStore,
+	gates: GateRunner,
+	tasks: Tasks,
+	migrate: () => unknown,
+): Record<OperationName, OperationHandler> {
 	const taskFilter = (input: OperationInput) => ({
 		status: optionalString(input, "status"),
 		text: optionalString(input, "text"),
 		limit: optionalNumber(input, "limit"),
 	});
 	return {
+		"system.migrate": () => migrate(),
 		"artifact.create": (input) => artifacts.create(normalizeCreateInput(input)),
 		"artifact.query": (input) => artifacts.query(input),
 		"artifact.show": (input) => artifacts.get(string(input, "id"), {
@@ -151,12 +174,12 @@ function handlers(artifacts: ArtifactStore, gates: GateRunner, tasks: Tasks): Re
 		}),
 		"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"),
 			body: optionalString(input, "body"),
-			status: optionalString(input, "status") as "pending" | "active" | "done" | "failed" | undefined,
+			status: optionalString(input, "status") as TaskStatus | undefined,
 			labels: input["labels"] as string[] | undefined,
 			extra: input["extra"] as Record<string, unknown> | undefined,
 			gates: input["gates"] as Parameters<Tasks["create"]>[0]["gates"],
@@ -169,13 +192,17 @@ function handlers(artifacts: ArtifactStore, gates: GateRunner, tasks: Tasks): Re
 		"tasks.graph": (input) => tasks.graph(taskFilter(input)),
 		"tasks.plan": (input) => projectTaskExecution(tasks.graph(taskFilter(input))),
 		"tasks.show": (input) => tasks.show(string(input, "id")),
+		"tasks.active": () => tasks.active(),
+		"tasks.focus": (input) => tasks.focus(string(input, "id")),
 		"tasks.start": (input) => tasks.transition(string(input, "id"), "start"),
+		"tasks.submit": (input) => tasks.transition(string(input, "id"), "submit"),
 		"tasks.complete": (input) => tasks.completeAsync(string(input, "id")),
 		"tasks.run_gates": (input) => tasks.runGates(string(input, "id")),
 		"tasks.set_checklist": (input) => tasks.setChecklist(string(input, "id"), input["checklist"] as Checklist),
-		"tasks.context": () => taskContext(artifacts),
-		"tasks.fail": (input) => tasks.transition(string(input, "id"), "fail"),
+		"tasks.context": () => taskContext(artifacts, tasks.active()?.id),
+		"tasks.reject": (input) => tasks.transition(string(input, "id"), "reject"),
 		"tasks.retry": (input) => tasks.transition(string(input, "id"), "retry"),
+		"tasks.cancel": (input) => tasks.transition(string(input, "id"), "cancel"),
 		"tasks.depend": (input) => tasks.depend(string(input, "id"), string(input, "dependency_id")),
 		"tasks.contain": (input) => tasks.contain(string(input, "parent_id"), string(input, "child_id")),
 		"docs.create": (input) => createDocument(artifacts, {
@@ -204,6 +231,7 @@ function handlers(artifacts: ArtifactStore, gates: GateRunner, tasks: Tasks): Re
 		"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, {
@@ -213,6 +241,10 @@ function handlers(artifacts: ArtifactStore, gates: GateRunner, tasks: Tasks): Re
 		"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)),
@@ -223,13 +255,22 @@ export function createPapyrusService(path: string): PapyrusService {
 	const db = openDb(path);
 	const artifacts = new SQLiteArtifactStore(db);
 	const gates = new SQLiteGateRunner(db);
-	const tasks = new Tasks(artifacts, gates);
-	const registry = handlers(artifacts, gates, tasks);
+	const focus = new SQLiteTaskFocusStore(db);
+	const tasks = new Tasks(artifacts, gates, focus);
+	const registry = handlers(artifacts, gates, tasks, () => migrateDb(db));
+	const state = (): SchemaState => {
+		const current = schemaVersion(db);
+		return { current, required: SQLITE_SCHEMA_VERSION, migrationRequired: current !== SQLITE_SCHEMA_VERSION };
+	};
 	return {
 		operationNames: () => [...EXPECTED_OPERATION_NAMES],
+		schemaState: state,
 		async execute(operation, input = {}) {
 			const handler = registry[operation as OperationName];
 			if (!handler) throw new UnknownOperationError(`unknown operation "${operation}"`);
+			if (operation !== "system.migrate" && state().migrationRequired) {
+				throw new MigrationRequiredError("database migration required; run `papyrus migrate task-lifecycle`");
+			}
 			return handler(input);
 		},
 		checkpoint: () => { db.exec("PRAGMA wal_checkpoint(PASSIVE)"); },
@@ -278,7 +319,7 @@ export function createApp(deps: { service: PapyrusService; token: string }): { f
 			}
 			const url = new URL(request.url);
 			if (request.method === "GET" && url.pathname === "/health") {
-				return json({ ok: true, version: VERSION });
+				return json({ ok: true, version: VERSION, schema: deps.service.schemaState() });
 			}
 			if (request.method === "GET" && url.pathname === "/api/v1/ops") {
 				return json({ operations: deps.service.operationNames() });