@danypops/papyrus 0.1.0 → 0.2.0

package/README.md

@@ -1,6 +1,6 @@
 # Papyrus
 
-Graph artifact service for Pi — enforced SQLite schema, domain facades, and native interactive frontends.
+Graph artifact service for Pi — enforced SQLite schema, domain tools and services, and native interactive frontends.
 
 Artifacts are rows in SQLite. Edges are typed relations. Kinds and relations are **registered and enforced**—the schema is the protocol. A supervised Bun daemon is the sole database owner; Pi extensions and other clients use its authenticated loopback service API.
 
@@ -9,7 +9,7 @@ Artifacts are rows in SQLite. Edges are typed relations. Kinds and relations are
 ```text
 Pi tools + TUI
       ↓
-tasks / docs / rules / skills facades
+tasks / docs / rules / skills domain tools
       ↓
 Papyrus client → authenticated loopback daemon
       ↓
@@ -18,7 +18,7 @@ operation registry + lifecycle services
 graph-store operations → SQLite (WAL)
 ```
 
-The `papyrus_*` tools remain low-level administration escape hatches. Normal agent work should use the domain facade tools.
+The `papyrus_*` tools remain low-level administration escape hatches. Normal agent work should use the domain tools.
 
 ## Storage and service
 
@@ -31,6 +31,12 @@ $XDG_RUNTIME_DIR/papyrus/{port,token}   # private daemon discovery
 bun src/cli.ts service install   # install, enable, and start user service
 bun src/cli.ts service status
 bun src/cli.ts service restart
+
+# Authenticated daemon-backed task automation (add --json for machine output)
+papyrus tasks plan
+papyrus tasks depend <task-id> <prerequisite-id>
+papyrus tasks start <task-id>
+papyrus tasks complete <task-id>
 ```
 
 For repository work, install the versioned ownership guard once:
@@ -50,17 +56,19 @@ Papyrus enforces four artifact kinds:
 - `doc` — knowledge: specifications, decisions, and research
 - `task` — work: desired outcomes, gates, checklists, and dependencies
 - `rule` — governance injected into the Pi system prompt
-- `skill` — reusable procedural knowledge
+- `skill` — a parameterized workflow bundle whose validated arguments render a connected collection of deterministic Tasks plus contextual Rules and Docs
 
 Each kind has an enforced status vocabulary. Every edge endpoint must exist, and every edge relation must be registered in `relation_names`. Relations are universal: any artifact kind can link to any other kind.
 
 ### Hierarchy and traversal
 
-Use `contains` and `part_of` for explicit parent/child structure; use `depends_on` for execution ordering. Graph reads are cycle-safe and bounded by `depth` and `max_nodes` (defaults: depth 4, 100 nodes; hard ceilings: depth 20, 1,000 nodes).
+Use `contains` and `part_of` for explicit parent/child structure; use `depends_on` for execution ordering. Dependency edges form an executable DAG: self-dependencies and cycles are rejected, fan-in waits for every prerequisite, and fan-out may activate several successors. Graph reads are cycle-safe and bounded by `depth` and `max_nodes` (defaults: depth 4, 100 nodes; hard ceilings: depth 20, 1,000 nodes). Executable task plans are additionally bounded to 1,000 tasks and 10,000 relationships.
+
+### Skills and compatibility templates
 
-### Artifact templates
+A Papyrus Skill is distinct from a conventional prompt-only skill: its input API and templates define a connected Task/Rule/Doc workflow. Task dependencies and gates provide deterministic execution; Rules provide scoped governance; Docs provide invocation context and provenance. The versioned workflow-instantiation API is tracked as active Papyrus work.
 
-Templates remain inside the four-kind model: create a `skill` with subtype `artifact-template` and metadata `{targetKind, defaults, required}`. Instantiate it through `papyrus_create` with `template_id`; defaults merge recursively, explicit arrays replace defaults, required paths such as `extra.owner` are validated, and target-kind mismatches are rejected.
+The existing `artifact-template` skill subtype remains a compatibility mechanism for one-artifact templates with metadata `{targetKind, defaults, required}`. Instantiate it through `papyrus_create` with `template_id`; defaults merge recursively, explicit arrays replace defaults, required paths such as `extra.owner` are validated, and target-kind mismatches are rejected.
 
 ## Tools
 
@@ -71,9 +79,9 @@ The `papyrus_*` tools are the low-level graph-store API:
 - **`papyrus_graph`** — link artifacts, perform bounded traversal, or update status
 - **`papyrus_show`** — read nested metadata and bounded edges, optionally running gates
 
-Agent-facing facade tools own domain lifecycle invariants and sit above this store API:
+Agent-facing domain tools own lifecycle invariants and sit above this store API:
 
-- **`tasks`** — create/list/show, replace evidence-bearing checklists, hierarchy/dependencies, start/fail/retry, non-blocking gates, and gate-enforced completion
+- **`tasks`** — create/list/show/plan, replace evidence-bearing checklists, hierarchy/dependencies, start/fail/retry, non-blocking gates, and gate-enforced completion with automatic activation of newly ready successors
 - **`docs`** — create/list/show, activate/archive/reopen, and document-safe graph links
 - **`rules`** — create/list/show/preview, enable/disable, and attach governance gates to tasks
 - **`skills`** — create/list/show/invoke, enable/disable, create templates, and instantiate templates
@@ -98,7 +106,9 @@ Run `/tasks` for the interactive task panel:
 - `/` filters; arrow keys navigate; Enter opens task actions
 - `g` opens the programmatic Unicode graph; Tab switches dependency/composition views and arrow keys pan
 - advance the `pending → active → done` lifecycle or retry `failed → pending`
-- inspect a nested task hierarchy, composition, dependencies, evidence-bearing checklists, and verification gates
+- completing an active task runs only that task’s gates; success marks it done and activates every direct pending successor whose full prerequisite set is done
+- successors are never auto-completed: each must pass its own gates; fan-in, fan-out, diamonds, and disconnected DAGs remain explicit
+- inspect deterministic execution layers, readiness, a nested task hierarchy, composition, dependencies, evidence-bearing checklists, and verification gates
 - Show details keeps Checklist and Validation gates separate from incidental Metadata, then renders relationships as a Unicode graph footer; `↑/↓` scrolls and `←/→` pans wide graphs
 - the compact persistent widget shows active work in containment order, indents active children beneath active parents, and points to `/tasks` for the complete graph
 
@@ -119,6 +129,8 @@ Proof types are `file`, `symbol`, `code`, `test`, `command`, `artifact`, and `ur
 
 Papyrus also injects an Alef-style reconciliation block on every agent turn while work remains: `Current`, `Desired`, `Verify`, and `Next`. The agent is explicitly instructed to ask **“Did we accomplish this task?”** and run gates before marking it done. The injection disappears when every task is complete.
 
+In TUI and RPC modes, the extension checks bounded active Tasks at Pi’s public `agent_settled` lifecycle boundary. If active work remains and no continuation is already pending, it queues one hidden next turn so the agent continues instead of handing off merely because a low-level run ended. Driving is single-flight and pauses after 20 automatic turns or 6 unchanged task snapshots. Use `/task-drive on`, `/task-drive off`, or `/task-drive status`; human input and task progress reset the bounded counters.
+
 ## Why
 
 Papyrus keeps SQLite’s local simplicity while centralizing writes, migrations, lifecycle invariants, gate execution, and maintenance in one small supervised process. The loopback bearer token prevents unrelated local HTTP callers from mutating the graph, while the native Pi extension provides richer domain tools and TUI integration.

package/extension/src/{facade-tools.ts → domain-tools.ts}

@@ -3,6 +3,8 @@ import { Type } from "typebox";
 import type { Artifact } from "../../src/domain/artifact.ts";
 import { PROOF_TYPES } from "../../src/domain/checklist.ts";
 import type { GateResult } from "../../src/domain/gate.ts";
+import type { TaskExecutionPlan } from "../../src/task-execution.ts";
+import type { TaskCompletion } from "../../src/task-service.ts";
 import { callService } from "./service-client.ts";
 
 function text(message: string, details: Record<string, unknown> = {}) {
@@ -23,11 +25,11 @@ const checklistCriterionSchema = Type.Object({
 	proof: Type.Array(proofReferenceSchema, { minItems: 1 }),
 });
 
-export function registerFacadeTools(pi: ExtensionAPI): void {
+export function registerDomainTools(pi: ExtensionAPI): void {
 	pi.registerTool({
 		name: "tasks",
 		label: "Tasks",
-		description: "Task domain facade. ACTIONS: create, list, show, start, complete (runs gates and refuses done on failure), fail, retry, run_gates, set_checklist, depend, contain. Checklist is an item-to-proof map; every item requires one or more typed evidence references. Prefer this over low-level papyrus_* tools for task work.",
+		description: "Task domain tool. ACTIONS: create, list, show, plan, start, complete (runs gates, refuses done on failure, and starts newly ready successors), fail, retry, run_gates, set_checklist, depend, contain. Dependency graphs support deterministic execution layers, fan-in, and fan-out; cycles are rejected. Checklist is an item-to-proof map; every item requires one or more typed evidence references. Prefer this over low-level papyrus_* tools for task work.",
 		parameters: Type.Object({
 			action: Type.String(),
 			id: Type.Optional(Type.String()),
@@ -61,14 +63,31 @@ export function registerFacadeTools(pi: ExtensionAPI): void {
 					const artifact = await callService<Record<string, unknown>, Artifact>("tasks.show", params);
 					return text(`${artifactLine(artifact)}\n\n${artifact.body}`, { artifact });
 				}
+				if (action === "plan") {
+					const plan = await callService<Record<string, unknown>, TaskExecutionPlan>("tasks.plan", params);
+					const byId = new Map(plan.nodes.map((node) => [node.id, node]));
+					const lines = plan.layers.flatMap((layer, index) => [
+						`Layer ${index + 1}`,
+						...layer.map((id) => {
+							const node = byId.get(id);
+							return node ? `  [${node.state}] ${node.id} ${node.title}` : `  [unknown] ${id}`;
+						}),
+					]);
+					if (plan.cycleIds.length > 0) lines.push(`Invalid cycle: ${plan.cycleIds.join(", ")}`);
+					return text(lines.join("\n") || "No tasks in execution plan.", { plan });
+				}
 				if (action === "set_checklist") {
 					const artifact = await callService<Record<string, unknown>, Artifact>("tasks.set_checklist", params);
 					return text(`Updated checklist: ${artifactLine(artifact)}`, { artifact });
 				}
 				if (action === "complete") {
-					const result = await callService<Record<string, unknown>, { artifact: Artifact; gates: GateResult[]; completed: boolean }>("tasks.complete", params);
+					const result = await callService<Record<string, unknown>, TaskCompletion>("tasks.complete", params);
 					const gates = result.gates.map((gate) => `${gate.passed ? "✓" : "✗"} ${gate.gate.type}: ${gate.gate.target} — ${gate.output}`).join("\n");
-					return text(`${result.completed ? "Completed" : "Not completed"}: ${artifactLine(result.artifact)}${gates ? `\n${gates}` : ""}`, { ...result });
+					const started = result.started.length > 0 ? `\nStarted: ${result.started.map(artifactLine).join(", ")}` : "";
+					const blocked = result.blocked.length > 0
+						? `\nBlocked: ${result.blocked.map((entry) => `${artifactLine(entry.artifact)} waits for ${entry.dependencyIds.join(", ")}`).join("; ")}`
+						: "";
+					return text(`${result.completed ? "Completed" : "Not completed"}: ${artifactLine(result.artifact)}${started}${blocked}${gates ? `\n${gates}` : ""}`, { ...result });
 				}
 				if (action === "run_gates") {
 					const gates = await callService<Record<string, unknown>, GateResult[]>("tasks.run_gates", params);
@@ -88,7 +107,7 @@ export function registerFacadeTools(pi: ExtensionAPI): void {
 	pi.registerTool({
 		name: "docs",
 		label: "Documents",
-		description: "Document domain facade. ACTIONS: create, list, show, activate, archive, reopen, link. Prefer this over low-level papyrus_* tools for document work.",
+		description: "Document domain tool. ACTIONS: create, list, show, activate, archive, reopen, link. Prefer this over low-level papyrus_* tools for document work.",
 		parameters: Type.Object({
 			action: Type.String(),
 			id: Type.Optional(Type.String()),
@@ -133,7 +152,7 @@ export function registerFacadeTools(pi: ExtensionAPI): void {
 	pi.registerTool({
 		name: "rules",
 		label: "Rules",
-		description: "Rule domain facade. ACTIONS: create, list, show, preview, enable, disable, gate. Active rules inject into the agent system prompt.",
+		description: "Rule domain tool. ACTIONS: create, list, show, preview, enable, disable, gate. Active rules inject into the agent system prompt.",
 		parameters: Type.Object({
 			action: Type.String(), id: Type.Optional(Type.String()), title: Type.Optional(Type.String()),
 			body: Type.Optional(Type.String()), condition: Type.Optional(Type.String()), rule_action: Type.Optional(Type.String()),
@@ -170,7 +189,7 @@ export function registerFacadeTools(pi: ExtensionAPI): void {
 	pi.registerTool({
 		name: "skills",
 		label: "Skills",
-		description: "Skill and artifact-template domain facade. ACTIONS: create, create_template, list, show, invoke, enable, disable, instantiate.",
+		description: "Papyrus Skill workflow and compatibility-template domain tool. Papyrus Skills are parameterized Task/Rule/Doc bundles, distinct from prompt-only skills. ACTIONS: create, create_template, list, show, invoke, enable, disable, instantiate.",
 		parameters: Type.Object({
 			action: Type.String(), id: Type.Optional(Type.String()), title: Type.Optional(Type.String()),
 			body: Type.Optional(Type.String()), trigger: Type.Optional(Type.String()), steps: Type.Optional(Type.Array(Type.String())),

package/extension/src/index.ts

@@ -7,15 +7,21 @@
  * Injection: active rules + open tasks appended to system prompt every turn.
  *             "Are we there yet?" — the agent sees its open work items.
  */
-import type { ExtensionAPI, ExtensionUIContext, Theme } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI, ExtensionContext, ExtensionUIContext, Theme } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import { truncateToWidth } from "@earendil-works/pi-tui";
+import {
+	TASK_DRIVER_ACTIVE_LIMIT,
+	TASK_DRIVER_MAX_TURNS,
+	TASK_DRIVER_MAX_UNCHANGED_TURNS,
+} from "../../src/constants.ts";
 import type { Artifact } from "../../src/domain/artifact.ts";
 import type { GateResult } from "../../src/domain/gate.ts";
 import { formatMetadata } from "./artifact-format.ts";
 import { callService } from "./service-client.ts";
-import { registerFacadeTools } from "./facade-tools.ts";
+import { registerDomainTools } from "./domain-tools.ts";
 import type { TaskGraph } from "../../src/task-service.ts";
+import { TaskDriver, type ActiveTaskMarker } from "./task-driver.ts";
 import { buildTaskWidgetProjection } from "./task-widget.ts";
 
 function text(t: string, details: Record<string, unknown> = {}) {
@@ -130,7 +136,63 @@ class TaskOverlay {
 // ---------------------------------------------------------------------------
 
 export default async function (pi: ExtensionAPI) {
-	registerFacadeTools(pi);
+	registerDomainTools(pi);
+	const taskDriver = new TaskDriver({
+		maxTurns: TASK_DRIVER_MAX_TURNS,
+		maxUnchangedTurns: TASK_DRIVER_MAX_UNCHANGED_TURNS,
+	});
+
+	const driveActiveTasks = async (ctx: ExtensionContext): Promise<void> => {
+		if (ctx.mode !== "tui" && ctx.mode !== "rpc") return;
+		try {
+			const active = await callService<Record<string, unknown>, ActiveTaskMarker[]>("tasks.list", {
+				status: "active",
+				limit: TASK_DRIVER_ACTIVE_LIMIT,
+			});
+			const decision = taskDriver.evaluate(active, {
+				idle: ctx.isIdle(),
+				pendingMessages: ctx.hasPendingMessages(),
+			});
+			if (decision.action === "continue" && decision.prompt) {
+				pi.sendMessage({
+					customType: "papyrus-task-continuation",
+					content: decision.prompt,
+					display: false,
+				}, { triggerTurn: true, deliverAs: "nextTurn" });
+			} else if (decision.action === "pause" && ctx.hasUI) {
+				ctx.ui.notify(`Papyrus task driving paused: ${decision.reason}. Use /task-drive on to resume.`, "warning");
+			}
+		} catch {
+			// The daemon may be unavailable during startup, reload, or shutdown.
+		}
+	};
+
+	pi.registerCommand("task-drive", {
+		description: "Control bounded automatic continuation while active Papyrus Tasks remain",
+		handler: async (args, ctx) => {
+			const action = args.trim().toLowerCase() || "status";
+			if (action === "on") {
+				taskDriver.setEnabled(true);
+				ctx.ui.notify("Papyrus task driving enabled", "info");
+				await driveActiveTasks(ctx);
+				return;
+			}
+			if (action === "off") {
+				taskDriver.setEnabled(false);
+				ctx.ui.notify("Papyrus task driving disabled", "info");
+				return;
+			}
+			if (action !== "status") {
+				ctx.ui.notify("Usage: /task-drive <on|off|status>", "warning");
+				return;
+			}
+			const status = taskDriver.status();
+			ctx.ui.notify(
+				`Papyrus task driving: ${status.enabled ? "on" : "off"} · ${status.consecutiveTurns}/${TASK_DRIVER_MAX_TURNS} automatic turns${status.pausedReason ? ` · paused: ${status.pausedReason}` : ""}`,
+				"info",
+			);
+		},
+	});
 
 	// ── Low-level graph-store tools ────────────────────────────────────
 
@@ -140,10 +202,10 @@ export default async function (pi: ExtensionAPI) {
 		description:
 			"Create a graph artifact. KINDS: doc (knowledge — specs, decisions, research), " +
 			"task (work — with gates/checklists in extra), rule (governance — when doing X, follow Y; " +
-			"active rules inject into the system prompt), skill (procedural — when using X do A,B,C). " +
+			"active rules inject into the system prompt), skill (parameterized workflow bundle — validated inputs render connected Tasks, Rules, and Docs). " +
 			"RULE extra: {condition, action, severity: 'block'|'warn'|'info'}. " +
 			"TASK extra: {gates: [{type:'file-exists'|'contains'|'command'|'test', target, expect}], checklist: {'criterion': {proof: [{type:'file'|'symbol'|'code'|'test'|'command'|'artifact'|'url', target, expect}]}}}. " +
-			"SKILL extra: {trigger, steps: [...], tools: [...]}. " +
+			"Legacy SKILL extra: {trigger, steps: [...], tools: [...]}. Workflow Skill schemas are versioned separately. " +
 			"Templates are skills with subtype='artifact-template' and extra {targetKind, defaults, required}; pass template_id to instantiate.",
 		parameters: Type.Object({
 			kind: Type.Optional(Type.String({ description: "doc | task | rule | skill; optional when template_id supplies targetKind" })),
@@ -326,6 +388,16 @@ export default async function (pi: ExtensionAPI) {
 		}
 	});
 
+	// ── Keep driving active work after Pi has exhausted built-in continuations ──
+	// agent_settled is intentionally later than agent_end: Pi guarantees that
+	// retry, compaction retry, and queued follow-up processing have finished.
+
+	pi.on("input", (event) => {
+		if (event.source !== "extension") taskDriver.onHumanInput();
+	});
+	pi.on("agent_start", () => { taskDriver.onAgentStart(); });
+	pi.on("agent_settled", async (_event, ctx) => { await driveActiveTasks(ctx); });
+
 	// ── "Are we there yet?" — inject active tasks into every turn ──────
 	// The agent sees its open work items every turn. If there are failed
 	// tasks, they're explicitly called out — the agent should address them.

package/extension/src/task-driver.ts

@@ -0,0 +1,132 @@
+export interface ActiveTaskMarker {
+	id: string;
+	title: string;
+	updated_at: string;
+}
+
+export interface TaskDriverOptions {
+	maxTurns: number;
+	maxUnchangedTurns: number;
+}
+
+export interface TaskDriverState {
+	enabled: boolean;
+	queued: boolean;
+	consecutiveTurns: number;
+	unchangedTurns: number;
+	pausedReason?: string;
+}
+
+export interface TaskDriverDecision {
+	action: "continue" | "wait" | "pause";
+	reason: string;
+	prompt?: string;
+}
+
+const DISPLAYED_TASK_LIMIT = 3;
+const TITLE_LIMIT = 120;
+
+function fingerprint(tasks: ActiveTaskMarker[]): string {
+	return [...tasks]
+		.sort((left, right) => left.id.localeCompare(right.id))
+		.map((task) => `${task.id}:${task.updated_at}`)
+		.join("|");
+}
+
+function continuationPrompt(tasks: ActiveTaskMarker[]): string {
+	const names = tasks.slice(0, DISPLAYED_TASK_LIMIT).map((task) => `- ${task.id}: ${task.title.slice(0, TITLE_LIMIT)}`);
+	return [
+		"Continue active Papyrus work now; do not hand off merely because the previous Pi run settled.",
+		"Reconcile the active Tasks, choose the next concrete action, use tools, run gates before completion, and continue until done, blocked, or the bounded task driver pauses.",
+		"Active tasks:",
+		...names,
+	].join("\n");
+}
+
+export class TaskDriver {
+	private enabled = true;
+	private queued = false;
+	private consecutiveTurns = 0;
+	private unchangedTurns = 0;
+	private lastFingerprint: string | undefined;
+	private pausedReason: string | undefined;
+
+	constructor(private readonly options: TaskDriverOptions) {
+		if (!Number.isInteger(options.maxTurns) || options.maxTurns < 1) throw new Error("maxTurns must be a positive integer");
+		if (!Number.isInteger(options.maxUnchangedTurns) || options.maxUnchangedTurns < 1) {
+			throw new Error("maxUnchangedTurns must be a positive integer");
+		}
+	}
+
+	evaluate(tasks: ActiveTaskMarker[], context: { idle: boolean; pendingMessages: boolean }): TaskDriverDecision {
+		if (!this.enabled) return { action: "wait", reason: "disabled" };
+		if (!context.idle) return { action: "wait", reason: "Pi is not settled" };
+		if (context.pendingMessages) return { action: "wait", reason: "Pi already has pending messages" };
+		if (this.queued) return { action: "wait", reason: "continuation already queued" };
+		if (tasks.length === 0) {
+			this.resetProgress();
+			return { action: "wait", reason: "no active tasks" };
+		}
+
+		const currentFingerprint = fingerprint(tasks);
+		if (currentFingerprint !== this.lastFingerprint) {
+			this.lastFingerprint = currentFingerprint;
+			this.unchangedTurns = 0;
+			this.pausedReason = undefined;
+		} else {
+			this.unchangedTurns += 1;
+		}
+
+		if (this.consecutiveTurns >= this.options.maxTurns) {
+			return this.pause(`automatic turn limit reached (${this.options.maxTurns})`);
+		}
+		if (this.unchangedTurns >= this.options.maxUnchangedTurns) {
+			return this.pause(`no task progress after ${this.options.maxUnchangedTurns} automatic turns`);
+		}
+
+		this.queued = true;
+		this.consecutiveTurns += 1;
+		return {
+			action: "continue",
+			reason: "active tasks remain",
+			prompt: continuationPrompt(tasks),
+		};
+	}
+
+	onAgentStart(): void {
+		this.queued = false;
+	}
+
+	onHumanInput(): void {
+		this.resetProgress();
+	}
+
+	setEnabled(enabled: boolean): void {
+		this.enabled = enabled;
+		if (enabled) this.resetProgress();
+		else this.queued = false;
+	}
+
+	status(): TaskDriverState {
+		return {
+			enabled: this.enabled,
+			queued: this.queued,
+			consecutiveTurns: this.consecutiveTurns,
+			unchangedTurns: this.unchangedTurns,
+			...(this.pausedReason ? { pausedReason: this.pausedReason } : {}),
+		};
+	}
+
+	private pause(reason: string): TaskDriverDecision {
+		this.pausedReason = reason;
+		return { action: "pause", reason };
+	}
+
+	private resetProgress(): void {
+		this.queued = false;
+		this.consecutiveTurns = 0;
+		this.unchangedTurns = 0;
+		this.lastFingerprint = undefined;
+		this.pausedReason = undefined;
+	}
+}

package/extension/src/task-graph.ts

@@ -11,7 +11,7 @@ import { projectTaskGraph, type TaskGraphView } from "../../src/task-graph-view.
 import type { TaskGraph } from "../../src/task-service.ts";
 import { BeautifulMermaidRenderer } from "./beautiful-mermaid-renderer.ts";
 
-const GRAPH_VIEWS: TaskGraphView[] = ["dependencies", "composition"];
+const GRAPH_VIEWS: TaskGraphView[] = ["execution", "dependencies", "composition"];
 
 export class TaskGraphViewport {
 	private viewIndex = 0;
@@ -88,8 +88,8 @@ export async function showTaskGraph(
 	renderer: GraphRenderer = new BeautifulMermaidRenderer(),
 ): Promise<void> {
 	if (ctx.mode !== "tui") {
-		const rendered = renderer.render(projectTaskGraph(graph, "dependencies"));
-		ctx.ui.notify(rendered.lines.join("\n") || "No task dependency relationships", "info");
+		const rendered = renderer.render(projectTaskGraph(graph, "execution"));
+		ctx.ui.notify(rendered.lines.join("\n") || "No tasks in the execution graph", "info");
 		return;
 	}
 	await ctx.ui.custom<void>((tui, theme, _keybindings, done) =>

package/extension/src/tasks.ts

@@ -14,13 +14,17 @@ export { taskDetailsText } from "./task-detail-format.ts";
 export { showTaskDetails } from "./task-detail-view.ts";
 import type { Artifact } from "../../src/domain/artifact.ts";
 import type { GateResult } from "../../src/domain/gate.ts";
-import type { TaskGraph } from "../../src/task-service.ts";
+import { projectTaskExecution } from "../../src/task-execution.ts";
+import type { TaskCompletion, TaskGraph } from "../../src/task-service.ts";
 
 const GLYPHS: Record<string, string> = {
 	pending: "○",
+	ready: "◇",
+	blocked: "○",
 	active: "●",
 	done: "■",
 	failed: "▲",
+	invalid: "!",
 };
 
 const STATUS_ACTIONS: Record<string, string[]> = {
@@ -105,10 +109,19 @@ export async function showTasks(ctx: ExtensionCommandContext): Promise<void> {
 			try {
 				const operation = choice === "Start" ? "tasks.start" : choice === "Fail" ? "tasks.fail" : choice === "Retry" ? "tasks.retry" : "tasks.complete";
 				if (operation === "tasks.complete") {
-					const result = await callService<Record<string, unknown>, { artifact: Artifact; gates: GateResult[]; completed: boolean }>(operation, { id: action.row.id });
+					const result = await callService<Record<string, unknown>, TaskCompletion>(operation, { id: action.row.id });
 					action.row.status = result.artifact.status;
 					const gates = result.gates.map((gate) => `${gate.passed ? "✓" : "✗"} ${gate.gate.type}: ${gate.gate.target}`).join("\n");
-					ctx.ui.notify(result.completed ? `Completed ${result.artifact.id}${gates ? `\n${gates}` : ""}` : `Not complete; gates failed\n${gates}`, result.completed ? "info" : "warning");
+					const started = result.started.length > 0 ? `\nStarted: ${result.started.map((task) => task.title).join(", ")}` : "";
+					const blocked = result.blocked.length > 0
+						? `\nWaiting: ${result.blocked.map((entry) => `${entry.artifact.title} needs ${entry.dependencyIds.join(", ")}`).join("; ")}`
+						: "";
+					ctx.ui.notify(
+						result.completed
+							? `Completed ${result.artifact.id}${started}${blocked}${gates ? `\n${gates}` : ""}`
+							: `Not complete; gates failed\n${gates}`,
+						result.completed ? "info" : "warning",
+					);
 				} else {
 					const updated = await callService<Record<string, unknown>, Artifact>(operation, { id: action.row.id });
 					action.row.status = updated.status;
@@ -133,6 +146,7 @@ function renderPanel(ctx: ExtensionCommandContext, graph: TaskGraph): Promise<Pa
 		const searchInput = new Input();
 		const hierarchy = buildTaskHierarchy(graph);
 		const taskById = new Map(rows.map((task) => [task.id, task]));
+		const executionById = new Map(projectTaskExecution(graph).nodes.map((node) => [node.id, node]));
 		let searchActive = false;
 		let filtered = [...hierarchy];
 		let selectedIndex = 0;
@@ -148,10 +162,10 @@ function renderPanel(ctx: ExtensionCommandContext, graph: TaskGraph): Promise<Pa
 
 		function statusLine(): string {
 			const counts: Record<string, number> = {};
-			for (const r of rows) counts[r.status] = (counts[r.status] ?? 0) + 1;
-			return ["pending", "active", "done", "failed"]
-				.filter((s) => (counts[s] ?? 0) > 0)
-				.map((s) => `${GLYPHS[s] ?? s} ${counts[s]} ${s}`)
+			for (const node of executionById.values()) counts[node.state] = (counts[node.state] ?? 0) + 1;
+			return ["ready", "active", "blocked", "done", "failed", "invalid"]
+				.filter((state) => (counts[state] ?? 0) > 0)
+				.map((state) => `${GLYPHS[state] ?? state} ${counts[state]} ${state}`)
 				.join(", ");
 		}
 
@@ -196,14 +210,17 @@ function renderPanel(ctx: ExtensionCommandContext, graph: TaskGraph): Promise<Pa
 					const row = entry.task;
 					const selected = i === selectedIndex;
 					const cursor = selected ? theme.fg("accent", "❯") : " ";
-					const glyph = GLYPHS[row.status] ?? "?";
-					const statusColor = row.status === "active" ? "accent" : row.status === "done" ? "dim" : row.status === "failed" ? "warning" : "muted";
+					const execution = executionById.get(row.id);
+					const state = execution?.state ?? row.status;
+					const glyph = GLYPHS[state] ?? "?";
+					const statusColor = state === "active" || state === "ready" ? "accent" : state === "done" ? "dim" : state === "failed" || state === "invalid" ? "warning" : "muted";
 					const glyphStyled = theme.fg(statusColor, glyph);
 					const title = selected ? theme.bold(row.title) : row.title;
 					const indent = "  ".repeat(entry.depth);
 					const node = entry.childCount > 0 ? theme.fg("accent", "▾") : theme.fg("dim", "·");
 					const gates = (row.extra?.["gates"] as any[])?.length;
 					const relationParts: string[] = [];
+					if (execution) relationParts.push(execution.layer === null ? state : `layer ${execution.layer + 1} · ${state}`);
 					if (entry.childCount > 0) relationParts.push(`${entry.childCount} subtask${entry.childCount === 1 ? "" : "s"}`);
 					if (entry.dependencies.length > 0) {
 						const names = entry.dependencies.map((id) => taskById.get(id)?.title ?? id);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danypops/papyrus",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Daemon-backed graph artifacts, evidence-bearing tasks, rules, skills, and native TUI workflows for Pi",
   "type": "module",
   "keywords": ["pi-package"],

package/src/adapters/sqlite-artifact-store.ts

@@ -52,6 +52,12 @@ export class SQLiteArtifactStore implements ArtifactStore {
 			parameters.push(...filter.artifactIds, ...filter.artifactIds);
 		}
 		const where = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
+		let limit = "";
+		if (filter.limit !== undefined) {
+			if (!Number.isInteger(filter.limit) || filter.limit < 1) throw new Error("relationship limit must be a positive integer");
+			limit = "LIMIT ?";
+			parameters.push(filter.limit);
+		}
 		return this.db.prepare(`
 			SELECT edges.from_id AS "from", edges.relation, edges.to_id AS "to"
 			FROM edges
@@ -59,6 +65,7 @@ export class SQLiteArtifactStore implements ArtifactStore {
 			JOIN artifacts AS target ON target.id = edges.to_id
 			${where}
 			ORDER BY edges.rowid
+			${limit}
 		`).all(...parameters) as ArtifactEdge[];
 	}
 }