feat(T-MVI-06): add _next progressive disclosure directives to handlers

All high-volume domain handlers now return _next directives enabling
agents to drill deeper with minimal upfront data.

New: packages/core/src/mvi-helpers.ts
  - taskShowNext(id) — full, children, deps
  - taskListItemNext(id) — show
  - sessionListItemNext(id) — show, serialize
  - sessionStartNext() — current, stop
  - memoryFindHitNext(id) — fetch
  - NextDirectives type exported from barrel

Modified handlers:
  - tasks/show.ts: TaskDetail includes _next
  - tasks/list.ts: CompactTask includes _next
  - tasks/find.ts: FindResult includes _next
  - sessions/index.ts: start + list attach _next
  - sessions/find.ts: MinimalSessionRecord includes _next
  - memory/brain-retrieval.ts: BrainCompactHit includes _next

All changes additive — no query logic modified, no breaking changes.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: kryptobaseddev

packages/core/src/index.ts

@@ -289,6 +289,15 @@ export {
   runAllMigrations,
   runMigration,
 } from './migration/index.js';
+// MVI progressive disclosure helpers
+export type { NextDirectives } from './mvi-helpers.js';
+export {
+  memoryFindHitNext,
+  sessionListItemNext,
+  sessionStartNext,
+  taskListItemNext,
+  taskShowNext,
+} from './mvi-helpers.js';
 // Reconciliation
 export { reconcile } from './reconciliation/index.js';
 // Sessions

packages/core/src/memory/brain-retrieval.ts

@@ -17,6 +17,8 @@
  */
 
 import { createHash } from 'node:crypto';
+import type { NextDirectives } from '../mvi-helpers.js';
+import { memoryFindHitNext } from '../mvi-helpers.js';
 import { getBrainAccessor } from '../store/brain-accessor.js';
 import type {
   BRAIN_OBSERVATION_SOURCE_TYPES,
@@ -43,6 +45,8 @@ export interface BrainCompactHit {
   title: string;
   date: string;
   relevance?: number;
+  /** Progressive disclosure directives for follow-up operations. */
+  _next?: NextDirectives;
 }
 
 /** Parameters for searchBrainCompact. */
@@ -208,6 +212,11 @@ export async function searchBrainCompact(
     results = results.filter((r) => r.date <= dateEnd);
   }
 
+  // Enrich each hit with _next progressive disclosure directives
+  for (const hit of results) {
+    hit._next = memoryFindHitNext(hit.id);
+  }
+
   return {
     results,
     total: results.length,

packages/core/src/mvi-helpers.ts

@@ -0,0 +1,81 @@
+/**
+ * MVI _next directive helpers for progressive disclosure.
+ *
+ * When CLEO returns results in minimal MVI mode, `_next` provides a map of
+ * available follow-up operations the agent can take. This enables progressive
+ * disclosure: agents get lean results and can drill deeper only when needed.
+ *
+ * @example
+ * ```json
+ * {"id": "T042", "title": "Fix auth", "status": "active",
+ *   "_next": {"full": "cleo show T042", "children": "cleo find --parent T042"}}
+ * ```
+ *
+ * @task T-MVI-06
+ */
+
+/** Map of follow-up operation names to CLI command strings. */
+export type NextDirectives = Record<string, string>;
+
+/**
+ * Build `_next` directives for a full task detail result (tasks.show).
+ *
+ * @param taskId - The task ID to generate directives for
+ * @returns A map of available follow-up operations
+ */
+export function taskShowNext(taskId: string): NextDirectives {
+  return {
+    full: `cleo show ${taskId} --mvi full`,
+    children: `cleo find --parent ${taskId}`,
+    deps: `cleo deps ${taskId}`,
+  };
+}
+
+/**
+ * Build `_next` directives for a task in a list or find result.
+ *
+ * @param taskId - The task ID to generate directives for
+ * @returns A map of available follow-up operations
+ */
+export function taskListItemNext(taskId: string): NextDirectives {
+  return {
+    show: `cleo show ${taskId}`,
+  };
+}
+
+/**
+ * Build `_next` directives for a session in a list or find result.
+ *
+ * @param sessionId - The session ID to generate directives for
+ * @returns A map of available follow-up operations
+ */
+export function sessionListItemNext(sessionId: string): NextDirectives {
+  return {
+    show: `cleo session show ${sessionId}`,
+    serialize: `cleo session serialize ${sessionId}`,
+  };
+}
+
+/**
+ * Build `_next` directives for a session start result.
+ *
+ * @returns A map of available follow-up operations after starting a session
+ */
+export function sessionStartNext(): NextDirectives {
+  return {
+    current: 'cleo current',
+    stop: 'cleo session end',
+  };
+}
+
+/**
+ * Build `_next` directives for a memory search (find) hit.
+ *
+ * @param entryId - The brain entry ID to generate directives for
+ * @returns A map of available follow-up operations
+ */
+export function memoryFindHitNext(entryId: string): NextDirectives {
+  return {
+    fetch: `cleo memory fetch ${entryId}`,
+  };
+}

packages/core/src/sessions/find.ts

@@ -9,6 +9,8 @@
  */
 
 import type { Session, SessionScope } from '@cleocode/contracts';
+import type { NextDirectives } from '../mvi-helpers.js';
+import { sessionListItemNext } from '../mvi-helpers.js';
 import type { DataAccessor } from '../store/data-accessor.js';
 
 /** Minimal session record returned by findSessions(). */
@@ -18,6 +20,8 @@ export interface MinimalSessionRecord {
   status: string;
   startedAt: string;
   scope: SessionScope;
+  /** Progressive disclosure directives for follow-up operations. */
+  _next?: NextDirectives;
 }
 
 /** Parameters for findSessions(). */
@@ -82,13 +86,14 @@ export async function findSessions(
   return sessions.map(toMinimal);
 }
 
-/** Project a full Session to a MinimalSessionRecord. */
+/** Project a full Session to a MinimalSessionRecord with _next directives. */
 function toMinimal(s: Session): MinimalSessionRecord {
   return {
     id: s.id,
     name: s.name,
     status: s.status,
     startedAt: s.startedAt,
     scope: s.scope,
+    _next: sessionListItemNext(s.id),
   };
 }

packages/core/src/sessions/index.ts

@@ -8,6 +8,7 @@ import { randomBytes } from 'node:crypto';
 import type { Session, SessionScope } from '@cleocode/contracts';
 import { ExitCode } from '@cleocode/contracts';
 import { CleoError } from '../errors.js';
+import { sessionListItemNext, sessionStartNext } from '../mvi-helpers.js';
 import type { DataAccessor } from '../store/data-accessor.js';
 import { getAccessor } from '../store/data-accessor.js';
 
@@ -185,6 +186,9 @@ export async function startSession(
       /* Hooks are best-effort */
     });
 
+  // Attach _next progressive disclosure directives
+  Object.assign(session, { _next: sessionStartNext() });
+
   return session;
 }
 
@@ -358,6 +362,11 @@ export async function listSessions(
     sessions = sessions.slice(0, options.limit);
   }
 
+  // Attach _next progressive disclosure directives to each session
+  for (const s of sessions) {
+    Object.assign(s, { _next: sessionListItemNext(s.id) });
+  }
+
   return sessions;
 }
 

packages/core/src/tasks/find.ts

@@ -7,6 +7,8 @@
 import type { Task, TaskQueryFilters, TaskStatus } from '@cleocode/contracts';
 import { ExitCode } from '@cleocode/contracts';
 import { CleoError } from '../errors.js';
+import type { NextDirectives } from '../mvi-helpers.js';
+import { taskListItemNext } from '../mvi-helpers.js';
 import type { DataAccessor } from '../store/data-accessor.js';
 import { getAccessor } from '../store/data-accessor.js';
 
@@ -19,6 +21,8 @@ export interface FindResult {
   type?: string;
   parentId?: string | null;
   score: number;
+  /** Progressive disclosure directives for follow-up operations. */
+  _next?: NextDirectives;
 }
 
 /** Options for finding tasks. */
@@ -191,8 +195,14 @@ export async function findTasks(
   const offset = options.offset ?? 0;
   results = results.slice(offset, offset + limit);
 
+  // Enrich each result with _next progressive disclosure directives
+  const enrichedResults = results.map((r) => ({
+    ...r,
+    _next: taskListItemNext(r.id),
+  }));
+
   return {
-    results,
+    results: enrichedResults,
     total,
     query: queryStr,
     searchType,

packages/core/src/tasks/list.ts

@@ -6,6 +6,8 @@
 
 import type { Task, TaskPriority, TaskStatus, TaskType } from '@cleocode/contracts';
 import type { LAFSPage } from '@cleocode/lafs';
+import type { NextDirectives } from '../mvi-helpers.js';
+import { taskListItemNext } from '../mvi-helpers.js';
 import { paginate } from '../pagination.js';
 import type { DataAccessor, TaskQueryFilters } from '../store/data-accessor.js';
 
@@ -19,9 +21,11 @@ export interface CompactTask {
   priority: string;
   type?: string;
   parentId?: string | null;
+  /** Progressive disclosure directives for follow-up operations. */
+  _next?: NextDirectives;
 }
 
-/** Convert a full Task to compact representation. */
+/** Convert a full Task to compact representation with _next directives. */
 export function toCompact(task: Task): CompactTask {
   return {
     id: task.id,
@@ -30,6 +34,7 @@ export function toCompact(task: Task): CompactTask {
     priority: task.priority,
     type: task.type,
     parentId: task.parentId,
+    _next: taskListItemNext(task.id),
   };
 }
 
@@ -107,8 +112,14 @@ export async function listTasks(
         }
       : undefined;
 
+  // Enrich each task with _next progressive disclosure directives
+  const enrichedTasks = tasks.map((t) => ({
+    ...t,
+    _next: taskListItemNext(t.id),
+  }));
+
   return {
-    tasks,
+    tasks: enrichedTasks,
     total,
     filtered: filteredCount,
     page,

packages/core/src/tasks/show.ts

@@ -7,6 +7,8 @@
 import type { Task, TaskRef } from '@cleocode/contracts';
 import { ExitCode } from '@cleocode/contracts';
 import { CleoError } from '../errors.js';
+import type { NextDirectives } from '../mvi-helpers.js';
+import { taskShowNext } from '../mvi-helpers.js';
 import type { DataAccessor } from '../store/data-accessor.js';
 import { getAccessor } from '../store/data-accessor.js';
 
@@ -18,6 +20,8 @@ export interface TaskDetail extends Task {
   dependents?: string[];
   hierarchyPath?: string[];
   isArchived?: boolean;
+  /** Progressive disclosure directives for follow-up operations. */
+  _next?: NextDirectives;
 }
 
 /**
@@ -104,5 +108,7 @@ export async function showTask(
     }
   }
 
+  detail._next = taskShowNext(taskId);
+
   return detail;
 }