@xynogen/pix-todo 0.1.10 → 0.1.13

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@xynogen/pix-todo",
-	"version": "0.1.10",
+	"version": "0.1.13",
 	"description": "Pi tool — durable execution checklist (todo)",
 	"type": "module",
 	"main": "src/index.ts",

package/src/todo.test.ts

@@ -1,9 +1,5 @@
 import { beforeEach, describe, expect, test } from "bun:test";
-import registerTodo, {
-	renderTodoLines,
-	renderTodoSummaryLine,
-	type TodoItem,
-} from "./todo.ts";
+import registerTodo, { renderTodoLines, renderTodoSummaryLine, type TodoItem } from "./todo.ts";
 
 // registerTodo wraps its body in once(pi, "pix-todo") — a per-instance
 // WeakMap guard that dedupes activation across pix-core + a standalone install.
@@ -30,6 +26,7 @@ function makeHost(
 		data?: unknown;
 	}> = [],
 ) {
+	let capturedParameters: unknown;
 	let capturedExecute:
 		| ((
 				id: string,
@@ -40,10 +37,7 @@ function makeHost(
 		  }>)
 		| null = null;
 	const appendCalls: Array<{ type: string; data: unknown }> = [];
-	const handlers: Record<
-		string,
-		Array<(event: unknown, ctx?: unknown) => unknown>
-	> = {};
+	const handlers: Record<string, Array<(event: unknown, ctx?: unknown) => unknown>> = {};
 
 	let capturedRender:
 		| ((
@@ -57,9 +51,11 @@ function makeHost(
 	const pi = {
 		registerTool(def: {
 			name: string;
+			parameters: unknown;
 			execute: typeof capturedExecute;
 			renderResult?: typeof capturedRender;
 		}) {
+			capturedParameters = def.parameters;
 			capturedExecute = def.execute;
 			if (def.renderResult) capturedRender = def.renderResult;
 		},
@@ -70,8 +66,13 @@ function makeHost(
 			if (!handlers[ev]) handlers[ev] = [];
 			handlers[ev].push(fn);
 		},
-		async emit(ev: string, event?: unknown, ctx?: unknown) {
-			for (const fn of handlers[ev] ?? []) await fn(event, ctx);
+		async emit(ev: string, event?: unknown, ctx?: unknown): Promise<unknown> {
+			let last: unknown;
+			for (const fn of handlers[ev] ?? []) {
+				const result = await fn(event, ctx);
+				if (result !== undefined) last = result;
+			}
+			return last;
 		},
 	} as never;
 
@@ -84,6 +85,10 @@ function makeHost(
 	return {
 		pi,
 		sessionManager,
+		get parameters() {
+			if (!capturedParameters) throw new Error("parameters not captured");
+			return capturedParameters;
+		},
 		get execute() {
 			if (!capturedExecute) throw new Error("execute not captured");
 			return capturedExecute;
@@ -93,8 +98,13 @@ function makeHost(
 			return capturedRender;
 		},
 		appendCalls,
-		async emit(ev: string, event?: unknown, ctx?: unknown) {
-			for (const fn of handlers[ev] ?? []) await fn(event, ctx);
+		async emit(ev: string, event?: unknown, ctx?: unknown): Promise<unknown> {
+			let last: unknown;
+			for (const fn of handlers[ev] ?? []) {
+				const result = await fn(event, ctx);
+				if (result !== undefined) last = result;
+			}
+			return last;
 		},
 	};
 }
@@ -116,17 +126,37 @@ function text(result: { content: Array<{ type: string; text: string }> }) {
 	return result.content.map((c) => c.text).join("\n");
 }
 
+// ─── Tool schema ────────────────────────────────────────────────────────────
+
+test("todo exposes action and status as guided string enums", () => {
+	const host = makeHost();
+	registerTodo(host.pi);
+	const schema = host.parameters as {
+		properties: {
+			action: { type?: string; enum?: string[]; description?: string };
+			status: { type?: string; enum?: string[]; description?: string };
+		};
+	};
+	const action = schema.properties.action;
+	const status = schema.properties.status;
+
+	expect(action.type).toBe("string");
+	expect(action.enum).toEqual(["list", "set", "add", "update", "clear"]);
+	expect(action.description).toContain('"list" shows items');
+	expect(action.description).toContain('"update" changes one item by id');
+	expect(status?.type).toBe("string");
+	expect(status?.enum).toEqual(["pending", "in_progress", "done", "blocked"]);
+	expect(status?.description).toContain('"pending" = not started');
+	expect(status?.description).toContain('"blocked" = cannot proceed');
+});
+
 // ─── parseItems (via set/add) ───────────────────────────────────────────────
 
 describe("todo actions", () => {
 	test("list on empty returns (no todos)", async () => {
 		const host = makeHost();
 		registerTodo(host.pi);
-		await host.emit(
-			"session_start",
-			{},
-			{ sessionManager: host.sessionManager },
-		);
+		await host.emit("session_start", {}, { sessionManager: host.sessionManager });
 		const result = await run(host.execute, { action: "list" });
 		expect(text(result)).toBe("(no todos)");
 	});
@@ -134,11 +164,7 @@ describe("todo actions", () => {
 	test("set creates items from newline text", async () => {
 		const host = makeHost();
 		registerTodo(host.pi);
-		await host.emit(
-			"session_start",
-			{},
-			{ sessionManager: host.sessionManager },
-		);
+		await host.emit("session_start", {}, { sessionManager: host.sessionManager });
 		const result = await run(host.execute, {
 			action: "set",
 			items: "alpha\nbravo\ncharlie",
@@ -153,11 +179,7 @@ describe("todo actions", () => {
 	test("set creates items from numbered list", async () => {
 		const host = makeHost();
 		registerTodo(host.pi);
-		await host.emit(
-			"session_start",
-			{},
-			{ sessionManager: host.sessionManager },
-		);
+		await host.emit("session_start", {}, { sessionManager: host.sessionManager });
 		const result = await run(host.execute, {
 			action: "set",
 			items: "1. alpha\n2. bravo",
@@ -168,11 +190,7 @@ describe("todo actions", () => {
 	test("set creates items from bullet list", async () => {
 		const host = makeHost();
 		registerTodo(host.pi);
-		await host.emit(
-			"session_start",
-			{},
-			{ sessionManager: host.sessionManager },
-		);
+		await host.emit("session_start", {}, { sessionManager: host.sessionManager });
 		const result = await run(host.execute, {
 			action: "set",
 			items: "- alpha\n* bravo",
@@ -184,11 +202,7 @@ describe("todo actions", () => {
 	test("set ignores empty lines", async () => {
 		const host = makeHost();
 		registerTodo(host.pi);
-		await host.emit(
-			"session_start",
-			{},
-			{ sessionManager: host.sessionManager },
-		);
+		await host.emit("session_start", {}, { sessionManager: host.sessionManager });
 		const result = await run(host.execute, {
 			action: "set",
 			items: "alpha\n\nbravo\n  \ncharlie",
@@ -199,11 +213,7 @@ describe("todo actions", () => {
 	test("set with empty items returns error", async () => {
 		const host = makeHost();
 		registerTodo(host.pi);
-		await host.emit(
-			"session_start",
-			{},
-			{ sessionManager: host.sessionManager },
-		);
+		await host.emit("session_start", {}, { sessionManager: host.sessionManager });
 		const result = await run(host.execute, { action: "set", items: "" });
 		expect(result.isError).toBe(true);
 		expect(text(result)).toContain("non-empty");
@@ -212,11 +222,7 @@ describe("todo actions", () => {
 	test("set with only whitespace returns error", async () => {
 		const host = makeHost();
 		registerTodo(host.pi);
-		await host.emit(
-			"session_start",
-			{},
-			{ sessionManager: host.sessionManager },
-		);
+		await host.emit("session_start", {}, { sessionManager: host.sessionManager });
 		const result = await run(host.execute, { action: "set", items: "  \n  " });
 		expect(result.isError).toBe(true);
 	});
@@ -224,11 +230,7 @@ describe("todo actions", () => {
 	test("set resets ids on re-set", async () => {
 		const host = makeHost();
 		registerTodo(host.pi);
-		await host.emit(
-			"session_start",
-			{},
-			{ sessionManager: host.sessionManager },
-		);
+		await host.emit("session_start", {}, { sessionManager: host.sessionManager });
 		await run(host.execute, { action: "set", items: "first\nsecond" });
 		const result = await run(host.execute, { action: "set", items: "new" });
 		expect(text(result)).toContain("○ 1. new");
@@ -238,11 +240,7 @@ describe("todo actions", () => {
 	test("add appends items", async () => {
 		const host = makeHost();
 		registerTodo(host.pi);
-		await host.emit(
-			"session_start",
-			{},
-			{ sessionManager: host.sessionManager },
-		);
+		await host.emit("session_start", {}, { sessionManager: host.sessionManager });
 		await run(host.execute, { action: "set", items: "alpha" });
 		const result = await run(host.execute, {
 			action: "add",
@@ -258,11 +256,7 @@ describe("todo actions", () => {
 	test("add with ids continuing sequence", async () => {
 		const host = makeHost();
 		registerTodo(host.pi);
-		await host.emit(
-			"session_start",
-			{},
-			{ sessionManager: host.sessionManager },
-		);
+		await host.emit("session_start", {}, { sessionManager: host.sessionManager });
 		await run(host.execute, { action: "set", items: "first\nsecond\nthird" });
 		const result = await run(host.execute, { action: "add", items: "fourth" });
 		expect(text(result)).toContain("○ 4. fourth");
@@ -271,11 +265,7 @@ describe("todo actions", () => {
 	test("add with empty items returns error", async () => {
 		const host = makeHost();
 		registerTodo(host.pi);
-		await host.emit(
-			"session_start",
-			{},
-			{ sessionManager: host.sessionManager },
-		);
+		await host.emit("session_start", {}, { sessionManager: host.sessionManager });
 		const result = await run(host.execute, { action: "add", items: "" });
 		expect(result.isError).toBe(true);
 		expect(text(result)).toContain("non-empty");
@@ -284,11 +274,7 @@ describe("todo actions", () => {
 	test("update changes status", async () => {
 		const host = makeHost();
 		registerTodo(host.pi);
-		await host.emit(
-			"session_start",
-			{},
-			{ sessionManager: host.sessionManager },
-		);
+		await host.emit("session_start", {}, { sessionManager: host.sessionManager });
 		await run(host.execute, { action: "set", items: "alpha\nbravo" });
 		const result = await run(host.execute, {
 			action: "update",
@@ -304,11 +290,7 @@ describe("todo actions", () => {
 	test("update changes text", async () => {
 		const host = makeHost();
 		registerTodo(host.pi);
-		await host.emit(
-			"session_start",
-			{},
-			{ sessionManager: host.sessionManager },
-		);
+		await host.emit("session_start", {}, { sessionManager: host.sessionManager });
 		await run(host.execute, { action: "set", items: "old name" });
 		const result = await run(host.execute, {
 			action: "update",
@@ -321,11 +303,7 @@ describe("todo actions", () => {
 	test("update changes status and text together", async () => {
 		const host = makeHost();
 		registerTodo(host.pi);
-		await host.emit(
-			"session_start",
-			{},
-			{ sessionManager: host.sessionManager },
-		);
+		await host.emit("session_start", {}, { sessionManager: host.sessionManager });
 		await run(host.execute, { action: "set", items: "alpha" });
 		const result = await run(host.execute, {
 			action: "update",
@@ -341,11 +319,7 @@ describe("todo actions", () => {
 	test("opening a new in_progress closes the previous one", async () => {
 		const host = makeHost();
 		registerTodo(host.pi);
-		await host.emit(
-			"session_start",
-			{},
-			{ sessionManager: host.sessionManager },
-		);
+		await host.emit("session_start", {}, { sessionManager: host.sessionManager });
 		await run(host.execute, { action: "set", items: "a\nb\nc" });
 		await run(host.execute, { action: "update", id: 1, status: "in_progress" });
 		const result = await run(host.execute, {
@@ -363,11 +337,7 @@ describe("todo actions", () => {
 	test("opening a later item cascade-closes skipped pending items", async () => {
 		const host = makeHost();
 		registerTodo(host.pi);
-		await host.emit(
-			"session_start",
-			{},
-			{ sessionManager: host.sessionManager },
-		);
+		await host.emit("session_start", {}, { sessionManager: host.sessionManager });
 		await run(host.execute, { action: "set", items: "a\nb\nc\nd" });
 		// Jump straight to id 4 without opening 1-3; they should all auto-close.
 		const result = await run(host.execute, {
@@ -386,11 +356,7 @@ describe("todo actions", () => {
 	test("cascade-close leaves a blocked earlier item untouched", async () => {
 		const host = makeHost();
 		registerTodo(host.pi);
-		await host.emit(
-			"session_start",
-			{},
-			{ sessionManager: host.sessionManager },
-		);
+		await host.emit("session_start", {}, { sessionManager: host.sessionManager });
 		await run(host.execute, { action: "set", items: "a\nb\nc" });
 		await run(host.execute, { action: "update", id: 1, status: "blocked" });
 		const result = await run(host.execute, {
@@ -407,11 +373,7 @@ describe("todo actions", () => {
 	test("update unknown id returns error", async () => {
 		const host = makeHost();
 		registerTodo(host.pi);
-		await host.emit(
-			"session_start",
-			{},
-			{ sessionManager: host.sessionManager },
-		);
+		await host.emit("session_start", {}, { sessionManager: host.sessionManager });
 		const result = await run(host.execute, {
 			action: "update",
 			id: 999,
@@ -424,11 +386,7 @@ describe("todo actions", () => {
 	test("update without status or text does nothing", async () => {
 		const host = makeHost();
 		registerTodo(host.pi);
-		await host.emit(
-			"session_start",
-			{},
-			{ sessionManager: host.sessionManager },
-		);
+		await host.emit("session_start", {}, { sessionManager: host.sessionManager });
 		await run(host.execute, { action: "set", items: "unchanged" });
 		const result = await run(host.execute, { action: "update", id: 1 });
 		expect(text(result)).toContain("○ 1. unchanged");
@@ -437,11 +395,7 @@ describe("todo actions", () => {
 	test("clear empties list", async () => {
 		const host = makeHost();
 		registerTodo(host.pi);
-		await host.emit(
-			"session_start",
-			{},
-			{ sessionManager: host.sessionManager },
-		);
+		await host.emit("session_start", {}, { sessionManager: host.sessionManager });
 		await run(host.execute, { action: "set", items: "alpha\nbravo" });
 		const result = await run(host.execute, { action: "clear" });
 		expect(text(result)).toContain("Todos cleared");
@@ -453,11 +407,7 @@ describe("todo actions", () => {
 	test("clear resets id counter", async () => {
 		const host = makeHost();
 		registerTodo(host.pi);
-		await host.emit(
-			"session_start",
-			{},
-			{ sessionManager: host.sessionManager },
-		);
+		await host.emit("session_start", {}, { sessionManager: host.sessionManager });
 		await run(host.execute, { action: "set", items: "alpha\nbravo\ncharlie" });
 		await run(host.execute, { action: "clear" });
 		const result = await run(host.execute, { action: "set", items: "new" });
@@ -467,11 +417,7 @@ describe("todo actions", () => {
 	test("unknown action returns error", async () => {
 		const host = makeHost();
 		registerTodo(host.pi);
-		await host.emit(
-			"session_start",
-			{},
-			{ sessionManager: host.sessionManager },
-		);
+		await host.emit("session_start", {}, { sessionManager: host.sessionManager });
 		const result = await run(host.execute, { action: "bogus" });
 		expect(result.isError).toBe(true);
 		expect(text(result)).toContain("Unknown action");
@@ -480,11 +426,7 @@ describe("todo actions", () => {
 	test("all status glyphs render correctly", async () => {
 		const host = makeHost();
 		registerTodo(host.pi);
-		await host.emit(
-			"session_start",
-			{},
-			{ sessionManager: host.sessionManager },
-		);
+		await host.emit("session_start", {}, { sessionManager: host.sessionManager });
 		await run(host.execute, { action: "set", items: "a\nb\nc\nd" });
 		// Open id 2 first (cascade-closes nothing earlier we assert on), then set
 		// the others directly so each glyph is exercised without cascade interfering.
@@ -508,11 +450,7 @@ describe("persistence", () => {
 	test("set persists todos", async () => {
 		const host = makeHost();
 		registerTodo(host.pi);
-		await host.emit(
-			"session_start",
-			{},
-			{ sessionManager: host.sessionManager },
-		);
+		await host.emit("session_start", {}, { sessionManager: host.sessionManager });
 		host.appendCalls.length = 0;
 		await run(host.execute, { action: "set", items: "alpha\nbravo" });
 		expect(host.appendCalls.length).toBe(1);
@@ -529,11 +467,7 @@ describe("persistence", () => {
 	test("add persists todos", async () => {
 		const host = makeHost();
 		registerTodo(host.pi);
-		await host.emit(
-			"session_start",
-			{},
-			{ sessionManager: host.sessionManager },
-		);
+		await host.emit("session_start", {}, { sessionManager: host.sessionManager });
 		await run(host.execute, { action: "set", items: "alpha" });
 		host.appendCalls.length = 0;
 		await run(host.execute, { action: "add", items: "bravo" });
@@ -543,11 +477,7 @@ describe("persistence", () => {
 	test("update persists todos", async () => {
 		const host = makeHost();
 		registerTodo(host.pi);
-		await host.emit(
-			"session_start",
-			{},
-			{ sessionManager: host.sessionManager },
-		);
+		await host.emit("session_start", {}, { sessionManager: host.sessionManager });
 		await run(host.execute, { action: "set", items: "alpha" });
 		host.appendCalls.length = 0;
 		await run(host.execute, { action: "update", id: 1, status: "done" });
@@ -557,11 +487,7 @@ describe("persistence", () => {
 	test("clear persists", async () => {
 		const host = makeHost();
 		registerTodo(host.pi);
-		await host.emit(
-			"session_start",
-			{},
-			{ sessionManager: host.sessionManager },
-		);
+		await host.emit("session_start", {}, { sessionManager: host.sessionManager });
 		await run(host.execute, { action: "set", items: "alpha" });
 		host.appendCalls.length = 0;
 		await run(host.execute, { action: "clear" });
@@ -590,11 +516,7 @@ describe("restore", () => {
 			},
 		]);
 		registerTodo(host.pi);
-		await host.emit(
-			"session_start",
-			{},
-			{ sessionManager: host.sessionManager },
-		);
+		await host.emit("session_start", {}, { sessionManager: host.sessionManager });
 		const result = await run(host.execute, { action: "list" });
 		expect(text(result)).toContain("● 1. restored");
 		expect(text(result)).toContain("Todos 1/1 done");
@@ -612,11 +534,7 @@ describe("restore", () => {
 			},
 		]);
 		registerTodo(host.pi);
-		await host.emit(
-			"session_start",
-			{},
-			{ sessionManager: host.sessionManager },
-		);
+		await host.emit("session_start", {}, { sessionManager: host.sessionManager });
 		const result = await run(host.execute, { action: "add", items: "new" });
 		expect(text(result)).toContain("○ 6. new");
 	});
@@ -635,11 +553,7 @@ describe("restore", () => {
 			},
 		]);
 		registerTodo(host.pi);
-		await host.emit(
-			"session_start",
-			{},
-			{ sessionManager: host.sessionManager },
-		);
+		await host.emit("session_start", {}, { sessionManager: host.sessionManager });
 		const result = await run(host.execute, { action: "add", items: "next" });
 		expect(text(result)).toContain("○ 8. next");
 	});
@@ -658,11 +572,7 @@ describe("restore", () => {
 			},
 		]);
 		registerTodo(host.pi);
-		await host.emit(
-			"session_start",
-			{},
-			{ sessionManager: host.sessionManager },
-		);
+		await host.emit("session_start", {}, { sessionManager: host.sessionManager });
 		const result = await run(host.execute, { action: "list" });
 		expect(text(result)).toContain("○ 1. real");
 	});
@@ -670,11 +580,7 @@ describe("restore", () => {
 	test("no todo-state entries starts empty", async () => {
 		const host = makeHost([{ type: "message", data: "hello" }]);
 		registerTodo(host.pi);
-		await host.emit(
-			"session_start",
-			{},
-			{ sessionManager: host.sessionManager },
-		);
+		await host.emit("session_start", {}, { sessionManager: host.sessionManager });
 		const result = await run(host.execute, { action: "list" });
 		expect(text(result)).toBe("(no todos)");
 	});
@@ -682,11 +588,7 @@ describe("restore", () => {
 	test("empty entries list starts empty", async () => {
 		const host = makeHost([]);
 		registerTodo(host.pi);
-		await host.emit(
-			"session_start",
-			{},
-			{ sessionManager: host.sessionManager },
-		);
+		await host.emit("session_start", {}, { sessionManager: host.sessionManager });
 		const result = await run(host.execute, { action: "list" });
 		expect(text(result)).toBe("(no todos)");
 	});
@@ -700,16 +602,139 @@ describe("restore", () => {
 			},
 		]);
 		registerTodo(host.pi);
-		await host.emit(
-			"session_start",
-			{},
-			{ sessionManager: host.sessionManager },
-		);
+		await host.emit("session_start", {}, { sessionManager: host.sessionManager });
 		const result = await run(host.execute, { action: "list" });
 		expect(text(result)).toBe("(no todos)");
 	});
 });
 
+// ─── Skip-guard ─────────────────────────────────────────────────────────────────────
+
+describe("skip-guard on marking done", () => {
+	test("warns when marking a later item done with earlier pending items", async () => {
+		const host = makeHost();
+		registerTodo(host.pi);
+		await host.emit("session_start", {}, { sessionManager: host.sessionManager });
+		await run(host.execute, { action: "set", items: "a\nb\nc\nd" });
+		// Mark items 1 and 4 done, leaving 2 and 3 pending
+		await run(host.execute, { action: "update", id: 1, status: "done" });
+		const result = await run(host.execute, { action: "update", id: 4, status: "done" });
+		const out = text(result);
+		expect(out).toContain("\u26a0 Earlier items still incomplete");
+		expect(out).toContain("#2 (b)");
+		expect(out).toContain("#3 (c)");
+		expect(out).toContain("Mark each done or blocked before proceeding");
+	});
+
+	test("no warning when all earlier items are done", async () => {
+		const host = makeHost();
+		registerTodo(host.pi);
+		await host.emit("session_start", {}, { sessionManager: host.sessionManager });
+		await run(host.execute, { action: "set", items: "a\nb\nc" });
+		await run(host.execute, { action: "update", id: 1, status: "done" });
+		await run(host.execute, { action: "update", id: 2, status: "done" });
+		const result = await run(host.execute, { action: "update", id: 3, status: "done" });
+		expect(text(result)).not.toContain("\u26a0");
+	});
+
+	test("no warning when marking the first item done", async () => {
+		const host = makeHost();
+		registerTodo(host.pi);
+		await host.emit("session_start", {}, { sessionManager: host.sessionManager });
+		await run(host.execute, { action: "set", items: "a\nb" });
+		const result = await run(host.execute, { action: "update", id: 1, status: "done" });
+		expect(text(result)).not.toContain("\u26a0");
+	});
+
+	test("no warning when earlier items are blocked (only pending/in_progress trigger)", async () => {
+		const host = makeHost();
+		registerTodo(host.pi);
+		await host.emit("session_start", {}, { sessionManager: host.sessionManager });
+		await run(host.execute, { action: "set", items: "a\nb\nc" });
+		await run(host.execute, { action: "update", id: 1, status: "blocked" });
+		await run(host.execute, { action: "update", id: 2, status: "done" });
+		const result = await run(host.execute, { action: "update", id: 3, status: "done" });
+		// blocked is an explicit decision, not incomplete — no warning
+		expect(text(result)).not.toContain("\u26a0");
+	});
+
+	test("warns about in_progress items too (not just pending)", async () => {
+		const host = makeHost();
+		registerTodo(host.pi);
+		await host.emit("session_start", {}, { sessionManager: host.sessionManager });
+		await run(host.execute, { action: "set", items: "a\nb\nc" });
+		await run(host.execute, { action: "update", id: 1, status: "in_progress" });
+		// Mark item 3 done while item 1 is still in_progress
+		const result = await run(host.execute, { action: "update", id: 3, status: "done" });
+		const out = text(result);
+		expect(out).toContain("\u26a0");
+		expect(out).toContain("#1 (a)");
+	});
+
+	test("no skip-guard on in_progress (only on done)", async () => {
+		// in_progress uses cascade-close instead, which is different behavior
+		const host = makeHost();
+		registerTodo(host.pi);
+		await host.emit("session_start", {}, { sessionManager: host.sessionManager });
+		await run(host.execute, { action: "set", items: "a\nb\nc" });
+		const result = await run(host.execute, { action: "update", id: 3, status: "in_progress" });
+		// Should cascade-close, not warn
+		expect(text(result)).not.toContain("\u26a0");
+		expect(text(result)).toContain("\u25cf 1. a"); // cascade-closed to done
+		expect(text(result)).toContain("\u25cf 2. b");
+	});
+});
+
+// ─── Turn-based reminder ────────────────────────────────────────────────────────────
+
+describe("turn-based todo reminder", () => {
+	test("injects reminder every 10 turns when incomplete items exist", async () => {
+		const host = makeHost();
+		registerTodo(host.pi);
+		await host.emit("session_start", {}, { sessionManager: host.sessionManager });
+		await run(host.execute, { action: "set", items: "a\nb" });
+
+		// Simulate 10 turns — only the 10th should inject
+		for (let i = 1; i <= 9; i++) {
+			const result = await host.emit("before_agent_start", { systemPrompt: "base" });
+			// before_agent_start returns undefined when no injection
+			expect(result).toBeUndefined();
+		}
+		// 10th turn should inject
+		const result = await host.emit("before_agent_start", { systemPrompt: "base" });
+		expect(result).toBeDefined();
+		const prompt = (result as { systemPrompt: string }).systemPrompt;
+		expect(prompt).toContain("base");
+		expect(prompt).toContain("Todo reminder");
+		expect(prompt).toContain("1. a");
+		expect(prompt).toContain("2. b");
+	});
+
+	test("does not inject when no todos exist", async () => {
+		const host = makeHost();
+		registerTodo(host.pi);
+		await host.emit("session_start", {}, { sessionManager: host.sessionManager });
+
+		for (let i = 1; i <= 10; i++) {
+			const result = await host.emit("before_agent_start", { systemPrompt: "base" });
+			expect(result).toBeUndefined();
+		}
+	});
+
+	test("does not inject when all items are done", async () => {
+		const host = makeHost();
+		registerTodo(host.pi);
+		await host.emit("session_start", {}, { sessionManager: host.sessionManager });
+		await run(host.execute, { action: "set", items: "a" });
+		await run(host.execute, { action: "update", id: 1, status: "done" });
+
+		for (let i = 1; i <= 10; i++) {
+			const result = await host.emit("before_agent_start", { systemPrompt: "base" });
+			expect(result).toBeUndefined();
+		}
+	});
+});
+
 describe("renderTodoLines (colored TUI render)", () => {
 	const items: TodoItem[] = [
 		{ id: 1, text: "alpha", status: "done" },
@@ -754,11 +779,7 @@ describe("renderResult snapshot isolation", () => {
 	test("a rendered card keeps its state after todos mutate", async () => {
 		const host = makeHost();
 		registerTodo(host.pi);
-		await host.emit(
-			"session_start",
-			{},
-			{ sessionManager: host.sessionManager },
-		);
+		await host.emit("session_start", {}, { sessionManager: host.sessionManager });
 		await run(host.execute, { action: "set", items: "alpha\nbravo" });
 
 		// Render once with a per-row state bag; snapshot is taken here.
@@ -789,8 +810,6 @@ describe("renderTodoSummaryLine (collapsed one-liner)", () => {
 			{ id: 1, text: "a", status: "done" },
 			{ id: 2, text: "b", status: "pending" },
 		];
-		expect(renderTodoSummaryLine(items, tagTheme)).toBe(
-			"[muted]Todos 1/2 done ✓[/]",
-		);
+		expect(renderTodoSummaryLine(items, tagTheme)).toBe("[muted]Todos 1/2 done ✓[/]");
 	});
 });

package/src/todo.ts

@@ -42,8 +42,7 @@ function readCollapseConfig(): CollapseConf {
 		if (!c || typeof c !== "object") return DEFAULT_COLLAPSE;
 		return {
 			enabled: typeof c.enabled === "boolean" ? c.enabled : true,
-			delaySec:
-				typeof c.delaySec === "number" && c.delaySec > 0 ? c.delaySec : 10,
+			delaySec: typeof c.delaySec === "number" && c.delaySec > 0 ? c.delaySec : 10,
 			tools:
 				c.tools && typeof c.tools === "object"
 					? (c.tools as Record<string, boolean | undefined>)
@@ -99,10 +98,7 @@ export type TodoTheme = {
 };
 
 /** One-line dim summary used once a card has collapsed. */
-export function renderTodoSummaryLine(
-	items: TodoItem[],
-	theme: TodoTheme,
-): string {
+export function renderTodoSummaryLine(items: TodoItem[], theme: TodoTheme): string {
 	if (!items.length) return theme.fg("muted", "(no todos)");
 	const done = items.filter((t) => t.status === "done").length;
 	return theme.fg("muted", `Todos ${done}/${items.length} done ✓`);
@@ -127,6 +123,22 @@ export function renderTodoLines(items: TodoItem[], theme: TodoTheme): string {
 	return `${head}\n${lines.join("\n")}`;
 }
 
+/**
+ * Skip-guard: when marking an item done, check for earlier items still
+ * pending or in_progress. Returns a warning string or "" if none skipped.
+ */
+function buildSkipWarning(items: TodoItem[], targetId: number): string {
+	const skipped = items.filter(
+		(o) => o.id < targetId && (o.status === "pending" || o.status === "in_progress"),
+	);
+	if (skipped.length === 0) return "";
+	const ids = skipped.map((s) => `#${s.id} (${s.text})`).join(", ");
+	return (
+		`\n\n\u26a0 Earlier items still incomplete: ${ids}. ` +
+		"Mark each done or blocked before proceeding."
+	);
+}
+
 const parseItems = (raw: string): string[] =>
 	raw
 		.split("\n")
@@ -145,9 +157,7 @@ export default function registerTodo(pi: ExtensionAPI): void {
 		function todoSummary(): string {
 			if (!todos.length) return "(no todos)";
 			const done = todos.filter((t) => t.status === "done").length;
-			const lines = todos.map(
-				(t) => `${TODO_GLYPH[t.status]} ${t.id}. ${t.text}`,
-			);
+			const lines = todos.map((t) => `${TODO_GLYPH[t.status]} ${t.id}. ${t.text}`);
 			return `Todos ${done}/${todos.length} done:\n${lines.join("\n")}`;
 		}
 
@@ -164,38 +174,27 @@ export default function registerTodo(pi: ExtensionAPI): void {
 			promptGuidelines: [
 				"When you start executing a multi-step plan in BUILD mode, seed the todo list with `todo(action:'set', items: <plan Implementation Phases>)`.",
 				"Mark each item in_progress before working it via `todo(action:'update', id, status)`; opening one auto-closes every earlier item, so just open the next and skipped steps mark done themselves.",
+				"When marking an item done, the tool checks for earlier incomplete items and warns you — resolve each skipped item (mark done or blocked) before moving on.",
 				"Call `todo(action:'list')` to recover your place after long runs or context compaction.",
 			],
 			parameters: Type.Object({
-				action: Type.Union(
-					[
-						Type.Literal("list"),
-						Type.Literal("set"),
-						Type.Literal("add"),
-						Type.Literal("update"),
-						Type.Literal("clear"),
-					],
-					{ description: "Operation to perform" },
-				),
+				action: Type.Enum(["list", "set", "add", "update", "clear"] as const, {
+					type: "string",
+					description:
+						'Required operation: "list" shows items; "set" replaces all from items; "add" appends items; "update" changes one item by id; "clear" removes all.',
+				}),
 				items: Type.Optional(
 					Type.String({
-						description:
-							"For set/add: newline-separated or numbered list of todo texts.",
+						description: "For set/add: newline-separated or numbered list of todo texts.",
 					}),
 				),
-				id: Type.Optional(
-					Type.Number({ description: "For update: target todo id." }),
-				),
+				id: Type.Optional(Type.Number({ description: "For update: target todo id." })),
 				status: Type.Optional(
-					Type.Union(
-						[
-							Type.Literal("pending"),
-							Type.Literal("in_progress"),
-							Type.Literal("done"),
-							Type.Literal("blocked"),
-						],
-						{ description: "For update: new status." },
-					),
+					Type.Enum(["pending", "in_progress", "done", "blocked"] as const, {
+						type: "string",
+						description:
+							'For update: "pending" = not started; "in_progress" = active; "done" = finished; "blocked" = cannot proceed.',
+					}),
 				),
 				text: Type.Optional(
 					Type.String({
@@ -220,9 +219,7 @@ export default function registerTodo(pi: ExtensionAPI): void {
 						context.invalidate();
 					}, collapseDelayMs());
 				}
-				const render = state.collapsed
-					? renderTodoSummaryLine
-					: renderTodoLines;
+				const render = state.collapsed ? renderTodoSummaryLine : renderTodoLines;
 				return new Text(render(state.snapshot, theme as TodoTheme), 0, 0);
 			},
 
@@ -258,8 +255,7 @@ export default function registerTodo(pi: ExtensionAPI): void {
 					case "add": {
 						const texts = parseItems(params.items ?? "");
 						if (!texts.length) return fail("add requires non-empty `items`.");
-						for (const text of texts)
-							todos.push({ id: nextTodoId++, text, status: "pending" });
+						for (const text of texts) todos.push({ id: nextTodoId++, text, status: "pending" });
 						persistTodos();
 						return ok(todoSummary());
 					}
@@ -267,6 +263,7 @@ export default function registerTodo(pi: ExtensionAPI): void {
 					case "update": {
 						const t = todos.find((x) => x.id === params.id);
 						if (!t) return fail(`No todo with id ${params.id}.`);
+						let skipWarning = "";
 						if (params.status) {
 							// Sequential-progress invariant: opening a task means everything
 							// before it is finished. Cascade-close every earlier pending or
@@ -276,15 +273,17 @@ export default function registerTodo(pi: ExtensionAPI): void {
 								for (const other of todos)
 									if (
 										other.id < t.id &&
-										(other.status === "pending" ||
-											other.status === "in_progress")
+										(other.status === "pending" || other.status === "in_progress")
 									)
 										other.status = "done";
+
+							if (params.status === "done") skipWarning = buildSkipWarning(todos, t.id);
+
 							t.status = params.status;
 						}
 						if (params.text) t.text = params.text;
 						persistTodos();
-						return ok(todoSummary());
+						return ok(todoSummary() + skipWarning);
 					}
 
 					case "clear":
@@ -299,6 +298,32 @@ export default function registerTodo(pi: ExtensionAPI): void {
 			},
 		});
 
+		// ── Turn-based reminder ─────────────────────────────────────────────
+		// Every TODO_REMINDER_INTERVAL turns, inject the current todo summary
+		// into the system prompt so the model stays aware of pending work and
+		// can't hand-wave or ignore incomplete items.
+		const TODO_REMINDER_INTERVAL = 10;
+		let todoTurnCount = 0;
+
+		pi.on("before_agent_start", async (event) => {
+			todoTurnCount++;
+			// Only inject when there are active (non-empty) todos
+			if (todos.length === 0) return;
+			// Check if any items are still incomplete
+			const hasIncomplete = todos.some((t) => t.status === "pending" || t.status === "in_progress");
+			if (!hasIncomplete) return;
+			// Fire on every Nth turn
+			if (todoTurnCount % TODO_REMINDER_INTERVAL !== 0) return;
+
+			const reminder =
+				"Todo reminder — incomplete items remain:\n" +
+				todoSummary() +
+				"\nCall `todo(action:'list')` to review, then continue working through pending items.";
+
+			const existing = event.systemPrompt ?? "";
+			return { systemPrompt: existing ? `${existing}\n\n${reminder}` : reminder };
+		});
+
 		// Restore the checklist from session entries so it survives restart.
 		pi.on("session_start", async (_event, ctx) => {
 			const entries = ctx.sessionManager.getEntries() as Array<{
@@ -311,9 +336,7 @@ export default function registerTodo(pi: ExtensionAPI): void {
 				.pop();
 			if (Array.isArray(lastTodo?.data?.todos)) {
 				todos = lastTodo.data.todos;
-				nextTodoId =
-					lastTodo.data.nextTodoId ??
-					todos.reduce((m, t) => Math.max(m, t.id + 1), 1);
+				nextTodoId = lastTodo.data.nextTodoId ?? todos.reduce((m, t) => Math.max(m, t.id + 1), 1);
 			}
 		});
 	});