@danypops/papyrus 0.1.0 → 0.2.1

package/src/cli.ts

@@ -4,8 +4,12 @@ import { mkdirSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
+import { connectPapyrusClient, type PapyrusClient } from "./client.ts";
 import { DAEMON_UNIT_NAME } from "./constants.ts";
 import { serveMain } from "./daemon.ts";
+import type { GateResult } from "./domain/gate.ts";
+import type { TaskExecutionPlan } from "./task-execution.ts";
+import type { TaskBlockage, TaskCompletion } from "./task-service.ts";
 
 export interface SystemdUnitOptions {
 	bunBin: string;
@@ -49,14 +53,105 @@ function installService(): void {
 	systemctl("restart", DAEMON_UNIT_NAME);
 }
 
+const USAGE = `Usage:
+  papyrus serve
+  papyrus service <install|start|stop|restart|status>
+  papyrus tasks plan [--json]
+  papyrus tasks complete <id> [--json]
+  papyrus tasks start <id> [--json]
+  papyrus tasks depend <id> <prerequisite-id> [--json]`;
+
 function usage(): never {
-	console.error("Usage: papyrus serve | service <install|start|stop|restart|status>");
+	console.error(USAGE);
 	process.exit(2);
 }
 
-export function main(args: string[] = process.argv.slice(2)): void {
+type TaskCliClient = Pick<PapyrusClient, "call">;
+type CliArtifact = { id: string; title: string; status: string };
+type CliCompletion = Omit<TaskCompletion, "artifact" | "started" | "blocked"> & {
+	artifact: CliArtifact;
+	started: CliArtifact[];
+	blocked: Array<Omit<TaskBlockage, "artifact"> & { artifact: CliArtifact }>;
+	gates: GateResult[];
+};
+
+function artifactLabel(artifact: CliArtifact): string {
+	return `${artifact.id} ${artifact.title}`;
+}
+
+function planText(plan: TaskExecutionPlan): string {
+	const byId = new Map(plan.nodes.map((node) => [node.id, node]));
+	const lines = ["Execution order:"];
+	plan.layers.forEach((layer, index) => {
+		lines.push(`  Layer ${index + 1}:`);
+		for (const id of layer) {
+			const node = byId.get(id);
+			lines.push(node ? `    [${node.state}] ${node.id} ${node.title}` : `    [unknown] ${id}`);
+		}
+	});
+	if (plan.layers.length === 0) lines.push("  (no tasks)");
+	if (plan.cycleIds.length > 0) lines.push(`  Invalid cycle: ${plan.cycleIds.join(", ")}`);
+	return lines.join("\n");
+}
+
+export async function runTaskCli(args: string[], client: TaskCliClient): Promise<string> {
+	const json = args.includes("--json");
+	const positional = args.filter((arg) => arg !== "--json");
+	const [action, id, dependencyId] = positional;
+	let result: unknown;
+	let human: string;
+	switch (action) {
+		case "plan": {
+			if (id) throw new Error("tasks plan accepts no positional arguments");
+			const plan = await client.call<Record<string, never>, TaskExecutionPlan>("tasks.plan", {});
+			result = plan;
+			human = planText(plan);
+			break;
+		}
+		case "complete": {
+			if (!id || dependencyId) throw new Error("tasks complete requires exactly one task id");
+			const completion = await client.call<{ id: string }, CliCompletion>("tasks.complete", { id });
+			result = completion;
+			const lines = [`${completion.completed ? "Completed" : "Not completed"}: ${artifactLabel(completion.artifact)}`];
+			if (completion.started.length > 0) lines.push(`Started: ${completion.started.map(artifactLabel).join(", ")}`);
+			if (completion.blocked.length > 0) {
+				lines.push(`Blocked: ${completion.blocked.map((entry) => `${artifactLabel(entry.artifact)} waits for ${entry.dependencyIds.join(", ")}`).join("; ")}`);
+			}
+			for (const gate of completion.gates) lines.push(`${gate.passed ? "✓" : "✗"} ${gate.gate.type}: ${gate.gate.target} — ${gate.output}`);
+			human = lines.join("\n");
+			break;
+		}
+		case "start": {
+			if (!id || dependencyId) throw new Error("tasks start requires exactly one task id");
+			const artifact = await client.call<{ id: string }, CliArtifact>("tasks.start", { id });
+			result = artifact;
+			human = `Started: ${artifactLabel(artifact)}`;
+			break;
+		}
+		case "depend": {
+			if (!id || !dependencyId || positional.length !== 3) throw new Error("tasks depend requires a task id and prerequisite id");
+			const artifact = await client.call<{ id: string; dependency_id: string }, CliArtifact>("tasks.depend", {
+				id,
+				dependency_id: dependencyId,
+			});
+			result = artifact;
+			human = `Dependency added: ${artifactLabel(artifact)} waits for ${dependencyId}`;
+			break;
+		}
+		default:
+			throw new Error("tasks action must be plan, complete, start, or depend");
+	}
+	return json ? JSON.stringify(result) : human;
+}
+
+export async function main(args: string[] = process.argv.slice(2)): Promise<void> {
 	const [command, action] = args;
 	if (command === "serve") { serveMain(); return; }
+	if (command === "tasks") {
+		const client = await connectPapyrusClient();
+		console.log(await runTaskCli(args.slice(1), client));
+		return;
+	}
 	if (command !== "service") usage();
 	switch (action) {
 		case "install": installService(); break;
@@ -68,4 +163,9 @@ export function main(args: string[] = process.argv.slice(2)): void {
 	}
 }
 
-if (import.meta.main) main();
+if (import.meta.main) {
+	void main().catch((error) => {
+		console.error(error instanceof Error ? error.message : String(error));
+		process.exitCode = 1;
+	});
+}

package/src/constants.ts

@@ -1,5 +1,3 @@
-export const VERSION = "0.1.0";
-
 /** Long-running daemon transport and state. */
 export const DAEMON_HOST = "127.0.0.1";
 export const DAEMON_PORT_FILE = "port";
@@ -30,6 +28,14 @@ export const TASK_GRAPH_MIN_VISIBLE_LINES = 8;
 export const TASK_GRAPH_MAX_VISIBLE_LINES = 30;
 export const TASK_GRAPH_RESERVED_ROWS = 8;
 export const TASK_GRAPH_HORIZONTAL_PAN_COLUMNS = 4;
+/** Hard bounds for executable dependency DAG projection and cycle checks. */
+export const TASK_EXECUTION_MAX_NODES = 1_000;
+export const TASK_EXECUTION_MAX_EDGES = 10_000;
+export const TASK_EXECUTION_MAX_DEGREE = 100;
+/** Bounded automatic Pi continuations while active Papyrus Tasks remain. */
+export const TASK_DRIVER_ACTIVE_LIMIT = 4;
+export const TASK_DRIVER_MAX_TURNS = 20;
+export const TASK_DRIVER_MAX_UNCHANGED_TURNS = 6;
 export const GRAPH_RENDER_PADDING_X = 2;
 export const GRAPH_RENDER_PADDING_Y = 1;
 export const GRAPH_RENDER_BOX_PADDING = 0;
@@ -69,13 +75,13 @@ export function dbPath(): string {
  * rule  = Governance — context injection ("when doing X, follow Y").
  *         Maps to AGENTS.md semantics: active rules with inject:true are
  *         appended to the system prompt on before_agent_start.
- * skill = Procedural — "when using X,Y,Z do A,B,C" (richer SKILL.md metadata)
+ * skill = Parameterized workflow bundle — validated inputs render connected Task, Rule, and Doc collections.
  */
 export const SEED_KINDS = [
 	{ name: "doc", description: "Knowledge — descriptive reference (specs, decisions, research, designs)" },
 	{ name: "task", description: "Work — action items with gates, checklists, and dependencies" },
 	{ name: "rule", description: "Governance — context injection (when doing X, follow Y). Maps to AGENTS.md" },
-	{ name: "skill", description: "Procedural — when using X,Y,Z do A,B,C (SKILL.md metadata)" },
+	{ name: "skill", description: "Parameterized workflow bundle — inputs and templates load deterministic tasks plus contextual rules and docs" },
 ] as const;
 
 export const SEED_STATUSES = [

package/src/db.ts

@@ -80,7 +80,7 @@ const SEED_SQL = `
 INSERT OR IGNORE INTO kinds VALUES ('doc','Knowledge — what we know (specs, decisions, research, designs)');
 INSERT OR IGNORE INTO kinds VALUES ('task','Work — what we are doing (goals, steps, checklists)');
 INSERT OR IGNORE INTO kinds VALUES ('rule','Governance — when doing X, follow Y');
-INSERT OR IGNORE INTO kinds VALUES ('skill','Procedural — when using X,Y,Z do A,B,C');
+INSERT OR IGNORE INTO kinds VALUES ('skill','Parameterized workflow bundle — inputs and templates load tasks, rules, and docs');
 INSERT OR IGNORE INTO statuses VALUES ('draft','doc');
 INSERT OR IGNORE INTO statuses VALUES ('active','doc');
 INSERT OR IGNORE INTO statuses VALUES ('archived','doc');

package/src/domain/artifact.ts

@@ -53,4 +53,5 @@ export interface ArtifactLink {
 export interface RelationshipQuery {
 	kind?: string;
 	artifactIds?: string[];
+	limit?: number;
 }

package/src/domain/skill-definition.ts

@@ -0,0 +1,217 @@
+import { SEED_RELATIONS } from "../constants.ts";
+
+export type SkillArgumentValue = string | number | boolean;
+export type SkillInputType = "string" | "number" | "boolean";
+
+export interface SkillInputDefinition {
+	type: SkillInputType;
+	required?: boolean;
+	default?: SkillArgumentValue;
+	enum?: SkillArgumentValue[];
+}
+
+export interface SkillDocBlueprint {
+	ref: string;
+	title: string;
+	body?: string;
+	subtype?: string;
+	labels?: string[];
+	extra?: Record<string, unknown>;
+}
+
+export interface SkillRuleBlueprint {
+	ref: string;
+	title: string;
+	body?: string;
+	condition?: string;
+	action?: string;
+	severity?: "block" | "warn" | "info";
+	labels?: string[];
+	extra?: Record<string, unknown>;
+}
+
+export interface SkillTaskBlueprint {
+	ref: string;
+	title: string;
+	body?: string;
+	dependsOn?: string[];
+	parent?: string;
+	labels?: string[];
+	extra?: Record<string, unknown>;
+}
+
+export interface SkillBlueprints {
+	docs: SkillDocBlueprint[];
+	rules: SkillRuleBlueprint[];
+	tasks: SkillTaskBlueprint[];
+}
+
+export interface SkillBlueprintLink {
+	from: string;
+	relation: string;
+	to: string;
+}
+
+export interface SkillDefinition {
+	version: 1;
+	inputs: Record<string, SkillInputDefinition>;
+	blueprints: SkillBlueprints;
+	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 RELATIONS = new Set<string>(SEED_RELATIONS);
+
+function record(value: unknown, label: string): Record<string, unknown> {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) throw new Error(`${label} must be an object`);
+	return value as Record<string, unknown>;
+}
+
+function array(value: unknown, label: string): unknown[] {
+	if (!Array.isArray(value)) throw new Error(`${label} must be an array`);
+	return value;
+}
+
+function string(value: unknown, label: string): string {
+	if (typeof value !== "string" || value.length === 0) throw new Error(`${label} must be a non-empty string`);
+	return value;
+}
+
+function validateArgumentValue(name: string, type: SkillInputType, value: unknown): SkillArgumentValue {
+	if (typeof value !== type || (type === "number" && !Number.isFinite(value))) {
+		throw new Error(`skill argument "${name}" must be a ${type}`);
+	}
+	return value as SkillArgumentValue;
+}
+
+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}`);
+	const result: Record<string, SkillInputDefinition> = {};
+	for (const [name, raw] of entries) {
+		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`);
+		const type = input["type"] as SkillInputType;
+		if (input["required"] !== undefined && typeof input["required"] !== "boolean") {
+			throw new Error(`skill input "${name}" required must be boolean`);
+		}
+		const normalized: SkillInputDefinition = { type };
+		if (input["required"] !== undefined) normalized.required = input["required"] as boolean;
+		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`);
+			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`);
+			}
+		}
+		result[name] = normalized;
+	}
+	return result;
+}
+
+function validateBlueprint<T extends { ref: string; title: string }>(value: unknown, kind: string): T {
+	const source = record(value, `skill ${kind} blueprint`);
+	const ref = string(source["ref"], `skill ${kind} blueprint ref`);
+	if (!NAME_PATTERN.test(ref)) throw new Error(`invalid skill blueprint ref "${ref}"`);
+	const title = string(source["title"], `skill ${kind} blueprint title`);
+	return { ...source, ref, title } as T;
+}
+
+function placeholders(value: unknown, result: Set<string> = new Set()): Set<string> {
+	if (typeof value === "string") {
+		for (const match of value.matchAll(PLACEHOLDER_PATTERN)) result.add(match[1]!);
+	} else if (Array.isArray(value)) {
+		for (const entry of value) placeholders(entry, result);
+	} else if (typeof value === "object" && value !== null) {
+		for (const entry of Object.values(value)) placeholders(entry, result);
+	}
+	return result;
+}
+
+function assertAcyclic(tasks: SkillTaskBlueprint[]): void {
+	const byRef = new Map(tasks.map((task) => [task.ref, task]));
+	const visiting = new Set<string>();
+	const visited = new Set<string>();
+	const visit = (ref: string): void => {
+		if (visiting.has(ref)) throw new Error(`skill task dependency cycle includes "${ref}"`);
+		if (visited.has(ref)) return;
+		visiting.add(ref);
+		for (const dependency of byRef.get(ref)?.dependsOn ?? []) visit(dependency);
+		visiting.delete(ref);
+		visited.add(ref);
+	};
+	for (const task of tasks) visit(task.ref);
+}
+
+export function validateSkillDefinition(value: unknown): SkillDefinition {
+	const source = record(value, "skill definition");
+	if (source["version"] !== 1) throw new Error("skill definition version must be 1");
+	const inputs = validateInputs(source["inputs"]);
+	const rawBlueprints = record(source["blueprints"], "skill blueprints");
+	const docs = array(rawBlueprints["docs"] ?? [], "skill doc blueprints").map((entry) => validateBlueprint<SkillDocBlueprint>(entry, "doc"));
+	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`);
+	const refs = new Set<string>();
+	for (const blueprint of all) {
+		if (refs.has(blueprint.ref)) throw new Error(`duplicate skill blueprint ref "${blueprint.ref}"`);
+		refs.add(blueprint.ref);
+	}
+	for (const task of tasks) {
+		if (task.dependsOn !== undefined && !Array.isArray(task.dependsOn)) throw new Error(`skill task "${task.ref}" dependsOn must be an array`);
+		for (const dependency of task.dependsOn ?? []) {
+			if (!tasks.some((candidate) => candidate.ref === dependency)) throw new Error(`unknown skill task dependency ref "${dependency}"`);
+		}
+		if (task.parent !== undefined && !tasks.some((candidate) => candidate.ref === task.parent)) {
+			throw new Error(`unknown skill task parent ref "${task.parent}"`);
+		}
+	}
+	assertAcyclic(tasks);
+	for (const name of placeholders(all)) {
+		if (!(name in inputs)) throw new Error(`unknown skill input placeholder "${name}"`);
+	}
+	const links = array(source["links"] ?? [], "skill links").map((entry) => {
+		const link = record(entry, "skill link");
+		const from = string(link["from"], "skill link from");
+		const relation = string(link["relation"], "skill link relation");
+		const to = string(link["to"], "skill link to");
+		if (!refs.has(from)) throw new Error(`unknown skill blueprint ref "${from}"`);
+		if (!refs.has(to)) throw new Error(`unknown skill blueprint ref "${to}"`);
+		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}`);
+	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}"`);
+	}
+	const result: Record<string, SkillArgumentValue> = {};
+	for (const [name, input] of Object.entries(definition.inputs)) {
+		const raw = source[name] ?? input.default;
+		if (raw === undefined) {
+			if (input.required) throw new Error(`missing required skill argument "${name}"`);
+			continue;
+		}
+		const normalized = validateArgumentValue(name, input.type, raw);
+		if (input.enum && !input.enum.includes(normalized)) {
+			throw new Error(`skill argument "${name}" must be one of: ${input.enum.join(", ")}`);
+		}
+		result[name] = normalized;
+	}
+	return result;
+}

package/src/{facades.ts → domain-services.ts}

@@ -192,7 +192,7 @@ export function showSkill(artifacts: ArtifactStore, id: string): Artifact {
 export function skillInvocation(artifacts: ArtifactStore, id: string): string {
 	const skill = requireKind(artifacts, id, "skill");
 	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 facade instantiate action.`;
+		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.`;
 	}
 	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") : [];

package/src/service.ts

@@ -1,4 +1,5 @@
-import { SERVICE_MAX_BODY_BYTES, VERSION } from "./constants.ts";
+import { SERVICE_MAX_BODY_BYTES } from "./constants.ts";
+import { VERSION } from "./version.ts";
 import { openDb } from "./db.ts";
 import { SQLiteArtifactStore } from "./adapters/sqlite-artifact-store.ts";
 import { SQLiteGateRunner } from "./adapters/sqlite-gate-runner.ts";
@@ -6,6 +7,7 @@ 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 {
 	createArtifactTemplate,
@@ -27,7 +29,7 @@ import {
 	transitionRule,
 	transitionSkill,
 	type DocumentRelation,
-} from "./facades.ts";
+} from "./domain-services.ts";
 import { taskContext } from "./task-context.ts";
 
 export const EXPECTED_OPERATION_NAMES = [
@@ -42,6 +44,7 @@ export const EXPECTED_OPERATION_NAMES = [
 	"tasks.create",
 	"tasks.list",
 	"tasks.graph",
+	"tasks.plan",
 	"tasks.show",
 	"tasks.start",
 	"tasks.complete",
@@ -131,7 +134,14 @@ function handlers(artifacts: ArtifactStore, gates: GateRunner, tasks: Tasks): Re
 			maxNodes: optionalNumber(input, "max_nodes") ?? optionalNumber(input, "maxNodes"),
 		}),
 		"graph.link": (input) => {
-			artifacts.link({ from: string(input, "from"), relation: string(input, "relation"), to: string(input, "to") });
+			const from = string(input, "from");
+			const relation = string(input, "relation");
+			const to = string(input, "to");
+			if (relation === "depends_on" && artifacts.get(from)?.kind === "task" && artifacts.get(to)?.kind === "task") {
+				tasks.depend(from, to);
+			} else {
+				artifacts.link({ from, relation, to });
+			}
 			return { ok: true };
 		},
 		"graph.tree": (input) => artifacts.get(string(input, "id"), {
@@ -157,6 +167,7 @@ function handlers(artifacts: ArtifactStore, gates: GateRunner, tasks: Tasks): Re
 		}),
 		"tasks.list": (input) => tasks.list(taskFilter(input)),
 		"tasks.graph": (input) => tasks.graph(taskFilter(input)),
+		"tasks.plan": (input) => projectTaskExecution(tasks.graph(taskFilter(input))),
 		"tasks.show": (input) => tasks.show(string(input, "id")),
 		"tasks.start": (input) => tasks.transition(string(input, "id"), "start"),
 		"tasks.complete": (input) => tasks.completeAsync(string(input, "id")),

package/src/task-execution.ts

@@ -0,0 +1,124 @@
+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 interface TaskExecutionNode {
+	id: string;
+	title: string;
+	status: string;
+	state: TaskExecutionState;
+	layer: number | null;
+	prerequisiteIds: string[];
+	successorIds: string[];
+}
+
+export interface TaskExecutionPlan {
+	nodes: TaskExecutionNode[];
+	layers: string[][];
+	cycleIds: string[];
+}
+
+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";
+	return "blocked";
+}
+
+function assertBounds(graph: TaskGraph): void {
+	if (graph.nodes.length > TASK_EXECUTION_MAX_NODES) {
+		throw new Error(`task execution graph exceeds ${TASK_EXECUTION_MAX_NODES} nodes`);
+	}
+	for (const node of graph.nodes) {
+		if (node.dependencyIds.length > TASK_EXECUTION_MAX_DEGREE) {
+			throw new Error(`task "${node.task.id}" exceeds ${TASK_EXECUTION_MAX_DEGREE} prerequisites`);
+		}
+	}
+	const edgeCount = graph.nodes.reduce((count, node) => count + node.dependencyIds.length, 0);
+	if (edgeCount > TASK_EXECUTION_MAX_EDGES) {
+		throw new Error(`task execution graph exceeds ${TASK_EXECUTION_MAX_EDGES} dependency edges`);
+	}
+}
+
+/** Build deterministic topological layers ordered by creation time and task ID. */
+export function projectTaskExecution(graph: TaskGraph): TaskExecutionPlan {
+	assertBounds(graph);
+	const orderedNodes = [...graph.nodes].sort((left, right) =>
+		left.task.created_at.localeCompare(right.task.created_at) || left.task.id.localeCompare(right.task.id));
+	const byId = new Map(orderedNodes.map((node) => [node.task.id, node]));
+	const order = new Map(orderedNodes.map((node, index) => [node.task.id, index]));
+	const successors = new Map(orderedNodes.map((node) => [node.task.id, [] as string[]]));
+	const inDegree = new Map<string, number>();
+
+	for (const node of orderedNodes) {
+		const prerequisites = node.dependencyIds.filter((id) => byId.has(id));
+		inDegree.set(node.task.id, prerequisites.length);
+		for (const prerequisiteId of prerequisites) {
+			const dependentIds = successors.get(prerequisiteId)!;
+			if (dependentIds.length >= TASK_EXECUTION_MAX_DEGREE) {
+				throw new Error(`task "${prerequisiteId}" exceeds ${TASK_EXECUTION_MAX_DEGREE} successors`);
+			}
+			dependentIds.push(node.task.id);
+		}
+	}
+
+	let current = orderedNodes.filter((node) => inDegree.get(node.task.id) === 0).map((node) => node.task.id);
+	const layers: string[][] = [];
+	const processed = new Set<string>();
+	const layerById = new Map<string, number>();
+	while (current.length > 0) {
+		const layer = [...current].sort((left, right) => order.get(left)! - order.get(right)!);
+		layers.push(layer);
+		const next: string[] = [];
+		for (const id of layer) {
+			processed.add(id);
+			layerById.set(id, layers.length - 1);
+			for (const successorId of successors.get(id) ?? []) {
+				const remaining = inDegree.get(successorId)! - 1;
+				inDegree.set(successorId, remaining);
+				if (remaining === 0) next.push(successorId);
+			}
+		}
+		current = next;
+	}
+
+	const cycleIds = orderedNodes.map((node) => node.task.id).filter((id) => !processed.has(id));
+	const cycleSet = new Set(cycleIds);
+	return {
+		layers,
+		cycleIds,
+		nodes: orderedNodes.map((node) => {
+			const prerequisiteIds = node.dependencyIds.filter((id) => byId.has(id));
+			const prerequisitesDone = prerequisiteIds.every((id) => byId.get(id)!.task.status === "done");
+			const state = executionState(node.task.status, cycleSet.has(node.task.id), prerequisitesDone);
+			return {
+				id: node.task.id,
+				title: node.task.title,
+				status: node.task.status,
+				state,
+				layer: layerById.get(node.task.id) ?? null,
+				prerequisiteIds,
+				successorIds: successors.get(node.task.id) ?? [],
+			};
+		}),
+	};
+}
+
+/** Reject a dependency edge when the prerequisite already reaches the dependent. */
+export function assertDependencyEdgeAllowed(graph: TaskGraph, id: string, dependencyId: string): void {
+	assertBounds(graph);
+	if (id === dependencyId) throw new Error(`task "${id}" cannot depend on itself`);
+	const byId = new Map(graph.nodes.map((node) => [node.task.id, node]));
+	if (!byId.has(id) || !byId.has(dependencyId)) throw new Error("dependency endpoints must be present in the task graph");
+
+	const pending = [dependencyId];
+	const visited = new Set<string>();
+	while (pending.length > 0) {
+		const current = pending.pop()!;
+		if (current === id) throw new Error(`dependency cycle: "${id}" cannot depend on "${dependencyId}"`);
+		if (visited.has(current)) continue;
+		visited.add(current);
+		for (const prerequisiteId of byId.get(current)?.dependencyIds ?? []) pending.push(prerequisiteId);
+	}
+}

package/src/task-graph-view.ts

@@ -1,7 +1,17 @@
 import type { DisplayGraph, DisplayGraphEdge } from "./domain/display-graph.ts";
+import { projectTaskExecution, type TaskExecutionState } from "./task-execution.ts";
 import type { TaskGraph } from "./task-service.ts";
 
-export type TaskGraphView = "dependencies" | "composition";
+export type TaskGraphView = "execution" | "dependencies" | "composition";
+
+const EXECUTION_GLYPHS: Record<TaskExecutionState, string> = {
+	done: "■",
+	active: "●",
+	ready: "◇",
+	blocked: "○",
+	failed: "▲",
+	invalid: "!",
+};
 
 export function projectTaskGraph(graph: TaskGraph, view: TaskGraphView): DisplayGraph {
 	const edges: DisplayGraphEdge[] = [];
@@ -14,7 +24,7 @@ export function projectTaskGraph(graph: TaskGraph, view: TaskGraphView): Display
 	};
 
 	for (const node of graph.nodes) {
-		if (view === "dependencies") {
+		if (view === "execution" || view === "dependencies") {
 			for (const dependencyId of node.dependencyIds) {
 				addEdge({ from: dependencyId, to: node.task.id, label: "unlocks" });
 			}
@@ -23,12 +33,21 @@ export function projectTaskGraph(graph: TaskGraph, view: TaskGraphView): Display
 		}
 	}
 
-	const connected = new Set(edges.flatMap((edge) => [edge.from, edge.to]));
+	const connected = view === "execution"
+		? new Set(graph.nodes.map((node) => node.task.id))
+		: new Set(edges.flatMap((edge) => [edge.from, edge.to]));
+	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}`,
+			status: node.state,
+		}))
+		: graph.nodes
+			.filter((node) => connected.has(node.task.id))
+			.map((node) => ({ id: node.task.id, label: node.task.title, status: node.task.status }));
 	return {
 		direction: "TD",
-		nodes: graph.nodes
-			.filter((node) => connected.has(node.task.id))
-			.map((node) => ({ id: node.task.id, label: node.task.title, status: node.task.status })),
+		nodes,
 		edges: edges.filter((edge) => connected.has(edge.from) && connected.has(edge.to)),
 	};
 }