@cleocode/contracts 2026.4.0 → 2026.4.3

package/src/results.ts

@@ -11,107 +11,158 @@ import type { TaskRecord } from './task-record.js';
 
 /** Task summary counts used in dashboard and stats views. */
 export interface TaskSummary {
+  /** Number of tasks in `pending` status. */
   pending: number;
+  /** Number of tasks in `active` status. */
   active: number;
+  /** Number of tasks in `blocked` status. */
   blocked: number;
+  /** Number of tasks in `done` status. */
   done: number;
+  /** Number of tasks in `cancelled` status. */
   cancelled: number;
+  /** Total non-archived tasks (pending + active + blocked + done + cancelled). */
   total: number;
+  /** Number of archived tasks. */
   archived: number;
+  /** Grand total including archived tasks. */
   grandTotal: number;
 }
 
 /** Label frequency entry. */
 export interface LabelCount {
+  /** Label string value. */
   label: string;
+  /** Number of tasks tagged with this label. */
   count: number;
 }
 
 /** Dashboard result from system.dash query. */
 export interface DashboardResult {
+  /** Project name. */
   project: string;
+  /** Currently active phase slug, or `null` if no phase is active. */
   currentPhase: string | null;
+  /** Aggregate task status counts. */
   summary: TaskSummary;
+  /** Current task work focus state. */
   taskWork: {
     currentTask: string | null;
     task: TaskRecord | null;
   };
+  /** Currently active session ID, or `null`. */
   activeSession: string | null;
+  /** High-priority tasks requiring attention. */
   highPriority: {
     count: number;
     tasks: TaskRecord[];
   };
+  /** Blocked tasks that need unblocking. */
   blockedTasks: {
     count: number;
     limit: number;
     tasks: TaskRecord[];
   };
+  /** Recently completed tasks. */
   recentCompletions: TaskRecord[];
+  /** Most frequently used labels with counts. */
   topLabels: LabelCount[];
 }
 
 /** Current state counts used in stats results. */
 export interface StatsCurrentState {
+  /** Number of tasks in `pending` status. */
   pending: number;
+  /** Number of tasks in `active` status. */
   active: number;
+  /** Number of tasks in `done` status. */
   done: number;
+  /** Number of tasks in `blocked` status. */
   blocked: number;
+  /** Number of tasks in `cancelled` status. */
   cancelled: number;
+  /** Total active (non-done, non-cancelled) tasks. */
   totalActive: number;
+  /** Number of archived tasks. */
   archived: number;
+  /** Grand total including archived tasks. */
   grandTotal: number;
 }
 
 /** Completion metrics for a given time period. */
 export interface StatsCompletionMetrics {
+  /** Number of days in the measurement period. */
   periodDays: number;
+  /** Tasks completed within the period. */
   completedInPeriod: number;
+  /** Tasks created within the period. */
   createdInPeriod: number;
+  /** Completion rate as a ratio (0.0 to 1.0). */
   completionRate: number;
 }
 
 /** Activity metrics for a given time period. */
 export interface StatsActivityMetrics {
+  /** Tasks created within the period. */
   createdInPeriod: number;
+  /** Tasks completed within the period. */
   completedInPeriod: number;
+  /** Tasks archived within the period. */
   archivedInPeriod: number;
 }
 
 /** All-time cumulative statistics. */
 export interface StatsAllTime {
+  /** Total tasks ever created. */
   totalCreated: number;
+  /** Total tasks ever completed. */
   totalCompleted: number;
+  /** Total tasks ever cancelled. */
   totalCancelled: number;
+  /** Total tasks ever archived. */
   totalArchived: number;
+  /** Archived tasks that were in `done` status when archived. */
   archivedCompleted: number;
 }
 
 /** Cycle time statistics. */
 export interface StatsCycleTimes {
+  /** Average days from creation to completion, or `null` if no samples. */
   averageDays: number | null;
+  /** Number of completed tasks used to compute the average. */
   samples: number;
 }
 
 /** Stats result from system.stats query. */
 export interface StatsResult {
+  /** Current task status distribution. */
   currentState: StatsCurrentState;
+  /** Task count grouped by priority level. */
   byPriority: Record<string, number>;
+  /** Task count grouped by task type. */
   byType: Record<string, number>;
+  /** Task count grouped by phase slug. */
   byPhase: Record<string, number>;
+  /** Completion throughput for the measurement period. */
   completionMetrics: StatsCompletionMetrics;
+  /** Creation/completion/archive activity for the period. */
   activityMetrics: StatsActivityMetrics;
+  /** Cumulative all-time statistics. */
   allTime: StatsAllTime;
+  /** Average time from task creation to completion. */
   cycleTimes: StatsCycleTimes;
 }
 
 /** Log query result from system.log query. */
 export interface LogQueryResult {
+  /** Audit log entries matching the query. */
   entries: Array<{
     operation: string;
     taskId?: string;
     timestamp: string;
     [key: string]: unknown;
   }>;
+  /** Pagination metadata for the query result. */
   pagination: {
     total: number;
     offset: number;
@@ -122,13 +173,21 @@ export interface LogQueryResult {
 
 /** Context monitoring data from system.context query. */
 export interface ContextResult {
+  /** Whether context monitoring is available for the current provider. */
   available: boolean;
+  /** Human-readable context usage status (e.g. `"healthy"`, `"warning"`). */
   status: string;
+  /** Context usage as a percentage (0-100). */
   percentage: number;
+  /** Estimated current token count. */
   currentTokens: number;
+  /** Maximum token capacity for the provider. */
   maxTokens: number;
+  /** ISO 8601 timestamp of the last context measurement. */
   timestamp: string | null;
+  /** Whether the context data is stale (older than threshold). */
   stale: boolean;
+  /** Per-session context usage breakdown. */
   sessions: Array<{
     file: string;
     sessionId: string | null;
@@ -140,9 +199,13 @@ export interface ContextResult {
 
 /** Sequence counter data from system.sequence query. */
 export interface SequenceResult {
+  /** Current sequence counter value. */
   counter: number;
+  /** Last task ID generated. */
   lastId: string;
+  /** Integrity checksum of the sequence state. */
   checksum: string;
+  /** Next task ID that will be generated. */
   nextId: string;
 }
 
@@ -152,8 +215,11 @@ export interface SequenceResult {
 
 /** Compact task reference used across analysis and dependency results. */
 export interface TaskRef {
+  /** Task identifier. */
   id: string;
+  /** Task title. */
   title: string;
+  /** Current task status string. */
   status: string;
 }
 
@@ -162,28 +228,42 @@ export type TaskRefPriority = Pick<TaskRef, 'id' | 'title'> & { priority?: strin
 
 /** Task with leverage score for prioritization. */
 export interface LeveragedTask {
+  /** Task identifier. */
   id: string;
+  /** Task title. */
   title: string;
+  /** Leverage score (higher = more impactful to work on). */
   leverage: number;
+  /**
+   * Explanation of why this task has high leverage.
+   * @defaultValue undefined
+   */
   reason?: string;
 }
 
 /** Bottleneck task — blocks other tasks. */
 export interface BottleneckTask {
+  /** Task identifier. */
   id: string;
+  /** Task title. */
   title: string;
+  /** Number of other tasks blocked by this task. */
   blocksCount: number;
 }
 
 /** Task analysis result from tasks.analyze. */
 export interface TaskAnalysisResult {
+  /** Top recommended task to work on next, or `null` if none available. */
   recommended: (LeveragedTask & { reason: string }) | null;
+  /** Tasks that block the most other tasks. */
   bottlenecks: BottleneckTask[];
+  /** Tasks grouped by priority tier. */
   tiers: {
     critical: LeveragedTask[];
     high: LeveragedTask[];
     normal: LeveragedTask[];
   };
+  /** Aggregate analysis metrics. */
   metrics: {
     totalTasks: number;
     actionable: number;
@@ -194,14 +274,23 @@ export interface TaskAnalysisResult {
 
 /** Single task dependency result from tasks.deps. */
 export interface TaskDepsResult {
+  /** ID of the task whose dependencies were analyzed. */
   taskId: string;
+  /** Tasks that this task depends on. */
   dependsOn: TaskRef[];
+  /** Tasks that depend on this task. */
   dependedOnBy: TaskRef[];
+  /** Dependency IDs that reference non-existent tasks. */
   unresolvedDeps: string[];
+  /** Whether all dependencies are in a terminal status. */
   allDepsReady: boolean;
 }
 
 /** Completion result — unblocked tasks after completing a task. */
 export interface CompleteTaskUnblocked {
+  /**
+   * Tasks that became unblocked as a result of the completion.
+   * @defaultValue undefined
+   */
   unblockedTasks?: TaskRef[];
 }

package/src/session.ts

@@ -13,58 +13,129 @@ export type { SessionStatus };
 
 /** Session scope JSON blob shape. */
 export interface SessionScope {
+  /** Scope type (e.g. `"global"`, `"epic"`, `"task"`, `"custom"`). */
   type: string;
+  /**
+   * Epic ID when scope type is `"epic"`.
+   * @defaultValue undefined
+   */
   epicId?: string;
+  /**
+   * Root task ID when scope is narrowed to a subtree.
+   * @defaultValue undefined
+   */
   rootTaskId?: string;
+  /**
+   * Whether to include descendant tasks of the root task.
+   * @defaultValue undefined
+   */
   includeDescendants?: boolean;
+  /**
+   * Phase slug to filter tasks by.
+   * @defaultValue undefined
+   */
   phaseFilter?: string | null;
+  /**
+   * Label filter to narrow the scope to specific labels.
+   * @defaultValue undefined
+   */
   labelFilter?: string[] | null;
+  /**
+   * Maximum hierarchy depth to include.
+   * @defaultValue undefined
+   */
   maxDepth?: number | null;
+  /**
+   * Explicit task IDs to include regardless of other filters.
+   * @defaultValue undefined
+   */
   explicitTaskIds?: string[] | null;
+  /**
+   * Task IDs to exclude from the scope.
+   * @defaultValue undefined
+   */
   excludeTaskIds?: string[] | null;
+  /**
+   * Task IDs computed from the scope definition at resolution time.
+   * @defaultValue undefined
+   */
   computedTaskIds?: string[];
+  /**
+   * ISO 8601 timestamp of when computed task IDs were last resolved.
+   * @defaultValue undefined
+   */
   computedAt?: string;
 }
 
 /** Session statistics. */
 export interface SessionStats {
+  /** Number of tasks completed during this session. */
   tasksCompleted: number;
+  /** Number of new tasks created during this session. */
   tasksCreated: number;
+  /** Number of task updates performed during this session. */
   tasksUpdated: number;
+  /** Number of times the focus task was changed. */
   focusChanges: number;
+  /** Total minutes the session was in active status. */
   totalActiveMinutes: number;
+  /** Number of times the session was suspended and resumed. */
   suspendCount: number;
 }
 
 /** Active task work state within a session. */
 export interface SessionTaskWork {
+  /** ID of the task currently being worked on, or `null` if none. */
   taskId: string | null;
+  /** ISO 8601 timestamp of when the current task was set, or `null`. */
   setAt: string | null;
 }
 
 /** Session domain type — plain interface aligned with Drizzle sessions table. */
 export interface Session {
+  /** Unique session identifier (e.g. `"ses_20260401..."`) . */
   id: string;
+  /** Human-readable session name. */
   name: string;
+  /** Current session lifecycle status. */
   status: SessionStatus;
+  /** Scope definition controlling which tasks are visible. */
   scope: SessionScope;
+  /** Active task work state within the session. */
   taskWork: SessionTaskWork;
+  /** ISO 8601 timestamp of when the session started. */
   startedAt: string;
+  /** ISO 8601 timestamp of when the session ended. @defaultValue undefined */
   endedAt?: string;
+  /** Agent identifier that owns this session. @defaultValue undefined */
   agent?: string;
+  /** Timestamped notes appended during the session. @defaultValue undefined */
   notes?: string[];
+  /** IDs of tasks completed during this session. @defaultValue undefined */
   tasksCompleted?: string[];
+  /** IDs of tasks created during this session. @defaultValue undefined */
   tasksCreated?: string[];
+  /** Serialized handoff JSON for session continuity. @defaultValue undefined */
   handoffJson?: string | null;
+  /** ID of the session that preceded this one. @defaultValue undefined */
   previousSessionId?: string | null;
+  /** ID of the session that follows this one. @defaultValue undefined */
   nextSessionId?: string | null;
+  /** Provider-specific agent identifier string. @defaultValue undefined */
   agentIdentifier?: string | null;
+  /** ISO 8601 timestamp of when the handoff was consumed. @defaultValue undefined */
   handoffConsumedAt?: string | null;
+  /** Agent that consumed the handoff. @defaultValue undefined */
   handoffConsumedBy?: string | null;
+  /** Serialized debrief JSON from session end. @defaultValue undefined */
   debriefJson?: string | null;
+  /** Aggregate session statistics. @defaultValue undefined */
   stats?: SessionStats;
+  /** Number of times this session has been resumed. @defaultValue undefined */
   resumeCount?: number;
+  /** Whether this session is in grade/evaluation mode. @defaultValue undefined */
   gradeMode?: boolean;
+  /** ID of the provider adapter used for this session. @defaultValue undefined */
   providerId?: string | null;
 }
 
@@ -75,7 +146,9 @@ export interface Session {
  * provided for consumers that expect it at the top level of the result.
  */
 export interface SessionStartResult {
+  /** The newly created or resumed session. */
   session: Session;
+  /** Convenience alias for `session.id`. */
   sessionId: string;
 }
 
@@ -84,6 +157,11 @@ export interface SessionStartResult {
  *
  * Provides discoverable query methods for common session lookups.
  * Does NOT change the DataAccessor interface — consumers create views from Session[].
+ *
+ * @remarks
+ * SessionView is a read-only collection wrapper that provides convenience
+ * methods for filtering, searching, and sorting sessions. It does not own
+ * the data and performs no mutations on the underlying array.
  */
 export class SessionView {
   private readonly _sessions: Session[];

package/src/status-registry.ts

@@ -6,7 +6,7 @@
  *
  * Dependency direction:
  *   status-registry.ts → schema.ts, types/task.ts, validation/engine.ts,
- *                         mcp/lib/security.ts, dispatch/lib/security.ts, ...
+ *                         dispatch/lib/security.ts, ...
  */
 
 // === WORKFLOW NAMESPACE ===