@danypops/papyrus 0.4.0 → 0.6.0

package/src/skill-execution.ts

@@ -9,9 +9,11 @@ import {
 	type SkillDefinition,
 } from "./domain/skill-definition.ts";
 import type { ArtifactStore } from "./ports/artifact-store.ts";
+import type { TaskEventContext } from "./domain/task-event.ts";
+import type { TaskEventStore } from "./ports/task-event-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";
+import type { TaskGraph, TaskNode, TaskStatus } 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*}}$/;
@@ -115,6 +117,7 @@ export function instantiateSkillWorkflow(
 	artifacts: ArtifactStore,
 	skillId: string,
 	input: InstantiateSkillWorkflowInput = {},
+	history?: { events: TaskEventStore; context?: TaskEventContext },
 ): SkillWorkflowRunResult {
 	const { definition } = requireWorkflowSkill(artifacts, skillId);
 	const arguments_ = resolveSkillArguments(definition, input.arguments);
@@ -138,7 +141,7 @@ export function instantiateSkillWorkflow(
 	}
 
 	const atomic = requireAtomicArtifactStore(artifacts);
-	return atomic.atomic(() => {
+	const persist = () => atomic.atomic(() => {
 		const docs = rendered.blueprints.docs.map((blueprint) => artifacts.create({
 			id: ids.get(blueprint.ref),
 			kind: "doc",
@@ -163,14 +166,26 @@ export function instantiateSkillWorkflow(
 				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 } },
-		}));
+		const tasks = rendered.blueprints.tasks.map((blueprint) => {
+			const task = 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 } },
+			});
+			if (history) history.events.append({
+				taskId: task.id,
+				type: "created",
+				actor: history.context?.actor ?? "system",
+				source: history.context?.source ?? "skill-run",
+				toStatus: task.status as TaskStatus,
+				...(history.context?.sessionId === undefined ? {} : { sessionId: history.context.sessionId }),
+				...(history.context?.reason === undefined ? {} : { reason: history.context.reason }),
+			});
+			return task;
+		});
 
 		for (const blueprint of rendered.blueprints.tasks) {
 			const id = ids.get(blueprint.ref)!;
@@ -201,4 +216,5 @@ export function instantiateSkillWorkflow(
 			execution: projectTaskExecution(executionGraph(tasks, rendered, ids)),
 		};
 	});
+	return history ? history.events.atomic(persist) : persist();
 }

package/src/task-automation.ts

@@ -0,0 +1,188 @@
+import {
+	TASK_AUTOMATION_ERROR_ID_MAX_LENGTH,
+	TASK_AUTOMATION_ERROR_MESSAGE_MAX_LENGTH,
+	TASK_AUTOMATION_GATE_CONCURRENCY,
+	TASK_AUTOMATION_HARD_MAX_RUNTIME_MS,
+	TASK_AUTOMATION_HARD_MAX_TASKS_PER_SWEEP,
+	TASK_AUTOMATION_INTERVAL_MS,
+	TASK_AUTOMATION_MAX_CANDIDATE_SCAN,
+	TASK_AUTOMATION_MAX_GATE_CONCURRENCY,
+	TASK_AUTOMATION_MAX_INTERVAL_MS,
+	TASK_AUTOMATION_MAX_RUNTIME_MS,
+	TASK_AUTOMATION_MAX_TASKS_PER_SWEEP,
+	TASK_AUTOMATION_MIN_INTERVAL_MS,
+} from "./constants.ts";
+import type { Artifact } from "./domain/artifact.ts";
+import { projectTaskExecution } from "./task-execution.ts";
+import type { Tasks } from "./task-service.ts";
+
+export interface TaskAutomationSettings {
+	enabled: boolean;
+	intervalMs: number;
+	maxTasksPerSweep: number;
+	gateConcurrency: number;
+	maxRuntimeMs: number;
+}
+
+export interface TaskAutomationResult {
+	skipped?: "disabled" | "in-flight";
+	examined: number;
+	completed: number;
+	rejected: number;
+	started: number;
+	errors: Array<{ taskId: string; message: string }>;
+	timedOut: boolean;
+}
+
+function boundedInteger(
+	env: Record<string, string | undefined>,
+	name: string,
+	fallback: number,
+	minimum: number,
+	maximum: number,
+): number {
+	const source = env[name];
+	if (source === undefined || source === "") return fallback;
+	const value = Number(source);
+	if (!Number.isInteger(value) || value < minimum || value > maximum) {
+		throw new Error(`${name} must be an integer between ${minimum} and ${maximum}`);
+	}
+	return value;
+}
+
+export function taskAutomationSettings(env: Record<string, string | undefined> = process.env): TaskAutomationSettings {
+	const enabled = env["PAPYRUS_AUTOMATION_ENABLED"] === "1";
+	if (env["PAPYRUS_AUTOMATION_ENABLED"] !== undefined && env["PAPYRUS_AUTOMATION_ENABLED"] !== "0" && !enabled) {
+		throw new Error("PAPYRUS_AUTOMATION_ENABLED must be 0 or 1");
+	}
+	return {
+		enabled,
+		intervalMs: boundedInteger(env, "PAPYRUS_AUTOMATION_INTERVAL_MS", TASK_AUTOMATION_INTERVAL_MS, TASK_AUTOMATION_MIN_INTERVAL_MS, TASK_AUTOMATION_MAX_INTERVAL_MS),
+		maxTasksPerSweep: boundedInteger(env, "PAPYRUS_AUTOMATION_MAX_TASKS", TASK_AUTOMATION_MAX_TASKS_PER_SWEEP, 1, TASK_AUTOMATION_HARD_MAX_TASKS_PER_SWEEP),
+		gateConcurrency: boundedInteger(env, "PAPYRUS_AUTOMATION_GATE_CONCURRENCY", TASK_AUTOMATION_GATE_CONCURRENCY, 1, TASK_AUTOMATION_MAX_GATE_CONCURRENCY),
+		maxRuntimeMs: boundedInteger(env, "PAPYRUS_AUTOMATION_MAX_RUNTIME_MS", TASK_AUTOMATION_MAX_RUNTIME_MS, 1, TASK_AUTOMATION_HARD_MAX_RUNTIME_MS),
+	};
+}
+
+function automationEnabled(task: Artifact): boolean {
+	const automation = task.extra["automation"];
+	return typeof automation === "object"
+		&& automation !== null
+		&& !Array.isArray(automation)
+		&& (automation as Record<string, unknown>)["enabled"] === true;
+}
+
+function emptyResult(skipped?: TaskAutomationResult["skipped"]): TaskAutomationResult {
+	return { ...(skipped ? { skipped } : {}), examined: 0, completed: 0, rejected: 0, started: 0, errors: [], timedOut: false };
+}
+
+function boundedError(taskId: string, error: unknown): TaskAutomationResult["errors"][number] {
+	const message = error instanceof Error ? error.message : String(error);
+	return {
+		taskId: taskId.slice(0, TASK_AUTOMATION_ERROR_ID_MAX_LENGTH),
+		message: message.slice(0, TASK_AUTOMATION_ERROR_MESSAGE_MAX_LENGTH),
+	};
+}
+
+export interface TaskAutomationScheduler {
+	setInterval(callback: () => void, intervalMs: number): unknown;
+	clearInterval(handle: unknown): void;
+}
+
+const SYSTEM_SCHEDULER: TaskAutomationScheduler = {
+	setInterval: (callback, intervalMs) => setInterval(callback, intervalMs),
+	clearInterval: (handle) => clearInterval(handle as ReturnType<typeof setInterval>),
+};
+
+export function scheduleTaskAutomation(
+	settings: TaskAutomationSettings,
+	sweep: () => Promise<unknown>,
+	onError: (error: unknown) => void,
+	scheduler: TaskAutomationScheduler = SYSTEM_SCHEDULER,
+): () => void {
+	if (!settings.enabled) return () => {};
+	const handle = scheduler.setInterval(() => { void sweep().catch(onError); }, settings.intervalMs);
+	return () => scheduler.clearInterval(handle);
+}
+
+export class TaskAutomationReconciler {
+	private inFlight = false;
+
+	constructor(
+		private readonly tasks: Tasks,
+		private readonly settings: TaskAutomationSettings,
+		private readonly now: () => number = () => Date.now(),
+	) {}
+
+	status(): TaskAutomationSettings & { inFlight: boolean } {
+		return { ...this.settings, inFlight: this.inFlight };
+	}
+
+	async reconcile(): Promise<TaskAutomationResult> {
+		if (!this.settings.enabled) return emptyResult("disabled");
+		if (this.inFlight) return emptyResult("in-flight");
+		this.inFlight = true;
+		try { return await this.runSweep(); }
+		finally { this.inFlight = false; }
+	}
+
+	private async runSweep(): Promise<TaskAutomationResult> {
+		const result = emptyResult();
+		const deadline = this.now() + this.settings.maxRuntimeMs;
+		const candidates = this.tasks.list({ status: "review", limit: TASK_AUTOMATION_MAX_CANDIDATE_SCAN })
+			.filter(automationEnabled)
+			.sort((left, right) => left.id.localeCompare(right.id))
+			.slice(0, this.settings.maxTasksPerSweep);
+		const completedIds = new Set<string>();
+
+		for (let offset = 0; offset < candidates.length; offset += this.settings.gateConcurrency) {
+			if (this.now() >= deadline) { result.timedOut = true; break; }
+			const batch = candidates.slice(offset, offset + this.settings.gateConcurrency);
+			await Promise.all(batch.map(async (task) => {
+				result.examined += 1;
+				try {
+					const completion = await this.tasks.completeAsync(task.id, {
+						actor: "daemon",
+						source: "automation-reconciler",
+						reason: "automation-enabled review reconciliation",
+					}, { focusSuccessor: false, gateDeadlineMs: deadline });
+					if (completion.completed) {
+						result.completed += 1;
+						completedIds.add(task.id);
+					} else result.rejected += 1;
+				} catch (error) {
+					result.errors.push(boundedError(task.id, error));
+				}
+			}));
+		}
+
+		let remaining = Math.max(0, this.settings.maxTasksPerSweep - result.examined);
+		if (remaining > 0 && completedIds.size > 0 && this.now() < deadline) {
+			let graph: ReturnType<Tasks["graph"]>;
+			try { graph = this.tasks.graph(); }
+			catch (error) {
+				result.errors.push(boundedError("graph", error));
+				return result;
+			}
+			const stateById = new Map(projectTaskExecution(graph).nodes.map((node) => [node.id, node.state]));
+			for (const node of [...graph.nodes].sort((left, right) => left.task.id.localeCompare(right.task.id))) {
+				if (remaining === 0 || this.now() >= deadline) break;
+				if (node.task.status !== "todo" || !automationEnabled(node.task) || stateById.get(node.task.id) !== "ready") continue;
+				if (!node.dependencyIds.some((id) => completedIds.has(id))) continue;
+				try {
+					this.tasks.transition(node.task.id, "start", {
+						actor: "daemon",
+						source: "automation-reconciler",
+						reason: "automation-enabled successor became ready",
+					});
+					result.started += 1;
+					remaining -= 1;
+				} catch (error) {
+					result.errors.push(boundedError(node.task.id, error));
+				}
+			}
+		}
+		if (this.now() >= deadline) result.timedOut = true;
+		return result;
+	}
+}

package/src/task-service.ts

@@ -2,9 +2,11 @@ import { TASK_EXECUTION_MAX_DEGREE, TASK_EXECUTION_MAX_EDGES, TASK_EXECUTION_MAX
 import type { Artifact } from "./domain/artifact.ts";
 import { checklistEntries, validateChecklist, type Checklist, type ProofReference } from "./domain/checklist.ts";
 import type { Gate, GateResult } from "./domain/gate.ts";
+import type { AppendTaskEvent, TaskEventContext, TaskHistoryPage, TaskHistoryQuery, TaskLifecycleStatus } from "./domain/task-event.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 { InMemoryTaskEventStore, type TaskEventStore } from "./ports/task-event-store.ts";
 import { assertDependencyEdgeAllowed } from "./task-execution.ts";
 
 export interface TaskFilter {
@@ -13,11 +15,13 @@ export interface TaskFilter {
 	limit?: number;
 }
 
-export type TaskStatus = "todo" | "in-progress" | "review" | "rejected" | "done" | "canceled";
+export type TaskStatus = TaskLifecycleStatus;
 
 export interface CreateTaskInput {
+	id?: string;
 	title: string;
 	body?: string;
+	subtype?: string;
 	status?: TaskStatus;
 	labels?: string[];
 	extra?: Record<string, unknown>;
@@ -42,6 +46,11 @@ export interface ChecklistReview {
 	reason?: string;
 }
 
+export interface TaskCompletionOptions {
+	focusSuccessor?: boolean;
+	gateDeadlineMs?: number;
+}
+
 export interface TaskCompletion {
 	artifact: Artifact;
 	gates: GateResult[];
@@ -77,6 +86,7 @@ export class Tasks {
 		private readonly artifacts: ArtifactStore,
 		private readonly gates: GateRunner,
 		private readonly focusStore: TaskFocusStore = new InMemoryTaskFocusStore(),
+		private readonly events: TaskEventStore = new InMemoryTaskEventStore(),
 	) {}
 
 	private require(id: string): Artifact {
@@ -86,27 +96,32 @@ export class Tasks {
 		return artifact;
 	}
 
-	create(input: CreateTaskInput): Artifact {
-		if ((input.dependsOn?.length ?? 0) > TASK_EXECUTION_MAX_DEGREE) {
-			throw new Error(`task cannot exceed ${TASK_EXECUTION_MAX_DEGREE} prerequisites`);
-		}
-		if (input.parentId) this.require(input.parentId);
-		for (const dependency of input.dependsOn ?? []) this.require(dependency);
-		const extra: Record<string, unknown> = { ...(input.extra ?? {}) };
-		if (input.gates !== undefined) extra["gates"] = input.gates;
-		if (input.checklist !== undefined) extra["checklist"] = validateChecklist(input.checklist);
-		const task = this.artifacts.create({
-			kind: "task",
-			title: input.title,
-			body: input.body,
-			status: input.status,
-			labels: input.labels,
-			extra,
-			templateId: input.templateId,
+	create(input: CreateTaskInput, context: TaskEventContext = {}): Artifact {
+		return this.events.atomic(() => {
+			if ((input.dependsOn?.length ?? 0) > TASK_EXECUTION_MAX_DEGREE) {
+				throw new Error(`task cannot exceed ${TASK_EXECUTION_MAX_DEGREE} prerequisites`);
+			}
+			if (input.parentId) this.require(input.parentId);
+			for (const dependency of input.dependsOn ?? []) this.require(dependency);
+			const extra: Record<string, unknown> = { ...(input.extra ?? {}) };
+			if (input.gates !== undefined) extra["gates"] = input.gates;
+			if (input.checklist !== undefined) extra["checklist"] = validateChecklist(input.checklist);
+			const task = this.artifacts.create({
+				id: input.id,
+				kind: "task",
+				title: input.title,
+				body: input.body,
+				subtype: input.subtype,
+				status: input.status,
+				labels: input.labels,
+				extra,
+				templateId: input.templateId,
+			});
+			if (input.parentId) this.contain(input.parentId, task.id);
+			for (const dependency of input.dependsOn ?? []) this.depend(task.id, dependency);
+			this.appendEvent({ taskId: task.id, type: "created", toStatus: task.status as TaskStatus }, context);
+			return this.show(task.id);
 		});
-		if (input.parentId) this.contain(input.parentId, task.id);
-		for (const dependency of input.dependsOn ?? []) this.depend(task.id, dependency);
-		return this.show(task.id);
 	}
 
 	list(filter: TaskFilter = {}): Artifact[] {
@@ -185,48 +200,55 @@ export class Tasks {
 		return task;
 	}
 
-	transition(id: string, action: TaskTransition): Artifact {
-		const task = this.require(id);
-		const transition = TASK_TRANSITIONS[action];
-		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);
-		}
-		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;
+	transition(id: string, action: TaskTransition, context: TaskEventContext = {}): Artifact {
+		return this.events.atomic(() => {
+			const task = this.require(id);
+			const transition = TASK_TRANSITIONS[action];
+			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);
+			}
+			const updated = this.artifacts.setStatus(id, transition.to)!;
+			const eventType = { start: "started", submit: "submitted", reject: "review_rejected", retry: "retried", cancel: "canceled" }[action] as AppendTaskEvent["type"];
+			this.appendEvent({ taskId: id, type: eventType, fromStatus: task.status as TaskStatus, toStatus: transition.to }, context);
+			if (action === "start" || action === "retry") this.propagateProgressToAncestors(id, context);
+			if (action === "retry") this.focusStore.set(id);
+			if (action === "cancel") this.focusStore.clear(id);
+			return updated;
+		});
 	}
 
-	complete(id: string): TaskCompletion {
+	complete(id: string, context: TaskEventContext = {}, options: TaskCompletionOptions = {}): TaskCompletion {
 		const task = this.requireReview(id);
+		const attemptId = crypto.randomUUID();
+		this.events.atomic(() => this.appendEvent({ taskId: id, type: "completion_attempted", fromStatus: "review", toStatus: "review", attemptId }, context));
 		const checklist = this.reviewChecklist(task);
 		const results = this.gates.run(id);
-		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, checklist);
+		return this.resolveCompletion(id, attemptId, results, checklist, context, options);
 	}
 
-	async completeAsync(id: string): Promise<TaskCompletion> {
+	async completeAsync(id: string, context: TaskEventContext = {}, options: TaskCompletionOptions = {}): Promise<TaskCompletion> {
 		const task = this.requireReview(id);
+		const attemptId = crypto.randomUUID();
+		this.events.atomic(() => this.appendEvent({ taskId: id, type: "completion_attempted", fromStatus: "review", toStatus: "review", attemptId }, context));
 		const checklist = this.reviewChecklist(task);
+		const results = await this.gates.runAsync(id, { deadlineMs: options.gateDeadlineMs });
+		this.requireReview(id);
+		return this.resolveCompletion(id, attemptId, results, checklist, context, options);
+	}
+
+	async runGates(id: string, context: TaskEventContext = {}): Promise<GateResult[]> {
+		this.require(id);
 		const results = await this.gates.runAsync(id);
-		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.requireReview(id);
-		return this.finish(current.id, results, checklist);
+		this.events.atomic(() => this.appendEvent({ taskId: id, type: "gates_evaluated", evidence: { gates: results, result: results.every((gate) => gate.passed) ? "passed" : "failed" } }, context));
+		return results;
 	}
 
-	runGates(id: string): Promise<GateResult[]> {
+	history(id: string, query: TaskHistoryQuery = {}): TaskHistoryPage {
 		this.require(id);
-		return this.gates.runAsync(id);
+		return this.events.history(id, query);
 	}
 
 	setChecklist(id: string, checklist: Checklist): Artifact {
@@ -234,6 +256,19 @@ export class Tasks {
 		return this.artifacts.setExtra(id, { ...task.extra, checklist: validateChecklist(checklist) })!;
 	}
 
+	setAutomation(id: string, enabled: boolean, context: TaskEventContext = {}): Artifact {
+		return this.events.atomic(() => {
+			const task = this.require(id);
+			const current = task.extra["automation"];
+			const automation = typeof current === "object" && current !== null && !Array.isArray(current)
+				? current as Record<string, unknown>
+				: {};
+			const updated = this.artifacts.setExtra(id, { ...task.extra, automation: { ...automation, enabled } })!;
+			this.appendEvent({ taskId: id, type: enabled ? "automation_enabled" : "automation_disabled" }, context);
+			return updated;
+		});
+	}
+
 	depend(id: string, dependencyId: string): Artifact {
 		this.require(id);
 		this.require(dependencyId);
@@ -282,7 +317,7 @@ export class Tasks {
 			.filter((parentId, index, ids) => ids.indexOf(parentId) === index);
 	}
 
-	private propagateProgressToAncestors(id: string): void {
+	private propagateProgressToAncestors(id: string, context: TaskEventContext): void {
 		const pending = this.parentIds(id);
 		const visited = new Set<string>();
 		while (pending.length > 0) {
@@ -291,7 +326,14 @@ export class Tasks {
 			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");
+			if (parent.status === "todo") {
+				this.artifacts.setStatus(parentId, "in-progress");
+				this.appendEvent({ taskId: parentId, type: "started", fromStatus: "todo", toStatus: "in-progress" }, {
+					...context,
+					source: "task-ancestry",
+					reason: `nested task ${id} entered progress`,
+				});
+			}
 			pending.push(...this.parentIds(parentId));
 		}
 	}
@@ -315,7 +357,33 @@ export class Tasks {
 		return ids;
 	}
 
-	private finish(id: string, gates: GateResult[], checklist: ChecklistReview[]): TaskCompletion {
+	private resolveCompletion(
+		id: string,
+		attemptId: string,
+		gates: GateResult[],
+		checklist: ChecklistReview[],
+		context: TaskEventContext,
+		options: TaskCompletionOptions,
+	): TaskCompletion {
+		const failed = gates.some((gate) => !gate.passed) || checklist.some((item) => !item.accepted);
+		if (failed) {
+			return this.events.atomic(() => {
+				const artifact = this.artifacts.setStatus(id, "rejected")!;
+				this.appendEvent({
+					taskId: id,
+					type: "review_rejected",
+					fromStatus: "review",
+					toStatus: "rejected",
+					attemptId,
+					evidence: { gates, checklist, result: "rejected" },
+				}, context);
+				return { artifact, gates, checklist, completed: false, focused: this.active(), blocked: [] };
+			});
+		}
+		return this.events.atomic(() => this.finish(id, attemptId, gates, checklist, context, options));
+	}
+
+	private finish(id: string, attemptId: string, gates: GateResult[], checklist: ChecklistReview[], context: TaskEventContext, options: TaskCompletionOptions): TaskCompletion {
 		const successorIds = this.relationships(id)
 			.filter((edge) => edge.relation === "depends_on" && edge.to === id)
 			.map((edge) => edge.from);
@@ -323,6 +391,14 @@ export class Tasks {
 			throw new Error(`task "${id}" exceeds ${TASK_EXECUTION_MAX_DEGREE} successors`);
 		}
 		const artifact = this.artifacts.setStatus(id, "done")!;
+		this.appendEvent({
+			taskId: id,
+			type: "completed",
+			fromStatus: "review",
+			toStatus: "done",
+			attemptId,
+			evidence: { gates, checklist, result: "completed" },
+		}, context);
 		this.focusStore.clear(id);
 		const blocked: TaskBlockage[] = [];
 		let focused: Artifact | null = null;
@@ -335,7 +411,7 @@ export class Tasks {
 				blocked.push({ artifact: successor, dependencyIds });
 				continue;
 			}
-			if (!focused) {
+			if (options.focusSuccessor !== false && !focused) {
 				this.focusStore.set(successor.id);
 				focused = successor;
 			}
@@ -343,6 +419,16 @@ export class Tasks {
 		return { artifact, gates, checklist, completed: true, focused, blocked };
 	}
 
+	private appendEvent(event: Omit<AppendTaskEvent, "actor" | "source">, context: TaskEventContext): void {
+		this.events.append({
+			...event,
+			actor: context.actor ?? "system",
+			source: context.source ?? "task-domain",
+			...(context.sessionId === undefined ? {} : { sessionId: context.sessionId }),
+			...(context.reason === undefined ? {} : { reason: context.reason }),
+		});
+	}
+
 	private requireReview(id: string): Artifact {
 		const task = this.require(id);
 		if (task.status !== "review") throw new Error(`cannot complete task from ${task.status}`);