@cleocode/core 2026.4.11 → 2026.4.12

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;

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

@@ -0,0 +1,97 @@
+/**
+ * Regression tests: CleoError fix hints on validation-layer throws.
+ *
+ * Each test invokes a validation function with invalid input and asserts that
+ * the thrown CleoError carries a non-empty `fix` string and, where applicable,
+ * a `details.field` identifying the failing field.
+ *
+ * @task T341
+ * @epic T335
+ */
+
+import { describe, expect, it } from 'vitest';
+import { CleoError } from '../../errors.js';
+import { sanitizeFilePath } from '../engine.js';
+import { loadManifestEntryByTaskId, loadManifestEntryFromFile } from '../protocols/_shared.js';
+
+// ---------------------------------------------------------------------------
+// Helper
+// ---------------------------------------------------------------------------
+
+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);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// sanitizeFilePath — engine.ts
+// ---------------------------------------------------------------------------
+
+describe('error-hints: sanitizeFilePath', () => {
+  it('empty path — fix mentions file path, field=path', () => {
+    assertErrorHints(() => sanitizeFilePath(''), {
+      detailsField: 'path',
+    });
+  });
+
+  it('path with shell metachar — fix mentions shell metacharacters, field=path', () => {
+    assertErrorHints(() => sanitizeFilePath('/tmp/file;rm -rf /'), {
+      fixIncludes: 'metacharacter',
+      detailsField: 'path',
+    });
+  });
+
+  it('path ending in backslash — fix mentions backslash, field=path', () => {
+    assertErrorHints(() => sanitizeFilePath('/tmp/file\\'), {
+      fixIncludes: 'backslash',
+      detailsField: 'path',
+    });
+  });
+
+  it('path with newline — fix mentions newline, field=path', () => {
+    assertErrorHints(() => sanitizeFilePath('/tmp/file\ninjected'), {
+      fixIncludes: 'newline',
+      detailsField: 'path',
+    });
+  });
+});
+
+// ---------------------------------------------------------------------------
+// loadManifestEntryByTaskId — protocols/_shared.ts
+// ---------------------------------------------------------------------------
+
+describe('error-hints: loadManifestEntryByTaskId', () => {
+  it('task not in manifest — fix mentions manifest entry, field=taskId', () => {
+    // This will always throw NOT_FOUND since no manifest exists in test env
+    assertErrorHints(() => loadManifestEntryByTaskId('T9999'), {
+      fixIncludes: 'manifest',
+      detailsField: 'taskId',
+    });
+  });
+});
+
+describe('error-hints: loadManifestEntryFromFile', () => {
+  it('manifest file not found — fix mentions manifest file path, field=manifestFile', () => {
+    assertErrorHints(() => loadManifestEntryFromFile('/nonexistent/path/manifest.json'), {
+      fixIncludes: 'manifest',
+      detailsField: 'manifestFile',
+    });
+  });
+});

package/src/validation/engine.ts

@@ -94,7 +94,10 @@ const SHELL_METACHARACTERS = new Set([
  */
 export function sanitizeFilePath(path: string): string {
   if (!path) {
-    throw new CleoError(ExitCode.VALIDATION_ERROR, 'Empty path provided');
+    throw new CleoError(ExitCode.VALIDATION_ERROR, 'Empty path provided', {
+      fix: 'Provide a non-empty file path',
+      details: { field: 'path' },
+    }); /* internal invariant — no user action */
   }
 
   for (const char of path) {
@@ -102,6 +105,10 @@ export function sanitizeFilePath(path: string): string {
       throw new CleoError(
         ExitCode.VALIDATION_ERROR,
         `Path contains shell metacharacters - potential injection attempt: ${path}`,
+        {
+          fix: 'Remove shell metacharacters from the file path',
+          details: { field: 'path', actual: path },
+        },
       );
     }
   }
@@ -110,6 +117,10 @@ export function sanitizeFilePath(path: string): string {
     throw new CleoError(
       ExitCode.VALIDATION_ERROR,
       'Path ends with backslash - potential injection attempt',
+      {
+        fix: 'Remove trailing backslash from the file path',
+        details: { field: 'path', actual: path },
+      },
     );
   }
 
@@ -117,6 +128,10 @@ export function sanitizeFilePath(path: string): string {
     throw new CleoError(
       ExitCode.VALIDATION_ERROR,
       'Path contains newline/carriage return - potential injection attempt',
+      {
+        fix: 'Remove newline characters from the file path',
+        details: { field: 'path', actual: path },
+      },
     );
   }
 

package/src/validation/param-utils.ts

@@ -56,7 +56,7 @@ interface ParamDef {
   items?: { type: ParamType };
   cli?: ParamCliDef;
   /** Schema config for dispatch adapter. */
-  mcp?: ParamSchemaDef;
+  dispatch?: ParamSchemaDef;
 }
 
 // ---------------------------------------------------------------------------
@@ -79,7 +79,7 @@ export interface JSONSchemaObject {
 }
 
 // ---------------------------------------------------------------------------
-// 1. buildMcpInputSchema (name kept for backward compat)
+// 1. buildDispatchInputSchema
 // ---------------------------------------------------------------------------
 
 /**
@@ -87,18 +87,18 @@ export interface JSONSchemaObject {
  *
  * Algorithm:
  *  1. Iterate `def.params`
- *  2. Skip params where schema `mcp.hidden === true`
+ *  2. Skip params where schema `dispatch.hidden === true`
  *  3. Map ParamType → JSON Schema type
  *  4. Collect names where `required === true` into `required[]`
  *  5. Return { type: 'object', properties, required }
  */
-export function buildMcpInputSchema(def: OperationDef): JSONSchemaObject {
+export function buildDispatchInputSchema(def: OperationDef): JSONSchemaObject {
   const properties: Record<string, JsonSchemaProperty> = {};
   const required: string[] = [];
 
   for (const param of def.params ?? []) {
     // Skip CLI-only params from dispatch schema
-    if (param.mcp?.hidden === true) continue;
+    if (param.dispatch?.hidden === true) continue;
 
     const prop: JsonSchemaProperty = {
       type: paramTypeToJsonSchema(param.type),
@@ -109,8 +109,8 @@ export function buildMcpInputSchema(def: OperationDef): JSONSchemaObject {
       prop.items = { type: 'string' };
     }
 
-    if (param.mcp?.enum) {
-      prop.enum = param.mcp.enum;
+    if (param.dispatch?.enum) {
+      prop.enum = param.dispatch.enum;
     }
 
     properties[param.name] = prop;
@@ -123,6 +123,9 @@ export function buildMcpInputSchema(def: OperationDef): JSONSchemaObject {
   return { type: 'object', properties, required };
 }
 
+/** @deprecated Use {@link buildDispatchInputSchema} instead. */
+export const buildMcpInputSchema = buildDispatchInputSchema;
+
 function paramTypeToJsonSchema(t: ParamDef['type']): JsonSchemaType {
   switch (t) {
     case 'string':

package/src/validation/protocols/_shared.ts

@@ -46,7 +46,10 @@ export function loadManifestEntryByTaskId(taskId: string): ManifestEntryInput {
   const manifestPath = getManifestPath();
   const entry = findManifestEntry(taskId, manifestPath);
   if (!entry) {
-    throw new CleoError(ExitCode.NOT_FOUND, `No manifest entry found for task ${taskId}`);
+    throw new CleoError(ExitCode.NOT_FOUND, `No manifest entry found for task ${taskId}`, {
+      fix: `Ensure the agent wrote a manifest entry for ${taskId} before validation`,
+      details: { field: 'taskId', actual: taskId },
+    });
   }
   return JSON.parse(entry) as ManifestEntryInput;
 }
@@ -59,7 +62,10 @@ export function loadManifestEntryByTaskId(taskId: string): ManifestEntryInput {
  */
 export function loadManifestEntryFromFile(manifestFile: string): ManifestEntryInput {
   if (!existsSync(manifestFile)) {
-    throw new CleoError(ExitCode.NOT_FOUND, `Manifest file not found: ${manifestFile}`);
+    throw new CleoError(ExitCode.NOT_FOUND, `Manifest file not found: ${manifestFile}`, {
+      fix: `Ensure the manifest file exists at: ${manifestFile}`,
+      details: { field: 'manifestFile', actual: manifestFile },
+    });
   }
   return JSON.parse(readFileSync(manifestFile, 'utf-8')) as ManifestEntryInput;
 }
@@ -78,11 +84,13 @@ export function throwIfStrictFailed(
 ): void {
   if (!opts.strict || result.valid) return;
   const code = PROTOCOL_EXIT_CODES[protocol];
+  const errorViolations = result.violations.filter((v) => v.severity === 'error');
   throw new CleoError(
     code,
-    `${protocol} protocol violations for ${taskId}: ${result.violations
-      .filter((v) => v.severity === 'error')
-      .map((v) => v.message)
-      .join('; ')}`,
+    `${protocol} protocol violations for ${taskId}: ${errorViolations.map((v) => v.message).join('; ')}`,
+    {
+      fix: `Review ${protocol} protocol requirements and correct the listed violations`,
+      details: { field: 'protocol', actual: protocol },
+    },
   );
 }