@cleocode/core 2026.4.9 → 2026.4.12

package/src/tasks/__tests__/error-hints.test.ts

@@ -0,0 +1,256 @@
+/**
+ * Regression tests: CleoError fix hints on task-layer throws.
+ *
+ * Each test invokes a core function with invalid input and asserts that
+ * the thrown CleoError carries:
+ *   - options.fix   — a non-empty string with a concrete recovery action
+ *   - options.details.field — the specific field that failed
+ *
+ * @task T341
+ * @epic T335
+ */
+
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { CleoError } from '../../errors.js';
+import { createTestDb, type TestDbEnv } from '../../store/__tests__/test-db-helper.js';
+import { resetDbState } from '../../store/sqlite.js';
+import {
+  addTask,
+  validateDepends,
+  validateLabels,
+  validatePhaseFormat,
+  validateSize,
+  validateStatus,
+  validateTaskType,
+  validateTitle,
+} from '../add.js';
+import { findTasks } from '../find.js';
+import { showLabelTasks } from '../labels.js';
+import { showTask } from '../show.js';
+
+// ---------------------------------------------------------------------------
+// Helper: assert a CleoError has fix + details
+// ---------------------------------------------------------------------------
+
+function assertErrorHints(
+  fn: () => unknown,
+  opts: { fixIncludes?: string; detailsField?: string },
+): void {
+  let caught: unknown;
+  try {
+    fn();
+  } catch (err) {
+    caught = err;
+  }
+  expect(caught).toBeInstanceOf(CleoError);
+  const e = caught as CleoError;
+  expect(e.fix).toBeTruthy();
+  if (opts.fixIncludes) {
+    expect(e.fix).toContain(opts.fixIncludes);
+  }
+  if (opts.detailsField) {
+    expect(e.details).toBeDefined();
+    expect(e.details!.field).toBe(opts.detailsField);
+  }
+}
+
+async function assertAsyncErrorHints(
+  fn: () => Promise<unknown>,
+  opts: { fixIncludes?: string; detailsField?: string },
+): Promise<void> {
+  let caught: unknown;
+  try {
+    await fn();
+  } catch (err) {
+    caught = err;
+  }
+  expect(caught).toBeInstanceOf(CleoError);
+  const e = caught as CleoError;
+  expect(e.fix).toBeTruthy();
+  if (opts.fixIncludes) {
+    expect(e.fix).toContain(opts.fixIncludes);
+  }
+  if (opts.detailsField) {
+    expect(e.details).toBeDefined();
+    expect(e.details!.field).toBe(opts.detailsField);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('error-hints: validateTitle', () => {
+  it('empty title — fix mentions cleo add, field=title', () => {
+    assertErrorHints(() => validateTitle(''), {
+      fixIncludes: 'cleo add',
+      detailsField: 'title',
+    });
+  });
+
+  it('whitespace-only title — fix mentions cleo add, field=title', () => {
+    assertErrorHints(() => validateTitle('   '), {
+      fixIncludes: 'cleo add',
+      detailsField: 'title',
+    });
+  });
+
+  it('title too long — fix mentions 200, field=title, details has expected/actual', () => {
+    let caught: unknown;
+    try {
+      validateTitle('a'.repeat(201));
+    } catch (err) {
+      caught = err;
+    }
+    expect(caught).toBeInstanceOf(CleoError);
+    const e = caught as CleoError;
+    expect(e.fix).toContain('200');
+    expect(e.details).toBeDefined();
+    expect(e.details!.field).toBe('title');
+    expect(e.details!.expected).toBe(200);
+    expect(e.details!.actual).toBe(201);
+  });
+});
+
+describe('error-hints: validateStatus', () => {
+  it('invalid status — fix mentions --status, field=status', () => {
+    assertErrorHints(() => validateStatus('broken'), {
+      fixIncludes: '--status',
+      detailsField: 'status',
+    });
+  });
+});
+
+describe('error-hints: validateSize', () => {
+  it('invalid size — fix mentions --size, field=size', () => {
+    assertErrorHints(() => validateSize('giant'), {
+      fixIncludes: '--size',
+      detailsField: 'size',
+    });
+  });
+});
+
+describe('error-hints: validateTaskType', () => {
+  it('invalid type — fix mentions --type, field=type', () => {
+    assertErrorHints(() => validateTaskType('mega-task'), {
+      fixIncludes: '--type',
+      detailsField: 'type',
+    });
+  });
+});
+
+describe('error-hints: validateLabels', () => {
+  it('invalid label — fix mentions pattern, field=labels', () => {
+    assertErrorHints(() => validateLabels(['UPPERCASE']), {
+      fixIncludes: '^[a-z]',
+      detailsField: 'labels',
+    });
+  });
+});
+
+describe('error-hints: validatePhaseFormat', () => {
+  it('invalid phase — fix mentions pattern, field=phase', () => {
+    assertErrorHints(() => validatePhaseFormat('UPPER_CASE'), {
+      fixIncludes: '^[a-z]',
+      detailsField: 'phase',
+    });
+  });
+});
+
+describe('error-hints: validateDepends (sync helper)', () => {
+  it('invalid dep ID format — fix mentions T### format, field=depends', () => {
+    assertErrorHints(() => validateDepends(['invalid'], []), {
+      fixIncludes: 'T###',
+      detailsField: 'depends',
+    });
+  });
+
+  it('dep not found — fix mentions cleo find, field=depends', () => {
+    assertErrorHints(() => validateDepends(['T999'], []), {
+      fixIncludes: 'find',
+      detailsField: 'depends',
+    });
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Anti-hallucination throw (add.ts line ~436)
+// ---------------------------------------------------------------------------
+
+describe('error-hints: anti-hallucination (title === description)', () => {
+  let env: TestDbEnv;
+
+  beforeEach(async () => {
+    resetDbState();
+    env = await createTestDb();
+  });
+
+  afterEach(async () => {
+    await env.cleanup();
+  });
+
+  it('throws with fix mentioning --desc, field=description', async () => {
+    await assertAsyncErrorHints(
+      () =>
+        addTask(
+          {
+            title: 'same text',
+            description: 'same text',
+          },
+          env.tempDir,
+          env.accessor,
+        ),
+      { fixIncludes: '--desc', detailsField: 'description' },
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// findTasks — query required
+// ---------------------------------------------------------------------------
+
+describe('error-hints: findTasks (query required)', () => {
+  it('missing query — fix mentions cleo find, field=query', async () => {
+    await assertAsyncErrorHints(() => findTasks({}), {
+      fixIncludes: 'cleo find',
+      detailsField: 'query',
+    });
+  });
+});
+
+// ---------------------------------------------------------------------------
+// showTask — task ID required
+// ---------------------------------------------------------------------------
+
+describe('error-hints: showTask (id required)', () => {
+  it('empty id — fix mentions cleo show, field=taskId', async () => {
+    await assertAsyncErrorHints(() => showTask(''), {
+      fixIncludes: 'cleo show',
+      detailsField: 'taskId',
+    });
+  });
+});
+
+// ---------------------------------------------------------------------------
+// showLabelTasks — no tasks with label
+// ---------------------------------------------------------------------------
+
+describe('error-hints: showLabelTasks (label not found)', () => {
+  let env: TestDbEnv;
+
+  beforeEach(async () => {
+    resetDbState();
+    env = await createTestDb();
+  });
+
+  afterEach(async () => {
+    await env.cleanup();
+  });
+
+  it('no tasks with label — fix mentions cleo labels, field=label', async () => {
+    await assertAsyncErrorHints(
+      () => showLabelTasks('nonexistent-label', env.tempDir, env.accessor),
+      { fixIncludes: 'cleo labels', detailsField: 'label' },
+    );
+  });
+});

package/src/tasks/add.ts

@@ -39,7 +39,7 @@ import { resolveDefaultPipelineStage, validatePipelineStage } from './pipeline-s
  */
 export interface AddTaskOptions {
   title: string;
-  description: string;
+  description?: string;
   status?: TaskStatus;
   priority?: TaskPriority;
   type?: TaskType;
@@ -93,10 +93,16 @@ export function buildDefaultVerification(initializedAt: string): TaskVerificatio
  */
 export function validateTitle(title: string): void {
   if (!title || title.trim().length === 0) {
-    throw new CleoError(ExitCode.INVALID_INPUT, 'Task title is required');
+    throw new CleoError(ExitCode.INVALID_INPUT, 'Task title is required', {
+      fix: 'Provide a title: cleo add "<title>"',
+      details: { field: 'title' },
+    });
   }
   if (title.length > 200) {
-    throw new CleoError(ExitCode.VALIDATION_ERROR, 'Task title must be 200 characters or less');
+    throw new CleoError(ExitCode.VALIDATION_ERROR, 'Task title must be 200 characters or less', {
+      fix: 'Shorten title to 200 characters or fewer',
+      details: { field: 'title', expected: 200, actual: title.length },
+    });
   }
 }
 
@@ -109,6 +115,10 @@ export function validateStatus(status: string): asserts status is TaskStatus {
     throw new CleoError(
       ExitCode.VALIDATION_ERROR,
       `Invalid status: ${status} (must be ${TASK_STATUSES.join('|')})`,
+      {
+        fix: `cleo add ... --status <${TASK_STATUSES.join('|')}>`,
+        details: { field: 'status', expected: TASK_STATUSES, actual: status },
+      },
     );
   }
 }
@@ -152,6 +162,10 @@ export function normalizePriority(priority: string | number): TaskPriority {
       throw new CleoError(
         ExitCode.VALIDATION_ERROR,
         `Invalid numeric priority: ${priority} (must be 1-9)`,
+        {
+          fix: `Use a numeric priority 1-9 or one of: ${VALID_PRIORITIES.join('|')}`,
+          details: { field: 'priority', expected: '1-9', actual: priority },
+        },
       );
     }
     return mapped;
@@ -172,6 +186,10 @@ export function normalizePriority(priority: string | number): TaskPriority {
   throw new CleoError(
     ExitCode.VALIDATION_ERROR,
     `Invalid priority: ${priority} (must be ${VALID_PRIORITIES.join('|')} or numeric 1-9)`,
+    {
+      fix: `cleo add ... --priority <${VALID_PRIORITIES.join('|')}>`,
+      details: { field: 'priority', expected: VALID_PRIORITIES, actual: priority },
+    },
   );
 }
 
@@ -194,6 +212,10 @@ export function validateTaskType(type: string): asserts type is TaskType {
     throw new CleoError(
       ExitCode.VALIDATION_ERROR,
       `Invalid task type: ${type} (must be ${valid.join('|')})`,
+      {
+        fix: `cleo add ... --type <${valid.join('|')}>`,
+        details: { field: 'type', expected: valid, actual: type },
+      },
     );
   }
 }
@@ -208,6 +230,10 @@ export function validateSize(size: string): asserts size is TaskSize {
     throw new CleoError(
       ExitCode.VALIDATION_ERROR,
       `Invalid size: ${size} (must be ${valid.join('|')})`,
+      {
+        fix: `cleo add ... --size <${valid.join('|')}>`,
+        details: { field: 'size', expected: valid, actual: size },
+      },
     );
   }
 }
@@ -223,6 +249,10 @@ export function validateLabels(labels: string[]): void {
       throw new CleoError(
         ExitCode.VALIDATION_ERROR,
         `Invalid label format: '${trimmed}' (must be lowercase alphanumeric with hyphens/periods)`,
+        {
+          fix: `Labels must match pattern ^[a-z][a-z0-9.-]*$ (e.g. my-label, v1.0)`,
+          details: { field: 'labels', expected: '^[a-z][a-z0-9.-]*$', actual: trimmed },
+        },
       );
     }
   }
@@ -237,6 +267,10 @@ export function validatePhaseFormat(phase: string): void {
     throw new CleoError(
       ExitCode.VALIDATION_ERROR,
       `Invalid phase format: ${phase} (must be lowercase alphanumeric with hyphens)`,
+      {
+        fix: `Phase slugs must match pattern ^[a-z][a-z0-9-]*$ (e.g. dev-phase-1)`,
+        details: { field: 'phase', expected: '^[a-z][a-z0-9-]*$', actual: phase },
+      },
     );
   }
 }
@@ -253,10 +287,17 @@ export function validateDepends(depends: string[], tasks: Task[]): void {
       throw new CleoError(
         ExitCode.VALIDATION_ERROR,
         `Invalid dependency ID format: '${trimmed}' (must be T### format)`,
+        {
+          fix: 'Dependency IDs must match T### format (e.g. T123, T4567)',
+          details: { field: 'depends', expected: 'T###', actual: trimmed },
+        },
       );
     }
     if (!existingIds.has(trimmed)) {
-      throw new CleoError(ExitCode.NOT_FOUND, `Dependency task not found: ${trimmed}`);
+      throw new CleoError(ExitCode.NOT_FOUND, `Dependency task not found: ${trimmed}`, {
+        fix: `cleo find "${trimmed}"`,
+        details: { field: 'depends', actual: trimmed },
+      });
     }
   }
 }
@@ -294,6 +335,10 @@ export function validateParent(
     throw new CleoError(
       ExitCode.DEPTH_EXCEEDED,
       `Cannot add child to ${parentId}: max hierarchy depth (${maxDepth}) would be exceeded`,
+      {
+        fix: 'Reparent this task under a higher-level epic',
+        details: { field: 'parentId', expected: `depth < ${maxDepth}`, actual: depth },
+      },
     );
   }
 
@@ -436,6 +481,10 @@ export async function addTask(
     throw new CleoError(
       ExitCode.VALIDATION_ERROR,
       'Title and description must be different (anti-hallucination rule)',
+      {
+        fix: 'Provide --desc with a description different from the title',
+        details: { field: 'description' },
+      },
     );
   }
 
@@ -508,11 +557,18 @@ export async function addTask(
         throw new CleoError(
           ExitCode.VALIDATION_ERROR,
           `Invalid dependency ID format: '${trimmed}' (must be T### format)`,
+          {
+            fix: 'Dependency IDs must match T### format (e.g. T123, T4567)',
+            details: { field: 'depends', expected: 'T###', actual: trimmed },
+          },
         );
       }
       const exists = await dataAccessor.taskExists(trimmed);
       if (!exists) {
-        throw new CleoError(ExitCode.NOT_FOUND, `Dependency task not found: ${trimmed}`);
+        throw new CleoError(ExitCode.NOT_FOUND, `Dependency task not found: ${trimmed}`, {
+          fix: `cleo find "${trimmed}"`,
+          details: { field: 'depends', actual: trimmed },
+        });
       }
     }
   }
@@ -532,6 +588,10 @@ export async function addTask(
         throw new CleoError(
           ExitCode.NOT_FOUND,
           `Phase '${phase}' not found. Valid phases: ${validPhases || 'none'}. Use --add-phase to create new.`,
+          {
+            fix: `cleo add ... --add-phase to create '${phase}', or use one of: ${validPhases || 'none'}`,
+            details: { field: 'phase', expected: Object.keys(phases), actual: phase },
+          },
         );
       }
       // Create phase
@@ -554,12 +614,18 @@ export async function addTask(
   // Parent hierarchy validation using targeted queries
   if (parentId) {
     if (!/^T\d{3,}$/.test(parentId)) {
-      throw new CleoError(ExitCode.INVALID_INPUT, `Invalid parent ID format: ${parentId}`);
+      throw new CleoError(ExitCode.INVALID_INPUT, `Invalid parent ID format: ${parentId}`, {
+        fix: 'Parent IDs must match T### format (e.g. T123)',
+        details: { field: 'parentId', expected: 'T###', actual: parentId },
+      });
     }
     // Validate parent exists
     const parentTask = await dataAccessor.loadSingleTask(parentId);
     if (!parentTask) {
-      throw new CleoError(ExitCode.PARENT_NOT_FOUND, `Parent task ${parentId} not found`);
+      throw new CleoError(ExitCode.PARENT_NOT_FOUND, `Parent task ${parentId} not found`, {
+        fix: `Use 'cleo find "${parentId}"' to search or create as standalone task`,
+        details: { field: 'parentId', actual: parentId },
+      });
     }
 
     // Read hierarchy limits from config via policy module
@@ -573,6 +639,14 @@ export async function addTask(
       throw new CleoError(
         ExitCode.DEPTH_EXCEEDED,
         `Maximum nesting depth ${policy.maxDepth} would be exceeded`,
+        {
+          fix: 'Reparent this task under a higher-level epic',
+          details: {
+            field: 'parentId',
+            expected: `depth < ${policy.maxDepth}`,
+            actual: parentDepth + 1,
+          },
+        },
       );
     }
 
@@ -586,6 +660,14 @@ export async function addTask(
         throw new CleoError(
           ExitCode.SIBLING_LIMIT,
           `Parent ${parentId} already has ${counted} children (limit: ${policy.maxSiblings})`,
+          {
+            fix: 'Create as standalone task or increase hierarchy.maxSiblings in config',
+            details: {
+              field: 'parentId',
+              expected: `<= ${policy.maxSiblings} siblings`,
+              actual: counted,
+            },
+          },
         );
       }
     }
@@ -596,6 +678,14 @@ export async function addTask(
       throw new CleoError(
         ExitCode.SIBLING_LIMIT,
         `Parent ${parentId} already has ${activeCount} active children (maxActiveSiblings=${policy.maxActiveSiblings})`,
+        {
+          fix: 'Complete or cancel an active sibling before adding a new task here',
+          details: {
+            field: 'parentId',
+            expected: `<= ${policy.maxActiveSiblings} active siblings`,
+            actual: activeCount,
+          },
+        },
       );
     }
 
@@ -676,7 +766,7 @@ export async function addTask(
     const previewTask: Task = {
       id: 'T???',
       title: options.title,
-      description: options.description,
+      description: options.description ?? '',
       status,
       priority,
       type: taskType,
@@ -767,7 +857,7 @@ export async function addTask(
   const task: Task = {
     id: taskId,
     title: options.title,
-    description: options.description,
+    description: options.description ?? '',
     status,
     priority,
     type: taskType,

package/src/tasks/complete.ts

@@ -115,7 +115,10 @@ export async function completeTask(
 
   // Already done
   if (task.status === 'done') {
-    throw new CleoError(ExitCode.TASK_COMPLETED, `Task ${options.taskId} is already completed`);
+    throw new CleoError(ExitCode.TASK_COMPLETED, `Task ${options.taskId} is already completed`, {
+      fix: `To reopen, run cleo update ${options.taskId} --status active`,
+      details: { field: 'status', expected: 'not done', actual: 'done' },
+    });
   }
 
   // Check if task has incomplete dependencies

package/src/tasks/find.ts

@@ -100,7 +100,10 @@ export async function findTasks(
   accessor?: DataAccessor,
 ): Promise<FindTasksResult> {
   if (!options.query && !options.id) {
-    throw new CleoError(ExitCode.INVALID_INPUT, 'Search query or --id is required');
+    throw new CleoError(ExitCode.INVALID_INPUT, 'Search query or --id is required', {
+      fix: 'cleo find "<query>"',
+      details: { field: 'query' },
+    });
   }
 
   const acc = accessor ?? (await getAccessor(cwd));

package/src/tasks/labels.ts

@@ -45,7 +45,10 @@ export async function showLabelTasks(
   const { tasks } = await acc.queryTasks({ label });
 
   if (tasks.length === 0) {
-    throw new CleoError(ExitCode.NOT_FOUND, `No tasks found with label '${label}'`);
+    throw new CleoError(ExitCode.NOT_FOUND, `No tasks found with label '${label}'`, {
+      fix: 'cleo labels list to see available labels',
+      details: { field: 'label', actual: label },
+    });
   }
 
   return {

package/src/tasks/relates.ts

@@ -20,7 +20,10 @@ export async function suggestRelated(
   const { tasks: allTasks } = await acc.queryTasks({});
   const task = allTasks.find((t) => t.id === taskId);
   if (!task) {
-    throw new CleoError(ExitCode.NOT_FOUND, `Task ${taskId} not found`);
+    throw new CleoError(ExitCode.NOT_FOUND, `Task ${taskId} not found`, {
+      fix: `cleo find "${taskId}"`,
+      details: { field: 'taskId', actual: taskId },
+    });
   }
 
   const suggestions: Array<Pick<TaskRef, 'id' | 'title'> & { score: number; reason: string }> = [];
@@ -80,12 +83,18 @@ export async function addRelation(
 
   const fromExists = await acc.taskExists(from);
   if (!fromExists) {
-    throw new CleoError(ExitCode.NOT_FOUND, `Task ${from} not found`);
+    throw new CleoError(ExitCode.NOT_FOUND, `Task ${from} not found`, {
+      fix: `cleo find "${from}"`,
+      details: { field: 'from', actual: from },
+    });
   }
 
   const toExists = await acc.taskExists(to);
   if (!toExists) {
-    throw new CleoError(ExitCode.NOT_FOUND, `Task ${to} not found`);
+    throw new CleoError(ExitCode.NOT_FOUND, `Task ${to} not found`, {
+      fix: `cleo find "${to}"`,
+      details: { field: 'to', actual: to },
+    });
   }
 
   // Persist to task_relations table via accessor (T5168 fix)
@@ -112,7 +121,10 @@ export async function listRelations(
   const acc = accessor ?? (await getAccessor(cwd));
   const task = await acc.loadSingleTask(taskId);
   if (!task) {
-    throw new CleoError(ExitCode.NOT_FOUND, `Task ${taskId} not found`);
+    throw new CleoError(ExitCode.NOT_FOUND, `Task ${taskId} not found`, {
+      fix: `cleo find "${taskId}"`,
+      details: { field: 'taskId', actual: taskId },
+    });
   }
 
   // task.relates is populated from task_relations table by loadSingleTask

package/src/tasks/show.ts

@@ -35,7 +35,10 @@ export async function showTask(
   accessor?: DataAccessor,
 ): Promise<TaskDetail> {
   if (!taskId) {
-    throw new CleoError(ExitCode.INVALID_INPUT, 'Task ID is required');
+    throw new CleoError(ExitCode.INVALID_INPUT, 'Task ID is required', {
+      fix: 'cleo show T###',
+      details: { field: 'taskId' },
+    });
   }
 
   const acc = accessor ?? (await getAccessor(cwd));

package/src/tasks/update.ts

@@ -153,7 +153,14 @@ export async function updateTask(
     const { validateStatusTransition } = await import('../validation/validation-rules.js');
     const transitionViolations = validateStatusTransition(task.status, options.status);
     if (transitionViolations.length > 0) {
-      throw new CleoError(ExitCode.VALIDATION_ERROR, transitionViolations[0].message);
+      throw new CleoError(ExitCode.VALIDATION_ERROR, transitionViolations[0].message, {
+        fix: `Valid transitions from '${task.status}': see cleo update --help`,
+        details: {
+          field: transitionViolations[0].field ?? 'status',
+          expected: `valid transition from ${task.status}`,
+          actual: options.status,
+        },
+      });
     }
 
     const oldStatus = task.status;
@@ -319,12 +326,19 @@ export async function updateTask(
         // Validate target parent exists
         const newParent = await acc.loadSingleTask(newParentId);
         if (!newParent) {
-          throw new CleoError(ExitCode.PARENT_NOT_FOUND, `Parent task ${newParentId} not found`);
+          throw new CleoError(ExitCode.PARENT_NOT_FOUND, `Parent task ${newParentId} not found`, {
+            fix: `Use 'cleo find "${newParentId}"' to search or remove --parent flag`,
+            details: { field: 'parentId', actual: newParentId },
+          });
         }
         if (newParent.type === 'subtask') {
           throw new CleoError(
             ExitCode.INVALID_PARENT_TYPE,
             `Cannot parent under subtask '${newParentId}'`,
+            {
+              fix: `Choose an epic or task as parent instead of subtask '${newParentId}'`,
+              details: { field: 'parentId', expected: 'epic or task', actual: 'subtask' },
+            },
           );
         }
 
@@ -334,6 +348,10 @@ export async function updateTask(
           throw new CleoError(
             ExitCode.CIRCULAR_REFERENCE,
             `Moving '${options.taskId}' under '${newParentId}' would create a circular reference`,
+            {
+              fix: `Choose a parent that is not a descendant of ${options.taskId}`,
+              details: { field: 'parentId', actual: newParentId },
+            },
           );
         }
 
@@ -346,6 +364,14 @@ export async function updateTask(
           throw new CleoError(
             ExitCode.DEPTH_EXCEEDED,
             `Maximum nesting depth ${policy.maxDepth} would be exceeded`,
+            {
+              fix: 'Choose a parent at a shallower level in the hierarchy',
+              details: {
+                field: 'parentId',
+                expected: `depth < ${policy.maxDepth}`,
+                actual: parentDepth + 1,
+              },
+            },
           );
         }
 
@@ -362,7 +388,10 @@ export async function updateTask(
   }
 
   if (changes.length === 0) {
-    throw new CleoError(ExitCode.NO_CHANGE, 'No changes specified');
+    throw new CleoError(ExitCode.NO_CHANGE, 'No changes specified', {
+      fix: `Provide at least one field to update (e.g. cleo update ${options.taskId} --status active)`,
+      details: { field: 'options' },
+    });
   }
 
   task.updatedAt = now;