@danypops/papyrus 0.2.1 → 0.4.0

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)),
+		};
+	});
+}

package/src/task-context.ts

@@ -1,8 +1,8 @@
 import type { Artifact } from "./domain/artifact.ts";
 import type { ArtifactStore } from "./ports/artifact-store.ts";
 import {
-	TASK_CONTEXT_ACTIVE_LIMIT,
-	TASK_CONTEXT_FAILED_LIMIT,
+	TASK_CONTEXT_CURRENT_LIMIT,
+	TASK_CONTEXT_REJECTED_LIMIT,
 	TASK_RECONCILIATION_INSTRUCTION,
 } from "./constants.ts";
 
@@ -34,19 +34,20 @@ function renderCurrent(task: Artifact): string[] {
 	];
 }
 
-export function taskContext(artifacts: ArtifactStore): string | null {
+export function taskContext(artifacts: ArtifactStore, activeTaskId?: string): string | null {
 	const tasks = artifacts.query({ kind: "task" }).sort((left, right) => left.updated_at.localeCompare(right.updated_at));
-	const open = tasks.filter((task) => task.status !== "done");
+	const open = tasks.filter((task) => task.status !== "done" && task.status !== "canceled");
 	if (open.length === 0) return null;
 
 	const done = tasks.length - open.length;
-	const active = open.filter((task) => task.status === "active").slice(0, TASK_CONTEXT_ACTIVE_LIMIT);
-	const next = open.find((task) => task.status === "pending");
-	const failed = open.filter((task) => task.status === "failed").slice(0, TASK_CONTEXT_FAILED_LIMIT);
+	const active = activeTaskId ? open.find((task) => task.id === activeTaskId) : undefined;
+	const current = active ? [active] : open.filter((task) => task.status === "in-progress" || task.status === "review").slice(0, TASK_CONTEXT_CURRENT_LIMIT);
+	const next = open.find((task) => task.status === "todo");
+	const rejected = open.filter((task) => task.status === "rejected").slice(0, TASK_CONTEXT_REJECTED_LIMIT);
 	const lines = [`Progress: ${done}/${tasks.length} done`];
-	for (const task of active) lines.push(...renderCurrent(task));
+	for (const task of current) lines.push(...renderCurrent(task));
 	if (next) lines.push(`Next: ${next.title} (${next.id})`);
-	if (failed.length > 0) lines.push(`Blocked: ${failed.map((task) => `${task.title} (${task.id})`).join(", ")}`);
+	if (rejected.length > 0) lines.push(`Rejected: ${rejected.map((task) => `${task.title} (${task.id})`).join(", ")}`);
 	lines.push("", TASK_RECONCILIATION_INSTRUCTION);
 	return lines.join("\n");
 }

package/src/task-execution.ts

@@ -1,12 +1,22 @@
 import { TASK_EXECUTION_MAX_DEGREE, TASK_EXECUTION_MAX_EDGES, TASK_EXECUTION_MAX_NODES } from "./constants.ts";
 import type { TaskGraph } from "./task-service.ts";
 
-export type TaskExecutionState = "done" | "active" | "ready" | "blocked" | "failed" | "invalid";
+export type TaskExecutionState =
+	| "todo"
+	| "in-progress"
+	| "review"
+	| "rejected"
+	| "done"
+	| "canceled"
+	| "ready"
+	| "blocked"
+	| "invalid";
 
 export interface TaskExecutionNode {
 	id: string;
 	title: string;
 	status: string;
+	active: boolean;
 	state: TaskExecutionState;
 	layer: number | null;
 	prerequisiteIds: string[];
@@ -21,8 +31,10 @@ export interface TaskExecutionPlan {
 
 function executionState(status: string, invalid: boolean, prerequisitesDone: boolean): TaskExecutionState {
 	if (invalid) return "invalid";
-	if (status === "done" || status === "active" || status === "failed") return status;
-	if (status === "pending" && prerequisitesDone) return "ready";
+	if (status === "todo") return prerequisitesDone ? "ready" : "blocked";
+	if (["in-progress", "review", "rejected", "done", "canceled"].includes(status)) {
+		return status as TaskExecutionState;
+	}
 	return "blocked";
 }
 
@@ -96,6 +108,7 @@ export function projectTaskExecution(graph: TaskGraph): TaskExecutionPlan {
 				id: node.task.id,
 				title: node.task.title,
 				status: node.task.status,
+				active: node.active === true,
 				state,
 				layer: layerById.get(node.task.id) ?? null,
 				prerequisiteIds,

package/src/task-graph-view.ts

@@ -5,11 +5,14 @@ import type { TaskGraph } from "./task-service.ts";
 export type TaskGraphView = "execution" | "dependencies" | "composition";
 
 const EXECUTION_GLYPHS: Record<TaskExecutionState, string> = {
+	todo: "○",
+	"in-progress": "●",
+	review: "◆",
+	rejected: "▲",
 	done: "■",
-	active: "●",
+	canceled: "×",
 	ready: "◇",
 	blocked: "○",
-	failed: "▲",
 	invalid: "!",
 };
 
@@ -39,7 +42,7 @@ export function projectTaskGraph(graph: TaskGraph, view: TaskGraphView): Display
 	const nodes = view === "execution"
 		? projectTaskExecution(graph).nodes.map((node) => ({
 			id: node.id,
-			label: `${EXECUTION_GLYPHS[node.state]} ${node.title} · ${node.layer === null ? "no layer" : `layer ${node.layer + 1}`} · ${node.state}`,
+			label: `${node.active ? "▶ " : ""}${EXECUTION_GLYPHS[node.state]} ${node.title} · ${node.layer === null ? "no layer" : `layer ${node.layer + 1}`} · ${node.state}`,
 			status: node.state,
 		}))
 		: graph.nodes

package/src/task-service.ts

@@ -1,9 +1,10 @@
 import { TASK_EXECUTION_MAX_DEGREE, TASK_EXECUTION_MAX_EDGES, TASK_EXECUTION_MAX_NODES } from "./constants.ts";
 import type { Artifact } from "./domain/artifact.ts";
-import { validateChecklist, type Checklist } from "./domain/checklist.ts";
+import { checklistEntries, validateChecklist, type Checklist, type ProofReference } from "./domain/checklist.ts";
 import type { Gate, GateResult } from "./domain/gate.ts";
 import type { ArtifactStore } from "./ports/artifact-store.ts";
 import type { GateRunner } from "./ports/gate-runner.ts";
+import { InMemoryTaskFocusStore, type TaskFocusStore } from "./ports/task-focus-store.ts";
 import { assertDependencyEdgeAllowed } from "./task-execution.ts";
 
 export interface TaskFilter {
@@ -12,10 +13,12 @@ export interface TaskFilter {
 	limit?: number;
 }
 
+export type TaskStatus = "todo" | "in-progress" | "review" | "rejected" | "done" | "canceled";
+
 export interface CreateTaskInput {
 	title: string;
 	body?: string;
-	status?: "pending" | "active" | "done" | "failed";
+	status?: TaskStatus;
 	labels?: string[];
 	extra?: Record<string, unknown>;
 	gates?: Gate[];
@@ -25,23 +28,32 @@ export interface CreateTaskInput {
 	dependsOn?: string[];
 }
 
-export type TaskTransition = "start" | "fail" | "retry";
+export type TaskTransition = "start" | "submit" | "reject" | "retry" | "cancel";
 
 export interface TaskBlockage {
 	artifact: Artifact;
 	dependencyIds: string[];
 }
 
+export interface ChecklistReview {
+	item: string;
+	proof: ProofReference[];
+	accepted: boolean;
+	reason?: string;
+}
+
 export interface TaskCompletion {
 	artifact: Artifact;
 	gates: GateResult[];
+	checklist: ChecklistReview[];
 	completed: boolean;
-	started: Artifact[];
+	focused: Artifact | null;
 	blocked: TaskBlockage[];
 }
 
 export interface TaskNode {
 	task: Artifact;
+	active?: boolean;
 	parentIds: string[];
 	childIds: string[];
 	dependencyIds: string[];
@@ -52,16 +64,19 @@ export interface TaskGraph {
 	rootIds: string[];
 }
 
-const TASK_TRANSITIONS: Record<TaskTransition, { from: string[]; to: string }> = {
-	start: { from: ["pending"], to: "active" },
-	fail: { from: ["pending", "active"], to: "failed" },
-	retry: { from: ["failed"], to: "pending" },
+const TASK_TRANSITIONS: Record<TaskTransition, { from: TaskStatus[]; to: TaskStatus }> = {
+	start: { from: ["todo"], to: "in-progress" },
+	submit: { from: ["in-progress"], to: "review" },
+	reject: { from: ["review"], to: "rejected" },
+	retry: { from: ["rejected"], to: "in-progress" },
+	cancel: { from: ["todo", "in-progress", "review", "rejected"], to: "canceled" },
 };
 
 export class Tasks {
 	constructor(
 		private readonly artifacts: ArtifactStore,
 		private readonly gates: GateRunner,
+		private readonly focusStore: TaskFocusStore = new InMemoryTaskFocusStore(),
 	) {}
 
 	private require(id: string): Artifact {
@@ -108,8 +123,10 @@ export class Tasks {
 			throw new Error(`task execution graph exceeds ${TASK_EXECUTION_MAX_NODES} nodes`);
 		}
 		const byId = new Map(tasks.map((task) => [task.id, task]));
+		const focusedId = this.focusStore.get();
 		const nodes = new Map(tasks.map((task) => [task.id, {
 			task,
+			active: task.id === focusedId,
 			parentIds: [] as string[],
 			childIds: [] as string[],
 			dependencyIds: [] as string[],
@@ -148,34 +165,63 @@ export class Tasks {
 		return this.artifacts.get(id, { tree: true })!;
 	}
 
+	active(): Artifact | null {
+		const id = this.focusStore.get();
+		if (!id) return null;
+		const task = this.artifacts.get(id);
+		if (!task || task.kind !== "task" || task.status === "done" || task.status === "canceled") {
+			this.focusStore.clear(id);
+			return null;
+		}
+		return task;
+	}
+
+	focus(id: string): Artifact {
+		const task = this.require(id);
+		if (task.status === "done" || task.status === "canceled") {
+			throw new Error(`cannot focus task from ${task.status}`);
+		}
+		this.focusStore.set(id);
+		return task;
+	}
+
 	transition(id: string, action: TaskTransition): Artifact {
 		const task = this.require(id);
 		const transition = TASK_TRANSITIONS[action];
-		if (!transition.from.includes(task.status)) throw new Error(`cannot ${action} task from ${task.status}`);
+		if (!transition.from.includes(task.status as TaskStatus)) throw new Error(`cannot ${action} task from ${task.status}`);
 		if (action === "start") {
 			const blocking = this.dependencyIds(id).filter((dependencyId) => this.require(dependencyId).status !== "done");
 			if (blocking.length > 0) throw new Error(`task "${id}" is blocked by dependencies: ${blocking.join(", ")}`);
+			this.focusStore.set(id);
 		}
-		return this.artifacts.setStatus(id, transition.to)!;
+		const updated = this.artifacts.setStatus(id, transition.to)!;
+		if (action === "start" || action === "retry") this.propagateProgressToAncestors(id);
+		if (action === "retry") this.focusStore.set(id);
+		if (action === "cancel") this.focusStore.clear(id);
+		return updated;
 	}
 
 	complete(id: string): TaskCompletion {
-		const task = this.requireActive(id);
+		const task = this.requireReview(id);
+		const checklist = this.reviewChecklist(task);
 		const results = this.gates.run(id);
-		if (results.some((gate) => !gate.passed)) {
-			return { artifact: task, gates: results, completed: false, started: [], blocked: [] };
+		if (results.some((gate) => !gate.passed) || checklist.some((item) => !item.accepted)) {
+			const artifact = this.artifacts.setStatus(id, "rejected")!;
+			return { artifact, gates: results, checklist, completed: false, focused: this.active(), blocked: [] };
 		}
-		return this.finish(id, results);
+		return this.finish(id, results, checklist);
 	}
 
 	async completeAsync(id: string): Promise<TaskCompletion> {
-		this.requireActive(id);
+		const task = this.requireReview(id);
+		const checklist = this.reviewChecklist(task);
 		const results = await this.gates.runAsync(id);
-		if (results.some((gate) => !gate.passed)) {
-			return { artifact: this.require(id), gates: results, completed: false, started: [], blocked: [] };
+		if (results.some((gate) => !gate.passed) || checklist.some((item) => !item.accepted)) {
+			const artifact = this.artifacts.setStatus(id, "rejected")!;
+			return { artifact, gates: results, checklist, completed: false, focused: this.active(), blocked: [] };
 		}
-		const current = this.requireActive(id);
-		return this.finish(current.id, results);
+		const current = this.requireReview(id);
+		return this.finish(current.id, results, checklist);
 	}
 
 	runGates(id: string): Promise<GateResult[]> {
@@ -226,6 +272,39 @@ export class Tasks {
 		return relationships;
 	}
 
+	private parentIds(id: string): string[] {
+		return this.relationships(id)
+			.flatMap((edge) => {
+				if (edge.relation === "part_of" && edge.from === id) return [edge.to];
+				if (edge.relation === "contains" && edge.to === id) return [edge.from];
+				return [];
+			})
+			.filter((parentId, index, ids) => ids.indexOf(parentId) === index);
+	}
+
+	private propagateProgressToAncestors(id: string): void {
+		const pending = this.parentIds(id);
+		const visited = new Set<string>();
+		while (pending.length > 0) {
+			const parentId = pending.shift()!;
+			if (visited.has(parentId)) continue;
+			if (visited.size >= TASK_EXECUTION_MAX_NODES) throw new Error("task ancestry exceeds execution node bound");
+			visited.add(parentId);
+			const parent = this.require(parentId);
+			if (parent.status === "todo") this.artifacts.setStatus(parentId, "in-progress");
+			pending.push(...this.parentIds(parentId));
+		}
+	}
+
+	private reviewChecklist(task: Artifact): ChecklistReview[] {
+		return checklistEntries(task.extra["checklist"]).map((entry) => ({
+			item: entry.item,
+			proof: entry.proof,
+			accepted: !entry.legacy && entry.proof.length > 0,
+			...((entry.legacy || entry.proof.length === 0) ? { reason: "typed proof reference required" } : {}),
+		}));
+	}
+
 	private dependencyIds(id: string): string[] {
 		const ids = this.relationships(id)
 			.filter((edge) => edge.relation === "depends_on" && edge.from === id)
@@ -236,7 +315,7 @@ export class Tasks {
 		return ids;
 	}
 
-	private finish(id: string, gates: GateResult[]): TaskCompletion {
+	private finish(id: string, gates: GateResult[], checklist: ChecklistReview[]): TaskCompletion {
 		const successorIds = this.relationships(id)
 			.filter((edge) => edge.relation === "depends_on" && edge.to === id)
 			.map((edge) => edge.from);
@@ -244,25 +323,29 @@ export class Tasks {
 			throw new Error(`task "${id}" exceeds ${TASK_EXECUTION_MAX_DEGREE} successors`);
 		}
 		const artifact = this.artifacts.setStatus(id, "done")!;
-		const started: Artifact[] = [];
+		this.focusStore.clear(id);
 		const blocked: TaskBlockage[] = [];
-		for (const successorId of successorIds) {
+		let focused: Artifact | null = null;
+		for (const successorId of [...successorIds].sort()) {
 			const successor = this.require(successorId);
-			if (successor.status !== "pending") continue;
+			if (successor.status === "done" || successor.status === "canceled") continue;
 			const dependencyIds = this.dependencyIds(successorId)
 				.filter((dependencyId) => this.require(dependencyId).status !== "done");
 			if (dependencyIds.length > 0) {
 				blocked.push({ artifact: successor, dependencyIds });
 				continue;
 			}
-			started.push(this.artifacts.setStatus(successorId, "active")!);
+			if (!focused) {
+				this.focusStore.set(successor.id);
+				focused = successor;
+			}
 		}
-		return { artifact, gates, completed: true, started, blocked };
+		return { artifact, gates, checklist, completed: true, focused, blocked };
 	}
 
-	private requireActive(id: string): Artifact {
+	private requireReview(id: string): Artifact {
 		const task = this.require(id);
-		if (task.status !== "active") throw new Error(`cannot complete task from ${task.status}`);
+		if (task.status !== "review") throw new Error(`cannot complete task from ${task.status}`);
 		return task;
 	}
 }