@oisin-ee/pi-todo 0.9.3 → 0.10.0

package/README.md

@@ -25,6 +25,8 @@ The model calls `todo` with one `op`. Tasks are addressed by their exact content
 Creation and append leave tasks pending. Nothing starts automatically. This replaces the previous single-active, automatic-start behavior.
 Use `start` to activate or reopen work explicitly. Starting a child also opens its parent. Starting a parent does not start its children.
 
+Keep `content` a short headline: aim under 60 characters, imperative, no trailing detail. Put context, approach, or acceptance detail in the optional `description` (one or two sentences). Outcomes and subtask drafts accept `description`; a plain string item has none. A blank description counts as none. `update` with `description` sets it on an open task or subtask, and a blank value clears it. It never changes `content` or how a task is selected. `view` prints a description on the line under its headline; the Pi widget shows headlines only.
+
 `items` accepts strings or outcomes with string subtasks:
 
 ```json
@@ -89,8 +91,10 @@ Alt+J/K scrolls the hosted rows. Alt+I toggles their expansion. Ordinary editor
 `/todos` and Alt+T request the shared Todos view. `/todos list` still prints the full list.
 When shared presentation ends, the standalone widget returns without changing task state.
 
-The [version 2 display contract](https://github.com/oisin-ee/dogsled/blob/main/docs/pi-work.md)
+The [version 3 display contract](https://github.com/oisin-ee/dogsled/blob/main/docs/pi-work.md)
 defines the snapshot request, acknowledgement, release, and read-only view events.
+Version 3 adds `display.sections` to the snapshot: four typed status groups (`in_progress`, `pending`, `completed`, `abandoned`), always present and in that order, each with a count and its items. Each item carries its text, optional description, review flag, contract summary, and all subtasks (each with its own optional description). The core owns this grouping; a presenter only draws it.
+Pi-todo does not answer version 2 requests.
 Incompatible versions leave the standalone widget available. Rendering failures restore it without changing saved tasks.
 
 ## Plannotator plans

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oisin-ee/pi-todo",
-  "version": "0.9.3",
+  "version": "0.10.0",
   "description": "A todo tool for pi with a Rust core: one active task, state on the session branch.",
   "keywords": [
     "pi-extension",

package/src/display.ts

@@ -1,7 +1,7 @@
-import type { Subtask, TodoList } from "./wasm.ts";
+import type { Subtask, TodoList, TodoSection } from "./wasm.ts";
+import { sections, view } from "./wasm.ts";
 import type { Theme } from "@earendil-works/pi-coding-agent";
 import { TodoView } from "./embedded.ts";
-import { view } from "./wasm.ts";
 
 /** Host-owned layout and rendering services for an inline todo view. */
 interface ViewHost {
@@ -25,6 +25,8 @@ interface TodoDisplay {
   readonly summary: string;
   readonly current: string;
   readonly text: string;
+  /** Status groups owned by the core: in_progress, pending, completed, abandoned. */
+  readonly sections: readonly TodoSection[];
   readonly state: unknown;
   readonly createView: (host: ViewHost) => HostedView;
 }
@@ -58,6 +60,7 @@ const emptyCount = 0,
       createView: (host) => new TodoView(list, host),
       current,
       empty: list.tasks.length === emptyCount,
+      sections: sections(list),
       state: list,
       summary: text.split("\n").at(headerIndex) ?? "",
       text,

package/src/generated/todo_core.d.ts

@@ -5,6 +5,7 @@
  */
 export interface DraftItem {
     content: string;
+    description?: string;
     key?: string | undefined;
     contract?: ContractDraft;
 }
@@ -14,6 +15,10 @@ export interface DraftItem {
  */
 export interface Subtask {
     content: string;
+    /**
+     * Detail behind the short `content` headline.
+     */
+    description?: string;
     status: Status;
     unit?: Unit;
 }
@@ -31,6 +36,10 @@ export interface Change {
  */
 export interface Task {
     content: string;
+    /**
+     * Detail behind the short `content` headline.
+     */
+    description?: string;
     status: Status;
     subtasks?: Subtask[];
     unit?: Unit;
@@ -199,6 +208,10 @@ export interface Request {
     contract?: ContractDraft | undefined;
     start?: string | undefined;
     evidence?: string | undefined;
+    /**
+     * For `update`: sets the description; blank clears it; absent leaves it.
+     */
+    description?: string | undefined;
 }
 
 /**
@@ -217,6 +230,28 @@ export interface WidgetRow {
     text: string;
 }
 
+/**
+ * One subtask of a section item, with its contract summary.
+ */
+export interface SectionChild {
+    status: Status;
+    text: string;
+    description: string | undefined;
+    unit: string | undefined;
+}
+
+/**
+ * One top-level task of a section, with every subtask.
+ */
+export interface SectionItem {
+    status: Status;
+    text: string;
+    review: boolean;
+    description: string | undefined;
+    unit: string | undefined;
+    children: SectionChild[];
+}
+
 /**
  * Opaque executor identity; no process interpretation belongs here.
  */
@@ -280,7 +315,7 @@ export interface Scope {
 /**
  * Root creation accepts standalone outcomes or outcomes with leaf work units.
  */
-export type Item = string | { content: string; subtasks: LeafItem[] } | DraftItem;
+export type Item = string | { content: string; description?: string; subtasks: LeafItem[] } | DraftItem;
 
 /**
  * Semantic styling for a terminal row.
@@ -316,6 +351,15 @@ export type Operation = "init" | "start" | "done" | "drop" | "append" | "view" |
  */
 export type Status = "pending" | "in_progress" | "completed" | "abandoned";
 
+/**
+ * The tasks of one status, in list order.
+ */
+export interface TodoSection {
+    status: Status;
+    count: number;
+    items: SectionItem[];
+}
+
 /**
  * The whole todo list of a session branch.
  */
@@ -442,6 +486,15 @@ export function parse(snapshot: unknown): TodoList;
  */
 export function protect(before: TodoList, after: TodoList, leases: UnitRef[]): void;
 
+/**
+ * Typed status groups of `list`: always four sections, in a fixed order.
+ *
+ * # Errors
+ *
+ * Throws when `list` is not a valid todo list.
+ */
+export function sections(list: TodoList): TodoSection[];
+
 /**
  * Records an executor's exact release evidence, never acceptance.
  *
@@ -482,6 +535,7 @@ export interface InitOutput {
     readonly inspect: (a: number, b: number, c: number, d: number) => void;
     readonly parse: (a: number, b: number) => void;
     readonly protect: (a: number, b: number, c: number, d: number, e: number) => void;
+    readonly sections: (a: number, b: number) => void;
     readonly settle: (a: number, b: number, c: number, d: number, e: number, f: number) => void;
     readonly view: (a: number, b: number) => void;
     readonly widget: (a: number, b: number, c: number) => void;

package/src/generated/todo_core.js

@@ -290,6 +290,35 @@ export function protect(before, after, leases) {
     }
 }
 
+/**
+ * Typed status groups of `list`: always four sections, in a fixed order.
+ *
+ * # Errors
+ *
+ * Throws when `list` is not a valid todo list.
+ * @param {TodoList} list
+ * @returns {TodoSection[]}
+ */
+export function sections(list) {
+    try {
+        const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+        wasm.sections(retptr, addBorrowedObject(list));
+        var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
+        var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
+        var r2 = getDataViewMemory0().getInt32(retptr + 4 * 2, true);
+        var r3 = getDataViewMemory0().getInt32(retptr + 4 * 3, true);
+        if (r3) {
+            throw takeObject(r2);
+        }
+        var v1 = getArrayJsValueFromWasm0(r0, r1);
+        wasm.__wbindgen_export4(r0, r1 * 4, 4);
+        return v1;
+    } finally {
+        wasm.__wbindgen_add_to_stack_pointer(16);
+        heap[stack_pointer++] = undefined;
+    }
+}
+
 /**
  * Records an executor's exact release evidence, never acceptance.
  *

package/src/generated/todo_core_bg.wasm.d.ts

@@ -11,6 +11,7 @@ export const init: (a: number, b: number, c: number) => void;
 export const inspect: (a: number, b: number, c: number, d: number) => void;
 export const parse: (a: number, b: number) => void;
 export const protect: (a: number, b: number, c: number, d: number, e: number) => void;
+export const sections: (a: number, b: number) => void;
 export const settle: (a: number, b: number, c: number, d: number, e: number, f: number) => void;
 export const view: (a: number, b: number) => void;
 export const widget: (a: number, b: number, c: number) => void;

package/src/guidance.ts

@@ -7,6 +7,8 @@ const workUnitGuidance =
   "Supply deliverable, repository-relative scope, acceptance, prerequisite IDs, and self or worker/profile assignment. " +
   "Use local keys for new prerequisites and the optional start selector for atomic creation and activation. " +
   "Use returned IDs after creation. Update drafts before start; only one complete self leaf executes locally. " +
-  "Done requires concrete acceptance evidence; worker exit alone is not acceptance.";
+  "Done requires concrete acceptance evidence; worker exit alone is not acceptance. " +
+  "Keep content a short headline (aim under 60 characters, imperative, no trailing detail); " +
+  "put context, approach, or acceptance detail in the optional description (one or two sentences).";
 
 export { workUnitGuidance };

package/src/index.ts

@@ -39,7 +39,7 @@ export default function piTodo(pi: TodoAPI): void {
   provider.register();
   registerGate(pi, provider);
   pi.registerTool({
-    description: `Keep branch-local outcomes and executable contracts. Use returned IDs, not labels. Draft creation is pending. Start one complete self-assigned leaf; workers require their assigned profile through the executor. Update replaces pending contract fields. Done requires acceptance evidence. Parents require explicit integration review after children close. ${workUnitGuidance}`,
+    description: `Keep branch-local outcomes and executable contracts. Use returned IDs, not labels. Draft creation is pending. Start one complete self-assigned leaf; workers require their assigned profile through the executor. Update replaces pending contract fields and may set or clear an open item's description. Done requires acceptance evidence. Parents require explicit integration review after children close. ${workUnitGuidance}`,
     async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
       const result = provider.run(params, ctx);
       work.publish(ctx);

package/src/schema.ts

@@ -1,7 +1,11 @@
 import { StringEnum } from "@earendil-works/pi-ai";
 import { Type } from "typebox";
 
-const strings = Type.Immutable(Type.Array(Type.String())),
+const description = Type.String({
+    description:
+      "Optional detail behind the short content headline: context, approach, or acceptance in one or two sentences. Blank is none.",
+  }),
+  strings = Type.Immutable(Type.Array(Type.String())),
   scope = Type.Immutable(
     Type.Object(
       {
@@ -43,6 +47,7 @@ const strings = Type.Immutable(Type.Array(Type.String())),
     {
       content: Type.String(),
       contract: Type.Optional(contract),
+      description: Type.Optional(description),
       key: Type.Optional(Type.String()),
     },
     { additionalProperties: false },
@@ -51,7 +56,10 @@ const strings = Type.Immutable(Type.Array(Type.String())),
   leaf = Type.Union([Type.String(), draft]),
   subtasks = Type.Immutable(Type.Array(leaf)),
   outcome = Type.Immutable(
-    Type.Object({ content: Type.String(), subtasks }, { additionalProperties: false }),
+    Type.Object(
+      { content: Type.String(), description: Type.Optional(description), subtasks },
+      { additionalProperties: false },
+    ),
   ),
   item = Type.Union([leaf, outcome]),
   items = Type.Immutable(Type.Array(item)),
@@ -68,10 +76,15 @@ const strings = Type.Immutable(Type.Array(Type.String())),
     description:
       "Unit ID, or exact legacy content before migration. Children can use their ID without parent.",
   }),
+  change = Type.String({
+    description:
+      "update only: set the open task or subtask description; blank clears it; omit to keep it. Never changes content.",
+  }),
   parameters = Type.Immutable(
     Type.Object(
       {
         contract: Type.Optional(contract),
+        description: Type.Optional(change),
         evidence: Type.Optional(evidence),
         items: Type.Optional(items),
         op: StringEnum(["init", "start", "done", "drop", "append", "view", "update"] as const),

package/src/wasm.ts

@@ -25,6 +25,7 @@ export {
   completion_reminder as completionReminder,
   init,
   parse,
+  sections,
   view,
   widget,
 } from "./generated/todo_core.js";
@@ -51,10 +52,13 @@ export type {
   Operation,
   ReminderFact,
   Request,
+  SectionChild,
+  SectionItem,
   Status,
   Subtask,
   Task,
   TodoList,
+  TodoSection,
   WidgetKind,
   WidgetRow,
 } from "./generated/todo_core.js";

package/src/work.ts

@@ -12,7 +12,7 @@ interface WorkHost extends TodoHost {
 }
 
 type WorkCommands = Readonly<Pick<ExtensionAPI, "registerCommand" | "registerShortcut">>;
-const protocolVersion = 2,
+const protocolVersion = 3,
   initialRevision = 0;
 
 interface WorkContext extends TodoContext {