@pi9/todo 0.1.0 → 0.3.0

package/README.md

@@ -1,87 +1,17 @@
 # @pi9/todo
 
-A phased, branch-aware todo tool for the [Pi coding agent](https://github.com/earendil-works/pi-mono).
+A phased, session-aware todo tool for the [Pi coding agent](https://github.com/earendil-works/pi-mono), with adaptive system reminders and a persistent widget that keeps the current plan visible while you work.
 
-## Features
-
-- Concise phased plans with immutable task names
-- Destructive plan replacement and non-destructive task addition
-- Atomic status transitions addressed by exact phase and task names
-- Explicit `pending`, `in_progress`, `completed`, and `cancelled` statuses
-- State restored from the active Pi session branch
-- A persistent, configurable todo widget above or below the editor
-- Rich tool rendering with active-task summaries and expandable phase progress
-- Native-style self-rendered tool shells with no extra spacing for hidden activity
-
-Todo snapshots are stored in tool-result details, so `/tree` navigation restores the plan associated with that branch.
-
-## Tool contract
-
-The provider-facing schema is one flat object rather than a union, which keeps it compatible across Pi providers. Action-specific requirements are validated atomically by the tool.
+![A phased todo plan showing completed, active, and pending tasks](media/todo-plan.png)
 
-### Set the complete plan
-
-`set` discards the complete current plan and creates exactly the supplied phases and tasks. Every task starts `pending`. An empty `phases` array clears the plan.
-
-```json
-{
-  "action": "set",
-  "phases": [
-    {
-      "name": "Build",
-      "tasks": ["Implement session restoration", "Add integration coverage"]
-    }
-  ]
-}
-```
-
-### Add newly discovered work
-
-`add` creates missing phases or appends tasks to existing phases without changing current tasks or statuses. New tasks start `pending`.
-
-```json
-{
-  "action": "add",
-  "phases": [
-    {
-      "name": "Verify",
-      "tasks": ["Run the complete test suite"]
-    }
-  ]
-}
-```
-
-### Transition task statuses
-
-`transition` applies status changes atomically using exact phase and task names.
-
-```json
-{
-  "action": "transition",
-  "transitions": [
-    {
-      "phase": "Build",
-      "task": "Implement session restoration",
-      "status": "completed"
-    },
-    {
-      "phase": "Verify",
-      "task": "Run the complete test suite",
-      "status": "in_progress"
-    }
-  ]
-}
-```
-
-Phase names and task names are immutable. Task names must be unique within their phase. Cancel obsolete tasks instead of removing them; cancel and add a corrected task when its name needs to change. All `in_progress` tasks must belong to one phase.
-
-### View the plan
-
-`view` returns the complete plan or one exact phase:
+## Features
 
-```json
-{ "action": "view", "phase": "Build" }
-```
+- **Phased planning.** Organize work into concise phases with immutable task names, detailed descriptions, and explicit `pending`, `in_progress`, `completed`, or `cancelled` statuses.
+- **Context-efficient tool.** A compact, purpose-built tool description gives the model clear planning controls while consuming minimal context-window space.
+- **Session-aware state.** Todo snapshots travel with Pi session branches, so `/tree` navigation restores the plan associated with each branch.
+- **Persistent widget.** Keep active work visible above or below the editor, with configurable placement, task limits, and status glyphs.
+- **Adaptive reminders.** System reminders refresh the model's awareness of stale plans during long runs and restore the full plan after context compaction.
+- **Native tool rendering.** Compact tool output summarizes active work and expands into phase progress while respecting configurable visibility settings.
 
 ## Install
 
@@ -104,7 +34,12 @@ The settings loader reads global settings from `~/.pi/agent/todo/settings.json`.
   "widgetPlacement": "aboveEditor",
   "maxVisibleTasks": 5,
   "fallbackGlyphs": false,
-  "toolVisibility": "set-only"
+  "toolVisibility": "set-only",
+  "dynamicReminders": true,
+  "reminderMinTurns": 4,
+  "reminderMaxTurns": 8,
+  "reminderOutputTokens": 16000,
+  "reminderMaxPerRun": 2
 }
 ```
 
@@ -116,9 +51,13 @@ The settings loader reads global settings from `~/.pi/agent/todo/settings.json`.
 - `"set-only"` shows only `set` operations.
 - `"none"` hides normal Todo activity.
 
-Errors are always shown. Todo output uses native-style self-rendered shells, and hidden successful operations render zero lines. When expanded, the latest rendered `set` result on the active branch follows later additions and transitions; historical details and collapsed rendering remain unchanged.
+Errors are always shown, while hidden successful operations take up no terminal space. Expanded output stays synchronized with the latest plan on the active branch.
+
+Dynamic reminders keep the model aware of the plan during longer runs without adding messages to session history. The turn, output-token, and per-run settings control their cadence; set `dynamicReminders` to `false` to disable them.
+
+After Pi compacts the context window, the extension supplies the full phased plan once on the next turn so work can continue without losing task state. This does not alter Pi's compaction summary or session history.
 
-Settings load when a session starts. The widget refreshes after todo changes and `/tree` navigation. Set `widgetPlacement` to `"off"` to disable it.
+Settings load when a session starts. The widget refreshes after todo changes and `/tree` navigation. Active tasks keep their normal status glyph; when work is active, a separate indented current-work line below the plan uses Pi's standard spinner and dim text. After all tasks become terminal, the widget shows the final phase summary for five seconds before clearing. Set `widgetPlacement` to `"off"` to disable the widget.
 
 ## Development
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pi9/todo",
-  "version": "0.1.0",
-  "description": "Pi extension for managing agent todo tasks.",
+  "version": "0.3.0",
+  "description": "Phased, session-aware todo planning for Pi agents.",
   "license": "MIT",
   "author": "Chase Cummings <chaseecummings@gmail.com>",
   "type": "module",
@@ -18,6 +18,7 @@
   "homepage": "https://github.com/Chase-C/pi9/tree/main/packages/todo#readme",
   "files": [
     "src",
+    "media",
     "README.md",
     "LICENSE"
   ],

package/src/format.ts

@@ -1,6 +1,5 @@
-import type { Todo, TodoState } from "./types.js";
-
-export type PhasedTodo = Todo & { phase: string };
+import { todoGlyph } from "./glyphs.js";
+import type { Todo, TodoState, TodoStatus } from "./types.js";
 
 export interface TodoCounts {
   open: number;
@@ -8,8 +7,10 @@ export interface TodoCounts {
   cancelled: number;
 }
 
+export type TodoStatusCounts = Record<TodoStatus, number>;
+
 /** A small, plain-text representation used in tool results and model context. */
-export function formatTodoSummary(state: TodoState | undefined): string {
+export function formatTodoSummary(state: TodoState | undefined, includeDescriptions = false): string {
   const tasks = todoTasks(state);
   if (tasks.length === 0) return "No todo tasks.";
 
@@ -20,42 +21,78 @@ export function formatTodoSummary(state: TodoState | undefined): string {
     ...(counts.cancelled ? [`${counts.cancelled} cancelled`] : []),
   ].join(" · ");
 
-  return [`Todo: ${summary}`, ...formatTodoTaskLines(state)].join("\n");
+  return [
+    `Todo: ${summary}`,
+    ...(includeDescriptions && state?.workingOn ? [`Working on: ${state.workingOn}`] : []),
+    ...formatTodoTaskLines(state, includeDescriptions),
+  ].join("\n");
 }
 
-export function formatTodoTaskLines(state: TodoState | undefined): string[] {
-  if (!state || state.phases.every((phase) => phase.tasks.length === 0)) return [];
+export function formatTodoTaskLines(state: TodoState | undefined, includeDescriptions = false): string[] {
+  if (!state) return [];
+
   const lines: string[] = [];
   for (const phase of state.phases) {
     if (phase.tasks.length === 0) continue;
     lines.push(`${phase.name}:`);
-    lines.push(...phase.tasks.map((task) => `  ${taskMarker(task)} ${task.name}`));
+    lines.push(...phase.tasks.map((task) =>
+      `  ${taskMarker(task)} ${task.name}${includeDescriptions ? ` — ${task.description}` : ""}`,
+    ));
   }
   return lines;
 }
 
-export function countTodos(state: TodoState | readonly Todo[] | undefined): TodoCounts {
-  const tasks = Array.isArray(state) ? state : todoTasks(state as TodoState | undefined);
-  let open = 0;
-  let completed = 0;
-  let cancelled = 0;
-  for (const task of tasks) {
-    if (task.status === "completed") completed++;
-    else if (task.status === "cancelled") cancelled++;
-    else open++;
-  }
-  return { open, completed, cancelled };
+/** Formats the complete one-shot Todo snapshot injected after compaction. */
+export function formatTodoCompactionContext(state: TodoState): string | undefined {
+  if (!state.phases.some((phase) => phase.tasks.length > 0)) return undefined;
+
+  const plan = state.phases.flatMap((phase) => [
+    `${phase.name}:`,
+    ...(phase.tasks.length === 0
+      ? ["  (no tasks)"]
+      : phase.tasks.map((task) => `  [${task.status}] ${task.name}: ${task.description}`)),
+  ]);
+  return [
+    "<system-reminder source=\"todo-post-compaction\">",
+    "Todo plan after compaction:",
+    ...(state.workingOn ? [`Current work: ${state.workingOn}`] : []),
+    ...plan,
+    "Continue using this plan and keep task statuses current.",
+    "Do not mention this reminder to the user.",
+    "</system-reminder>",
+  ].join("\n");
+}
+
+export function countTodoStatuses(tasks: readonly Todo[]): TodoStatusCounts {
+  const counts: TodoStatusCounts = { pending: 0, in_progress: 0, completed: 0, cancelled: 0 };
+  for (const task of tasks) counts[task.status] += 1;
+  return counts;
+}
+
+export function countTodos(tasks: readonly Todo[]): TodoCounts {
+  const counts = countTodoStatuses(tasks);
+  return {
+    open: counts.pending + counts.in_progress,
+    completed: counts.completed,
+    cancelled: counts.cancelled,
+  };
+}
+
+export function formatTodoProgress(label: string, tasks: readonly Todo[]): string {
+  const counts = countTodoStatuses(tasks);
+  return [
+    label,
+    ...(counts.in_progress ? [`${counts.in_progress} active`] : []),
+    ...(counts.pending ? [`${counts.pending} pending`] : []),
+    ...(counts.completed ? [`${counts.completed} completed`] : []),
+    ...(counts.cancelled ? [`${counts.cancelled} cancelled`] : []),
+  ].join(" · ");
 }
 
 export function taskMarker(task: Pick<Todo, "status">): string {
-  switch (task.status) {
-    case "completed": return "✓";
-    case "in_progress": return "▶";
-    case "cancelled": return "×";
-    default: return "○";
-  }
+  return todoGlyph(task.status, true);
 }
 
-export function todoTasks(state: TodoState | undefined): PhasedTodo[] {
-  return state?.phases.flatMap((phase) => phase.tasks.map((task) => ({ ...task, phase: phase.name }))) ?? [];
+export function todoTasks(state: TodoState | undefined): readonly Todo[] {
+  return state?.phases.flatMap((phase) => phase.tasks) ?? [];
 }

package/src/persistence.ts

@@ -1,79 +1,50 @@
-import { TODO_ACTIONS, TODO_STATUSES, type TodoState, type TodoToolDetails } from "./types.js";
+import { cloneTodoState, createTodoState, isTodoState } from "./state.js";
+import { isTodoActionName, type TodoActionName, type TodoState } from "./types.js";
 
 export const TODO_TOOL_NAME = "todo";
 
-export const createEmptyTodoState = (): TodoState => ({ phases: [] });
-
-export function cloneTodoState(state: TodoState): TodoState {
-  return structuredClone(state);
-}
-
 type BranchContext = {
   sessionManager: {
     getBranch(): readonly unknown[];
   };
 };
 
-type ToolResultEntry = {
+type TodoSnapshotDetails = {
+  action: TodoActionName;
+  state: TodoState;
+};
+
+type TodoResultEntry = {
   type: "message";
   message: {
     role: "toolResult";
-    toolName?: unknown;
+    toolName: typeof TODO_TOOL_NAME;
     isError?: unknown;
-    details?: unknown;
+    details: TodoSnapshotDetails;
   };
 };
 
-function isTodoState(value: unknown): value is TodoState {
-  if (typeof value !== "object" || value === null) return false;
-  const state = value as { phases?: unknown };
-  if (!Array.isArray(state.phases)) return false;
-
-  const phaseNames = new Set<string>();
-  let activePhase: string | undefined;
-  for (const value of state.phases) {
-    if (typeof value !== "object" || value === null) return false;
-    const phase = value as { name?: unknown; tasks?: unknown };
-    if (!validName(phase.name) || phaseNames.has(phase.name) || !Array.isArray(phase.tasks)) return false;
-    phaseNames.add(phase.name);
-
-    const taskNames = new Set<string>();
-    for (const value of phase.tasks) {
-      if (typeof value !== "object" || value === null) return false;
-      const task = value as { name?: unknown; status?: unknown };
-      if (!validName(task.name) || taskNames.has(task.name) || !(TODO_STATUSES as readonly unknown[]).includes(task.status)) return false;
-      if (task.status === "in_progress") {
-        if (activePhase !== undefined && activePhase !== phase.name) return false;
-        activePhase = phase.name;
-      }
-      taskNames.add(task.name);
-    }
-  }
-  return true;
-}
-
-function validName(value: unknown): value is string {
-  return typeof value === "string" && value !== "" && value === value.trim();
-}
-
-function isTodoToolDetails(value: unknown): value is TodoToolDetails {
-  if (typeof value !== "object" || value === null) return false;
+function isTodoSnapshotDetails(value: unknown): value is TodoSnapshotDetails {
+  if (!value || typeof value !== "object") return false;
   const details = value as { action?: unknown; state?: unknown };
-  return typeof details.action === "string"
-    && (TODO_ACTIONS as readonly string[]).includes(details.action)
-    && isTodoState(details.state);
+  return isTodoActionName(details.action) && isTodoState(details.state);
 }
 
-function isSuccessfulTodoResult(value: unknown): value is ToolResultEntry {
-  if (typeof value !== "object" || value === null) return false;
-  const entry = value as Partial<ToolResultEntry>;
-  return entry.type === "message"
-    && typeof entry.message === "object"
-    && entry.message !== null
-    && entry.message.role === "toolResult"
-    && entry.message.toolName === TODO_TOOL_NAME
-    && entry.message.isError !== true
-    && isTodoToolDetails(entry.message.details);
+function isSuccessfulTodoResult(value: unknown): value is TodoResultEntry {
+  if (!value || typeof value !== "object") return false;
+  const entry = value as { type?: unknown; message?: unknown };
+  if (entry.type !== "message" || !entry.message || typeof entry.message !== "object") return false;
+
+  const message = entry.message as {
+    role?: unknown;
+    toolName?: unknown;
+    isError?: unknown;
+    details?: unknown;
+  };
+  return message.role === "toolResult"
+    && message.toolName === TODO_TOOL_NAME
+    && message.isError !== true
+    && isTodoSnapshotDetails(message.details);
 }
 
 /** Restores the latest successful todo snapshot from the current session branch. */
@@ -81,7 +52,7 @@ export function restoreTodoState(ctx: BranchContext): TodoState {
   const branch = ctx.sessionManager.getBranch();
   for (let index = branch.length - 1; index >= 0; index -= 1) {
     const entry = branch[index];
-    if (isSuccessfulTodoResult(entry)) return cloneTodoState((entry.message.details as TodoToolDetails).state);
+    if (isSuccessfulTodoResult(entry)) return cloneTodoState(entry.message.details.state);
   }
-  return createEmptyTodoState();
+  return createTodoState();
 }

package/src/reminder-cadence.ts

@@ -0,0 +1,59 @@
+export interface ReminderCadenceConfig {
+  readonly minTurns: number;
+  readonly maxTurns: number;
+  readonly outputTokens: number;
+  readonly maxPerRun: number;
+}
+
+export interface ReminderCadenceState {
+  readonly turns: number;
+  readonly outputTokens: number;
+  readonly remindersThisRun: number;
+}
+
+export function createReminderCadenceState(): ReminderCadenceState {
+  return { turns: 0, outputTokens: 0, remindersThisRun: 0 };
+}
+
+export function beginReminderAgentRun(state: ReminderCadenceState): ReminderCadenceState {
+  return { ...state, remindersThisRun: 0 };
+}
+
+export function noteReminderTurn(
+  state: ReminderCadenceState,
+  outputTokens: number = 0,
+): ReminderCadenceState {
+  return {
+    ...state,
+    turns: state.turns + 1,
+    outputTokens: state.outputTokens + validTokenCount(outputTokens),
+  };
+}
+
+export function noteTodoInteraction(state: ReminderCadenceState): ReminderCadenceState {
+  return { ...state, turns: 0, outputTokens: 0 };
+}
+
+export function consumeDueReminder(
+  state: ReminderCadenceState,
+  config: ReminderCadenceConfig,
+): { due: boolean; state: ReminderCadenceState } {
+  const minimumMet = state.turns >= config.minTurns;
+  const triggerMet = state.turns >= config.maxTurns || state.outputTokens >= config.outputTokens;
+  const belowCap = state.remindersThisRun < config.maxPerRun;
+
+  if (!minimumMet || !triggerMet || !belowCap) return { due: false, state };
+
+  return {
+    due: true,
+    state: {
+      turns: 0,
+      outputTokens: 0,
+      remindersThisRun: state.remindersThisRun + 1,
+    },
+  };
+}
+
+function validTokenCount(value: number): number {
+  return Number.isFinite(value) && value >= 0 ? value : 0;
+}

package/src/reminder.ts

@@ -0,0 +1,24 @@
+import { countTodoStatuses, todoTasks } from "./format.js";
+import { currentTodoPhaseIndex } from "./state.js";
+import { isTerminalTodo, type TodoState } from "./types.js";
+
+/** Formats the transient model-context reminder for an unfinished todo plan. */
+export function formatTodoReminder(state: TodoState): string | undefined {
+  const activePhase = state.phases[currentTodoPhaseIndex(state.phases)];
+  if (!activePhase) return undefined;
+
+  const openTasks = activePhase.tasks.filter((task) => !isTerminalTodo(task));
+  const counts = countTodoStatuses(todoTasks(state));
+
+  return [
+    "<system-reminder>",
+    `Active phase: ${activePhase.name}`,
+    ...(state.workingOn ? [`Current work: ${state.workingOn}`] : []),
+    "Open tasks in this phase:",
+    ...openTasks.map((task) => `- [${task.status}] ${task.name}: ${task.description}`),
+    `Counts: ${counts.in_progress} in_progress, ${counts.pending} pending, ${counts.completed} completed, ${counts.cancelled} cancelled.`,
+    "Review and update the todo if task status has changed.",
+    "Do not mention this reminder to the user.",
+    "</system-reminder>",
+  ].join("\n");
+}

package/src/renderer.ts

@@ -1,23 +1,16 @@
 import type { Theme } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
 
-import { countTodos, formatTodoSummary, todoTasks, type PhasedTodo } from "./format.js";
+import { countTodos, formatTodoProgress, todoTasks } from "./format.js";
 import { todoGlyph } from "./glyphs.js";
-import type { TodoParams } from "./schema.js";
-import { todoAddressKey } from "./state.js";
-import type { Todo, TodoAddress, TodoPhase, TodoState, TodoToolDetails } from "./types.js";
+import { currentTodoPhaseIndex, todoAddressKey } from "./state.js";
+import { isTerminalTodo, todoTaskPriority, type Todo, type TodoAddress, type TodoToolDetails } from "./types.js";
 
 type ThemeLike = Partial<Pick<Theme, "fg" | "bold" | "strikethrough">>;
 type ThemeColor = Parameters<Theme["fg"]>[0];
 
 export type TodoRendererOptions = { fallbackGlyphs?: boolean };
 
-export function renderCall(params: TodoParams | undefined, theme?: ThemeLike): Text {
-  const action = params?.action;
-  const label = typeof action === "string" && action ? `todo ${action}` : "todo";
-  return new Text(paint(theme, "toolTitle", label), 0, 0);
-}
-
 export function renderResult(
   result: { details?: TodoToolDetails; content?: readonly { type?: string; text?: string }[] },
   options: { expanded?: boolean } = {},
@@ -30,15 +23,14 @@ export function renderResult(
   const tasks = todoTasks(state);
   if (tasks.length === 0 && state.phases.length === 0) return new Text(paint(theme, "muted", "No todo tasks."), 0, 0);
 
-  const counts = countTodos(state);
-  const header = todoHeader(counts);
+  const header = todoHeader(countTodos(tasks));
   if (options.expanded !== true) return new Text(collapsedText(header, tasks, theme, rendererOptions), 0, 0);
 
   const changed = new Set((result.details?.changedTasks ?? []).map(addressKey));
-  const selectedPhase = selectedPhaseIndex(state.phases);
-  const lines = [toolTitle(todoSummary(tasks), theme)];
+  const selectedPhase = currentTodoPhaseIndex(state.phases);
+  const lines = [toolTitle(formatTodoProgress("Todos", tasks), theme)];
   for (const [index, phase] of state.phases.entries()) {
-    const heading = `  ${index + 1}. ${phaseSummary(phase)}`;
+    const heading = `  ${index + 1}. ${formatTodoProgress(phase.name, phase.tasks)}`;
     lines.push(index === selectedPhase ? toolTitle(heading, theme) : paint(theme, "dim", heading));
     for (const task of orderedTasks(phase.tasks)) {
       lines.push(renderTask(phase.name, task, changed, theme, rendererOptions));
@@ -47,10 +39,6 @@ export function renderResult(
   return new Text(lines.join("\n"), 0, 0);
 }
 
-export function formatResultText(details: TodoToolDetails | undefined): string {
-  return formatTodoSummary(details?.state);
-}
-
 function todoHeader(counts: ReturnType<typeof countTodos>, title = "Todo"): string {
   return [
     `${title} · ${counts.open} open`,
@@ -59,70 +47,26 @@ function todoHeader(counts: ReturnType<typeof countTodos>, title = "Todo"): stri
   ].join(" · ");
 }
 
-function collapsedText(header: string, tasks: PhasedTodo[], theme: ThemeLike | undefined, options: TodoRendererOptions): string {
+function collapsedText(header: string, tasks: readonly Todo[], theme: ThemeLike | undefined, options: TodoRendererOptions): string {
   const active = tasks.find((task) => task.status === "in_progress");
   const activeText = active ? `Active: ${todoGlyph(active.status, options.fallbackGlyphs)} ${active.name}` : undefined;
   return [paint(theme, "muted", header), ...(activeText ? [paint(theme, "warning", activeText)] : []), paint(theme, "dim", "↵ expand")].join(" · ");
 }
 
-function todoSummary(tasks: Todo[]): string {
-  const active = tasks.filter((task) => task.status === "in_progress").length;
-  const pending = tasks.filter((task) => task.status === "pending").length;
-  const completed = tasks.filter((task) => task.status === "completed").length;
-  const cancelled = tasks.filter((task) => task.status === "cancelled").length;
-  return [
-    "Todos",
-    ...(active ? [`${active} active`] : []),
-    ...(pending ? [`${pending} pending`] : []),
-    ...(completed ? [`${completed} completed`] : []),
-    ...(cancelled ? [`${cancelled} cancelled`] : []),
-  ].join(" · ");
-}
-
-function phaseSummary(phase: TodoPhase): string {
-  const active = phase.tasks.filter((task) => task.status === "in_progress").length;
-  const pending = phase.tasks.filter((task) => task.status === "pending").length;
-  const completed = phase.tasks.filter((task) => task.status === "completed").length;
-  const cancelled = phase.tasks.filter((task) => task.status === "cancelled").length;
-  return [
-    phase.name,
-    ...(active ? [`${active} active`] : []),
-    ...(pending ? [`${pending} pending`] : []),
-    ...(completed ? [`${completed} completed`] : []),
-    ...(cancelled ? [`${cancelled} cancelled`] : []),
-  ].join(" · ");
-}
-
-function selectedPhaseIndex(phases: TodoPhase[]): number {
-  const active = phases.findIndex((phase) => phase.tasks.some((task) => task.status === "in_progress"));
-  if (active !== -1) return active;
-  return phases.findIndex((phase) => phase.tasks.some((task) => task.status === "pending"));
-}
-
-function orderedTasks(tasks: Todo[]): Todo[] {
+function orderedTasks(tasks: readonly Todo[]): Todo[] {
   return tasks
     .map((task, index) => ({ task, index }))
-    .sort((left, right) => taskPriority(left.task) - taskPriority(right.task) || left.index - right.index)
+    .sort((left, right) => todoTaskPriority(left.task) - todoTaskPriority(right.task) || left.index - right.index)
     .map(({ task }) => task);
 }
 
-function taskPriority(task: Todo): number {
-  if (task.status === "in_progress") return 0;
-  if (task.status === "pending") return 1;
-  return 2;
-}
-
 function renderTask(phase: string, task: Todo, changed: Set<string>, theme: ThemeLike | undefined, options: TodoRendererOptions): string {
-  const text = isTerminal(task) && theme?.strikethrough ? theme.strikethrough(task.name) : task.name;
+  const text = isTerminalTodo(task) && theme?.strikethrough ? theme.strikethrough(task.name) : task.name;
   let line = `    ${todoGlyph(task.status, options.fallbackGlyphs)} ${text}`;
   if ((task.status === "in_progress" || changed.has(todoAddressKey(phase, task.name))) && theme?.bold) line = theme.bold(line);
   return paint(theme, statusColor(task.status), line);
 }
 
-function isTerminal(task: Todo): boolean {
-  return task.status === "completed" || task.status === "cancelled";
-}
-
 function addressKey(address: TodoAddress): string {
   return todoAddressKey(address.phase, address.task);
 }

package/src/schema.ts

@@ -1,35 +1,31 @@
 import { StringEnum } from "@earendil-works/pi-ai";
 import { Type } from "typebox";
-import { TODO_ACTIONS, TODO_STATUSES, type TodoActionName, type TodoPhaseInput, type TodoTransitionInput } from "./types.js";
+import { TODO_ACTIONS, TODO_STATUSES } from "./types.js";
+
+export const TodoTaskSchema = Type.Object({
+  name: Type.String({
+    description: "Unique immutable task name within the phase; ~5–10 words describing what, not how.",
+  }),
+  description: Type.String({
+    description: "1–3 sentences expanding on the name with relevant context, constraints, or expected outcome.",
+  }),
+}, { additionalProperties: false });
 
 export const TodoPhaseSchema = Type.Object({
-  name: Type.String({ minLength: 1, description: "Immutable phase name, 1 or 2 words, unique." }),
-  tasks: Type.Array(Type.String({
-    minLength: 1,
-    description: "Immutable task name, ideally 5–10 words, what not how, unique within its phase.",
-  })),
+  name: Type.String({ description: "Unique immutable phase name; 1–2 words." }),
+  tasks: Type.Array(TodoTaskSchema, { minItems: 1 }),
 }, { additionalProperties: false });
 
 export const TodoTransitionSchema = Type.Object({
-  phase: Type.String({ minLength: 1, description: "Exact immutable phase name." }),
-  task: Type.String({ minLength: 1, description: "Exact immutable task name within the phase." }),
-  status: StringEnum(TODO_STATUSES, { description: "New task status." }),
+  phase: Type.String({ description: "Exact name of an existing phase." }),
+  task: Type.String({ description: "Exact name of an existing task within the phase." }),
+  status: StringEnum(TODO_STATUSES, { description: "Status to assign to the task." }),
 }, { additionalProperties: false });
 
 /** Flat provider-facing schema. Action-specific requirements are enforced by the transition. */
 export const TodoParamsSchema = Type.Object({
   action: StringEnum(TODO_ACTIONS),
-  phases: Type.Optional(Type.Array(TodoPhaseSchema)),
+  phases: Type.Optional(Type.Array(TodoPhaseSchema, { minItems: 1 })),
   transitions: Type.Optional(Type.Array(TodoTransitionSchema, { minItems: 1 })),
-  phase: Type.Optional(Type.String({ minLength: 1, description: "Optional exact phase name used to filter view." })),
+  workingOn: Type.Optional(Type.String({ description: "Concise summary of the current work." })),
 }, { additionalProperties: false });
-
-/** Broad parameter view used by tool render hooks. */
-export type TodoParams = {
-  action: TodoActionName;
-  phases?: TodoPhaseInput[];
-  transitions?: TodoTransitionInput[];
-  phase?: string;
-};
-
-export const TodoSchema = TodoParamsSchema;