// Get next ready task with full context (recommended for work sessions)
const task = await tasks.nextReady(milestoneId); // TaskWithContext | null
if (!task) {
  console.log("No ready tasks");
  return;
}

// Get all ready tasks (for progress overview)
const readyTasks = await tasks.list({ ready: true }); // Task[]

// 1. Get next ready task (returns TaskWithContext | null)
const task = await tasks.nextReady();
if (!task) return "No ready tasks";

// 2. Review context (available on TaskWithContext)
console.log(task.context.own);       // This task's context
console.log(task.context.parent);    // Parent's context (if depth > 0)
console.log(task.context.milestone); // Root milestone context (if depth > 1)
console.log(task.learnings.own);     // Learnings attached to this task (bubbled from children)

// 3. Start work (VCS required - creates bookmark, records start commit)
await tasks.start(task.id);

// 4. Implement...

// 5. Complete with learnings (VCS required - commits changes, bubbles learnings to parent)
await tasks.complete(task.id, {
  result: "Implemented login endpoint with JWT tokens",
  learnings: ["bcrypt rounds should be 12 for production"]
});

// Alternative: Cancel if abandoning (does NOT satisfy blockers)
await tasks.cancel(task.id);

// 6. Archive finished tasks to hide from default list
await tasks.archive(task.id);

const task = await tasks.get(taskId); // Returns TaskWithContext
// task.context.own      - this task's context (always present)
// task.context.parent   - parent task's context (if depth > 0)
// task.context.milestone - root milestone's context (if depth > 1)

// Task's own learnings (bubbled from completed children)
// task.learnings.own - learnings attached to this task

// Add blocker - taskA waits for taskB
await tasks.block(taskA.id, taskB.id);

// Remove blocker
await tasks.unblock(taskA.id, taskB.id);