@getpipher/armory-todo 0.2.0 → 0.3.0

package/src/archive.ts

@@ -8,12 +8,13 @@
 import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { dirname } from "node:path";
 import { getArchivePath } from "./paths.ts";
+import { migrateV2ToV3 } from "./migrate.ts";
 import type { Todo } from "./todo-store.ts";
 import { loadConfig } from "./config.ts";
 import { loadStore, saveStore, TodoError } from "./todo-store.ts";
 
 export interface ArchiveStore {
-  version: 2;
+  version: 3;
   updatedAt: string;
   todos: Todo[];
 }
@@ -23,7 +24,7 @@ function now(): string {
 }
 
 function emptyArchive(): ArchiveStore {
-  return { version: 2, updatedAt: now(), todos: [] };
+  return { version: 3, updatedAt: now(), todos: [] };
 }
 
 /** Load the archive. Missing file → empty store (no file created). */
@@ -36,6 +37,15 @@ export function loadArchive(): ArchiveStore {
     if (!parsed || typeof parsed !== "object" || !Array.isArray(parsed.todos)) {
       throw new Error("invalid archive shape");
     }
+    if (parsed.version === 2) {
+      // v2 → v3: curated + fallback, persist once (symmetric with the live store).
+      const migrated = migrateV2ToV3(parsed as any) as unknown as ArchiveStore;
+      saveArchive(migrated);
+      return migrated;
+    }
+    if (parsed.version !== 3) {
+      throw new Error("invalid archive shape");
+    }
     return parsed;
   } catch {
     try {
@@ -190,7 +200,7 @@ export function listArchived(filter: ArchiveListFilter = {}): ArchiveListResult
   if (filter.status) out = out.filter((t) => t.status === filter.status);
   if (filter.text) {
     const q = filter.text.toLowerCase();
-    out = out.filter((t) => t.text.toLowerCase().includes(q));
+    out = out.filter((t) => t.title.toLowerCase().includes(q) || t.notes.toLowerCase().includes(q));
   }
   if (filter.since) out = out.filter((t) => (t.closedAt ?? t.updatedAt) >= (filter.since as string));
   if (filter.before) out = out.filter((t) => (t.closedAt ?? t.updatedAt) < (filter.before as string));

package/src/health.ts

@@ -23,6 +23,12 @@ export interface ArchiveHealth {
   older_180d: number;      // closedAt older than archiveOldDays
 }
 
+export interface NotesBytes {
+  total: number;
+  max: number;
+  avg: number;
+}
+
 export type HealthFlag =
   | "ACTIVE_LARGE" | "ACTIVE_STALE"
   | "PARKED_LARGE" | "PARKED_STALE"
@@ -32,6 +38,7 @@ export interface HealthReport {
   active: ActiveHealth;
   parked: ParkedHealth;
   archive: ArchiveHealth;
+  notesBytes: NotesBytes;
   flags: HealthFlag[];
   suggestions: string[];
 }
@@ -55,6 +62,15 @@ export function healthReport(): HealthReport {
   const parkedStale = parkedTodos.filter((t) => daysAgo(t.updatedAt) > h.parkedStaleDays).length;
   const archiveOld = archive.todos.filter((t) => t.closedAt && daysAgo(t.closedAt) > h.archiveOldDays).length;
 
+  // notes bytes across active + parked (archived excluded — sealed history).
+  const apTodos = [...openTodos, ...ipTodos, ...parkedTodos];
+  const notesSizes = apTodos.map((t) => Buffer.byteLength(t.notes, "utf8"));
+  const notesBytes: NotesBytes = {
+    total: notesSizes.reduce((a, b) => a + b, 0),
+    max: notesSizes.length ? Math.max(...notesSizes) : 0,
+    avg: notesSizes.length ? Math.round(notesSizes.reduce((a, b) => a + b, 0) / notesSizes.length) : 0,
+  };
+
   const active: ActiveHealth = {
     open: openTodos.length,
     in_progress: ipTodos.length,
@@ -77,5 +93,5 @@ export function healthReport(): HealthReport {
   if (parkedStale > 0) suggestions.push(`parked: ${parkedStale} parked > ${h.parkedStaleDays}d → restore or hard-prune`);
   if (actionable.length > h.activeMaxOpen) suggestions.push(`active: ${actionable.length} open+in_progress (max ${h.activeMaxOpen}) → close or park some before adding more`);
 
-  return { active, parked, archive: arch, flags, suggestions };
+  return { active, parked, archive: arch, notesBytes, flags, suggestions };
 }

package/src/migrate.ts

@@ -10,6 +10,36 @@
 import { copyFileSync, existsSync, mkdirSync, renameSync, unlinkSync } from "node:fs";
 import { join } from "node:path";
 
+// v2 → v3 schema migration helpers. splitTextFallback is used by loadStore's
+// inline derivation (Task 1) and by migrateV2ToV3 (Task 2, with the curated
+// map). TITLE_MAX here must match the constant in todo-store.ts.
+const TITLE_MAX = 120;
+
+/** Truncate at the last word boundary ≤ TITLE_MAX (hard cut if none). No "…"
+ *  suffix — the cap is a hard rule, not a display truncation. */
+function truncateWordBoundary(s: string): string {
+  if (s.length <= TITLE_MAX) return s;
+  const slice = s.slice(0, TITLE_MAX);
+  const sp = slice.lastIndexOf(" ");
+  return sp > 0 ? slice.slice(0, sp) : slice;
+}
+
+/** Derive { title, notes } from a v2 `text` string (the fallback for any v2
+ *  todo not in the curated map). Deterministic + idempotent. */
+export function splitTextFallback(text: string): { title: string; notes: string } {
+  const raw = (text ?? "").trim();
+  if (!raw) return { title: "(untitled)", notes: "" };
+  const nl = raw.indexOf("\n");
+  if (nl < 0) {
+    if (raw.length <= TITLE_MAX) return { title: raw, notes: "" };
+    return { title: truncateWordBoundary(raw), notes: raw };
+  }
+  const firstLine = raw.slice(0, nl).trim();
+  const rest = raw.slice(nl + 1).trim();
+  if (firstLine.length <= TITLE_MAX) return { title: firstLine, notes: rest };
+  return { title: truncateWordBoundary(firstLine), notes: `${firstLine}\n${rest}` };
+}
+
 export interface MigrateInput {
   /** The v2 folder (e.g. ~/.pi/agent/todo/). */
   todoDir: string;
@@ -42,4 +72,83 @@ export function migrateIfNeeded(input: MigrateInput): void {
     try { copyFileSync(backup, input.legacyPath); } catch { /* best-effort */ }
     throw new Error(`migration failed: could not move ${input.legacyPath} → ${target}`);
   }
-}
+}
+// v2 → v3 schema migration: each todo gains title + notes (curated for the
+// 2 ids known at migration time; splitTextFallback for the rest), drops text.
+// Pure — does not touch disk. Deterministic + idempotent on v2 input.
+// (splitTextFallback + TITLE_MAX are defined above, alongside migrateIfNeeded.)
+
+/** A v2 todo (has `text`, no `title`/`notes`). */
+export interface V2Todo {
+  id: string;
+  text: string;
+  project: string;
+  tags: string[];
+  priority: string;
+  status: string;
+  source: string;
+  createdAt: string;
+  updatedAt: string;
+  closedAt: string | null;
+}
+
+/** v2 store shape (input to migrateV2ToV3). */
+export interface V2Store {
+  version: 2;
+  updatedAt: string;
+  todos: V2Todo[];
+}
+
+// Hand-curated title + notes for the 2 todos known at v2→v3 migration time
+// (the only survivors of the v0.2.0 incident). Any other v2 todo uses
+// splitTextFallback. Curated notes are reformatted for clarity, not a
+// mechanical split.
+const CURATED_V2_TO_V3: Record<string, { title: string; notes: string }> = {
+  "td-mrt3zp9fcnug3p": {
+    title: "ZeroClaw×Solana bounty — Phase 4-5: demo video (score bottleneck, unstarted)",
+    notes: `superteam.fun/earn/listing/zeroclaw · Superteam Brasil · 5,000 USDG pool / 1st=1,800 · winner Aug 21 2026 · TARGET #1.
+
+PHASE 0-2 DONE ✅. PHASE 3 (RESEARCH+SPEC+PLAN + impl alerts+custody+docs) DONE ✅ — slices A-F+H, 45 tests, committed 8fd7483→80614c8, PUSHED, PR #76 retitled "Palinurus — depin-attest + depin-rewards", 17 commits.
+
+claim_tx (G) DEFERRED — Helium hotspots are cNFTs → claim needs distribute_compression_rewards_v0 + DAS get_asset_proof (merkle proof), multi-session; PDAs verified, design in README.
+
+Decision (score-max): ship alerts core complete, pivot to DEMO track.
+
+NEXT (★ Phase 4-5, the score bottleneck — submission REQUIRES a demo video, currently unstarted):
+(1) ASYNC: RECTOR's free Relay Community key → real Helium fixtures + live smoke test;
+(2) Phase 4: wiring SVG (docs/wiring-diagram.svg, dark-mode, NOT ASCII) + marketing site (palinurus.rectorspace.com, Next.js+Tailwind+shadcn) + demo recording guide;
+(3) Phase 5: record demo ≤3min (real ZeroClaw+Telegram, terminal+phone) → ElevenLabs voiceover → ffmpeg → submit on Superteam Earn + engage #solana-bounty Discord.
+
+Test totals: 184 (71 palinurus-core + 68 depin-attest + 45 depin-rewards), all clippy+wasm clean.
+HANDOFF: ~/Documents/secret/strategy/zeroclaw-solana/session-handoff-2026-07-21.md
+Docs: {RESEARCH-3,SPEC-3,PLAN-3}-depin-rewards.md (SPEC-3 §4 + PLAN-3 G corrected for cNFT)
+Cwd: ~/local-dev/RECTOR-LABS/zeroclaw-plugins/plugins/depin-rewards
+PR: https://github.com/zeroclaw-labs/zeroclaw-plugins/pull/76`,
+  },
+  "td-mrt4e1qi9td6jz": {
+    title: "armory-todo v0.2.0 — Workstream A shipped (lifecycle boxes + prune + health + TUI)",
+    notes: `ALL 3 SPECS DONE ✅. SPEC-1 (store: parked+prune+archive+restore, 12 tasks), SPEC-2 (health+hard-prune, 6 tasks), SPEC-3 (interactive /todo TUI panel, 4 tasks). 147/147 tests across 7 suites. 24 commits on feat/spec-1-lifecycle-boxes, PR #3 retitled to full v0.2.0 scope. Auto-publish CI (release.yml, org NPM_TOKEN).
+
+INCIDENT (SPEC-1 Task 9): migration bug destroyed real 52KB/47-todo store (35 done + ~10 open lost, no backup). FIXED (c034509): migration guarded to only run when TODO_DIR is default. RECOVERED: 2 todos.
+
+Shipped: merge PR #3 → tag v0.2.0 → CI auto-publish → npm:@getpipher/armory-todo@0.2.0.
+Out of scope: B (title+notes split), C (preventive caps+project registry).`,
+  },
+};
+
+/** Transform a v2 store into a v3 store: each todo gains title + notes
+ *  (curated for the 2 known ids, splitTextFallback for the rest), drops text.
+ *  Pure — does not touch disk. Deterministic + idempotent on v2 input. */
+export function migrateV2ToV3(store: V2Store): { version: 3; updatedAt: string; todos: any[] } {
+  const todos = store.todos.map((t) => {
+    const curated = CURATED_V2_TO_V3[t.id];
+    if (curated) {
+      const { text: _drop, ...rest } = t;
+      return { ...rest, title: curated.title, notes: curated.notes };
+    }
+    const { title, notes } = splitTextFallback(t.text ?? "");
+    const { text: _drop, ...rest } = t;
+    return { ...rest, title, notes };
+  });
+  return { version: 3, updatedAt: store.updatedAt, todos };
+}

package/src/panel-data.ts

@@ -7,24 +7,17 @@ import type { Todo } from "./todo-store.ts";
 import type { ArchiveSummary } from "./archive.ts";
 import type { TodoConfig } from "./config.ts";
 
-/** Format a todo as a SelectList item: "[id] (prio)⏵ (project) text…".
- *  The project tag is placed BEFORE the text so it's always visible (not
- *  clipped at the right edge). The text is truncated to a readable summary
- *  (first ~80 chars) so long running-log todos don't blow out the row width.
- *  The full text is still accessible via the "Edit text" action in the panel. */
+/** Format a todo as a SelectList item: "[id] (prio)⏵ (project) • title".
+ *  title is already ≤120 chars (enforced at write time), so no truncation is
+ *  needed. The • marker shows when notes is non-empty (signals "open the
+ *  detail view / use `todo get` for context"). */
 export function todoToItem(t: Todo): SelectItem {
   const pin = t.status === "in_progress" ? " ⏵" : "";
   const proj = t.project ? ` (${t.project})` : "";
-  const prefix = `[${t.id}] (${t.priority})${pin}${proj}`;
-  const maxText = 80;
-  let text = t.text;
-  if (text.length > maxText) {
-    const firstLine = text.split("\n")[0]!;
-    text = firstLine.length > maxText ? firstLine.slice(0, maxText - 1) + "…" : firstLine + "…";
-  }
+  const dot = t.notes.trim() ? " •" : "";
   return {
     value: t.id,
-    label: `${prefix} ${text}`,
+    label: `[${t.id}] (${t.priority})${pin}${proj}${dot} ${t.title}`,
   };
 }
 
@@ -50,7 +43,7 @@ export function actionsForTodo(t: Todo): { label: string; action: string }[] {
   if (t.status === "done" || t.status === "cancelled") {
     actions.push({ label: "Restore (from archive)", action: "restore" });
   }
-  actions.push({ label: "Edit text", action: "edit" });
+  actions.push({ label: "Edit title", action: "edit" });
   actions.push({ label: "Delete (cancel)", action: "delete" });
   return actions;
 }

package/src/panel.ts

@@ -47,6 +47,8 @@ export class TodoPanel extends Container {
   private editMode = false;
   private editInput: Input | null = null;
   private editId = "";
+  private detailMode = false;
+  private detailId = "";
   private settingsList: SettingsList | null = null;
   private config: TodoConfig;
   private healthFlags: string[] = [];
@@ -105,6 +107,20 @@ export class TodoPanel extends Container {
     } else if (this.actionMode && this.actionList) {
       this.addChild(new Text(this.theme.fg("accent", "  Action:"), 0, 0));
       this.addChild(this.actionList);
+    } else if (this.detailMode) {
+      const all = listTodos({ status: "all", limit: 200 });
+      const t = all.find((x) => x.id === this.detailId);
+      if (!t) { this.detailMode = false; this.renderShell(); return; }
+      const proj = t.project || "no project";
+      const tags = t.tags.length ? t.tags.join(" ") : "(none)";
+      const notesText = t.notes || "(empty)";
+      this.addChild(new Text(this.theme.fg("accent", "  " + t.title), 0, 0));
+      this.addChild(new Text(this.theme.fg("muted", "  (" + t.priority + "/" + t.status + ") - " + proj + " - #" + tags), 0, 0));
+      this.addChild(new Spacer(1));
+      this.addChild(new Text(this.theme.fg("dim", "  notes:"), 0, 0));
+      this.addChild(new Text("  " + notesText, 0, 0));
+      this.addChild(new Spacer(1));
+      this.addChild(new Text(this.theme.fg("dim", "  notes: read-only - todo update <id> notes=... to edit"), 0, 0));
     } else if (this.currentBox === "config") {
       this.renderConfigBox();
     } else {
@@ -179,7 +195,7 @@ export class TodoPanel extends Container {
       this.onNotify("Todo not found in the live store (archive restore: use the archive box).", "info");
       return;
     }
-    const acts = actionsForTodo(todo);
+    const acts = [{ label: "View detail", action: "view" }, ...actionsForTodo(todo)];
     const items: SelectItem[] = acts.map((a) => ({ value: a.action, label: a.label }));
     this.actionList = new SelectList(items, 8, {
       selectedPrefix: (s) => this.theme.fg("accent", s),
@@ -194,9 +210,23 @@ export class TodoPanel extends Container {
     this.renderShell();
   }
 
+  private viewDetail(id: string): void {
+    const all = listTodos({ status: "all", limit: 200 });
+    const t = all.find((x) => x.id === id);
+    if (!t) { this.onNotify("Todo not found.", "info"); return; }
+    this.detailId = id;
+    this.detailMode = true;
+    this.actionMode = false;
+    this.actionList = null;
+    this.editMode = false;
+    this.editInput = null;
+    this.renderShell();
+  }
+
   private async executeAction(id: string, action: string): Promise<void> {
     try {
       switch (action) {
+        case "view": this.viewDetail(id); return;
         case "complete": completeTodo(id); this.onNotify(`Completed ${id}`); break;
         case "park": parkTodo(id); this.onNotify(`Parked ${id}`); break;
         case "open": updateTodo(id, { status: "open" as Status }); this.onNotify(`Re-activated ${id}`); break;
@@ -207,9 +237,12 @@ export class TodoPanel extends Container {
           const t = all.find((x) => x.id === id);
           this.editId = id;
           this.editInput = new Input();
-          this.editInput.setValue(t?.text ?? "");
+          this.editInput.setValue(t?.title ?? "");
           this.editInput.onSubmit = (value) => {
-            if (value.trim()) { updateTodo(id, { text: value.trim() }); this.onNotify(`Edited ${id}`); }
+            if (value.trim()) {
+              try { updateTodo(id, { title: value.trim() }); this.onNotify(`Edited ${id}`); }
+              catch (err) { this.onNotify((err as Error).message, "error"); }
+            }
             this.exitEditMode();
           };
           this.editInput.onEscape = () => this.exitEditMode();
@@ -221,7 +254,7 @@ export class TodoPanel extends Container {
         }
       }
     } catch (err) {
-      this.onNotify(`Error: ${(err as Error).message}`, "error");
+      this.onNotify((err as Error).message, "error");
     }
     this.actionMode = false;
     this.actionList = null;
@@ -308,6 +341,17 @@ export class TodoPanel extends Container {
       this.invalidate();
       return;
     }
+    if (this.detailMode) {
+      if (matchesKey(data, "escape") || matchesKey(data, "esc") || matchesKey(data, "enter") || matchesKey(data, "return")) {
+        this.detailMode = false;
+        this.detailId = "";
+        this.refreshList();
+        this.renderShell();
+        return;
+      }
+      this.invalidate();
+      return;
+    }
     if (this.actionMode && this.actionList) {
       if (matchesKey(data, "escape") || matchesKey(data, "esc")) {
         this.actionMode = false;

package/src/todo-store.ts

@@ -18,7 +18,7 @@ import {
 } from "node:fs";
 import { dirname } from "node:path";
 import { getLivePath, getTodoDir, getLegacyPath } from "./paths.ts";
-import { migrateIfNeeded } from "./migrate.ts";
+import { migrateIfNeeded, migrateV2ToV3 } from "./migrate.ts";
 
 export type Priority = "low" | "med" | "high" | "critical";
 export type Status = "open" | "in_progress" | "parked" | "done" | "cancelled";
@@ -31,7 +31,8 @@ const STATUS_SET = new Set(STATUSES);
 
 export interface Todo {
   id: string;
-  text: string;
+  title: string;       // ≤120 chars, non-empty, trimmed
+  notes: string;       // any length, may be ""
   project: string;
   tags: string[];
   priority: Priority;
@@ -43,13 +44,14 @@ export interface Todo {
 }
 
 export interface Store {
-  version: 2;
+  version: 3;
   updatedAt: string;
   todos: Todo[];
 }
 
 export interface AddInput {
-  text: string;
+  title: string;
+  notes?: string;
   project?: string;
   tags?: string[];
   priority?: Priority;
@@ -57,7 +59,8 @@ export interface AddInput {
 }
 
 export interface UpdateInput {
-  text?: string;
+  title?: string;
+  notes?: string;
   project?: string;
   tags?: string[];
   priority?: Priority;
@@ -86,8 +89,19 @@ function genId(): string {
   return "td-" + Date.now().toString(36) + Math.random().toString(36).slice(2, 8);
 }
 
+const TITLE_MAX = 120;  // must match the constant in migrate.ts
+
+function normalizeTitle(raw: string): string {
+  const t = raw.trim();
+  if (!t) throw new TodoError("title is required");
+  if (t.length > TITLE_MAX) {
+    throw new TodoError(`title must be ≤${TITLE_MAX} chars (got ${t.length}); move detail into notes`);
+  }
+  return t;
+}
+
 function emptyStore(): Store {
-  return { version: 2, updatedAt: now(), todos: [] };
+  return { version: 3, updatedAt: now(), todos: [] };
 }
 
 export function getStorePath(): string {
@@ -105,14 +119,18 @@ export function loadStore(): Store {
   if (!existsSync(path)) return emptyStore();
   try {
     const raw = readFileSync(path, "utf8");
-    const parsed = JSON.parse(raw) as Store;
+    let parsed = JSON.parse(raw) as Store;
     if (!parsed || typeof parsed !== "object" || !Array.isArray(parsed.todos)) {
       throw new Error("invalid store shape");
     }
-    if (parsed.version !== 2) {
-      // v1 → v2: accept it (the migration moved the file), just bump the version in memory.
-      // The data shape is otherwise identical; parked status is new but old todos won't have it.
-      parsed.version = 2;
+    if (parsed.version === 2) {
+      // v2 → v3: curated map + fallback, persist once so migration runs a single time.
+      const migrated = migrateV2ToV3(parsed as any) as unknown as Store;
+      saveStore(migrated);
+      return migrated;
+    }
+    if (parsed.version !== 3) {
+      throw new Error("invalid store shape");
     }
     return parsed;
   } catch {
@@ -160,13 +178,14 @@ function findOrFail(store: Store, id: string): Todo {
 }
 
 export function addTodo(input: AddInput): Todo {
-  const text = (input.text ?? "").trim();
-  if (!text) throw new TodoError("text is required");
+  const title = normalizeTitle(input.title);
   if (input.priority) assertPriority(input.priority);
+  const notes = (input.notes ?? "").trim();
   const store = loadStore();
   const todo: Todo = {
     id: genId(),
-    text,
+    title,
+    notes,
     project: (input.project ?? "").trim(),
     tags: (input.tags ?? []).map((t) => t.trim()).filter(Boolean),
     priority: input.priority ?? "med",
@@ -195,7 +214,7 @@ export function listTodos(filter: ListFilter = {}): Todo[] {
   if (filter.tag) out = out.filter((t) => t.tags.includes(filter.tag as string));
   if (filter.text) {
     const q = filter.text.toLowerCase();
-    out = out.filter((t) => t.text.toLowerCase().includes(q));
+    out = out.filter((t) => t.title.toLowerCase().includes(q) || t.notes.toLowerCase().includes(q));
   }
   if (filter.since) out = out.filter((t) => t.createdAt >= (filter.since as string));
   if (filter.before) out = out.filter((t) => t.createdAt < (filter.before as string));
@@ -218,11 +237,8 @@ export function listTodos(filter: ListFilter = {}): Todo[] {
 export function updateTodo(id: string, patch: UpdateInput): Todo {
   const store = loadStore();
   const todo = findOrFail(store, id);
-  if (patch.text !== undefined) {
-    const text = patch.text.trim();
-    if (!text) throw new TodoError("text must not be empty");
-    todo.text = text;
-  }
+  if (patch.title !== undefined) todo.title = normalizeTitle(patch.title);
+  if (patch.notes !== undefined) todo.notes = patch.notes.trim();
   if (patch.project !== undefined) todo.project = patch.project.trim();
   if (patch.tags !== undefined) todo.tags = patch.tags.map((t) => t.trim()).filter(Boolean);
   if (patch.priority !== undefined) {
@@ -242,6 +258,11 @@ export function updateTodo(id: string, patch: UpdateInput): Todo {
   return todo;
 }
 
+export function getTodo(id: string): Todo {
+  const store = loadStore();
+  return findOrFail(store, id);
+}
+
 export function completeTodo(id: string): Todo {
   return updateTodo(id, { status: "done" });
 }
@@ -272,7 +293,8 @@ export function renderOpenBlock(max = 15): string {
   const lines = shown.map((t) => {
     const tag = t.project ? ` (${t.project})` : "";
     const pin = t.status === "in_progress" ? " ⏵" : "";
-    return `- [${t.id}] (${t.priority})${pin} ${t.text}${tag}`;
+    const dot = t.notes.trim() ? " •" : "";
+    return `- [${t.id}] (${t.priority})${pin}${dot} ${t.title}${tag}`;
   });
   const overflow = todos.length > max ? `\n- … +${todos.length - max} more (use \`todo list\`)` : "";
   return `## Open TODOs (${todos.length})\n${lines.join("\n")}${overflow}\n`;