@pi-archimedes/todo 2.3.0 → 2.4.0

package/README.md

@@ -17,7 +17,7 @@ Track complex multi-step tasks structured in a todo list with automatic clearing
 
 ### Multiple todos with progress tracking
 
-Widget showing three todos with completion status — completed items dimmed with strikethrough, in-progress highlighted:
+Widget showing three todos with completion status — completed items dimmed with strikethrough, the item currently being worked on highlighted:
 
 ![todos multiple todos](../../docs/images/todos-multiple-todos.png)
 
@@ -59,9 +59,9 @@ The `manage_todo_list` tool accepts two operations:
 {
   "operation": "write",
   "todoList": [
-    { "id": 1, "title": "Parse config files", "description": "Read and validate all config files", "status": "in-progress" },
-    { "id": 2, "title": "Build state manager", "description": "Implement TodoStateManager class", "status": "not-started" },
-    { "id": 3, "title": "Wire up widget", "description": "Connect widget to bus events", "status": "not-started" }
+    { "content": "Parse config files", "description": "Read and validate all config files", "status": "in_progress" },
+    { "content": "Build state manager", "description": "Implement TodoStateManager class", "status": "pending" },
+    { "content": "Wire up widget", "description": "Connect widget to bus events", "status": "pending" }
   ]
 }
 ```
@@ -75,8 +75,8 @@ The `manage_todo_list` tool accepts two operations:
 
 | Status | Icon | Description |
 |--------|------|-------------|
-| `not-started` | ○ | Not yet begun |
-| `in-progress` | ◉ | Currently being worked on |
+| `pending` | ○ | Not yet begun |
+| `in_progress` | ◉ | Currently being worked on |
 | `completed` | ✓ | Fully finished |
 
 ## Auto-clear

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-archimedes/todo",
-  "version": "2.3.0",
+  "version": "2.4.0",
   "type": "module",
   "keywords": [
     "pi-package"
@@ -10,8 +10,12 @@
     "src"
   ],
   "main": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./prepare-args": "./src/prepare-args.ts"
+  },
   "dependencies": {
-    "@pi-archimedes/core": "2.3.0"
+    "@pi-archimedes/core": "2.4.0"
   },
   "peerDependencies": {
     "@earendil-works/pi-ai": ">=0.1.0",

package/src/index.test.ts

@@ -0,0 +1,160 @@
+/**
+ * Index-level test: the bus consumer guarantee.
+ *
+ * The parent todo widget receives subagent todo state ONLY via the
+ * TODOS_UPDATE bus event. These tests prove that whatever the producer
+ * emits (legacy shapes, garbage) the consumer stored in `subagentTodos`
+ * is always canonical — the widget can render real text and can never
+ * print the string "undefined".
+ */
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { getBus, Events } from "@pi-archimedes/core/bus";
+import { registerTodo } from "./index.js";
+
+describe("todo index — bus consumer normalization", () => {
+  const captured: Record<string, unknown> = {};
+  const handlers: Record<string, Function> = {};
+  const registered: { tool?: any; commands: Record<string, unknown> } = { commands: {} };
+
+  const pi = {
+    on(evt: string, fn: Function) {
+      handlers[evt] = fn;
+    },
+    registerTool(tool: any) {
+      registered.tool = tool;
+    },
+    registerCommand(name: string, def: unknown) {
+      registered.commands[name] = def;
+    },
+  } as unknown as ExtensionAPI;
+
+  const ctx = {
+    ui: {
+      setWidget(id: string, component: unknown) {
+        captured[id] = component;
+      },
+    },
+    sessionManager: { getBranch: () => [] },
+  } as any;
+
+  // The widget calls theme.fg / theme.strikethrough; same behavior these
+  // tests rely on (identity-ish, no ANSI) is enough to inspect the text.
+  const theme: any = {
+    fg: (_c: unknown, s: unknown) => String(s),
+    strikethrough: (s: unknown) => String(s),
+  };
+
+  function renderLines(): string[] {
+    // Read fresh on every render step — the factory can be replaced, or
+    // self-cleared to undefined, between steps.
+    const factory = captured["todo-list"] as
+      | ((_tui: unknown, t: unknown) => { render(width: number): string[]; invalidate(): void })
+      | undefined;
+    expect(typeof factory).toBe("function");
+    const comp = factory!(null, theme);
+    return comp.render(200);
+  }
+
+  beforeAll(() => {
+    registerTodo(pi as any);
+  });
+
+  it("normalizes a legacy subagent payload — renders real text, never 'undefined'", async () => {
+    // CRITICAL ordering: session_start must fire BEFORE seeding, because
+    // reconstructState → state.loadFromSession(ctx) resets the list from
+    // getBranch() (mock returns []), which would wipe the seed.
+    const start = handlers.session_start;
+    if (typeof start !== "function") throw new Error("session_start handler not registered");
+    let anyP: unknown;
+    anyP = start(undefined, ctx as any);
+    await anyP;
+
+    // Seed main state through the real tool.
+    const result = await registered.tool.execute(
+      "c1",
+      { operation: "write", todoList: [{ content: "Main task", status: "pending" }] },
+      undefined,
+      undefined,
+      ctx as any,
+    );
+    expect(result.isError).toBeFalsy();
+
+    // Legacy (old-schema) subagent payload: id/title/not-started.
+    getBus().emit(Events.TODOS_UPDATE, {
+      source: "subagent:fake1",
+      todos: [{ id: 1, title: "Old shape task", status: "not-started" }],
+    });
+
+    const lines = renderLines();
+    const joined = lines.join("\n");
+    expect(joined).toContain("Old shape task");
+    expect(joined).toContain("Main task");
+    expect(joined).not.toContain("undefined");
+  });
+
+  it("ignores unrecoverable payloads without crashing (no phantom column)", () => {
+    // State from the previous test persists (same registered instance).
+    expect(() => {
+      getBus().emit(Events.TODOS_UPDATE, { source: "subagent:fake2", todos: "garbage" });
+      getBus().emit(Events.TODOS_UPDATE, {
+        source: "subagent:fake2",
+        todos: [{ status: "pending" }],
+      });
+    }).not.toThrow();
+
+    const lines = renderLines();
+    const joined = lines.join("\n");
+    expect(joined).toContain("Main task");
+    expect(lines.some((l) => l.includes("subagent (fake2)"))).toBe(false);
+  });
+
+  it("TODOS_CLEAR removes the subagent column", () => {
+    getBus().emit(Events.TODOS_CLEAR, { source: "subagent:fake1" });
+
+    const lines = renderLines();
+    const joined = lines.join("\n");
+    expect(lines.some((l) => l.includes("subagent (fake1)"))).toBe(false);
+    expect(joined).toContain("Main task");
+  });
+
+  it("renders the plain agent name for a unique per-child (suffixed) source", async () => {
+    // Fresh setup mirroring test 1: session_start first (resets main), then
+    // seed main through the real tool, then a suffixed subagent bus emit.
+    const start = handlers.session_start;
+    if (typeof start !== "function") throw new Error("session_start handler not registered");
+    let anyP: unknown;
+    anyP = start(undefined, ctx as any);
+    await anyP;
+
+    const result = await registered.tool.execute(
+      "c1",
+      { operation: "write", todoList: [{ content: "Main task", status: "pending" }] },
+      undefined,
+      undefined,
+      ctx as any,
+    );
+    expect(result.isError).toBeFalsy();
+
+    // Per-child source now carries a suffix; the header must still render
+    // just the agent name, not the uuid.
+    getBus().emit(Events.TODOS_UPDATE, {
+      source: "subagent:fake1:aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee",
+      todos: [{ id: 1, title: "Old shape task", status: "not-started" }],
+    });
+
+    const lines = renderLines();
+    const joined = lines.join("\n");
+    expect(lines.some((l) => l.includes("subagent (fake1)"))).toBe(true);
+    expect(joined).toContain("Old shape task");
+    expect(joined).toContain("Main task");
+    expect(joined).not.toContain("undefined");
+  });
+
+  afterAll(() => {
+    // Unsubscribes the bus listeners registered by registerTodo and
+    // clears state (fixture uses a pending item, so no auto-clear timer
+    // is pending, but cancel defensively).
+    handlers.session_shutdown?.(undefined, ctx as any);
+  });
+});

package/src/index.ts

@@ -2,6 +2,7 @@ import type { ExtensionAPI, ExtensionContext, ExtensionCommandContext } from "@e
 import { getBus, Events } from "@pi-archimedes/core/bus";
 import { TodoStateManager } from "./state-manager.js";
 import { createManageTodoListTool } from "./tool.js";
+import { normalizeTodoItems } from "./prepare-args.js";
 import { updateWidget, clearWidget } from "./ui/todo-widget.js";
 import type { TodoItem } from "./types.js";
 
@@ -25,8 +26,17 @@ export function registerTodo(pi: ExtensionAPI): void {
   const unsubTodosUpdate = getBus().on(Events.TODOS_UPDATE, (payload: unknown) => {
     const data = payload as { source: string; todos: TodoItem[] };
     if (data.source === "main") return; // main handled locally
-    subagentTodos.set(data.source, data.todos);
-    refreshWidget();
+    // The consumer is the guarantee: producers (subagent stream, older
+    // child sessions) may emit raw or legacy shapes, so every incoming
+    // payload is normalized before it is stored. Unrecoverable payloads
+    // (normalizeTodoItems → undefined) and empty lists are not mirrored —
+    // the widget hides empty subagent columns, and TODOS_CLEAR/child-exit
+    // remain the lifecycle ends.
+    const normalized = normalizeTodoItems(data.todos);
+    if (normalized && normalized.length > 0) {
+      subagentTodos.set(data.source, normalized);
+      refreshWidget();
+    }
   });
   unsubscribes.push(unsubTodosUpdate);
 

package/src/prepare-args.test.ts

@@ -2,6 +2,7 @@ import { describe, it, expect } from "vitest";
 import {
   deriveTitleFromDescription,
   normalizeTodoItem,
+  normalizeTodoItems,
   prepareTodoArguments,
 } from "./prepare-args.js";
 
@@ -14,32 +15,25 @@ const REAL_STRINGIFIED_LIST =
   '"description": "Document all container-level env vars", ' +
   '"status": "in-progress"}]';
 
-const REAL_MISSING_TITLE = {
-  operation: "write",
-  todoList: [
-    { description: "Understand what c12d4a0 fixed and how the current base interacts with it", id: 1, status: "in-progress" },
-    { description: "Trace user_api_key_auth() catch-all behaviour", id: 2, status: "not-started" },
-  ],
-};
-
-const REAL_MISSING_STATUS = {
-  operation: "write",
-  todoList: [
-    { id: 1, title: "Fix shell command interpolation", description: "fetchNewToken() builds cmd as string" },
-    { id: 2, title: "Update tests", description: "add regression test" },
-  ],
-};
+// Legacy 4-field shape (id/title/description + dashed statuses) that older
+// sessions persisted — must normalize to the canonical {content, status}.
+const LEGACY_ITEM = { id: 1, title: "Fix auth", description: "Y", status: "not-started" };
 
 describe("prepareTodoArguments", () => {
-  it("passes through already-valid arguments unchanged", () => {
+  it("passes through already-valid canonical arguments unchanged", () => {
     const input = {
       operation: "write",
       todoList: [
-        { id: 1, title: "Task", description: "Desc", status: "in-progress" },
-        { id: 2, title: "Other", description: "More", status: "completed" },
+        { content: "Fix auth", status: "pending" as const },
+        { content: "Ship it", status: "completed" as const },
       ],
-    } as const;
-    expect(prepareTodoArguments(input)).toEqual(input);
+    };
+    const out = prepareTodoArguments(input);
+    expect(out).toEqual(input);
+    for (const item of out.todoList!) {
+      expect(Object.keys(item as Record<string, unknown>)).not.toContain("id");
+      expect(Object.keys(item as Record<string, unknown>)).not.toContain("title");
+    }
   });
 
   it("passes non-object arguments through untouched", () => {
@@ -48,14 +42,52 @@ describe("prepareTodoArguments", () => {
     }
   });
 
+  it("normalizes a legacy item (id/title/not-started) to canonical, dropping id", () => {
+    const out = prepareTodoArguments({ operation: "write", todoList: [LEGACY_ITEM] });
+    expect(out.todoList).toEqual([{ content: "Fix auth", description: "Y", status: "pending" }]);
+  });
+
+  it("reads Codex-shaped items ({step, status}) into content", () => {
+    const out = prepareTodoArguments({ operation: "write", todoList: [{ step: "X", status: "in_progress" }] });
+    expect(out.todoList).toEqual([{ content: "X", status: "in_progress" }]);
+  });
+
+  it("strips id (even null) and folds spaced statuses", () => {
+    const out = prepareTodoArguments({
+      operation: "write",
+      todoList: [{ id: null, content: "X", status: "in progress" }],
+    });
+    expect(out.todoList).toEqual([{ content: "X", status: "in_progress" }]);
+  });
+
+  it("recovers content from activeForm alone", () => {
+    const out = prepareTodoArguments({ operation: "write", todoList: [{ activeForm: "Adding tests" }] });
+    expect(out.todoList).toEqual([{ content: "Adding tests", status: "pending" }]);
+  });
+
+  it("wraps bare-string items into canonical items", () => {
+    const out = prepareTodoArguments({ operation: "write", todoList: ["write tests", "deploy it"] });
+    expect(out.todoList).toEqual([
+      { content: "write tests", status: "pending" },
+      { content: "deploy it", status: "pending" },
+    ]);
+  });
+
   it("parses a stringified todoList (real-world case, incl. mangled quotes)", () => {
     const out = prepareTodoArguments({ operation: "write", todoList: REAL_STRINGIFIED_LIST });
     expect(out.operation).toBe("write");
-    const list = out.todoList as Array<Record<string, unknown>>;
-    expect(Array.isArray(list)).toBe(true);
-    expect(list).toHaveLength(2);
-    expect(list[0]).toEqual({ id: 1, title: "Catalog all undocumented env vars", description: "Compare env vars from all K8s manifests against what is in AI-SETUP.md", status: "completed" });
-    expect(list[1]).toEqual({ id: 2, title: "Add K8s env vars section", description: "Document all container-level env vars", status: "in-progress" });
+    expect(out.todoList).toEqual([
+      {
+        content: "Catalog all undocumented env vars",
+        description: "Compare env vars from all K8s manifests against what is in AI-SETUP.md",
+        status: "completed",
+      },
+      {
+        content: "Add K8s env vars section",
+        description: "Document all container-level env vars",
+        status: "in_progress",
+      },
+    ]);
   });
 
   it("returns a stringified list it cannot parse, so the schema error still fires", () => {
@@ -63,113 +95,167 @@ describe("prepareTodoArguments", () => {
     expect(out.todoList).toBe("[{ def 《");
   });
 
-  it("derives a title when the model only sent description", () => {
-    const out = prepareTodoArguments(parseJSON(JSON.stringify(REAL_MISSING_TITLE)));
-    const list = out.todoList as Array<Record<string, unknown>>;
-    expect(list[0]?.title).not.toBe("");
-    expect(list[0]?.description).toBe("Understand what c12d4a0 fixed and how the current base interacts with it");
-    expect(list[1]).toEqual({ id: 2, title: expect.any(String), description: "Trace user_api_key_auth() catch-all behaviour", status: "not-started" });
+  it("last-resort scan picks the first unreserved string field", () => {
+    const out = prepareTodoArguments({ operation: "write", todoList: [{ instruction: "do X", status: "pending" }] });
+    expect(out.todoList).toEqual([{ content: "do X", status: "pending" }]);
   });
 
-  it("defaults missing status to not-started", () => {
-    const out = prepareTodoArguments(parseJSON(JSON.stringify(REAL_MISSING_STATUS)));
-    const list = out.todoList as Array<Record<string, unknown>>;
-    expect(list.every((item) => item?.status === "not-started")).toBe(true);
+  it("last-resort scan does NOT pick up status or id values", () => {
+    const out = prepareTodoArguments({ operation: "write", todoList: [{ id: 42, status: "bad" }] });
+    expect(out.todoList).toEqual([{ content: "", status: "pending" }]);
   });
 
-  it("normalizes status synonyms and spacing", () => {
-    const out = prepareTodoArguments({
-      operation: "write",
-      todoList: [
-        { id: 1, title: "a", description: "a", status: "In_Progress" },
-        { id: 2, title: "b", description: "b", status: "Done" },
-        { id: 3, title: "c", description: "c", status: "doing" },
-        { id: 4, title: "d", description: "d", status: "Pending" },
-        { id: 5, title: "e", description: "e", status: "CLOSED" },
-        { id: 6, title: "f", description: "f", status: "in-progress" },
-      ],
-    });
-    const list = out.todoList as Array<Record<string, unknown>>;
-    const statuses = list.map((item) => item?.status);
-    expect(statuses).toEqual(["in-progress", "completed", "in-progress", "not-started", "completed", "in-progress"]);
+  it("copies description from fallback keys (notes)", () => {
+    const out = prepareTodoArguments({ operation: "write", todoList: [{ title: "X", notes: "n" }] });
+    expect(out.todoList).toEqual([{ content: "X", description: "n", status: "pending" }]);
   });
 
-  it("repairs missing ids (string, null, missing) to sequential numbers", () => {
+  it("normalizes status synonyms, spacing and dashes", () => {
     const out = prepareTodoArguments({
       operation: "write",
       todoList: [
-        { title: "a", description: "a", status: "not-started" },
-        { id: "4", title: "b", description: "b", status: "not-started" },
-        { id: null, title: "c", description: "c", status: "not-started" },
+        { content: "a", status: "In_Progress" },
+        { content: "b", status: "Done" },
+        { content: "c", status: "doing" },
+        { content: "d", status: "Pending" },
+        { content: "e", status: "CLOSED" },
+        { content: "f", status: "in-progress" },
+        { content: "g", status: "wip" },
+        { content: "h", status: "open" },
+        { content: "i" },
       ],
     });
-    const list = out.todoList as Array<Record<string, unknown>>;
-    expect(list.map((item) => item?.id)).toEqual([1, 4, 3]);
-  });
-
-  it("wraps bare-string items into full items", () => {
-    const out = prepareTodoArguments({ operation: "write", todoList: ["write tests", "deploy it"] });
-    const list = out.todoList as Array<Record<string, unknown>>;
-    expect(list).toEqual([
-      { id: 1, title: "write tests", description: "write tests", status: "not-started" },
-      { id: 2, title: "deploy it", description: "deploy it", status: "not-started" },
+    const statuses = (out.todoList as Array<Record<string, unknown>>).map((item) => item?.status);
+    expect(statuses).toEqual([
+      "in_progress",
+      "completed",
+      "in_progress",
+      "pending",
+      "completed",
+      "in_progress",
+      "in_progress",
+      "pending",
+      "pending",
     ]);
   });
 
-  it("wraps a single bare object in an array and drops extra keys (item + top level)", () => {
+  it("end-to-end: prepareTodoArguments emits operation and canonical list", () => {
     const out = prepareTodoArguments({
       operation: "write",
-      extraTop: "drop me",
-      todoList: { id: 1, title: "a", description: "a", status: "completed", fluff: true },
+      todoList: [{ content: "a", status: "pending" }, LEGACY_ITEM],
     });
     expect(out).toEqual({
       operation: "write",
-      todoList: [{ id: 1, title: "a", description: "a", status: "completed" }],
+      todoList: [
+        { content: "a", status: "pending" },
+        { content: "Fix auth", description: "Y", status: "pending" },
+      ],
     });
   });
 
-  it("drops a null todoList and doesn't fabricate one", () => {
-    const out = prepareTodoArguments({ operation: "write", todoList: null });
-    expect(out).toEqual({ operation: "write" });
-    expect(Object.hasOwn(out, "todoList")).toBe(false);
-  });
-
   it("infers operation from a present list, tolerates casing, and defaults to read", () => {
     const withList = prepareTodoArguments({ operation: "WRITE-please", todoList: ["x"] });
     expect(withList.operation).toBe("write");
+    const inferred = prepareTodoArguments({ todoList: ["x"] });
+    expect(inferred.operation).toBe("write");
     const read = prepareTodoArguments({});
     expect(read).toEqual({ operation: "read" });
   });
 
-  it("looks up title/description under the keys models sometimes pick", () => {
+  it("drops a null todoList and doesn't fabricate one", () => {
+    const out = prepareTodoArguments({ operation: "write", todoList: null });
+    expect(out).toEqual({ operation: "write" });
+    expect(Object.hasOwn(out, "todoList")).toBe(false);
+  });
+
+  it("wraps a single bare object in an array and drops extra keys (item + top level)", () => {
     const out = prepareTodoArguments({
       operation: "write",
-      todoList: [{ id: 1, content: "Write the thing", details: "Long context here", status: "not-started" }],
+      extraTop: "drop me",
+      todoList: { content: "a", fluff: true, status: "completed" },
     });
-    const item = (out.todoList as Array<Record<string, unknown>>)[0];
-    expect(item).toEqual({ id: 1, title: "Write the thing", description: "Long context here", status: "not-started" });
+    expect(out).toEqual({ operation: "write", todoList: [{ content: "a", status: "completed" }] });
   });
 
   it("keeps null items null so the schema error stays meaningful", () => {
     const out = prepareTodoArguments({ operation: "write", todoList: [null, "x"] });
-    expect(out.todoList).toEqual([null, { id: 2, title: "x", description: "x", status: "not-started" }]);
+    expect(out.todoList).toEqual([null, { content: "x", status: "pending" }]);
   });
 
   it("is idempotent on repaired output", () => {
-    const parsed = parseJSON(
-      JSON.stringify({ ...REAL_MISSING_TITLE, extra: "gap", todoListX: [null] }),
-    ) as Record<string, unknown>;
-    const once = prepareTodoArguments(parsed);
-    const twice = prepareTodoArguments(once);
-    expect(twice).toEqual(once);
-  });
-
-  it("is idempotent on the real-world string + missing-title failures", () => {
     const once = prepareTodoArguments({ operation: "write", todoList: REAL_STRINGIFIED_LIST });
     expect(prepareTodoArguments(once)).toEqual(once);
-    expect(prepareTodoArguments(prepareTodoArguments(REAL_MISSING_TITLE))).toEqual(
-      prepareTodoArguments(REAL_MISSING_TITLE),
-    );
+    const legacy = prepareTodoArguments({ operation: "write", todoList: [LEGACY_ITEM] });
+    expect(prepareTodoArguments(legacy)).toEqual(legacy);
+  });
+});
+
+describe("normalizeTodoItem", () => {
+  it("returns a fresh canonical object (no id/title/description keys)", () => {
+    const out = normalizeTodoItem({ content: "Fix auth", status: "pending" }, 0);
+    expect(out).toEqual({ content: "Fix auth", status: "pending" });
+  });
+
+  it("keeps a textless item as an empty (valid-string) content item", () => {
+    expect(normalizeTodoItem({}, 0)).toEqual({ content: "", status: "pending" });
+  });
+
+  it("returns non-object items unchanged", () => {
+    expect(normalizeTodoItem(3, 0)).toBe(3);
+    expect(normalizeTodoItem("", 0)).toBe("");
+  });
+
+  it("derives content from description when only description was given", () => {
+    const desc = "Understand what c12d4a0 fixed and how the current base interacts with it";
+    const out = normalizeTodoItem({ description: desc, status: "in-progress" }, 0);
+    expect(out).toEqual({
+      content: deriveTitleFromDescription(desc),
+      description: desc,
+      status: "in_progress",
+    });
+  });
+});
+
+describe("normalizeTodoItems", () => {
+  it("returns canonical items as-is", () => {
+    expect(
+      normalizeTodoItems([
+        { content: "a", status: "pending" },
+        { content: "b", status: "in_progress" },
+      ])
+    ).toEqual([
+      { content: "a", status: "pending" },
+      { content: "b", status: "in_progress" },
+    ]);
+  });
+
+  it("normalizes legacy items", () => {
+    expect(normalizeTodoItems([LEGACY_ITEM])).toEqual([{ content: "Fix auth", description: "Y", status: "pending" }]);
+  });
+
+  it("returns [] for an empty input array", () => {
+    expect(normalizeTodoItems([])).toEqual([]);
+  });
+
+  it("returns undefined for null/undefined input", () => {
+    expect(normalizeTodoItems(null)).toBeUndefined();
+    expect(normalizeTodoItems(undefined)).toBeUndefined();
+  });
+
+  it("returns undefined when no item survives", () => {
+    expect(normalizeTodoItems([{ content: "", status: "pending" }])).toBeUndefined();
+    expect(normalizeTodoItems(["", null])).toBeUndefined();
+  });
+
+  it("wraps a single looks-like-todo object", () => {
+    expect(normalizeTodoItems({ title: "X", status: "not-started" })).toEqual([
+      { content: "X", status: "pending" },
+    ]);
+  });
+
+  it("returns undefined for unrelated values", () => {
+    expect(normalizeTodoItems(42)).toBeUndefined();
+    expect(normalizeTodoItems("a string")).toBeUndefined();
   });
 });
 
@@ -186,21 +272,3 @@ describe("deriveTitleFromDescription", () => {
     expect(title.endsWith(" ")).toBe(false);
   });
 });
-
-describe("normalizeTodoItem", () => {
-  it("keeps a textless item as an empty item", () => {
-    expect(normalizeTodoItem({}, 0)).toEqual({ id: 1, title: "", description: "", status: "not-started" });
-  });
-
-  it("returns non-object items unchanged", () => {
-    expect(normalizeTodoItem(3, 0)).toBe(3);
-    expect(normalizeTodoItem("", 0)).toBe("");
-  });
-});
-
-// ── helpers ─────────────────────────────────────────────────────────────────
-
-// Deep-clone fixture objects, mirroring how arguments arrive (post-JSON).
-function parseJSON(s: string): unknown {
-  return JSON.parse(s) as unknown;
-}