@fyeeme/pi-todo 1.0.0 → 1.0.1

package/src/tool.ts

@@ -9,6 +9,9 @@
  *   AgentTool class + ToolSession  → ToolDefinition + closure deps
  *   concurrency: "exclusive"      → executionMode: "sequential"
  *   session getTodoPhases/setTodoPhases → getPhases/setPhases/persist/broadcast
+ *   eager-todo promptGuidelines    → dropped (cognitive-neutral notepad: the
+ *       tool description documents the mechanics; the system prompt is not
+ *       steered)
  */
 
 import { readFileSync } from "node:fs";
@@ -22,7 +25,7 @@ import {
 	applyParams,
 	clonePhases,
 	formatSummary,
-	getCompletionTransitions,
+	getStatusTransitions,
 	inferTodoOp,
 	type TodoOperation,
 	type TodoOpEntry,
@@ -66,13 +69,6 @@ export const TodoParamsSchema = Type.Object({
 
 export type TodoParams = Static<typeof TodoParamsSchema>;
 
-/** Advisory nudge appended to the default system prompt while the tool is active. */
-export const TODO_PROMPT_GUIDELINES = [
-	"Consider calling the todo tool first to lay out a phased plan with a single `init` op. A good list covers the whole request — investigation through implementation and verification — not just the next step, with specific task descriptions a future turn could execute without re-planning.",
-	"A useful list keeps each task to a concise, specific 5-10 word label; the `init` op only accepts phase names and task-label strings, so don't invent extra task metadata fields.",
-	"If you create the list, continue the request in the same turn and avoid re-calling the todo tool unless task state materially changes.",
-];
-
 export interface TodoToolDeps {
 	/** Current in-memory phases (already cloned on write). */
 	getPhases(): TodoPhase[];
@@ -84,16 +80,23 @@ export interface TodoToolDeps {
 	broadcast(phases: TodoPhase[]): void;
 }
 
+/** The one write-back invariant: replace state, persist, broadcast — in that
+ *  order. Shared by the tool path and the /todo command path so the two can
+ *  never drift (persist/broadcast semantics live in index.ts's deps). */
+export function commitPhases(deps: TodoToolDeps, next: TodoPhase[]): void {
+	deps.setPhases(next);
+	deps.persist(next);
+	deps.broadcast(next);
+}
+
 export function createTodoTool(deps: TodoToolDeps): ToolDefinition<typeof TodoParamsSchema, TodoToolDetails> {
 	const definition: ToolDefinition<typeof TodoParamsSchema, TodoToolDetails> = {
 		name: "todo",
 		label: "Todo",
 		description: todoDescription,
-		promptSnippet: "Write a structured todo list to track progress within a session",
-		promptGuidelines: TODO_PROMPT_GUIDELINES,
 		parameters: TodoParamsSchema,
 		executionMode: "sequential",
-		renderCall: (args, theme) => renderTodoCall(args, theme),
+		renderCall: renderTodoCall,
 		// omp's renderer folds call args into the result view (touched-phase
 		// diffing); pi passes them through the render context.
 		renderResult: (result, options, theme, context) => renderTodoResult(result, options, theme, context?.args),
@@ -118,7 +121,7 @@ export function createTodoTool(deps: TodoToolDeps): ToolDefinition<typeof TodoPa
 			_onUpdate: undefined,
 			_ctx: ExtensionContext,
 		): Promise<AgentToolResult<TodoToolDetails>> {
-			const previousPhases = clonePhases(deps.getPhases());
+			const previousPhases = deps.getPhases();
 			const op: TodoOperation = params.op;
 			// Pure-view calls are reads: no normalization, no state write.
 			const readOnly = op === "view";
@@ -130,21 +133,47 @@ export function createTodoTool(deps: TodoToolDeps): ToolDefinition<typeof TodoPa
 			// the ops that did land. State stays at previous. pi's tool contract
 			// is throw-on-failure (no isError field on AgentToolResult), and the
 			// thrown message carries the errors plus the unchanged list so the
-			// model can retry with correct content.
+			// model can retry with correct content. formatSummary does not fold
+			// error results (the fold is gated on empty errors), so the full list
+			// is present even on big lists.
 			if (errors.length > 0) {
 				throw new Error(formatSummary(previousPhases, errors, readOnly));
 			}
 			if (!readOnly) {
-				deps.setPhases(clonePhases(updated));
-				deps.persist(clonePhases(updated));
-				deps.broadcast(clonePhases(updated));
+				// `updated` is a fresh clone nothing else references: hand ownership
+				// to the closure, and let persist/broadcast make their own
+				// entry-shaped snapshots (clonePhases inside index.ts).
+				commitPhases(deps, updated);
 			}
-			const completedTasks = readOnly ? [] : getCompletionTransitions(previousPhases, updated);
+			// Per-write confirmation, independent of summary folding: on big lists
+			// the folded summary may not show the operated tasks at all, so the
+			// model needs an explicit record of what changed (status + blocker note).
+			const transitions = readOnly ? [] : getStatusTransitions(previousPhases, updated);
 			const details: TodoToolDetails = { op, phases: clonePhases(updated), storage: "session" };
+			const completedTasks = transitions
+				.filter(transition => transition.to === "completed")
+				.map(({ phase, content }) => ({ phase, content }));
 			if (completedTasks.length > 0) details.completedTasks = completedTasks;
 
+			let text = formatSummary(updated, [], readOnly);
+			if (transitions.length > 0) {
+				const changed = transitions
+					.map(transition => {
+						const blocker =
+							transition.to === "blocked"
+								? updated
+									.find(phase => phase.name === transition.phase)
+									?.tasks.find(task => task.content === transition.content)?.blocker
+								: undefined;
+						const note = blocker ? ` (blocked: ${blocker})` : "";
+						return `  - ${transition.content} [${transition.from} → ${transition.to}]${note} (${transition.phase})`;
+					})
+					.join("\n");
+				text = `Changed:\n${changed}\n\n${text}`;
+			}
+
 			return {
-				content: [{ type: "text", text: formatSummary(updated, [], readOnly) }],
+				content: [{ type: "text", text }],
 				details,
 			};
 		},

package/test/omp-alignment.test.ts

@@ -11,31 +11,33 @@
  *     MarkdownPath                               |  escaped brackets, errors)
  *   tools/todo.ts phaseRomanNumeral              | algorithmic roman numerals
  *   tools/todo.ts selectCollapsedTodos /         | collapsed walking viewport
- *     selectWithinCap / todoMatchesAny-          |
- *     Description                                |
+ *     selectWithinCap                            |
  *   tools/todo.ts formatSummary                  | exact summary text
  *   tools/todo.ts formatMoreItems / pluralize    | ellipsis summaries
- *   session/todo-tracker.ts checkCompletion /    | reminder text, attempt
- *     isAwaitingUserAnswer                       | cycle, question guard
  *   modes/controllers/todo-command-controller.ts | /todo verb surface, fuzzy
- *                                                | matching, system reminder
+ *                                                | matching
  *
- * Every expected string is copied verbatim from the omp sources listed.
+ * Expected strings are copied verbatim from the omp sources listed, except
+ * where the deviations note below applies.
+ *
+ * Deliberate omp deviations NOT pinned here (cognitive-neutral refactor):
+ * normalizeInProgressTask / auto-promotion, stop-reminder machinery, and the
+ * subagent description matcher were removed; formatSummary's worked-ahead
+ * wording and the >20-task fold with its `view` hints are pi-todo deviations
+ * from omp (assertions below pin the pi-todo wording, not omp's). See
+ * src/state.ts header.
  */
 
 import { homedir } from "node:os";
 import { describe, expect, it } from "vitest";
 import {
 	formatSummary,
-	isAwaitingUserAnswer,
 	markdownToPhases,
-	normalizeInProgressTask,
 	phaseRomanNumeral,
 	phasesToMarkdown,
 	pluralize,
 	resolveTodoMarkdownPath,
 	selectCollapsedTodos,
-	todoMatchesAnyDescription,
 	type TodoItem,
 	type TodoPhase,
 } from "../src/state.ts";
@@ -126,9 +128,9 @@ describe("markdown round-trip matches omp", () => {
 		]);
 	});
 
-	it("normalizeInProgressTask runs on parse (omp markdownToPhases tail)", () => {
+	it("markdownToPhases parses statuses literally (no normalization)", () => {
 		const { phases } = markdownToPhases("- [ ] one\n- [ ] two");
-		expect(phases[0]?.tasks[0]?.status).toBe("in_progress");
+		expect(phases[0]?.tasks[0]?.status).toBe("pending");
 		expect(phases[0]?.tasks[1]?.status).toBe("pending");
 	});
 
@@ -169,11 +171,9 @@ function task(content: string, status: TodoItem["status"]): TodoItem {
 }
 
 describe("selectCollapsedTodos matches omp", () => {
-	const never = () => false;
-
 	it("returns everything within the cap", () => {
 		const tasks = [task("a", "in_progress"), task("b", "pending")];
-		const selection = selectCollapsedTodos(tasks, never, 8);
+		const selection = selectCollapsedTodos(tasks, 8);
 		expect(selection.items).toEqual(tasks);
 		expect(selection.summary).toBe("");
 	});
@@ -191,7 +191,7 @@ describe("selectCollapsedTodos matches omp", () => {
 			task("g", "pending"),
 			task("h", "pending"),
 		];
-		const selection = selectCollapsedTodos(tasks, never, 8);
+		const selection = selectCollapsedTodos(tasks, 8);
 		// Open work = 8 (a..h) ≤ cap; lead adds the LAST closed row additively.
 		expect(selection.items.map(t => t.content)).toEqual([
 			"closed-new",
@@ -209,7 +209,7 @@ describe("selectCollapsedTodos matches omp", () => {
 
 	it("counts hidden open work with the omp ellipsis summary", () => {
 		const tasks = [task("done", "completed"), ...Array.from({ length: 10 }, (_, i) => task(`t${i}`, "pending"))];
-		const selection = selectCollapsedTodos(tasks, never, 8);
+		const selection = selectCollapsedTodos(tasks, 8);
 		expect(selection.items.filter(t => t.content === "done")).toHaveLength(1);
 		expect(selection.summary).toBe("… 2 more todos");
 	});
@@ -221,54 +221,19 @@ describe("selectCollapsedTodos matches omp", () => {
 			task("w3", "in_progress"),
 			task("p", "pending"),
 		];
-		const selection = selectCollapsedTodos(tasks, never, 2);
+		const selection = selectCollapsedTodos(tasks, 2);
 		expect(selection.items.map(t => t.content)).toEqual(["w1", "w2"]);
 		expect(selection.summary).toBe("… 1 more active todo");
 	});
 
 	it("a settled phase selects over its closed tasks", () => {
 		const tasks = [task("a", "completed"), task("b", "abandoned"), task("c", "completed")];
-		const selection = selectCollapsedTodos(tasks, never, 8);
+		const selection = selectCollapsedTodos(tasks, 8);
 		expect(selection.items).toEqual(tasks);
 		expect(selection.summary).toBe("");
 	});
 });
 
-describe("todoMatchesAnyDescription matches omp", () => {
-	it("matches normalized equality and ≥6-char substrings both ways", () => {
-		expect(todoMatchesAnyDescription("Fix the build", ["fix the build!"])).toBe(true);
-		expect(todoMatchesAnyDescription("Sonnet #2: bug scan", ["Sonnet #2"])).toBe(true);
-		expect(todoMatchesAnyDescription("review", ["code review phase"])).toBe(true);
-		expect(todoMatchesAnyDescription("test", ["testing"])).toBe(false); // <6 overlap
-		expect(todoMatchesAnyDescription("", ["anything"])).toBe(false);
-	});
-});
-
-// ---------------------------------------------------------------------------
-// Stop-reminder guards — omp TodoTracker
-// ---------------------------------------------------------------------------
-
-describe("isAwaitingUserAnswer matches omp", () => {
-	it("detects question endings (word gates + non-ASCII)", () => {
-		expect(isAwaitingUserAnswer("Done for now.\nWhich database should I use?")).toBe(true);
-		expect(isAwaitingUserAnswer("Should I proceed?")).toBe(true);
-		expect(isAwaitingUserAnswer("要继续吗？")).toBe(true); // CJK question
-		expect(isAwaitingUserAnswer("Q1: ready?")).toBe(true); // prompt label
-	});
-
-	it("detects response cues", () => {
-		expect(isAwaitingUserAnswer("Please confirm the plan.")).toBe(true);
-		expect(isAwaitingUserAnswer("Let me know if that works")).toBe(true);
-	});
-
-	it("ignores prose with incidental question marks", () => {
-		// No question word/pronoun/non-ASCII gate fires; omp treats it as prose.
-		expect(isAwaitingUserAnswer("Fixed the optional foo?: string handling.")).toBe(false);
-		expect(isAwaitingUserAnswer("All checks pass.")).toBe(false);
-		expect(isAwaitingUserAnswer("")).toBe(false);
-	});
-});
-
 // ---------------------------------------------------------------------------
 // formatSummary — omp tools/todo.ts (tool result body)
 // ---------------------------------------------------------------------------
@@ -313,14 +278,14 @@ describe("formatSummary matches omp verbatim", () => {
 		);
 	});
 
-	it("renders the worked-ahead explanation (omp backward-pointer note)", () => {
+	it("renders the worked-ahead explanation (out-of-order completion note)", () => {
 		const phases: TodoPhase[] = [
 			{ name: "A", tasks: [{ content: "a", status: "pending" }] },
 			{ name: "B", tasks: [{ content: "b", status: "completed" }] },
 		];
 		const out = formatSummary(phases, []);
 		expect(out).toContain(
-			'Active phase 1/2 "A" (0/1) — earliest phase with open tasks; the in-progress pointer auto-advances to the earliest open task on each completion, so it can sit behind out-of-order work (nothing was un-completed).',
+			'Active phase 1/2 "A" (0/1) — earliest phase with open tasks; later phases may already hold completed work from out-of-order execution (nothing was un-completed).',
 		);
 	});
 
@@ -343,27 +308,3 @@ describe("pluralize matches omp", () => {
 		expect(pluralize("entry", 2)).toBe("entries");
 	});
 });
-
-// ---------------------------------------------------------------------------
-// normalizeInProgressTask invariant (omp applyParams tail)
-// ---------------------------------------------------------------------------
-
-describe("normalizeInProgressTask matches omp", () => {
-	it("demotes surplus in-progress tasks", () => {
-		const phases: TodoPhase[] = [
-			{ name: "A", tasks: [task("a", "in_progress"), task("b", "in_progress")] },
-		];
-		normalizeInProgressTask(phases);
-		expect(phases[0]?.tasks.map(t => t.status)).toEqual(["in_progress", "pending"]);
-	});
-
-	it("auto-promotes the earliest pending when none is in progress", () => {
-		const phases: TodoPhase[] = [
-			{ name: "A", tasks: [task("a", "completed"), task("b", "pending")] },
-			{ name: "B", tasks: [task("c", "pending")] },
-		];
-		normalizeInProgressTask(phases);
-		expect(phases[0]?.tasks[1]?.status).toBe("in_progress");
-		expect(phases[1]?.tasks[0]?.status).toBe("pending");
-	});
-});

package/test/render.test.ts

@@ -140,7 +140,8 @@ describe("todo render: result (omp renderer)", () => {
 	});
 
 	it("computeTouchedPhases consumes the call args via the render context (omp args fold)", () => {
-		// done on phase Two: One is untouched → one-line summary; Two expands.
+		// done on phase Two: Two is touched (completion + op phase); One is the
+		// earliest phase with open work, so it stays expanded too (no pointer).
 		const phases = [phase("One", ["pending"]), phase("Two", ["completed", "pending"])];
 		const completed: NonNullable<TodoToolDetails["completedTasks"]> = [{ phase: "Two", content: "two-1" }];
 		const out = text(
@@ -152,7 +153,8 @@ describe("todo render: result (omp renderer)", () => {
 			),
 		);
 		expect(out).toContain("I. One  0/1");
-		expect(out).not.toContain("one-1");
+		// Active phase (earliest open work) never collapses to a summary line.
+		expect(out).toContain("one-1");
 		expect(out).toContain("II. Two  1/2");
 		expect(out).toContain("two-2");
 	});

package/test/state.test.ts

@@ -7,8 +7,6 @@ import {
 	inferTodoOp,
 	isTodoPhase,
 	isTodoPhaseSnapshot,
-	normalizeInProgressTask,
-	openTasks,
 	type TodoOpEntry,
 	type TodoPhase,
 } from "../src/state.ts";
@@ -18,7 +16,7 @@ function phasesWithTasks(...entries: Array<[string, ...string[]]>): TodoPhase[]
 }
 
 describe("todo state: init", () => {
-	it("installs a phased list, all tasks pending, in order", () => {
+	it("installs a phased list, all tasks pending, in order (no auto-promotion)", () => {
 		const { phases, errors } = applyParams(
 			[],
 			{
@@ -31,8 +29,8 @@ describe("todo state: init", () => {
 		);
 		expect(errors).toEqual([]);
 		expect(phases.map(p => p.name)).toEqual(["Foundation", "Verify"]);
-		// normalizeInProgressTask auto-promotes the earliest pending task.
-		expect(phases[0].tasks[0]).toEqual({ content: "Scaffold", status: "in_progress" });
+		// Statuses change only through explicit ops: nothing auto-promotes.
+		expect(phases[0].tasks[0]).toEqual({ content: "Scaffold", status: "pending" });
 		expect(phases[0].tasks[1].status).toBe("pending");
 		expect(phases[1].tasks[0].status).toBe("pending");
 	});
@@ -73,7 +71,7 @@ describe("todo state: init", () => {
 			{
 				name: "Tasks",
 				tasks: [
-					{ content: "one", status: "in_progress" },
+					{ content: "one", status: "pending" },
 					{ content: "two", status: "pending" },
 				],
 			},
@@ -82,14 +80,15 @@ describe("todo state: init", () => {
 });
 
 describe("todo state: start", () => {
-	it("demotes every other in_progress task back to pending", () => {
+	it("marks the target in progress without touching other tasks (no invariant)", () => {
 		const phases: TodoPhase[] = [
 			{ name: "A", tasks: [{ content: "a1", status: "in_progress" }] },
 			{ name: "B", tasks: [{ content: "b1", status: "pending" }] },
 		];
 		const { phases: updated, errors } = applyParams(phases, { op: "start", task: "b1" });
 		expect(errors).toEqual([]);
-		expect(updated[0].tasks[0].status).toBe("pending");
+		// Multiple in_progress tasks are allowed: statuses are explicit-only.
+		expect(updated[0].tasks[0].status).toBe("in_progress");
 		expect(updated[1].tasks[0].status).toBe("in_progress");
 	});
 
@@ -274,60 +273,30 @@ describe("todo state: batch application", () => {
 		];
 		const { phases: updated, errors } = applyOpsToPhases(phases, [{ op: "rm", phase: "A" }, { op: "append", phase: "A", items: ["fresh"] }]);
 		expect(errors).toEqual([]);
-		expect(updated[0].tasks).toEqual([{ content: "fresh", status: "in_progress" }]);
+		expect(updated[0].tasks).toEqual([{ content: "fresh", status: "pending" }]);
 	});
 });
 
-describe("todo state: normalization", () => {
-	it("demotes surplus in_progress tasks", () => {
-		const phases: TodoPhase[] = [
-			{
-				name: "A",
-				tasks: [
-					{ content: "a1", status: "in_progress" },
-					{ content: "a2", status: "in_progress" },
-				],
-			},
-		];
-		normalizeInProgressTask(phases);
-		expect(phases[0].tasks.map(t => t.status)).toEqual(["in_progress", "pending"]);
-	});
-
-	it("auto-promotes the earliest pending task when none is in progress", () => {
+describe("todo state: explicit-status semantics (no normalization)", () => {
+	it("completion never auto-promotes another task", () => {
 		const phases: TodoPhase[] = [
 			{ name: "A", tasks: [{ content: "a1", status: "completed" }] },
 			{ name: "B", tasks: [{ content: "b1", status: "pending" }] },
 		];
-		normalizeInProgressTask(phases);
-		expect(phases[1].tasks[0].status).toBe("in_progress");
+		const { phases: updated } = applyParams(clonePhases(phases), { op: "done", task: "b1" });
+		expect(updated[1].tasks[0].status).toBe("completed");
+		// No hidden pointer: no task was touched besides the target.
+		expect(updated[0].tasks[0].status).toBe("completed");
 	});
 
-	it("out-of-order completion can move the pointer back to an earlier phase", () => {
-		let { phases } = applyParams(phasesWithTasks(["A", "a1", "a2"], ["B", "b1"]), { op: "done", task: "a1" });
-		({ phases } = applyParams(phases, { op: "done", task: "b1" }));
-		// b1 done; pointer returns to a2 (earliest open task).
-		expect(phases[0].tasks[1].status).toBe("in_progress");
+	it("out-of-order completion leaves every other status untouched", () => {
+		let { phases } = applyParams(phasesWithTasks(["A", "a1", "a2"], ["B", "b1"]), { op: "done", task: "b1" });
+		expect(phases[0].tasks.map(t => t.status)).toEqual(["pending", "pending"]);
 		expect(phases[1].tasks[0].status).toBe("completed");
 	});
 });
 
 describe("todo state: helpers", () => {
-	it("counts actionable open tasks, excluding settled and blocked work", () => {
-		const phases: TodoPhase[] = [
-			{
-				name: "A",
-				tasks: [
-					{ content: "a1", status: "completed" },
-					{ content: "a2", status: "abandoned" },
-					{ content: "a3", status: "pending" },
-					{ content: "a4", status: "in_progress" },
-					{ content: "a5", status: "blocked", blocker: "ci" },
-				],
-			},
-		];
-		expect(openTasks(phases).map(t => t.content)).toEqual(["a3", "a4"]);
-	});
-
 	it("validates phase snapshots for restore", () => {
 		expect(isTodoPhase({ name: "A", tasks: [{ content: "a", status: "pending" }] })).toBe(true);
 		expect(isTodoPhase({ name: "A", tasks: [{ content: "a", status: "bogus" }] })).toBe(false);
@@ -363,6 +332,36 @@ describe("todo state: summary text", () => {
 		expect(formatSummary([], ["boom"])).toBe("Errors: boom");
 		expect(formatSummary([], [])).toBe("Todo list cleared.");
 	});
+
+	it("folds the per-task dumps on big mutation results but view still echoes in full", () => {
+		// 25 tasks (> SUMMARY_FULL_LIST_LIMIT): 5 done, 20 open.
+		const statuses: TodoPhase[] = [
+			{
+				name: "Big",
+				tasks: Array.from({ length: 25 }, (_, i) => ({
+					content: `task ${i + 1}`,
+					status: (i < 5 ? "completed" : "pending") as TodoPhase["tasks"][number]["status"],
+				})),
+			},
+		];
+
+		// Mutation result: remaining capped at 10 + fold hints, no phase checklist.
+		const mutation = formatSummary(statuses, []);
+		expect(mutation).toContain("Remaining items (20):");
+		expect(mutation).toContain("- task 6 [pending] (Big)");
+		expect(mutation).toContain("… 10 more open — call `view` for the full list.");
+		expect(mutation).toContain("Overall: 5/25 done, 20 open.");
+		expect(mutation).toContain("Full checklist omitted (25 tasks) — `view` echoes it.");
+		expect(mutation).not.toContain("  Big:");
+		expect(mutation).not.toContain("- task 16 [pending]");
+
+		// view (readOnly): full echo, no folding, no omission notice.
+		const view = formatSummary(statuses, [], true);
+		expect(view).toContain("- task 25 [pending] (Big)");
+		expect(view).toContain("[X] task 1");
+		expect(view).not.toContain("Full checklist omitted");
+		expect(view).not.toContain("more open — call");
+	});
 });
 
 describe("todo state: params type", () => {