@fyeeme/pi-todo 1.0.0

package/src/state.ts

@@ -0,0 +1,842 @@
+/**
+ * pi-todo — pure todo state logic.
+ *
+ * Ported from oh-my-pi (github.com/can1357/oh-my-pi, a fork of badlogic/pi-mono)
+ * `packages/coding-agent/src/tools/todo.ts` — the data model, the nine
+ * operations, their validation semantics, and the summary text are carried
+ * over behavior-for-behavior. Dropped from the omp source (host-internal
+ * surfaces with no pi counterpart):
+ *   - markdown round-trip (omp /todo edit)   - prompt-line analysis machines
+ *   - collapsed-viewport selection / HUD      - subagent description matching
+ *   - nextActionableTask (prewalk consumer)   - tool examples (omp-only field)
+ */
+
+import * as os from "node:os";
+import * as path from "node:path";
+
+export type TodoStatus = "pending" | "in_progress" | "completed" | "abandoned" | "blocked";
+
+/** Operation names accepted by the todo tool and echoed in successful result details. */
+export type TodoOperation = "init" | "start" | "done" | "rm" | "drop" | "block" | "unblock" | "append" | "view";
+
+export interface TodoItem {
+	content: string;
+	status: TodoStatus;
+	/** When `status === "blocked"`, an optional note on what the task is waiting for. */
+	blocker?: string;
+}
+
+export interface TodoPhase {
+	name: string;
+	tasks: TodoItem[];
+}
+
+export interface TodoCompletionTransition {
+	phase: string;
+	content: string;
+}
+
+export interface TodoToolDetails {
+	/** Operation that produced this snapshot. */
+	op: TodoOperation;
+	phases: TodoPhase[];
+	storage: "session" | "memory";
+	completedTasks?: TodoCompletionTransition[];
+}
+
+/** Operation input accepted by applyEntry (schema-validated tool params). */
+export interface TodoOpEntry {
+	op: TodoOperation;
+	list?: Array<{ phase: string; items: string[] }>;
+	task?: string;
+	phase?: string;
+	items?: string[];
+	reason?: string;
+}
+
+// =============================================================================
+// Guards
+// =============================================================================
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** Whether an unknown value is a persisted todo phase. */
+export function isTodoPhase(value: unknown): value is TodoPhase {
+	if (!isRecord(value) || typeof value.name !== "string" || !Array.isArray(value.tasks)) return false;
+	return value.tasks.every(
+		task =>
+			isRecord(task) &&
+			typeof task.content === "string" &&
+			(task.status === "pending" ||
+				task.status === "in_progress" ||
+				task.status === "completed" ||
+				task.status === "abandoned" ||
+				task.status === "blocked"),
+	);
+}
+
+/** Whether an unknown value is a persisted `{ phases }` snapshot. */
+export function isTodoPhaseSnapshot(value: unknown): value is { phases: TodoPhase[] } {
+	return isRecord(value) && Array.isArray(value.phases) && value.phases.every(isTodoPhase);
+}
+
+// =============================================================================
+// State helpers
+// =============================================================================
+
+function findTaskByContent(phases: TodoPhase[], content: string): { task: TodoItem; phase: TodoPhase } | undefined {
+	for (const phase of phases) {
+		const task = phase.tasks.find(t => t.content === content);
+		if (task) return { task, phase };
+	}
+	return undefined;
+}
+
+function findPhaseByName(phases: TodoPhase[], name: string): TodoPhase | undefined {
+	return phases.find(phase => phase.name === name);
+}
+
+function cloneTask(task: TodoItem): TodoItem {
+	return task.blocker !== undefined
+		? { content: task.content, status: task.status, blocker: task.blocker }
+		: { content: task.content, status: task.status };
+}
+
+export function clonePhases(phases: TodoPhase[]): TodoPhase[] {
+	return phases.map(phase => ({ name: phase.name, tasks: phase.tasks.map(cloneTask) }));
+}
+
+function todoTransitionKey(phase: string, content: string): string {
+	return `${phase}\u0000${content}`;
+}
+
+export function getCompletionTransitions(previous: TodoPhase[], updated: TodoPhase[]): TodoCompletionTransition[] {
+	const previousStatuses = new Map<string, TodoStatus>();
+	for (const phase of previous) {
+		for (const task of phase.tasks) {
+			previousStatuses.set(todoTransitionKey(phase.name, task.content), task.status);
+		}
+	}
+
+	const transitions: TodoCompletionTransition[] = [];
+	for (const phase of updated) {
+		for (const task of phase.tasks) {
+			if (task.status !== "completed") continue;
+			const previousStatus = previousStatuses.get(todoTransitionKey(phase.name, task.content));
+			if (previousStatus && previousStatus !== "completed") {
+				transitions.push({ phase: phase.name, content: task.content });
+			}
+		}
+	}
+	return transitions;
+}
+
+/**
+ * Enforce the single-`in_progress` invariant after every mutation: demote
+ * surplus in-progress tasks, then auto-promote the earliest pending task when
+ * none is in progress (the "pointer" the todo prompt documents).
+ */
+export function normalizeInProgressTask(phases: TodoPhase[]): void {
+	const orderedTasks = phases.flatMap(phase => phase.tasks);
+	if (orderedTasks.length === 0) return;
+
+	const inProgressTasks = orderedTasks.filter(task => task.status === "in_progress");
+	if (inProgressTasks.length > 1) {
+		for (const task of inProgressTasks.slice(1)) {
+			task.status = "pending";
+		}
+	}
+
+	if (inProgressTasks.length > 0) return;
+
+	const firstPendingTask = orderedTasks.find(task => task.status === "pending");
+	if (firstPendingTask) firstPendingTask.status = "in_progress";
+}
+
+/** Whether a todo is settled: completed or deliberately abandoned. Shared so
+ *  the collapsed viewport and the summary counters can never disagree about
+ *  what "done" hides. */
+export function isClosedTodo<T extends { status: TodoStatus }>(task: T): boolean {
+	return task.status === "completed" || task.status === "abandoned";
+}
+
+// =============================================================================
+// Collapsed-viewport selection (omp #5873 walking viewport)
+// =============================================================================
+
+/** Minimum overlap (after normalization) required for a substring match.
+ * Picked at six chars to admit single-word identifiers like "review" /
+ * "Sonnet" without admitting tiny common substrings like "test" / "fix"
+ * that would collide across unrelated todos. */
+const TODO_DESCRIPTION_MIN_OVERLAP = 6;
+
+function normalizeForTodoMatch(value: string): string {
+	return value
+		.toLowerCase()
+		.replace(/[^\p{L}\p{N}]+/gu, " ")
+		.trim();
+}
+
+/**
+ * Report whether `content` likely names the same work as any entry in
+ * `descriptions`. Used by the todo renderer to light up a pending todo when an
+ * in-flight subagent is doing the work for it. Matching is normalize-then-equal
+ * first, with a substring fallback in either direction requiring at least
+ * {@link TODO_DESCRIPTION_MIN_OVERLAP} chars on the contained side.
+ */
+export function todoMatchesAnyDescription(content: string, descriptions: readonly string[]): boolean {
+	const target = normalizeForTodoMatch(content);
+	if (!target) return false;
+	for (const desc of descriptions) {
+		const candidate = normalizeForTodoMatch(desc);
+		if (!candidate) continue;
+		if (target === candidate) return true;
+		if (target.length >= TODO_DESCRIPTION_MIN_OVERLAP && candidate.includes(target)) return true;
+		if (candidate.length >= TODO_DESCRIPTION_MIN_OVERLAP && target.includes(candidate)) return true;
+	}
+	return false;
+}
+
+/** omp pluralize (packages/utils/src/format.ts). */
+export function pluralize(label: string, count: number): string {
+	if (count === 1) return label;
+	if (/(?:ch|sh|s|x|z)$/i.test(label)) return `${label}es`;
+	if (/[^aeiou]y$/i.test(label)) return `${label.slice(0, -1)}ies`;
+	return `${label}s`;
+}
+
+/** omp formatMoreItems (tools/render-utils.ts). */
+export function formatMoreItems(remaining: number, itemType: string): string {
+	const safeRemaining = Number.isFinite(remaining) ? remaining : 0;
+	return `… ${safeRemaining} more ${pluralize(itemType, safeRemaining)}`;
+}
+
+/** A todo the collapsed viewport treats as current work: the literal
+ *  `in_progress` task or a pending task a live subagent is executing. */
+function isActiveTodo<T extends { status: TodoStatus }>(task: T, isMatched: (task: T) => boolean): boolean {
+	return task.status === "in_progress" || (task.status === "pending" && isMatched(task));
+}
+
+/** Result of {@link selectCollapsedTodos}: the rows to render plus an optional
+ *  summary line (empty string ⇒ no summary row). */
+export interface CollapsedTodoSelection<T> {
+	items: T[];
+	summary: string;
+}
+
+/** Closed rows kept directly above the open window so finishing a task is
+ *  visible as it happens (omp COLLAPSED_CLOSED_CONTEXT). */
+const COLLAPSED_CLOSED_CONTEXT = 1;
+
+function selectWithinCap<T extends { status: TodoStatus }>(
+	base: T[],
+	isMatched: (task: T) => boolean,
+	cap: number,
+): CollapsedTodoSelection<T> {
+	if (base.length <= cap) return { items: base, summary: "" };
+
+	const active = base.filter(task => isActiveTodo(task, isMatched));
+	// Only when active work strictly exceeds the cap do we drop pending rows and
+	// count hidden *actives*. At exactly `cap` actives, fall through so the normal
+	// branch still surfaces any following pending work in the summary.
+	if (active.length > cap) {
+		const hiddenActive = active.length - cap;
+		return {
+			items: active.slice(0, cap),
+			summary: `… ${hiddenActive} more active ${pluralize("todo", hiddenActive)}`,
+		};
+	}
+
+	// Fill trailing rows with tasks following the first active one, so the
+	// promoted/current task leads and its successors follow in todo order.
+	const firstActiveIdx = active.length > 0 ? base.indexOf(active[0]) : 0;
+	const fill: T[] = [];
+	for (let i = firstActiveIdx; i < base.length && active.length + fill.length < cap; i++) {
+		const task = base[i];
+		if (isActiveTodo(task, isMatched)) continue;
+		fill.push(task);
+	}
+	const items = [...active, ...fill];
+	const hidden = base.length - items.length;
+	return { items, summary: hidden > 0 ? formatMoreItems(hidden, "todo") : "" };
+}
+
+/**
+ * Walking-viewport selection for a phase's collapsed todo preview (omp
+ * #5873). Applied to `tasks` in todo order: the open tasks run through
+ * {@link selectWithinCap}, led by the last {@link COLLAPSED_CLOSED_CONTEXT}
+ * closed tasks in todo order so a checked row remains visible even when callers
+ * complete work out of sequence. `summary` counts the open tasks that did not
+ * fit; the closed lead is context, not part of the budget.
+ */
+export function selectCollapsedTodos<T extends { status: TodoStatus }>(
+	tasks: T[],
+	isMatched: (task: T) => boolean,
+	cap: number,
+): CollapsedTodoSelection<T> {
+	const open = tasks.filter(task => !isClosedTodo(task));
+	// Closed tasks are never active, so a settled phase selects over itself.
+	if (open.length === 0) return selectWithinCap(tasks, isMatched, cap);
+	// `done` accepts any named task, so closed tasks are not necessarily a prefix.
+	const lead = tasks.filter(isClosedTodo).slice(-COLLAPSED_CLOSED_CONTEXT);
+	const selected = selectWithinCap(open, isMatched, cap);
+	return { items: [...lead, ...selected.items], summary: selected.summary };
+}
+
+// =============================================================================
+// Stop-reminder guards (omp TodoTracker.isAwaitingUserAnswer)
+// =============================================================================
+
+const MARKDOWN_PROMPT_PREFIX_RE = /^(?:>\s*)?(?:(?:[-*+]|\d+[.)])\s+)*/;
+const PROMPT_LABEL_RE = /^(?:q(?:uestion)?|ask)\s*\d*\s*[:.)-]\s*/i;
+const QUESTION_PROMPT_RE =
+	/^(?:what|which|when|where|why|how|who|whom|whose|do|does|did|can|could|would|will|should|is|are|am|may|shall)\b/i;
+const USER_DIRECTED_PROMPT_RE = /\b(?:you|your|we|our)\b/i;
+const USER_RESPONSE_CUE_RE =
+	/^(?:please\s+)?(?:confirm|reply|choose|pick|decide|advise)\b|^(?:please\s+)?answer\b|^(?:please\s+)?(?:let\s+me\s+know|tell\s+me)\b/i;
+/**
+ * A trailing question mark is the universal signal that a line is a question, but
+ * the English word/pronoun gates above exist to filter incidental "?" out of prose
+ * (e.g. a TypeScript `foo?: string` tail). Non-English text has no cheap word list,
+ * yet any non-ASCII character in a "?"/"？"-terminated line reliably marks it as
+ * genuine prose — so treat it as a real user-directed question (omp #7803).
+ */
+const NON_ASCII_TEXT_RE = /[^\x00-\x7F]/;
+
+interface PromptLine {
+	text: string;
+	hadPromptLabel: boolean;
+}
+
+function promptLine(line: string): PromptLine {
+	const withoutMarkdownPrefix = line.trim().replace(MARKDOWN_PROMPT_PREFIX_RE, "").trim();
+	const withoutPromptLabel = withoutMarkdownPrefix.replace(PROMPT_LABEL_RE, "").trim();
+	return {
+		text: withoutPromptLabel,
+		hadPromptLabel: withoutPromptLabel !== withoutMarkdownPrefix,
+	};
+}
+
+function isQuestionPromptLine(line: string): boolean {
+	const candidate = promptLine(line);
+	if (!/[?？]\s*$/.test(candidate.text)) return false;
+	return (
+		candidate.hadPromptLabel ||
+		QUESTION_PROMPT_RE.test(candidate.text) ||
+		USER_DIRECTED_PROMPT_RE.test(candidate.text) ||
+		NON_ASCII_TEXT_RE.test(candidate.text)
+	);
+}
+
+function isResponseCueLine(line: string): boolean {
+	const candidate = promptLine(line)
+		.text.replace(/[.!?。！？]+$/, "")
+		.trim();
+	return USER_RESPONSE_CUE_RE.test(candidate);
+}
+
+/** Whether an assistant reply ends by asking the user something — omp skips
+ *  the stop reminder in that case (the ball is in the user's court). */
+export function isAwaitingUserAnswer(assistantText: string): boolean {
+	const text = assistantText.trim();
+	if (!text) return false;
+	const lastLine = text.split(/\r?\n/).at(-1)?.trim();
+	return lastLine !== undefined && (isQuestionPromptLine(lastLine) || isResponseCueLine(lastLine));
+}
+
+// =============================================================================
+// Phase numbering (display-only, omp phaseRomanNumeral)
+// =============================================================================
+
+const ROMAN_PAIRS: Array<[number, string]> = [
+	[1000, "M"],
+	[900, "CM"],
+	[500, "D"],
+	[400, "CD"],
+	[100, "C"],
+	[90, "XC"],
+	[50, "L"],
+	[40, "XL"],
+	[10, "X"],
+	[9, "IX"],
+	[5, "V"],
+	[4, "IV"],
+	[1, "I"],
+];
+
+/** One-based ASCII roman numeral for display (I, II, III, IV, …). */
+export function phaseRomanNumeral(oneBasedIndex: number): string {
+	if (oneBasedIndex <= 0) return "";
+	let out = "";
+	let rem = oneBasedIndex;
+	for (const [value, sym] of ROMAN_PAIRS) {
+		while (rem >= value) {
+			out += sym;
+			rem -= value;
+		}
+	}
+	return out;
+}
+
+// =============================================================================
+// Markdown round-trip (omp /todo edit / copy / export / import)
+// =============================================================================
+
+const STATUS_TO_MARKER: Record<TodoStatus, string> = {
+	pending: " ",
+	in_progress: "/",
+	completed: "x",
+	abandoned: "-",
+	blocked: "!",
+};
+
+/** Render todo phases as a Markdown checklist suitable for editing/copying. */
+export function phasesToMarkdown(phases: TodoPhase[]): string {
+	if (phases.length === 0) return "# Todos\n";
+	const out: string[] = [];
+	for (let i = 0; i < phases.length; i++) {
+		if (i > 0) out.push("");
+		out.push(`# ${phases[i].name}`);
+		for (const task of phases[i].tasks) {
+			// A blocked task's reason rides in a trailing HTML comment: invisible in
+			// rendered markdown, unambiguous to parse back (task content can't
+			// contain the comment delimiters), so the note survives `/todo edit` and
+			// export/import round-trips.
+			const blockerNote = task.status === "blocked" && task.blocker ? ` <!-- blocker: ${task.blocker} -->` : "";
+			out.push(`- [${STATUS_TO_MARKER[task.status]}] ${task.content}${blockerNote}`);
+		}
+	}
+	return `${out.join("\n")}\n`;
+}
+
+const MARKER_TO_STATUS: Record<string, TodoStatus> = {
+	" ": "pending",
+	"": "pending",
+	x: "completed",
+	X: "completed",
+	"/": "in_progress",
+	">": "in_progress",
+	"-": "abandoned",
+	"~": "abandoned",
+	"!": "blocked",
+};
+
+/** Parse a Markdown checklist back into todo phases. */
+export function markdownToPhases(md: string): { phases: TodoPhase[]; errors: string[] } {
+	const errors: string[] = [];
+	const phases: TodoPhase[] = [];
+	let currentPhase: TodoPhase | undefined;
+
+	const lines = md.split(/\r?\n/);
+	for (let lineNum = 0; lineNum < lines.length; lineNum++) {
+		const raw = lines[lineNum];
+
+		const trimmed = raw.trim();
+		if (!trimmed) continue;
+
+		const headingMatch = /^#{1,6}\s+(.+?)\s*$/.exec(trimmed);
+		if (headingMatch) {
+			currentPhase = { name: headingMatch[1].trim(), tasks: [] };
+			phases.push(currentPhase);
+			continue;
+		}
+
+		// Tolerate backslash-escaped brackets (`- \[x\]`): some editors and
+		// markdown serializers escape `[` (and `]`) when round-tripping, yet the
+		// line still renders as a normal `[x]` checkbox. Accept either form.
+		const taskMatch = /^[-*+]\s*\\?\[(.?)\\?\]\s+(.+?)\s*$/.exec(trimmed);
+		if (taskMatch) {
+			if (!currentPhase) {
+				currentPhase = { name: "Todos", tasks: [] };
+				phases.push(currentPhase);
+			}
+			const marker = taskMatch[1];
+			const status = MARKER_TO_STATUS[marker];
+			if (!status) {
+				errors.push(`Line ${lineNum + 1}: unknown status marker "[${marker}]" (use [ ], [x], [/], [-], [!])`);
+				continue;
+			}
+			// Recover a blocked task's reason from its trailing HTML comment (see
+			// phasesToMarkdown), then strip the comment from the visible content.
+			const rawContent = taskMatch[2].trim();
+			const blockerMatch = /^(.*?)\s*<!--\s*blocker:\s*(.*?)\s*-->$/.exec(rawContent);
+			if (status === "blocked" && blockerMatch) {
+				currentPhase.tasks.push({ content: blockerMatch[1].trim(), status, blocker: blockerMatch[2].trim() });
+			} else {
+				currentPhase.tasks.push({ content: rawContent, status });
+			}
+			continue;
+		}
+
+		errors.push(`Line ${lineNum + 1}: unrecognized syntax "${trimmed}"`);
+	}
+
+	normalizeInProgressTask(phases);
+	return { phases, errors };
+}
+
+/** omp normalizePathLikeInput: trim + strip outer double quotes. */
+function normalizePathLikeInput(input: string): string {
+	const trimmed = input.trim();
+	if (trimmed.length >= 2 && trimmed.startsWith('"') && trimmed.endsWith('"')) {
+		return trimmed.slice(1, -1);
+	}
+	return trimmed;
+}
+
+/** omp resolveTodoMarkdownPath: default TODO.md, ~ expansion, cwd-relative. */
+export function resolveTodoMarkdownPath(input: string, cwd: string): string {
+	const raw = normalizePathLikeInput(input) || "TODO.md";
+	const expanded = raw === "~" ? os.homedir() : raw.startsWith("~/") ? path.join(os.homedir(), raw.slice(2)) : raw;
+	return path.isAbsolute(expanded) ? expanded : path.resolve(cwd, expanded);
+}
+
+/**
+ * Actionable open work (pending / in_progress): what stop-time reminders count.
+ * Blocked tasks are excluded — they are parked awaiting external input, so
+ * nagging about them would be noise (omp todo prompt: "excluded from
+ * stop-time incomplete-todo reminder").
+ */
+export function openTasks(phases: TodoPhase[]): TodoItem[] {
+	return phases.flatMap(phase =>
+		phase.tasks.filter(task => task.status === "pending" || task.status === "in_progress"),
+	);
+}
+
+// =============================================================================
+// Operation resolution
+// =============================================================================
+
+function resolveTaskOrError(
+	phases: TodoPhase[],
+	content: string | undefined,
+	errors: string[],
+): { task: TodoItem; phase: TodoPhase } | undefined {
+	if (!content) {
+		errors.push("Missing task content");
+		return undefined;
+	}
+	const hit = findTaskByContent(phases, content);
+	if (!hit) {
+		if (/^task-\d+$/.test(content)) {
+			errors.push(
+				`Task "${content}" not found. Tasks are referenced by content, not by IDs — pass the task's full text from the previous result.`,
+			);
+		} else {
+			const totalTasks = phases.reduce((sum, phase) => sum + phase.tasks.length, 0);
+			const hint = totalTasks === 0 ? " (todo list is empty — was it replaced or not yet created?)" : "";
+			errors.push(`Task "${content}" not found${hint}`);
+		}
+	}
+	return hit;
+}
+
+function resolvePhaseOrError(phases: TodoPhase[], name: string | undefined, errors: string[]): TodoPhase | undefined {
+	if (!name) {
+		errors.push("Missing phase name");
+		return undefined;
+	}
+	const phase = findPhaseByName(phases, name);
+	if (!phase) errors.push(`Phase "${name}" not found`);
+	return phase;
+}
+
+function getTaskTargets(phases: TodoPhase[], entry: TodoOpEntry, errors: string[]): TodoItem[] {
+	if (entry.task) {
+		const hit = resolveTaskOrError(phases, entry.task, errors);
+		return hit ? [hit.task] : [];
+	}
+	if (entry.phase) {
+		const phase = resolvePhaseOrError(phases, entry.phase, errors);
+		return phase ? [...phase.tasks] : [];
+	}
+	return phases.flatMap(phase => phase.tasks);
+}
+
+/** Phase name for `init` given a flat `items` list with no explicit `phase`. */
+const DEFAULT_INIT_PHASE = "Tasks";
+
+function initPhases(entry: TodoOpEntry, errors: string[]): TodoPhase[] {
+	// Models routinely flatten the single-phase init into `{op:"init", items:[...]}`
+	// (optionally with a bare `phase`) instead of the canonical
+	// `list: [{phase, items}]`. Accept that shape by synthesizing a one-phase list
+	// so a common, recoverable mistake isn't a hard error.
+	const list =
+		entry.list ??
+		(entry.items && entry.items.length > 0
+			? [{ phase: entry.phase ?? DEFAULT_INIT_PHASE, items: entry.items }]
+			: undefined);
+	if (!list) {
+		errors.push("Missing list for init operation");
+		return [];
+	}
+	// Duplicate phase names / task contents would be permanently unaddressable
+	// (every targeting op resolves the first match), so reject them up front.
+	const seenPhases = new Set<string>();
+	const seenTasks = new Set<string>();
+	for (const listEntry of list) {
+		if (seenPhases.has(listEntry.phase)) {
+			errors.push(`Duplicate phase "${listEntry.phase}" in init list`);
+		}
+		seenPhases.add(listEntry.phase);
+		for (const content of listEntry.items) {
+			if (seenTasks.has(content)) {
+				errors.push(`Duplicate task "${content}" in init list`);
+			}
+			seenTasks.add(content);
+		}
+	}
+	return list.map(listEntry => ({
+		name: listEntry.phase,
+		tasks: listEntry.items.map(content => ({ content, status: "pending" as const })),
+	}));
+}
+
+function appendItems(phases: TodoPhase[], entry: TodoOpEntry, errors: string[]): TodoPhase[] {
+	if (!entry.phase) {
+		errors.push("Missing phase name for append operation");
+		return phases;
+	}
+	if (!entry.items || entry.items.length === 0) {
+		errors.push("Missing items for append operation");
+		return phases;
+	}
+
+	// Validate the whole batch before mutating so a failing op reports every
+	// duplicate and leaves nothing half-applied.
+	const seen = new Set<string>();
+	let hasDuplicate = false;
+	for (const content of entry.items) {
+		if (seen.has(content) || findTaskByContent(phases, content)) {
+			errors.push(`Task "${content}" already exists`);
+			hasDuplicate = true;
+		}
+		seen.add(content);
+	}
+	if (hasDuplicate) return phases;
+
+	let phase = findPhaseByName(phases, entry.phase);
+	if (!phase) {
+		phase = { name: entry.phase, tasks: [] };
+		phases.push(phase);
+	}
+
+	for (const content of entry.items) {
+		phase.tasks.push({ content, status: "pending" });
+	}
+	return phases;
+}
+
+function removeTasks(phases: TodoPhase[], entry: TodoOpEntry, errors: string[]): TodoPhase[] {
+	if (entry.task) {
+		const hit = resolveTaskOrError(phases, entry.task, errors);
+		if (!hit) return phases;
+		hit.phase.tasks = hit.phase.tasks.filter(candidate => candidate !== hit.task);
+		return phases;
+	}
+	if (entry.phase) {
+		const phase = resolvePhaseOrError(phases, entry.phase, errors);
+		if (!phase) return phases;
+		phase.tasks = [];
+		return phases;
+	}
+	for (const phase of phases) {
+		phase.tasks = [];
+	}
+	return phases;
+}
+
+function applyEntry(phases: TodoPhase[], entry: TodoOpEntry, errors: string[]): TodoPhase[] {
+	switch (entry.op) {
+		case "init":
+			return initPhases(entry, errors);
+		case "start": {
+			const hit = resolveTaskOrError(phases, entry.task, errors);
+			if (!hit) return phases;
+			for (const phase of phases) {
+				for (const candidate of phase.tasks) {
+					if (candidate.status === "in_progress" && candidate !== hit.task) {
+						candidate.status = "pending";
+					}
+				}
+			}
+			hit.task.status = "in_progress";
+			return phases;
+		}
+		case "done": {
+			for (const task of getTaskTargets(phases, entry, errors)) {
+				task.status = "completed";
+			}
+			return phases;
+		}
+		case "drop": {
+			for (const task of getTaskTargets(phases, entry, errors)) {
+				task.status = "abandoned";
+			}
+			return phases;
+		}
+		case "block": {
+			if (!entry.task && !entry.phase) {
+				errors.push("block requires a task or phase target");
+				return phases;
+			}
+			// Collapse whitespace runs (incl. newlines) to single spaces: a blocker
+			// note rides on one Markdown checklist line and one summary line, so an
+			// embedded newline would corrupt the rendered line. Normalizing here
+			// keeps every consumer one-line-safe.
+			const reason = entry.reason?.replace(/\s+/g, " ").trim() || undefined;
+			for (const task of getTaskTargets(phases, entry, errors)) {
+				// Only actionable open work can be blocked: blocking a phase must not
+				// reopen completed/abandoned tasks or erase finished progress. An
+				// already-blocked task stays eligible so a later block can refine its
+				// blocker note (e.g. first blocked without a reason, then with one).
+				if (task.status !== "pending" && task.status !== "in_progress" && task.status !== "blocked") continue;
+				task.status = "blocked";
+				task.blocker = reason;
+			}
+			return phases;
+		}
+		case "unblock": {
+			if (!entry.task && !entry.phase) {
+				errors.push("unblock requires a task or phase target");
+				return phases;
+			}
+			for (const task of getTaskTargets(phases, entry, errors)) {
+				if (task.status === "blocked") {
+					task.status = "pending";
+					task.blocker = undefined;
+				}
+			}
+			return phases;
+		}
+		case "rm":
+			return removeTasks(phases, entry, errors);
+		case "append":
+			return appendItems(phases, entry, errors);
+		case "view":
+			return phases;
+	}
+}
+
+// =============================================================================
+// Missing-op inference
+// =============================================================================
+
+/**
+ * Infer a missing `op` from the raw argument shape. Only unambiguous shapes
+ * are inferred:
+ * - `list` → `init` (list is init-only)
+ * - `items` + `phase` → `append` (lazily creates the phase, so the result
+ *   matches a single-phase init when nothing exists yet)
+ * - bare `items` with no existing todos → `init` (nothing to overwrite)
+ * Targeting args alone (`task`/`phase`) map to several ops and stay an error.
+ */
+export function inferTodoOp(args: Record<string, unknown>, hasExistingPhases: boolean): TodoOperation | undefined {
+	if (Array.isArray(args.list) && args.list.length > 0) return "init";
+	if (Array.isArray(args.items) && args.items.length > 0) {
+		if (typeof args.phase === "string" && args.phase) return "append";
+		if (!hasExistingPhases) return "init";
+	}
+	return undefined;
+}
+
+export function applyParams(phases: TodoPhase[], params: TodoOpEntry): { phases: TodoPhase[]; errors: string[] } {
+	const errors: string[] = [];
+	const next = applyEntry(phases, params, errors);
+	normalizeInProgressTask(next);
+	return { phases: next, errors };
+}
+
+/** Apply an array of `todo`-style ops to existing phases. Used by /todo clear. */
+export function applyOpsToPhases(
+	currentPhases: TodoPhase[],
+	ops: TodoOpEntry[],
+): { phases: TodoPhase[]; errors: string[] } {
+	const errors: string[] = [];
+	let next = clonePhases(currentPhases);
+	for (const op of ops) {
+		next = applyEntry(next, op, errors);
+	}
+	normalizeInProgressTask(next);
+	return { phases: next, errors };
+}
+
+// =============================================================================
+// Summary text (tool result body)
+// =============================================================================
+
+export function formatSummary(phases: TodoPhase[], errors: string[], readOnly = false): string {
+	const tasks = phases.flatMap(phase => phase.tasks);
+	if (tasks.length === 0) {
+		if (errors.length > 0) return `Errors: ${errors.join("; ")}`;
+		return readOnly ? "Todo list is empty." : "Todo list cleared.";
+	}
+
+	const remainingByPhase = phases
+		.map(phase => ({
+			name: phase.name,
+			tasks: phase.tasks.filter(task => task.status === "pending" || task.status === "in_progress"),
+		}))
+		.filter(phase => phase.tasks.length > 0);
+	const remainingTasks = remainingByPhase.flatMap(phase => phase.tasks.map(task => ({ ...task, phase: phase.name })));
+
+	let currentIdx = phases.findIndex(phase =>
+		phase.tasks.some(task => task.status === "pending" || task.status === "in_progress"),
+	);
+	if (currentIdx === -1) currentIdx = phases.length - 1;
+	const current = phases[currentIdx];
+	const done = current.tasks.filter(task => task.status === "completed" || task.status === "abandoned").length;
+
+	const lines: string[] = [];
+	if (errors.length > 0) lines.push(`Errors: ${errors.join("; ")}`);
+	if (remainingTasks.length === 0) {
+		lines.push("Remaining items: none.");
+	} else {
+		lines.push(`Remaining items (${remainingTasks.length}):`);
+		for (const task of remainingTasks) {
+			lines.push(`  - ${task.content} [${task.status}] (${task.phase})`);
+		}
+	}
+	// Closed = completed + abandoned, mirroring the per-phase `done` count.
+	const closedAll = tasks.filter(task => task.status === "completed" || task.status === "abandoned").length;
+	const blockedAll = tasks.filter(task => task.status === "blocked").length;
+	// The active phase is the EARLIEST one still holding open work, so the
+	// in-progress pointer can sit in a phase whose successors already have
+	// completed tasks. Detect that "worked ahead" case to explain the
+	// otherwise-surprising backward pointer instead of letting it read as a
+	// completed task reverting to pending.
+	const workedAhead = phases.some(
+		(phase, idx) =>
+			idx > currentIdx && phase.tasks.some(task => task.status === "completed" || task.status === "abandoned"),
+	);
+	lines.push(
+		`Overall: ${closedAll}/${tasks.length} done, ${remainingTasks.length} open${blockedAll > 0 ? `, ${blockedAll} blocked` : ""}.`,
+	);
+	lines.push(
+		`Active phase ${currentIdx + 1}/${phases.length} "${current.name}" (${done}/${current.tasks.length})${
+			workedAhead
+				? " — 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)."
+				: "."
+		}`,
+	);
+	for (const phase of phases) {
+		lines.push(`  ${phase.name}:`);
+		for (const task of phase.tasks) {
+			const checkbox = task.status === "completed" ? "[X]" : "[ ]";
+			const tag =
+				task.status === "in_progress"
+					? " (in progress)"
+					: task.status === "abandoned"
+						? " (dropped)"
+						: task.status === "blocked"
+							? task.blocker
+								? ` (blocked: ${task.blocker})`
+								: " (blocked)"
+							: "";
+			lines.push(`    - ${checkbox} ${task.content}${tag}`);
+		}
+	}
+	return lines.join("\n");
+}