@comfanion/workflow 4.38.3-dev.0 → 4.38.3-dev.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@comfanion/workflow",
-  "version": "4.38.3-dev.0",
+  "version": "4.38.3-dev.2",
   "description": "Initialize OpenCode Workflow system for AI-assisted development with semantic code search",
   "type": "module",
   "bin": {

package/src/build-info.json

@@ -1,6 +1,6 @@
 {
-  "version": "4.38.3-dev.0",
-  "buildDate": "2026-01-28T10:28:17.932Z",
+  "version": "4.38.3-dev.2",
+  "buildDate": "2026-01-28T11:30:46.666Z",
   "files": [
     ".gitignore",
     "config.yaml",

package/src/opencode/plugins/__tests__/usethis-todo.test.ts

@@ -2,7 +2,7 @@ import { describe, it, expect, beforeEach, afterEach } from "bun:test"
 import { readFile } from "fs/promises"
 import { join } from "path"
 import { createTempDir, cleanupTempDir } from "./helpers/mock-ctx"
-import { write, update, read, get_by_id } from "../../tools/usethis_todo"
+import { write, update, read, read_by_id, read_five } from "../../tools/usethis_todo"
 
 describe("usethis_todo tool", () => {
   let tempDir: string
@@ -28,8 +28,8 @@ describe("usethis_todo tool", () => {
     const output = await write.execute(
       {
         todos: [
-          { id: "A1", content: "First task", description: "Longer details", status: "ready", priority: "HIGH" },
-          { id: "A2", content: "Second task", status: "pending", priority: "LOW" },
+          { id: "A1", content: "First task", description: "Longer details", status: "todo", priority: "HIGH" },
+          { id: "A2", content: "Second task", status: "todo", priority: "LOW" },
         ],
       },
       ctx
@@ -62,7 +62,7 @@ describe("usethis_todo tool", () => {
     await write.execute(
       {
         todos: [
-          { id: "A1", content: "First task", description: "v1", status: "pending", priority: "MED" },
+          { id: "A1", content: "First task", description: "v1", status: "todo", priority: "MED" },
         ],
       },
       ctx
@@ -72,7 +72,7 @@ describe("usethis_todo tool", () => {
       {
         todos: [
           { id: "A1", content: "First task", description: "v2", status: "done", priority: "MED" },
-          { id: "A2", content: "Second task", status: "ready", priority: "LOW" },
+          { id: "A2", content: "Second task", status: "todo", priority: "LOW" },
         ],
       },
       ctx
@@ -87,12 +87,35 @@ describe("usethis_todo tool", () => {
     expect(enhanced.find((t: any) => t.id === "A1")?.description).toBe("v2")
   })
 
+  it("auto-promotes ready -> done when releases exist", async () => {
+    const ctx = { sessionID: "sess-rel", directory: tempDir } as any
+
+    await write.execute(
+      {
+        todos: [
+          {
+            id: "A1",
+            content: "Ship it",
+            status: "ready",
+            priority: "HIGH",
+            releases: ["4.38.4"],
+          },
+        ],
+      },
+      ctx
+    )
+
+    const enhancedPath = join(tempDir, ".opencode", "session-todos", "sess-rel.json")
+    const enhanced = JSON.parse(await readFile(enhancedPath, "utf-8"))
+    expect(enhanced.find((t: any) => t.id === "A1")?.status).toBe("done")
+  })
+
   it("read returns graph with content", async () => {
     const ctx = { sessionID: "sess-read", directory: tempDir } as any
     await write.execute(
       {
         todos: [
-          { id: "A1", content: "Task content", status: "ready", priority: "HIGH" },
+          { id: "A1", content: "Task content", status: "todo", priority: "HIGH" },
         ],
       },
       ctx
@@ -103,7 +126,36 @@ describe("usethis_todo tool", () => {
     expect(output).toContain("Available Now")
   })
 
-  it("get_by_id returns single task", async () => {
+  it("read_five returns up to 5 available tasks with description", async () => {
+    const ctx = { sessionID: "sess-five", directory: tempDir } as any
+    await write.execute(
+      {
+        todos: [
+          { id: "A1", content: "T1", description: "D1", status: "todo", priority: "HIGH", blockedBy: ["B1"] },
+          { id: "A2", content: "T2", status: "todo", priority: "MED" },
+          { id: "A3", content: "T3", status: "todo", priority: "LOW" },
+          { id: "A4", content: "T4", status: "todo", priority: "LOW" },
+          { id: "A5", content: "T5", status: "todo", priority: "LOW" },
+          { id: "A6", content: "T6", status: "todo", priority: "LOW" },
+          { id: "B1", content: "B", status: "in_progress", priority: "LOW", blockedBy: ["C1"] },
+          { id: "C1", content: "C", status: "in_progress", priority: "MED" },
+        ],
+      },
+      ctx
+    )
+
+    const out = await read_five.execute({}, ctx)
+    expect(out).toContain("Next 5")
+    expect(out).toContain("A1")
+    expect(out).toContain("T1")
+    expect(out).toContain("D1")
+    expect(out).toContain("+1 more")
+    expect(out).toContain("Blocked By (resolved)")
+    expect(out).toContain("B1")
+    expect(out).toContain("C1")
+  })
+
+  it("read_by_id returns task with resolved blockers", async () => {
     const ctx = { sessionID: "sess-get", directory: tempDir } as any
     await write.execute(
       {
@@ -112,27 +164,42 @@ describe("usethis_todo tool", () => {
             id: "A1",
             content: "Task content",
             description: "More details",
-            status: "ready",
+            status: "todo",
             priority: "HIGH",
             blockedBy: ["B1"],
           },
+          {
+            id: "B1",
+            content: "Blocker task",
+            status: "done",
+            priority: "LOW",
+            blockedBy: ["C1"],
+          },
+          {
+            id: "C1",
+            content: "Root blocker",
+            status: "todo",
+            priority: "MED",
+          },
         ],
       },
       ctx
     )
 
-    const out = await get_by_id.execute({ id: "A1" }, ctx)
-    expect(out).toContain("id: A1")
-    expect(out).toContain("content:")
+    const out = await read_by_id.execute({ id: "A1" }, ctx)
+    expect(out).toContain("Task:")
+    expect(out).toContain("A1")
     expect(out).toContain("Task content")
-    expect(out).toContain("blockedBy: B1")
-    expect(out).toContain("description:")
     expect(out).toContain("More details")
+
+    expect(out).toContain("Blocked By (resolved):")
+    expect(out).toContain("B1")
+    expect(out).toContain("C1")
   })
 
-  it("get_by_id returns not found", async () => {
+  it("read_by_id returns not found", async () => {
     const ctx = { sessionID: "sess-miss", directory: tempDir } as any
-    const out = await get_by_id.execute({ id: "NOPE" }, ctx)
+    const out = await read_by_id.execute({ id: "NOPE" }, ctx)
     expect(out).toContain("not found")
   })
 })

package/src/opencode/plugins/usethis-todo-publish.ts

@@ -9,10 +9,18 @@ import type { Plugin } from "@opencode-ai/plugin"
 export const UsethisTodoPublish: Plugin = async ({ client }) => {
   return {
     "tool.execute.after": async (input, output) => {
-      if (input.tool !== "usethis_todo_write" && input.tool !== "usethis_todo_update") return
+      const publishTools = new Set([
+        "usethis_todo_write",
+        "usethis_todo_update",
+        "usethis_todo_read",
+        "usethis_todo_read_five",
+        "usethis_todo_read_by_id",
+      ])
+
+      if (!publishTools.has(input.tool)) return
 
       const text = [
-          `## TODO`,
+        `## TODO`,
         // `session: ${input.sessionID}`,
         "",
         output.output

package/src/opencode/tools/usethis_todo.ts

@@ -1,16 +1,17 @@
 /**
  * TODO Tool with Dependencies & Priority — v3 (dual storage)
- * 
+ *
  * 4 commands:
  *   usethis_todo_write({ todos: [...] })    - create/update TODO list
  *   usethis_todo_read()                     - read TODO with graph analysis
- *   usethis_todo_read_next_five()           - get next 5 available tasks
+ *   usethis_todo_read_five()           - get next 5 available tasks
+ *   usethis_todo_read_by_id()           - get next 5 available tasks
  *   usethis_todo_update(id, field, value)   - update any task field
- * 
+ *
  * Storage:
  *   Enhanced: .opencode/session-todos/{sid}.json  (title, blockedBy, graph)
  *   Native:  ~/.local/share/opencode/storage/todo/{sid}.json  (TUI display)
- * 
+ *
  * Features:
  * - Hierarchical IDs: E01-S01-T01
  * - Dependencies: blockedBy field
@@ -32,7 +33,8 @@ interface Todo {
   id: string              // E01-S01-T01
   content: string         // Short task summary
   description?: string    // Full task description (optional)
-  status: string          // pending | ready | in_progress | waiting_review | done | cancelled
+  releases?: string[]     // Release identifiers (optional)
+  status: string          // todo | in_progress | ready | done
   priority: string        // CRIT | HIGH | MED | LOW
   blockedBy?: string[]    // IDs of blocking tasks
   createdAt?: number
@@ -102,10 +104,10 @@ async function getNativePaths(sid: string): Promise<string[]> {
 function toNative(todo: Todo): NativeTodo {
   // Status mapping: our → native
   const statusMap: Record<string, string> = {
-    pending: "pending",
-    ready: "pending",           // native has no "ready"
+    todo: "pending",
     in_progress: "in_progress",
-    waiting_review: "in_progress",  // native has no "waiting_review"
+    ready: "in_progress",       // native has no "ready"
+    finished: "in_progress",    // back-compat
     done: "completed",          // native uses "completed" not "done"
     cancelled: "cancelled",
   }
@@ -116,13 +118,14 @@ function toNative(todo: Todo): NativeTodo {
     MED: "medium",
     LOW: "low",
   }
-  
+
   const deps = todo.blockedBy?.length ? ` [← ${todo.blockedBy.join(", ")}]` : ""
   const desc = todo.description?.trim() ? ` — ${todo.description.trim()}` : ""
+  const rel = todo.releases?.length ? ` [rel: ${todo.releases.join(", ")}]` : ""
 
   return {
     id: todo.id,
-    content: `${todo.content}${desc}${deps}`,
+    content: `${todo.content}${desc}${rel}${deps}`,
     status: statusMap[todo.status] || "pending",
     priority: prioMap[todo.priority] || "medium",
   }
@@ -130,7 +133,9 @@ function toNative(todo: Todo): NativeTodo {
 
 async function readTodos(sid: string, directory?: string): Promise<Todo[]> {
   try {
-    return JSON.parse(await fs.readFile(getEnhancedPath(sid, directory), "utf-8"))
+    const raw = JSON.parse(await fs.readFile(getEnhancedPath(sid, directory), "utf-8"))
+    if (!Array.isArray(raw)) return []
+    return raw.map((t: any) => normalizeTodo(t))
   } catch {
     return []
   }
@@ -141,16 +146,16 @@ async function writeTodos(todos: Todo[], sid: string, directory?: string): Promi
   const enhancedPath = getEnhancedPath(sid, directory)
   await fs.mkdir(path.dirname(enhancedPath), { recursive: true })
   await fs.writeFile(enhancedPath, JSON.stringify(todos, null, 2), "utf-8")
-  
+
   // 2. Native storage (for TUI display)
   const nativeTodos = todos.map(toNative)
   try {
     const nativePaths = await getNativePaths(sid)
     await Promise.allSettled(
-      nativePaths.map(async (nativePath) => {
-        await fs.mkdir(path.dirname(nativePath), { recursive: true })
-        await fs.writeFile(nativePath, JSON.stringify(nativeTodos, null, 2), "utf-8")
-      }),
+        nativePaths.map(async (nativePath) => {
+          await fs.mkdir(path.dirname(nativePath), { recursive: true })
+          await fs.writeFile(nativePath, JSON.stringify(nativeTodos, null, 2), "utf-8")
+        }),
     )
   } catch {
     // Native write failure is non-fatal
@@ -166,10 +171,11 @@ function analyzeGraph(todos: Todo[]): TodoGraph {
   const availableTodos: Todo[] = []
   
   for (const todo of todos) {
-    if (todo.status !== "ready") continue
+    if (normalizeStatus(todo.status) !== "todo") continue
     const activeBlockers = (todo.blockedBy || []).filter(id => {
       const b = todos.find(t => t.id === id)
-      return b && b.status !== "done"
+      const bs = normalizeStatus(b?.status)
+      return b && bs !== "done" && bs !== "cancelled"
     })
     if (activeBlockers.length === 0) {
       availableTodos.push(todo)
@@ -177,11 +183,11 @@ function analyzeGraph(todos: Todo[]): TodoGraph {
       blocked[todo.id] = activeBlockers
     }
   }
-  
+
   const P: Record<string, number> = { CRIT: 0, HIGH: 1, MED: 2, LOW: 3 }
   availableTodos.sort((a, b) => (P[a.priority] ?? 2) - (P[b.priority] ?? 2))
   const available = availableTodos.map(t => t.id)
-  
+
   // Parallel groups
   const parallel: string[][] = []
   const seen = new Set<string>()
@@ -200,7 +206,7 @@ function analyzeGraph(todos: Todo[]): TodoGraph {
     }
     if (group.length > 0) parallel.push(group)
   }
-  
+
   return { todos, available, parallel, blocked }
 }
 
@@ -209,52 +215,184 @@ function analyzeGraph(todos: Todo[]): TodoGraph {
 // ============================================================================
 
 const PE = (p?: string) => p === "CRIT" ? "🔴" : p === "HIGH" ? "🟠" : p === "LOW" ? "🟢" : "🟡"
-const SI = (s: string) => s === "done" ? "✓" : s === "in_progress" ? "⚙" : s === "ready" ? "○" : s === "cancelled" ? "✗" : s === "waiting_review" ? "⏳" : "·"
+const SI = (s: string) => s === "done" ? "✓" : s === "in_progress" ? "⚙" : s === "ready" ? "⏳" : s === "cancelled" ? "✗" : s === "todo" ? "○" : "·"
+
+function normalizeStatus(input: unknown): string {
+  const s = String(input || "").trim()
+
+  // New canonical set
+  if (s === "todo" || s === "in_progress" || s === "ready" || s === "done") return s
+
+  // Back-compat (older versions)
+  if (s === "pending") return "todo"
+  if (s === "waiting_review" || s === "finished") return "ready"
+  if (s === "completed") return "done"
+
+  // Keep cancelled if it appears (native supports it)
+  if (s === "cancelled") return "cancelled"
+
+  // Default
+  return "todo"
+}
+
+function normalizeReleases(input: unknown): string[] | undefined {
+  if (!Array.isArray(input)) return undefined
+  const values = input
+    .map((x) => String(x || "").trim())
+    .filter(Boolean)
+  return values.length ? values : undefined
+}
+
+function normalizeTodo(input: any): Todo {
+  const status = normalizeStatus(input?.status)
+  const releases = normalizeReleases(input?.releases)
+
+  // Auto transition: ready -> done when releases exist
+  const promotedStatus = status === "ready" && releases?.length ? "done" : status
+
+  return {
+    ...input,
+    status: promotedStatus,
+    releases,
+  }
+}
+
+function prioRank(p?: string): number {
+  return p === "CRIT" ? 0 : p === "HIGH" ? 1 : p === "MED" ? 2 : 3
+}
+
+function sortTodosForList(todos: Todo[]): Todo[] {
+  return todos
+    .slice()
+    .sort((a, b) => (prioRank(a.priority) - prioRank(b.priority)) || a.id.localeCompare(b.id))
+}
+
+function isBlocked(todo: Todo, byId: Map<string, Todo>): boolean {
+  const s = normalizeStatus(todo.status)
+  if (s !== "todo") return false
+  if (!todo.blockedBy?.length) return false
+  for (const id of todo.blockedBy) {
+    const b = byId.get(id)
+    const bs = normalizeStatus(b?.status)
+    if (!b) return true
+    if (bs !== "done" && bs !== "cancelled") return true
+  }
+  return false
+}
+
+function todoLine(todo: Todo, byId: Map<string, Todo>): string {
+  const desc = todo.description?.trim() ? ` — ${todo.description.trim()}` : ""
+  const rel = todo.releases?.length ? ` [rel: ${todo.releases.join(", ")}]` : ""
+  const deps = todo.blockedBy?.length ? ` ← ${todo.blockedBy.join(", ")}` : ""
+  const ns = normalizeStatus(todo.status)
+  const icon = isBlocked(todo, byId) ? "⊗" : SI(ns)
+  return `${icon} ${PE(todo.priority)} ${todo.id}: ${todo.content}${desc}${rel}${deps}`
+}
+
+function renderNestedTodoList(todos: Todo[], allTodos?: Todo[]): string {
+  const byId = new Map((allTodos || todos).map(t => [t.id, t]))
+
+  // Group by id pattern: E01-S01-T01 → 3 nested levels (E01 → S01 → tasks)
+  const groups = new Map<string, Map<string, Todo[]>>()
+  const flat: Todo[] = []
 
-function formatGraph(graph: TodoGraph): string {
-  const { todos } = graph
-  const total = todos.length
-  const done = todos.filter(t => t.status === "done").length
-  const wip = todos.filter(t => t.status === "in_progress").length
-  
-  const lines: string[] = [`═══ TODO Graph [${done}/${total} done, ${wip} in progress] ═══`, ""]
-  
-  lines.push("All Tasks:")
   for (const t of todos) {
-    const deps = t.blockedBy?.length ? ` ← ${t.blockedBy.join(", ")}` : ""
-    const desc = t.description?.trim() ? ` — ${t.description.trim()}` : ""
-    lines.push(`  ${SI(t.status)} ${PE(t.priority)} ${t.id}: ${t.content}${desc}${deps}`)
+    const parts = t.id.split("-")
+    if (parts.length >= 3) {
+      const epic = parts[0]
+      const story = parts[1]
+      if (!groups.has(epic)) groups.set(epic, new Map())
+      const storyMap = groups.get(epic)!
+      if (!storyMap.has(story)) storyMap.set(story, [])
+      storyMap.get(story)!.push(t)
+    } else {
+      flat.push(t)
+    }
   }
-  lines.push("")
-  
-  if (graph.available.length > 0) {
-    lines.push("Available Now:")
-    for (const id of graph.available) {
-      const t = todos.find(x => x.id === id)
-      const desc = t?.description?.trim() ? ` — ${t.description.trim()}` : ""
-      lines.push(`  → ${PE(t?.priority)} ${id}: ${t?.content}${desc}`)
+
+  const lines: string[] = []
+  const epicKeys = [...groups.keys()].sort()
+  for (const epic of epicKeys) {
+    lines.push(`- ${epic}`)
+    const storyMap = groups.get(epic)!
+    const storyKeys = [...storyMap.keys()].sort()
+    for (const story of storyKeys) {
+      lines.push(`  - ${epic}-${story}`)
+      const tasks = storyMap.get(story)!
+        .slice()
+        .sort((a, b) => a.id.localeCompare(b.id))
+      for (const t of tasks) {
+        lines.push(`    - ${todoLine(t, byId)}`)
+      }
     }
-  } else {
-    lines.push("Available Now: none")
   }
-  lines.push("")
-  
-  const multi = graph.parallel.filter(g => g.length > 1)
-  if (multi.length > 0) {
-    lines.push("Parallel Groups:")
-    multi.forEach((g, i) => lines.push(`  Group ${i + 1}: ${g.join(", ")}`))
-    lines.push("")
+
+  const flatSorted = flat.slice().sort((a, b) => a.id.localeCompare(b.id))
+  for (const t of flatSorted) {
+    lines.push(`- ${todoLine(t, byId)}`)
   }
-  
-  if (Object.keys(graph.blocked).length > 0) {
-    lines.push("Blocked:")
-    for (const [id, blockers] of Object.entries(graph.blocked)) {
-      const t = todos.find(x => x.id === id)
-      const desc = t?.description?.trim() ? ` — ${t.description.trim()}` : ""
-      lines.push(`  ⊗ ${id}: ${t?.content}${desc} ← waiting: ${blockers.join(", ")}`)
+
+  return lines.length ? lines.join("\n") : "- (empty)"
+}
+
+function resolveBlockers(todos: Todo[], rootIds: string[]): { blockers: Todo[]; missing: string[] } {
+  const byId = new Map(todos.map(t => [t.id, t]))
+  const blockers: Todo[] = []
+  const missing: string[] = []
+  const seen = new Set<string>()
+  const stack: string[] = []
+
+  for (const id of rootIds) {
+    const t = byId.get(id)
+    if (!t?.blockedBy?.length) continue
+    stack.push(...t.blockedBy)
+  }
+
+  while (stack.length > 0) {
+    const id = stack.shift()!
+    if (seen.has(id)) continue
+    seen.add(id)
+
+    const t = byId.get(id)
+    if (!t) {
+      missing.push(id)
+      continue
     }
+
+    blockers.push(t)
+    if (t.blockedBy?.length) stack.push(...t.blockedBy)
   }
-  
+
+  blockers.sort((a, b) => a.id.localeCompare(b.id))
+  missing.sort((a, b) => a.localeCompare(b))
+  return { blockers, missing }
+}
+
+function formatGraph(graph: TodoGraph): string {
+  const { todos } = graph
+  const total = todos.length
+  const done = todos.filter(t => normalizeStatus(t.status) === "done").length
+  const wip = todos.filter(t => normalizeStatus(t.status) === "in_progress").length
+
+  const availableTodos = graph.available
+    .map((id) => todos.find((t) => t.id === id))
+    .filter(Boolean) as Todo[]
+
+  const blockedTodos = Object.keys(graph.blocked)
+    .map((id) => todos.find((t) => t.id === id))
+    .filter(Boolean) as Todo[]
+
+  const lines: string[] = []
+  lines.push(`TODO Graph [${done}/${total} done, ${wip} in progress]`)
+  lines.push("")
+  lines.push("All Tasks:")
+  lines.push(renderNestedTodoList(sortTodosForList(todos), todos))
+  lines.push("")
+  lines.push("Available Now:")
+  lines.push(availableTodos.length ? renderNestedTodoList(availableTodos, todos) : "- (none)")
+  lines.push("")
+  lines.push("Blocked:")
+  lines.push(blockedTodos.length ? renderNestedTodoList(blockedTodos, todos) : "- (none)")
   return lines.join("\n")
 }
 
@@ -266,42 +404,56 @@ export const write = tool({
   description: "Create or update TODO list. TODOv2 (Prefer this instead of TODO)",
   args: {
     todos: tool.schema.array(
-      tool.schema.object({
-        id: tool.schema.string().describe("Task ID in concat format: E01-S01-T01"),
-        content: tool.schema.string().describe("Short task summary"),
-        description: tool.schema.string().optional().describe("Full task description"),
-        status: tool.schema.string().describe("pending | ready | in_progress | waiting_review | done | cancelled"),
-        priority: tool.schema.string().describe("CRIT | HIGH | MED | LOW"),
-        blockedBy: tool.schema.array(tool.schema.string()).optional().describe("IDs of blocking tasks"),
-      })
+        tool.schema.object({
+          id: tool.schema.string().describe("Task ID in concat format: E01-S01-T01"),
+          content: tool.schema.string().describe("Short task summary"),
+          description: tool.schema.string().optional().describe("Full task description"),
+          releases: tool.schema.array(tool.schema.string()).optional().describe("Release identifiers"),
+          status: tool.schema.string().describe("todo | in_progress | ready | done"),
+          priority: tool.schema.string().describe("CRIT | HIGH | MED | LOW"),
+          blockedBy: tool.schema.array(tool.schema.string()).optional().describe("IDs of blocking tasks"),
+        })
     ).describe("Array of todos"),
   },
   async execute(args, context) {
     const now = Date.now()
-    const todos = args.todos.map((t: any) => ({ ...t, createdAt: t.createdAt || now, updatedAt: now }))
+    const todos = args.todos.map((t: any) => normalizeTodo({ ...t, createdAt: t.createdAt || now, updatedAt: now }))
     await writeTodos(todos, context.sessionID, context.directory)
     return formatGraph(analyzeGraph(todos))
   },
 })
 
-export const read_next_five = tool({
+export const read_five = tool({
   description: "Read current TODO list. Shows Next 5 tasks.",
   args: {},
   async execute(_args, context) {
     const todos = await readTodos(context.sessionID, context.directory)
-    const graph = analyzeGraph(todos)
-    if (graph.available.length === 0) return "No tasks available. All blocked or not ready."
-    const next5 = graph.available.slice(0, 5)
-    const lines: string[] = ["Next 5 available tasks:", ""]
-    for (const id of next5) {
-      const t = graph.todos.find(x => x.id === id)
-      if (t) {
-        const desc = t.description?.trim() ? `\n   ${t.description.trim()}` : ""
-        lines.push(`${PE(t.priority)} ${id}: ${t.content}${desc}`)
-        lines.push("")
-      }
+    const ready = sortTodosForList(todos.filter(t => normalizeStatus(t.status) === "todo"))
+    if (ready.length === 0) return "No tasks in todo."
+
+    const items = ready.slice(0, 5)
+
+    const rootIds = items.map(t => t.id)
+    const rootSet = new Set(rootIds)
+    const resolved = resolveBlockers(todos, rootIds)
+    const blockers = resolved.blockers.filter(t => !rootSet.has(t.id))
+    const missing = resolved.missing
+
+    const more = ready.length > 5 ? `+${ready.length - 5} more` : ""
+
+    const lines: string[] = []
+    lines.push("Next 5:")
+    lines.push(renderNestedTodoList(items, todos))
+    if (more) lines.push(more)
+
+    lines.push("")
+    lines.push(`Blocked By (resolved) [${blockers.length}]:`)
+    lines.push(blockers.length ? renderNestedTodoList(blockers, todos) : "- (none)")
+    if (missing.length) {
+      lines.push("")
+      lines.push(`Blocked By missing: ${missing.join(", ")}`)
     }
-    if (graph.available.length > 5) lines.push(`... +${graph.available.length - 5} more`)
+
     return lines.join("\n")
   },
 })
@@ -316,8 +468,8 @@ export const read = tool({
   },
 })
 
-export const get_by_id = tool({
-  description: "Get one task by id.",
+export const read_by_id = tool({
+  description: "Read task by id.",
   args: {
     id: tool.schema.string().describe("Task ID"),
   },
@@ -326,31 +478,38 @@ export const get_by_id = tool({
     const todo = todos.find(t => t.id === args.id)
     if (!todo) return `❌ Task ${args.id} not found`
 
-    const deps = todo.blockedBy?.length ? `\nblockedBy: ${todo.blockedBy.join(", ")}` : ""
-    const desc = todo.description?.trim() ? `\n\ndescription:\n${todo.description.trim()}` : ""
-    return [
-      `id: ${todo.id}`,
-      `priority: ${todo.priority}`,
-      `status: ${todo.status}`,
-      deps,
-      `\ncontent:\n${todo.content}`,
-      desc,
-    ].filter(Boolean).join("\n")
+    const { blockers, missing } = resolveBlockers(todos, [todo.id])
+
+    const lines: string[] = []
+    lines.push("Task:")
+    lines.push(`- ${todoLine(todo, new Map(todos.map(t => [t.id, t])) )}`)
+
+    lines.push("")
+    lines.push("Blocked By (resolved):")
+    lines.push(blockers.length ? renderNestedTodoList(blockers, todos) : "- (none)")
+
+    if (missing.length) {
+      lines.push("")
+      lines.push(`Blocked By missing: ${missing.join(", ")}`)
+    }
+
+    return lines.join("\n")
   },
 })
 
 export const update = tool({
-  description: "Update tasks. Same interface as write, but merges by id.",
+  description: "Update task(s). Send 1 or many for update",
   args: {
     todos: tool.schema.array(
-      tool.schema.object({
-        id: tool.schema.string().describe("Task ID in concat format: E01-S01-T01"),
-        content: tool.schema.string().describe("Short task summary"),
-        description: tool.schema.string().optional().describe("Full task description"),
-        status: tool.schema.string().describe("pending | ready | in_progress | waiting_review | done | cancelled"),
-        priority: tool.schema.string().describe("CRIT | HIGH | MED | LOW"),
-        blockedBy: tool.schema.array(tool.schema.string()).optional().describe("IDs of blocking tasks"),
-      })
+        tool.schema.object({
+          id: tool.schema.string().describe("Task ID in concat format: E01-S01-T01"),
+          content: tool.schema.string().describe("Short task summary"),
+          description: tool.schema.string().optional().describe("Full task description"),
+          releases: tool.schema.array(tool.schema.string()).optional().describe("Release identifiers(from ready -> done)"),
+          status: tool.schema.string().describe("todo | in_progress | ready | done"),
+          priority: tool.schema.string().describe("CRIT | HIGH | MED | LOW"),
+          blockedBy: tool.schema.array(tool.schema.string()).optional().describe("IDs of blocking tasks(from todo -> blocked)"),
+        })
     ).describe("Array of todos to update"),
   },
   async execute(args, context) {
@@ -359,12 +518,16 @@ export const update = tool({
     const byId = new Map(todos.map(t => [t.id, t]))
 
     for (const incoming of args.todos) {
-      const existing = byId.get(incoming.id)
+      const normalizedIncoming: any = normalizeTodo(incoming)
+      const existing = byId.get(normalizedIncoming.id)
       if (existing) {
-        Object.assign(existing, incoming)
+        Object.assign(existing, normalizedIncoming)
         existing.updatedAt = now
+        // Ensure auto transition is applied after merge
+        existing.status = normalizeTodo(existing).status
+        existing.releases = normalizeTodo(existing).releases
       } else {
-        byId.set(incoming.id, { ...incoming, createdAt: now, updatedAt: now })
+        byId.set(normalizedIncoming.id, normalizeTodo({ ...normalizedIncoming, createdAt: now, updatedAt: now }))
       }
     }