trekoon 0.3.0 → 0.3.2

package/src/board/assets/components/Workspace.js

@@ -20,8 +20,8 @@ import {
   STATUS_LABELS,
   STATUS_ORDER,
 } from "./helpers.js";
-import { orderEpicsNewestFirst } from "../state/store.js";
-import { VIEW_MODES } from "../state/utils.js";
+import { DEFAULT_STATUS_FILTER, orderEpicsNewestFirst } from "../state/store.js";
+import { getSelectableStatuses, VIEW_MODES } from "../state/utils.js";
 
 // ---------------------------------------------------------------------------
 // Workspace header
@@ -58,6 +58,9 @@ function renderWorkspaceHeader(props) {
     visibleTasks,
   } = props;
 
+  const taskStatusFilter = store.taskStatusFilter || { ...DEFAULT_STATUS_FILTER };
+  const isTaskFilterNonDefault = STATUS_ORDER.some(s => taskStatusFilter[s] !== DEFAULT_STATUS_FILTER[s]);
+
   const description = selectedEpic.description?.trim() || "";
   const inlineSelect = `${fieldClasses()} !py-1 !px-2 !text-xs !min-h-0 !rounded-xl`;
   const epicStatusTooltip = "Change this epic's overall status.";
@@ -79,7 +82,7 @@ function renderWorkspaceHeader(props) {
             <label class="board-wh__control-label">
               <span class="board-wh__control-text">Epic status</span>
               <select class="${inlineSelect}" name="status" aria-label="Epic status" title="${escapeHtml(epicStatusTooltip)}" ${store.isMutating ? "disabled" : ""}>
-                ${STATUS_ORDER.map(s => `<option value="${escapeHtml(s)}" ${selectedEpic.status === s ? 'selected' : ''}>${escapeHtml(STATUS_LABELS[s] ?? s)}</option>`).join('')}
+                ${getSelectableStatuses(selectedEpic.status).map(s => `<option value="${escapeHtml(s)}" ${selectedEpic.status === s ? 'selected' : ''}>${escapeHtml(STATUS_LABELS[s] ?? s)}</option>`).join('')}
               </select>
             </label>
           </form>
@@ -114,6 +117,14 @@ function renderWorkspaceHeader(props) {
           <span class="${neutralChipClasses()}">${visibleTasks.length} visible</span>
           ${store.isMutating ? `<span class="${neutralChipClasses()}">Saving\u2026</span>` : ""}
         </div>
+        <div class="board-filter-bar">
+          ${STATUS_ORDER.map(status => {
+            const active = taskStatusFilter[status] !== false;
+            const count = selectedEpic.counts?.[status] ?? 0;
+            return `<button type="button" class="board-filter-pill ${active ? 'board-filter-pill--active' : 'board-filter-pill--inactive'} board-filter-pill--${status}" data-toggle-task-status-filter="${status}" aria-pressed="${active}" title="${active ? 'Hide' : 'Show'} ${STATUS_LABELS[status]} tasks">${STATUS_LABELS[status]} (${count})</button>`;
+          }).join('')}
+          ${isTaskFilterNonDefault ? `<button type="button" class="board-filter-pill board-filter-pill--reset" data-reset-task-filter title="Reset filters to defaults">Reset</button>` : ''}
+        </div>
         <div class="board-wh__actions">
           <div class="board-wh__action-group">
             <button type="button" class="board-copy-btn ${isCopied ? "board-copy-btn--active" : ""}" data-copy-epic-id="${escapeHtml(selectedEpic.id)}" aria-label="${escapeHtml(isCopied ? `Copied epic UUID for ${selectedEpic.title}` : copyLabel)}" title="${escapeHtml(isCopied ? "Epic UUID copied." : copyTooltip)}">
@@ -155,9 +166,12 @@ function renderWorkspaceHeader(props) {
 // ---------------------------------------------------------------------------
 
 function renderKanbanColumns(props) {
-  const { visibleTasks, selectedTaskId, isMutating } = props;
+  const { visibleTasks, selectedTaskId, isMutating, taskStatusFilter } = props;
+  const filter = taskStatusFilter || { ...DEFAULT_STATUS_FILTER };
 
-  const columnsMarkup = STATUS_ORDER.map((status) => {
+  const columnsMarkup = STATUS_ORDER
+    .filter((status) => filter[status] !== false)
+    .map((status) => {
     const columnTasks = visibleTasks.filter((t) => t.status === status);
     const columnTitle = readStatusLabel(status);
     const content = columnTasks.length === 0
@@ -265,19 +279,20 @@ function render(props) {
   const headerMarkup = renderWorkspaceHeader({
     selectedEpic,
     snapshotEpics,
-      store: {
-        copyFeedback: store.copyFeedback,
-        notesPanelOpen: store.notesPanelOpen,
-        isMutating: store.isMutating,
-        selectedEpicId: selectedEpic.id,
-        view: store.view,
+    store: {
+      copyFeedback: store.copyFeedback,
+      notesPanelOpen: store.notesPanelOpen,
+      isMutating: store.isMutating,
+      selectedEpicId: selectedEpic.id,
+      view: store.view,
       viewModes,
+      taskStatusFilter: store.taskStatusFilter,
     },
     visibleTasks,
   });
 
   const contentMarkup = store.view === "kanban"
-    ? renderKanbanColumns({ visibleTasks, selectedTaskId, isMutating: store.isMutating })
+    ? renderKanbanColumns({ visibleTasks, selectedTaskId, isMutating: store.isMutating, taskStatusFilter: store.taskStatusFilter })
     : renderListView({ visibleTasks, selectedTaskId });
 
   return `

package/src/board/assets/components/helpers.js

@@ -1,4 +1,4 @@
-import { escapeHtml, formatDate, normalizeStatus, STATUS_ORDER } from "../state/utils.js";
+import { escapeHtml, formatDate, getSelectableStatuses, normalizeStatus, STATUS_ORDER } from "../state/utils.js";
 
 export { escapeHtml, formatDate, normalizeStatus, STATUS_ORDER };
 
@@ -123,9 +123,10 @@ export function renderStatusBadge(rawStatus, label = readStatusLabel(rawStatus))
 }
 
 export function renderStatusSelect(name, selectedStatus, disabled = false) {
+  const statuses = getSelectableStatuses(selectedStatus);
   return `
     <select class="${fieldClasses()}" name="${escapeHtml(name)}" ${disabled ? "disabled" : ""}>
-      ${STATUS_ORDER.map((status) => `
+      ${statuses.map((status) => `
         <option value="${escapeHtml(status)}" ${selectedStatus === status ? "selected" : ""}>${escapeHtml(STATUS_LABELS[status] ?? status)}</option>
       `).join("")}
     </select>

package/src/board/assets/runtime/delegation.js

@@ -1,3 +1,5 @@
+import { isValidTransition } from "../state/utils.js";
+
 /**
  * Event delegation system for the board runtime.
  *
@@ -89,6 +91,31 @@ export function createDelegation(rootElement, actions) {
       return;
     }
 
+    // -- Status filter pills ---------------------------------------------------
+    const epicFilterEl = target.closest("[data-toggle-epic-status-filter]");
+    if (epicFilterEl) {
+      actions.toggleEpicStatusFilter(epicFilterEl.dataset.toggleEpicStatusFilter);
+      return;
+    }
+
+    const taskFilterEl = target.closest("[data-toggle-task-status-filter]");
+    if (taskFilterEl) {
+      actions.toggleTaskStatusFilter(taskFilterEl.dataset.toggleTaskStatusFilter);
+      return;
+    }
+
+    const resetEpicFilterEl = target.closest("[data-reset-epic-filter]");
+    if (resetEpicFilterEl) {
+      actions.resetEpicFilter();
+      return;
+    }
+
+    const resetTaskFilterEl = target.closest("[data-reset-task-filter]");
+    if (resetTaskFilterEl) {
+      actions.resetTaskFilter();
+      return;
+    }
+
     // -- Navigation -----------------------------------------------------------
 
     const navEl = target.closest("[data-nav]");
@@ -276,6 +303,15 @@ export function createDelegation(rootElement, actions) {
   // ---------------------------------------------------------------------------
   // Drag-and-drop delegation
   // ---------------------------------------------------------------------------
+  let draggedTaskStatus = null;
+
+  function cleanupDragFeedback() {
+    draggedTaskStatus = null;
+    for (const el of rootElement.querySelectorAll(".board-drop-valid, .board-drop-invalid")) {
+      el.classList.remove("board-drop-valid", "board-drop-invalid");
+    }
+  }
+
   function handleDragstart(event) {
     const draggable = event.target.closest("[data-draggable-task]");
     if (!draggable) return;
@@ -290,11 +326,28 @@ export function createDelegation(rootElement, actions) {
 
     event.dataTransfer?.setData("text/task-id", taskId);
     event.dataTransfer?.setData("text/plain", taskId);
+    draggedTaskStatus = actions.getTaskStatus(taskId);
   }
 
   function handleDragover(event) {
-    if (event.target.closest("[data-drop-status]")) {
+    const column = event.target.closest("[data-drop-status]");
+    if (!column) return;
+
+    const targetStatus = column.dataset.dropStatus;
+    if (draggedTaskStatus && isValidTransition(draggedTaskStatus, targetStatus)) {
       event.preventDefault();
+      column.classList.add("board-drop-valid");
+      column.classList.remove("board-drop-invalid");
+    } else if (draggedTaskStatus && targetStatus !== draggedTaskStatus) {
+      column.classList.add("board-drop-invalid");
+      column.classList.remove("board-drop-valid");
+    }
+  }
+
+  function handleDragleave(event) {
+    const column = event.target.closest("[data-drop-status]");
+    if (column && !column.contains(event.relatedTarget)) {
+      column.classList.remove("board-drop-valid", "board-drop-invalid");
     }
   }
 
@@ -309,7 +362,18 @@ export function createDelegation(rootElement, actions) {
       event.dataTransfer?.getData("text/task-id") ||
       event.dataTransfer?.getData("text/plain");
     const nextStatus = column.dataset.dropStatus;
+
+    if (draggedTaskStatus && !isValidTransition(draggedTaskStatus, nextStatus)) {
+      cleanupDragFeedback();
+      return;
+    }
+
     actions.dropTaskStatus(taskId, nextStatus);
+    cleanupDragFeedback();
+  }
+
+  function handleDragend() {
+    cleanupDragFeedback();
   }
 
   // ---------------------------------------------------------------------------
@@ -321,7 +385,9 @@ export function createDelegation(rootElement, actions) {
   rootElement.addEventListener("submit", handleSubmit);
   rootElement.addEventListener("dragstart", handleDragstart);
   rootElement.addEventListener("dragover", handleDragover);
+  rootElement.addEventListener("dragleave", handleDragleave);
   rootElement.addEventListener("drop", handleDrop);
+  rootElement.addEventListener("dragend", handleDragend);
   rootElement.addEventListener("keydown", handleDelegatedKeydown);
   window.addEventListener("keydown", handleKeydown);
 
@@ -335,7 +401,9 @@ export function createDelegation(rootElement, actions) {
     rootElement.removeEventListener("submit", handleSubmit);
     rootElement.removeEventListener("dragstart", handleDragstart);
     rootElement.removeEventListener("dragover", handleDragover);
+    rootElement.removeEventListener("dragleave", handleDragleave);
     rootElement.removeEventListener("drop", handleDrop);
+    rootElement.removeEventListener("dragend", handleDragend);
     rootElement.removeEventListener("keydown", handleDelegatedKeydown);
     window.removeEventListener("keydown", handleKeydown);
   };

package/src/board/assets/state/actions.js

@@ -1,5 +1,5 @@
 import { copyTextToClipboard } from "../runtime/clipboard.js";
-import { orderEpicsNewestFirst } from "./store.js";
+import { DEFAULT_STATUS_FILTER, orderEpicsNewestFirst } from "./store.js";
 
 function cloneSnapshot(snapshot) {
   if (typeof structuredClone === "function") {
@@ -404,6 +404,10 @@ export function createBoardActions(options) {
     removeDependency(sourceId, dependsOnId) {
       api.removeDependency(sourceId, dependsOnId, (snapshot) => removeDependencyInSnapshot(snapshot, sourceId, dependsOnId, normalizeSnapshot));
     },
+    getTaskStatus(taskId) {
+      const task = getTaskById(taskId);
+      return task?.status ?? null;
+    },
     dropTaskStatus(taskId, nextStatus) {
       const task = getTaskById(taskId);
       if (!task || !nextStatus || task.status === nextStatus) {
@@ -426,6 +430,28 @@ export function createBoardActions(options) {
         cascadeEpicStatusInSnapshot(snapshot, epicId, normalizedStatus, normalizeSnapshot),
       );
     },
+    toggleEpicStatusFilter(status) {
+      const current = store.epicStatusFilter || { ...DEFAULT_STATUS_FILTER };
+      store.epicStatusFilter = { ...current, [status]: !current[status] };
+      persist();
+      rerender();
+    },
+    toggleTaskStatusFilter(status) {
+      const current = store.taskStatusFilter || { ...DEFAULT_STATUS_FILTER };
+      store.taskStatusFilter = { ...current, [status]: !current[status] };
+      persist();
+      rerender();
+    },
+    resetEpicFilter() {
+      store.epicStatusFilter = { ...DEFAULT_STATUS_FILTER };
+      persist();
+      rerender();
+    },
+    resetTaskFilter() {
+      store.taskStatusFilter = { ...DEFAULT_STATUS_FILTER };
+      persist();
+      rerender();
+    },
     handleKeydown(event) {
       const boardState = getBoardState();
       const activeElement = document.activeElement;

package/src/board/assets/state/store.js

@@ -9,6 +9,18 @@ function normalizeSearch(value) {
 
 // --- Persistence helpers ---
 
+export const DEFAULT_STATUS_FILTER = { todo: true, blocked: true, in_progress: true, done: false };
+
+function readStatusFilter(raw) {
+  if (typeof raw !== "object" || raw === null) return { ...DEFAULT_STATUS_FILTER };
+  return {
+    todo: typeof raw.todo === "boolean" ? raw.todo : DEFAULT_STATUS_FILTER.todo,
+    blocked: typeof raw.blocked === "boolean" ? raw.blocked : DEFAULT_STATUS_FILTER.blocked,
+    in_progress: typeof raw.in_progress === "boolean" ? raw.in_progress : DEFAULT_STATUS_FILTER.in_progress,
+    done: typeof raw.done === "boolean" ? raw.done : DEFAULT_STATUS_FILTER.done,
+  };
+}
+
 export function readStoredState() {
   try {
     return JSON.parse(localStorage.getItem(STATE_STORAGE_KEY) || "{}");
@@ -77,13 +89,25 @@ export function orderEpicsNewestFirst(epics) {
 
 // --- Derived state selectors ---
 
+/** Recently-done epics stay visible for 24h even when the "done" filter is off. */
+const DONE_GRACE_PERIOD_MS = 86400000;
+
 const selectVisibleEpics = createSelector(
-  (s) => [s.snapshot?.epics, s.searchQuery],
-  (epics, searchQuery) => {
+  (s) => [s.snapshot?.epics, s.searchQuery, s.epicStatusFilter],
+  (epics, searchQuery, epicStatusFilter) => {
     if (!epics) return [];
+    const now = Date.now();
+    const filtered = epics.filter((epic) => {
+      if (epic.status === "done") {
+        if (!epicStatusFilter.done && (now - epic.updatedAt) > DONE_GRACE_PERIOD_MS) return false;
+      } else if (!epicStatusFilter[epic.status]) {
+        return false;
+      }
+      return true;
+    });
     const matchingEpics = searchQuery.length === 0
-      ? epics
-      : epics.filter((epic) => epic.searchText.includes(searchQuery));
+      ? filtered
+      : filtered.filter((epic) => epic.searchText.includes(searchQuery));
 
     return orderEpicsNewestFirst(matchingEpics);
   },
@@ -100,11 +124,12 @@ const selectTasksInScope = createSelector(
 );
 
 const selectVisibleTasks = createSelector(
-  (s) => [selectTasksInScope(s), s.searchQuery],
-  (tasksInScope, searchQuery) => {
+  (s) => [selectTasksInScope(s), s.searchQuery, s.taskStatusFilter],
+  (tasksInScope, searchQuery, taskStatusFilter) => {
+    const filtered = tasksInScope.filter((task) => taskStatusFilter[task.status]);
     return searchQuery.length === 0
-      ? tasksInScope
-      : tasksInScope.filter((task) => task.searchText.includes(searchQuery));
+      ? filtered
+      : filtered.filter((task) => task.searchText.includes(searchQuery));
   },
 );
 
@@ -287,6 +312,8 @@ export function createStore(initialSnapshot, options = {}) {
     notice: null,
     isMutating: false,
     notesPanelOpen: storedState.notesPanelOpen === true,
+    epicStatusFilter: readStatusFilter(storedState.epicStatusFilter),
+    taskStatusFilter: readStatusFilter(storedState.taskStatusFilter),
   };
 
   /** @type {Set<(state: object) => void>} */
@@ -306,6 +333,8 @@ export function createStore(initialSnapshot, options = {}) {
         view: state.view,
         selectedTaskId: state.selectedTaskId,
         notesPanelOpen: state.notesPanelOpen,
+        epicStatusFilter: state.epicStatusFilter,
+        taskStatusFilter: state.taskStatusFilter,
       });
   }
 

package/src/board/assets/state/utils.js

@@ -220,3 +220,45 @@ export function escapeHtml(value) {
     .replaceAll(">", ">")
     .replaceAll('"', """);
 }
+
+/**
+ * Valid status transitions mirroring the backend state machine (src/domain/types.ts).
+ * @type {Map<string, Set<string>>}
+ */
+export const VALID_TRANSITIONS = new Map([
+  ["todo", new Set(["in_progress", "blocked"])],
+  ["in_progress", new Set(["done", "blocked"])],
+  ["blocked", new Set(["in_progress", "todo"])],
+  ["done", new Set(["in_progress"])],
+]);
+
+/**
+ * Get the list of statuses a node can transition to from its current status.
+ * @param {string} currentStatus
+ * @returns {string[]}
+ */
+export function getValidTargets(currentStatus) {
+  const targets = VALID_TRANSITIONS.get(currentStatus);
+  return targets ? Array.from(targets) : [];
+}
+
+/**
+ * Check whether transitioning from one status to another is valid.
+ * @param {string} from
+ * @param {string} to
+ * @returns {boolean}
+ */
+export function isValidTransition(from, to) {
+  const targets = VALID_TRANSITIONS.get(from);
+  return targets ? targets.has(to) : false;
+}
+
+/**
+ * Return the current status plus all valid targets, useful for populating
+ * status select dropdowns.
+ * @param {string} currentStatus
+ * @returns {string[]}
+ */
+export function getSelectableStatuses(currentStatus) {
+  return [currentStatus, ...getValidTargets(currentStatus)];
+}

package/src/board/assets/styles/board.css

@@ -1929,3 +1929,71 @@ textarea,
 .\!px-2 { padding-inline: 0.5rem !important; }
 .\!text-xs { font-size: 0.75rem !important; line-height: 1rem !important; }
 .\!min-h-0 { min-height: 0 !important; }
+
+/* --- Drag-and-drop transition feedback --- */
+.board-drop-valid {
+  outline: 2px solid var(--board-accent);
+  outline-offset: -2px;
+  background: rgba(var(--board-accent-rgb, 99, 102, 241), 0.06);
+}
+
+.board-drop-invalid {
+  outline: 2px dashed rgba(239, 68, 68, 0.4);
+  outline-offset: -2px;
+  opacity: 0.6;
+  cursor: not-allowed;
+}
+
+/* --- Filter pills --- */
+.board-filter-bar {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 0.375rem;
+  margin-top: 0.75rem;
+}
+
+.board-filter-pill {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.25rem;
+  padding: 0.25rem 0.75rem;
+  border-radius: 9999px;
+  border: 1px solid var(--board-border);
+  background: var(--board-surface-2);
+  color: var(--board-text-muted);
+  font-size: 0.6875rem;
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.14em;
+  cursor: pointer;
+  transition: opacity 0.2s, border-color 0.2s, background 0.2s;
+  user-select: none;
+}
+
+.board-filter-pill:hover {
+  border-color: var(--board-border-strong);
+  background: rgba(255, 255, 255, 0.08);
+}
+
+.board-filter-pill:focus-visible {
+  outline: none;
+  box-shadow: 0 0 0 2px var(--board-border-strong);
+}
+
+.board-filter-pill--active {
+  opacity: 1;
+}
+
+.board-filter-pill--inactive {
+  opacity: 0.4;
+}
+
+.board-filter-pill--reset {
+  color: var(--board-accent);
+  border-color: var(--board-accent);
+}
+
+.board-filter-pill--reset:hover {
+  background: rgba(var(--board-accent-rgb, 99, 102, 241), 0.1);
+}

package/src/board/routes.ts

@@ -229,6 +229,7 @@ export function createBoardApiHandler(context: BoardRouteContext): (request: Req
           title: readOptionalString(body, "title"),
           description: readOptionalString(body, "description"),
           status: readOptionalString(body, "status"),
+          owner: readOptionalString(body, "owner"),
         });
         return buildMutationResponse(domain, { task });
       }
@@ -240,6 +241,7 @@ export function createBoardApiHandler(context: BoardRouteContext): (request: Req
           title: readOptionalString(body, "title"),
           description: readOptionalString(body, "description"),
           status: readOptionalString(body, "status"),
+          owner: readOptionalString(body, "owner"),
         });
         return buildMutationResponse(domain, { subtask });
       }

package/src/commands/epic.ts

@@ -18,6 +18,7 @@ import {
   suggestOptions,
 } from "./arg-parser";
 import { unexpectedFailureResult } from "./error-utils";
+import { buildTaskReadiness } from "./task-readiness";
 
 import { MutationService } from "../domain/mutation-service";
 import { TrackerDomain } from "../domain/tracker-domain";
@@ -44,7 +45,7 @@ function formatEpic(epic: EpicRecord): string {
 const VIEW_MODES = ["table", "compact", "tree", "detail"] as const;
 const LIST_VIEW_MODES = ["table", "compact"] as const;
 const DEFAULT_LIST_LIMIT = 10;
-const DEFAULT_OPEN_STATUSES = ["in_progress", "in-progress", "todo"] as const;
+const DEFAULT_OPEN_STATUSES = ["in_progress", "todo"] as const;
 const CREATE_OPTIONS = ["title", "t", "description", "d", "status", "s", "task", "subtask", "dep"] as const;
 const LIST_OPTIONS = ["status", "s", "limit", "l", "cursor", "all", "view"] as const;
 const SHOW_OPTIONS = ["view", "all"] as const;
@@ -115,7 +116,7 @@ function formatSearchHuman(matches: readonly SearchEntityMatch[], emptyMessage:
 }
 
 function getStatusPriority(status: string): number {
-  if (status === "in_progress" || status === "in-progress") {
+  if (status === "in_progress") {
     return 0;
   }
 
@@ -1391,6 +1392,76 @@ export async function runEpic(context: CliContext): Promise<CliResult> {
           data: { epic },
         });
       }
+      case "progress": {
+        const epicId: string = parsed.positional[1] ?? "";
+        if (epicId.length === 0) {
+          return failResult({
+            command: "epic.progress",
+            human: "Provide an epic id. Usage: trekoon epic progress <epic-id>",
+            data: { code: "invalid_input" },
+            error: {
+              code: "invalid_input",
+              message: "Missing epic id",
+            },
+          });
+        }
+
+        const epic = domain.getEpic(epicId);
+        if (!epic) {
+          return failResult({
+            command: "epic.progress",
+            human: `Epic not found: ${epicId}`,
+            data: { code: "not_found", id: epicId },
+            error: {
+              code: "not_found",
+              message: `Epic not found: ${epicId}`,
+            },
+          });
+        }
+
+        const allTasks = domain.listTasks(epicId);
+        let doneCount = 0;
+        let inProgressCount = 0;
+        let blockedCount = 0;
+        let todoCount = 0;
+        for (const t of allTasks) {
+          if (t.status === "done") doneCount += 1;
+          else if (t.status === "in_progress") inProgressCount += 1;
+          else if (t.status === "blocked") blockedCount += 1;
+          else if (t.status === "todo") todoCount += 1;
+        }
+
+        const readiness = buildTaskReadiness(domain, epicId);
+        const readyCount = readiness.summary.readyCount;
+        const nextCandidate = readiness.candidates[0] ?? null;
+
+        const nextTask = nextCandidate !== null
+          ? { id: nextCandidate.task.id, title: nextCandidate.task.title }
+          : null;
+
+        const total = allTasks.length;
+        let human = `Epic: ${epic.title}\n`;
+        human += `Total: ${total}, Done: ${doneCount}, In Progress: ${inProgressCount}, Blocked: ${blockedCount}, Todo: ${todoCount}, Ready: ${readyCount}`;
+        if (nextTask !== null) {
+          human += `\nNext candidate: ${nextTask.id} | ${nextTask.title}`;
+        }
+
+        return okResult({
+          command: "epic.progress",
+          human,
+          data: {
+            epicId: epic.id,
+            title: epic.title,
+            total,
+            doneCount,
+            inProgressCount,
+            blockedCount,
+            todoCount,
+            readyCount,
+            nextCandidate: nextTask,
+          },
+        });
+      }
       case "delete": {
         const epicId: string = parsed.positional[1] ?? "";
         mutations.deleteEpic(epicId);
@@ -1404,7 +1475,7 @@ export async function runEpic(context: CliContext): Promise<CliResult> {
       default:
         return failResult({
           command: "epic",
-          human: "Usage: trekoon epic <create|expand|list|show|search|replace|update|delete>",
+          human: "Usage: trekoon epic <create|expand|list|show|search|replace|update|delete|progress>",
           data: {
             args: context.args,
           },