@cleocode/contracts 2026.4.0 → 2026.4.2

package/dist/task.d.ts

@@ -38,32 +38,54 @@ export type VerificationAgent = 'planner' | 'coder' | 'testing' | 'qa' | 'cleanu
 export type VerificationGate = 'implemented' | 'testsPassed' | 'qaPassed' | 'cleanupDone' | 'securityPassed' | 'documented';
 /** Verification failure log entry. */
 export interface VerificationFailure {
+    /** Verification round number when the failure occurred. */
     round: number;
+    /** Agent that performed the verification and reported the failure. */
     agent: string;
+    /** Human-readable description of why verification failed. */
     reason: string;
+    /** ISO 8601 timestamp of when the failure was recorded. */
     timestamp: string;
 }
 /** Task verification state. */
 export interface TaskVerification {
+    /** Whether all required verification gates have passed. */
     passed: boolean;
+    /** Current verification round number (starts at 1). */
     round: number;
+    /** Gate pass/fail/pending status for each verification gate. */
     gates: Partial<Record<VerificationGate, boolean | null>>;
+    /** The last agent that performed a verification check, or `null`. */
     lastAgent: VerificationAgent | null;
+    /** ISO 8601 timestamp of the most recent verification update, or `null`. */
     lastUpdated: string | null;
+    /** Ordered log of all verification failures across rounds. */
     failureLog: VerificationFailure[];
-    /** ISO timestamp set when verification was first initialized on task creation (T061). */
+    /**
+     * ISO timestamp set when verification was first initialized on task creation (T061).
+     * @defaultValue undefined
+     */
     initializedAt?: string | null;
 }
 /** Task provenance tracking. */
 export interface TaskProvenance {
+    /** Agent or user that created this task, or `null` if unknown. */
     createdBy: string | null;
+    /** Agent or user that last modified this task, or `null` if unknown. */
     modifiedBy: string | null;
+    /** Session ID during which this task was created, or `null`. */
     sessionId: string | null;
 }
 /** A single task relation entry. */
 export interface TaskRelation {
+    /** ID of the related task. */
     taskId: string;
+    /** Relation type (e.g. `"blocks"`, `"related-to"`, `"duplicates"`). */
     type: string;
+    /**
+     * Optional reason explaining the relationship.
+     * @defaultValue undefined
+     */
     reason?: string;
 }
 /**
@@ -87,60 +109,66 @@ export interface Task {
     status: TaskStatus;
     /** Task priority level. Defaults to `'medium'` on creation. */
     priority: TaskPriority;
-    /** Task type in hierarchy. Inferred from parent context if not specified. */
+    /** Task type in hierarchy. Inferred from parent context if not specified. @defaultValue undefined */
     type?: TaskType;
-    /** ID of the parent task. `null` for root-level tasks. */
+    /** ID of the parent task. `null` for root-level tasks. @defaultValue undefined */
     parentId?: string | null;
-    /** Sort position within sibling scope. */
+    /** Sort position within sibling scope. @defaultValue undefined */
     position?: number | null;
-    /** Optimistic concurrency version for position changes. */
+    /** Optimistic concurrency version for position changes. @defaultValue undefined */
     positionVersion?: number;
-    /** Relative scope sizing (small/medium/large). NOT a time estimate. */
+    /** Relative scope sizing (small/medium/large). NOT a time estimate. @defaultValue undefined */
     size?: TaskSize | null;
-    /** Phase slug this task belongs to. */
+    /** Phase slug this task belongs to. @defaultValue undefined */
     phase?: string;
-    /** File paths associated with this task. */
+    /** File paths associated with this task. @defaultValue undefined */
     files?: string[];
-    /** Acceptance criteria for completion. */
+    /** Acceptance criteria for completion. @defaultValue undefined */
     acceptance?: string[];
-    /** IDs of tasks this task depends on. */
+    /** IDs of tasks this task depends on. @defaultValue undefined */
     depends?: string[];
-    /** Related task entries (non-dependency relationships). */
+    /** Related task entries (non-dependency relationships). @defaultValue undefined */
     relates?: TaskRelation[];
-    /** Epic lifecycle state. Only meaningful when `type = 'epic'`. */
+    /** Epic lifecycle state. Only meaningful when `type = 'epic'`. @defaultValue undefined */
     epicLifecycle?: EpicLifecycle | null;
-    /** When true, epic will not auto-complete when all children are done. */
+    /** When true, epic will not auto-complete when all children are done. @defaultValue undefined */
     noAutoComplete?: boolean | null;
-    /** Reason the task is blocked (free-form text). */
+    /** Reason the task is blocked (free-form text). @defaultValue undefined */
     blockedBy?: string;
-    /** Timestamped notes appended during task lifecycle. */
+    /** Timestamped notes appended during task lifecycle. @defaultValue undefined */
     notes?: string[];
-    /** Classification labels for filtering and grouping. */
+    /** Classification labels for filtering and grouping. @defaultValue undefined */
     labels?: string[];
-    /** Task origin/provenance category. */
+    /** Task origin/provenance category. @defaultValue undefined */
     origin?: TaskOrigin | null;
     /** ISO 8601 timestamp of task creation. Must not be in the future. */
     createdAt: string;
-    /** ISO 8601 timestamp of last update. Set automatically on mutation. */
+    /** ISO 8601 timestamp of last update. Set automatically on mutation. @defaultValue undefined */
     updatedAt?: string | null;
     /**
      * ISO 8601 timestamp of task completion. Set when `status` transitions to `'done'`.
      * See {@link CompletedTask} for the status-narrowed type where this is required.
+     *
+     * @defaultValue undefined
      */
     completedAt?: string;
     /**
      * ISO 8601 timestamp of task cancellation. Set when `status` transitions to `'cancelled'`.
      * See {@link CancelledTask} for the status-narrowed type where this is required.
+     *
+     * @defaultValue undefined
      */
     cancelledAt?: string;
     /**
      * Reason for cancellation. Required when `status = 'cancelled'`.
      * See {@link CancelledTask} for the status-narrowed type where this is required.
+     *
+     * @defaultValue undefined
      */
     cancellationReason?: string;
-    /** Verification pipeline state. */
+    /** Verification pipeline state. @defaultValue undefined */
     verification?: TaskVerification | null;
-    /** Provenance tracking (who created/modified, which session). */
+    /** Provenance tracking (who created/modified, which session). @defaultValue undefined */
     provenance?: TaskProvenance | null;
     /**
      * RCASD-IVTR+C pipeline stage this task is associated with.
@@ -150,9 +178,10 @@ export interface Task {
      *
      * Auto-assigned on creation; only moves forward through stages.
      * @task T060
+     * @defaultValue undefined
      */
     pipelineStage?: string | null;
-    /** Agent ID that has claimed/is assigned to this task. Null when unclaimed. */
+    /** Agent ID that has claimed/is assigned to this task. Null when unclaimed. @defaultValue undefined */
     assignee?: string | null;
 }
 /**
@@ -173,29 +202,29 @@ export interface TaskCreate {
      * without a description, and require it to differ from the title.
      */
     description: string;
-    /** Initial status. Defaults to `'pending'`. */
+    /** Initial status. Defaults to `'pending'`. @defaultValue 'pending' */
     status?: TaskStatus;
-    /** Priority level. Defaults to `'medium'`. */
+    /** Priority level. Defaults to `'medium'`. @defaultValue 'medium' */
     priority?: TaskPriority;
-    /** Task type. Inferred from parent context if not specified. */
+    /** Task type. Inferred from parent context if not specified. @defaultValue undefined */
     type?: TaskType;
-    /** Parent task ID for hierarchy placement. */
+    /** Parent task ID for hierarchy placement. @defaultValue undefined */
     parentId?: string | null;
-    /** Relative scope sizing. Defaults to `'medium'`. */
+    /** Relative scope sizing. Defaults to `'medium'`. @defaultValue 'medium' */
     size?: TaskSize;
-    /** Phase slug to assign. Inherited from project.currentPhase if not specified. */
+    /** Phase slug to assign. Inherited from project.currentPhase if not specified. @defaultValue undefined */
     phase?: string;
-    /** Classification labels. */
+    /** Classification labels. @defaultValue undefined */
     labels?: string[];
-    /** File paths associated with this task. */
+    /** File paths associated with this task. @defaultValue undefined */
     files?: string[];
-    /** Acceptance criteria. */
+    /** Acceptance criteria. @defaultValue undefined */
     acceptance?: string[];
-    /** IDs of tasks this task depends on. */
+    /** IDs of tasks this task depends on. @defaultValue undefined */
     depends?: string[];
-    /** Initial note to attach. */
+    /** Initial note to attach. @defaultValue undefined */
     notes?: string;
-    /** Sort position. Auto-calculated if not specified. */
+    /** Sort position. Auto-calculated if not specified. @defaultValue undefined */
     position?: number;
 }
 /**
@@ -229,69 +258,113 @@ export type CancelledTask = Task & {
 export type PhaseStatus = 'pending' | 'active' | 'completed';
 /** Phase definition. */
 export interface Phase {
+    /** Sort order of this phase in the project lifecycle. */
     order: number;
+    /** Human-readable phase name. */
     name: string;
+    /** Phase description. @defaultValue undefined */
     description?: string;
+    /** Current phase lifecycle status. */
     status: PhaseStatus;
+    /** ISO 8601 timestamp of when the phase started. @defaultValue undefined */
     startedAt?: string | null;
+    /** ISO 8601 timestamp of when the phase completed. @defaultValue undefined */
     completedAt?: string | null;
 }
 /** Phase transition record. */
 export interface PhaseTransition {
+    /** Slug of the phase that transitioned. */
     phase: string;
+    /** Type of transition that occurred. */
     transitionType: 'started' | 'completed' | 'rollback';
+    /** ISO 8601 timestamp of the transition. */
     timestamp: string;
+    /** Number of tasks in the phase at transition time. */
     taskCount: number;
+    /** Previous phase slug for rollback transitions. @defaultValue undefined */
     fromPhase?: string | null;
+    /** Optional reason for the transition. @defaultValue undefined */
     reason?: string;
 }
 /** Release status. */
 export type ReleaseStatus = 'planned' | 'active' | 'released';
 /** Release definition. */
 export interface Release {
+    /** Semantic version string (e.g. `"v2026.4.0"`). */
     version: string;
+    /** Current release lifecycle status. */
     status: ReleaseStatus;
+    /** Target release date in ISO 8601. @defaultValue undefined */
     targetDate?: string | null;
+    /** Actual release date in ISO 8601. @defaultValue undefined */
     releasedAt?: string | null;
+    /** Task IDs included in this release. */
     tasks: string[];
+    /** Release notes text. @defaultValue undefined */
     notes?: string | null;
+    /** Generated changelog content. @defaultValue undefined */
     changelog?: string | null;
 }
 /** Project metadata. */
 export interface ProjectMeta {
+    /** Project name from `.cleo/project-context.json`. */
     name: string;
+    /** Slug of the currently active phase. @defaultValue undefined */
     currentPhase?: string | null;
+    /** Phase definitions keyed by slug. */
     phases: Record<string, Phase>;
+    /** Ordered history of phase transitions. @defaultValue undefined */
     phaseHistory?: PhaseTransition[];
+    /** Release definitions for the project. @defaultValue undefined */
     releases?: Release[];
 }
 /** File metadata (_meta block). */
 export interface FileMeta {
+    /** Schema version of the task data file. */
     schemaVersion: string;
+    /** Spec version for forward compatibility. @defaultValue undefined */
     specVersion?: string;
+    /** Integrity checksum of the data file. */
     checksum: string;
+    /** Configuration version used when the file was last written. */
     configVersion: string;
+    /** ID of the last session that modified this file. @defaultValue undefined */
     lastSessionId?: string | null;
+    /** ID of the currently active session. @defaultValue undefined */
     activeSession?: string | null;
+    /** Number of active sessions at last write. @defaultValue undefined */
     activeSessionCount?: number;
+    /** Path to the sessions storage file. @defaultValue undefined */
     sessionsFile?: string | null;
+    /** Monotonically increasing file generation counter. @defaultValue undefined */
     generation?: number;
 }
 /** Session note in taskWork block. */
 export interface SessionNote {
+    /** Note text content. */
     note: string;
+    /** ISO 8601 timestamp of when the note was recorded. */
     timestamp: string;
+    /** Conversation ID for multi-turn context. @defaultValue undefined */
     conversationId?: string | null;
+    /** Agent that recorded this note. @defaultValue undefined */
     agent?: string | null;
 }
 /** Task work state. */
 export interface TaskWorkState {
+    /** ID of the task currently being worked on. @defaultValue undefined */
     currentTask?: string | null;
+    /** Slug of the current project phase. @defaultValue undefined */
     currentPhase?: string | null;
+    /** ISO 8601 timestamp until which work is blocked. @defaultValue undefined */
     blockedUntil?: string | null;
+    /** Most recent session note (legacy, use sessionNotes). @defaultValue undefined */
     sessionNote?: string | null;
+    /** Ordered list of session notes. @defaultValue undefined */
     sessionNotes?: SessionNote[];
+    /** Suggested next action for the agent. @defaultValue undefined */
     nextAction?: string | null;
+    /** ID of the primary session managing this work state. @defaultValue undefined */
     primarySession?: string | null;
 }
 //# sourceMappingURL=task.d.ts.map

package/dist/task.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"task.d.ts","sourceRoot":"","sources":["../src/task.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"task.d.ts","sourceRoot":"","sources":["../src/task.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cleocode/contracts",
-  "version": "2026.4.0",
+  "version": "2026.4.2",
   "description": "Domain types, interfaces, and contracts for the CLEO ecosystem",
   "type": "module",
   "main": "./dist/index.js",

package/src/adapter.ts

@@ -14,25 +14,85 @@ import type { AdapterSpawnProvider } from './spawn.js';
 import type { ExternalTaskProvider } from './task-sync.js';
 import type { AdapterTransportProvider } from './transport.js';
 
+/**
+ * Core provider adapter interface that every CLEO provider must implement.
+ *
+ * @remarks
+ * Provider adapters bridge CLEO's core engine to specific LLM providers
+ * (Claude, GPT, etc.). Each adapter declares its capabilities and exposes
+ * optional sub-providers for hooks, spawning, paths, and transport.
+ */
 export interface CLEOProviderAdapter {
+  /** Unique identifier for this adapter (e.g. `"claude"`, `"openai"`). */
   readonly id: string;
+  /** Human-readable display name for the adapter. */
   readonly name: string;
+  /** Semantic version of the adapter implementation. */
   readonly version: string;
+  /** Capability flags declaring what this adapter supports. */
   capabilities: AdapterCapabilities;
+  /**
+   * Optional hook provider for lifecycle event integration.
+   *
+   * @defaultValue undefined
+   */
   hooks?: AdapterHookProvider;
+  /**
+   * Optional spawn provider for launching sub-agents.
+   *
+   * @defaultValue undefined
+   */
   spawn?: AdapterSpawnProvider;
+  /** Installation provider for scaffolding adapter-specific config files. */
   install: AdapterInstallProvider;
+  /**
+   * Optional path provider for adapter-specific file locations.
+   *
+   * @defaultValue undefined
+   */
   paths?: AdapterPathProvider;
+  /**
+   * Optional context monitor provider for tracking token usage.
+   *
+   * @defaultValue undefined
+   */
   contextMonitor?: AdapterContextMonitorProvider;
+  /**
+   * Optional transport provider for inter-agent messaging.
+   *
+   * @defaultValue undefined
+   */
   transport?: AdapterTransportProvider;
+  /**
+   * Optional external task sync provider for bidirectional issue tracking.
+   *
+   * @defaultValue undefined
+   */
   taskSync?: ExternalTaskProvider;
+  /** Initialize the adapter for the given project directory. */
   initialize(projectDir: string): Promise<void>;
+  /** Release all resources held by the adapter. */
   dispose(): Promise<void>;
+  /** Return the current health status of the adapter. */
   healthCheck(): Promise<AdapterHealthStatus>;
 }
 
+/**
+ * Health check result returned by {@link CLEOProviderAdapter.healthCheck}.
+ *
+ * @remarks
+ * Used by the `cleo doctor` command to verify adapter connectivity and
+ * surface provider-specific diagnostic information.
+ */
 export interface AdapterHealthStatus {
+  /** Whether the adapter is currently operational. */
   healthy: boolean;
+  /** Name of the provider this status applies to. */
   provider: string;
+  /**
+   * Provider-specific diagnostic key-value pairs.
+   *
+   * @defaultValue undefined
+   */
   details?: Record<string, unknown>;
 }

package/src/brain.ts

@@ -9,31 +9,50 @@
 
 /** Compact brain entry reference used in contradiction analysis. */
 export interface BrainEntryRef {
+  /** Brain.db entry identifier. */
   id: string;
+  /** Entry type (e.g. `"observation"`, `"learning"`, `"decision"`). */
   type: string;
+  /** Full text content of the brain entry. */
   content: string;
+  /** ISO 8601 timestamp of when the entry was created. */
   createdAt: string;
 }
 
 /** Brain entry reference with summary, used in superseded analysis. */
 export interface BrainEntrySummary {
+  /** Brain.db entry identifier. */
   id: string;
+  /** Entry type (e.g. `"observation"`, `"learning"`, `"decision"`). */
   type: string;
+  /** ISO 8601 timestamp of when the entry was created. */
   createdAt: string;
+  /** Truncated summary of the entry content. */
   summary: string;
 }
 
 /** Contradiction detail between two brain entries. */
 export interface ContradictionDetail {
+  /** First entry in the contradicting pair. */
   entryA: BrainEntryRef;
+  /** Second entry in the contradicting pair. */
   entryB: BrainEntryRef;
+  /**
+   * Additional context explaining the scope of the contradiction.
+   *
+   * @defaultValue undefined
+   */
   context?: string;
+  /** Description of how the two entries conflict. */
   conflictDetails: string;
 }
 
 /** Superseded entry pair showing old and replacement entries. */
 export interface SupersededEntry {
+  /** The older entry that has been superseded. */
   oldEntry: BrainEntrySummary;
+  /** The newer entry that replaces the old one. */
   replacement: BrainEntrySummary;
+  /** Topic or category grouping these entries together. */
   grouping: string;
 }

package/src/capabilities.ts

@@ -9,6 +9,7 @@ export interface AdapterCapabilities {
   supportedHookEvents: string[];
   supportsSpawn: boolean;
   supportsInstall: boolean;
+  /** Always false. CLI is the only dispatch channel. */
   supportsMcp: boolean;
   supportsInstructionFiles: boolean;
   /** Provider-specific instruction file name, e.g. "CLAUDE.md", ".cursorrules" */

package/src/conduit.ts

@@ -109,6 +109,9 @@ export interface Conduit {
   /** Subscribe to incoming messages. Returns unsubscribe function. */
   onMessage(handler: (message: ConduitMessage) => void): ConduitUnsubscribe;
 
+  /** One-shot poll for new messages. Returns messages without subscribing. */
+  poll(options?: { limit?: number; since?: string }): Promise<ConduitMessage[]>;
+
   // --- Presence ---
 
   /** Send a heartbeat to indicate this agent is alive. */

package/src/config.ts

@@ -17,17 +17,25 @@ export type DateFormat = 'relative' | 'iso' | 'short' | 'long';
 
 /** Output configuration. */
 export interface OutputConfig {
+  /** Default output format for CLI responses. */
   defaultFormat: OutputFormat;
+  /** Whether to use ANSI color codes in terminal output. */
   showColor: boolean;
+  /** Whether to use Unicode symbols (checkmarks, arrows) in output. */
   showUnicode: boolean;
+  /** Whether to display progress bars for long-running operations. */
   showProgressBars: boolean;
+  /** Date display format for timestamps in output. */
   dateFormat: DateFormat;
 }
 
 /** Backup configuration. */
 export interface BackupConfig {
+  /** Maximum number of operational backups to retain during normal operations. */
   maxOperationalBackups: number;
+  /** Maximum number of safety backups to retain for disaster recovery. */
   maxSafetyBackups: number;
+  /** Whether to compress backup files to reduce disk usage. */
   compressionEnabled: boolean;
 }
 
@@ -36,8 +44,11 @@ export type EnforcementProfile = 'llm-agent-first' | 'human-cognitive' | 'custom
 
 /** Hierarchy configuration. */
 export interface HierarchyConfig {
+  /** Maximum nesting depth for task hierarchy (epic > task > subtask). */
   maxDepth: number;
+  /** Maximum number of sibling tasks under a single parent. */
   maxSiblings: number;
+  /** Whether deleting a parent cascades to all descendant tasks. */
   cascadeDelete: boolean;
   /** Maximum number of active (non-done) siblings. 0 = disabled. */
   maxActiveSiblings: number;
@@ -49,8 +60,11 @@ export interface HierarchyConfig {
 
 /** Session configuration. */
 export interface SessionConfig {
+  /** Whether to auto-start a session on first mutate operation. */
   autoStart: boolean;
+  /** Whether session end requires at least one note. */
   requireNotes: boolean;
+  /** Whether multiple concurrent sessions are allowed. */
   multiSession: boolean;
 }
 
@@ -115,6 +129,7 @@ export type LifecycleEnforcementMode = 'strict' | 'advisory' | 'off';
 
 /** Lifecycle enforcement configuration. */
 export interface LifecycleConfig {
+  /** Enforcement mode controlling how lifecycle rules are applied. */
   mode: LifecycleEnforcementMode;
 }
 
@@ -184,7 +199,7 @@ export interface BrainConfig {
   autoCapture: boolean;
   /** Whether to capture file change events (default: false). */
   captureFiles: boolean;
-  /** Whether to capture MCP tool events (default: false). */
+  /** Unused. CLI dispatch only. */
   captureMcp: boolean;
   /** Whether to capture active-work dispatch mutations (tasks.add, tasks.update) (default: false). */
   captureWork: boolean;
@@ -232,19 +247,37 @@ export interface SignalDockConfig {
 
 /** CLEO project configuration (config.json). */
 export interface CleoConfig {
+  /** Configuration schema version string. */
   version: string;
+  /** Output formatting preferences. */
   output: OutputConfig;
+  /** Database backup retention and compression settings. */
   backup: BackupConfig;
+  /** Task hierarchy depth and sibling constraints. */
   hierarchy: HierarchyConfig;
+  /** Session auto-start and multi-session policies. */
   session: SessionConfig;
+  /** Acceptance criteria and session enforcement rules. */
   enforcement: EnforcementConfig;
+  /** Verification gate pipeline settings. */
   verification: VerificationConfig;
+  /** Task lifecycle enforcement mode. */
   lifecycle: LifecycleConfig;
+  /** Log level, rotation, and audit retention settings. */
   logging: LoggingConfig;
+  /** Multi-contributor `.cleo/` state sharing settings. */
   sharing: SharingConfig;
-  /** SignalDock inter-agent transport (optional, disabled by default). */
+  /**
+   * SignalDock inter-agent transport (optional, disabled by default).
+   *
+   * @defaultValue undefined
+   */
   signaldock?: SignalDockConfig;
-  /** Brain memory system configuration (optional, uses defaults when absent). */
+  /**
+   * Brain memory system configuration (optional, uses defaults when absent).
+   *
+   * @defaultValue undefined
+   */
   brain?: BrainConfig;
 }
 
@@ -253,6 +286,8 @@ export type ConfigSource = 'cli' | 'env' | 'project' | 'global' | 'default';
 
 /** A resolved config value with its source. */
 export interface ResolvedValue<T> {
+  /** The resolved configuration value. */
   value: T;
+  /** Where this value was resolved from in the cascade. */
   source: ConfigSource;
 }