@cleocode/contracts 2026.3.38 → 2026.3.40

package/src/task-sync.ts

@@ -1,11 +1,10 @@
 /**
  * Task synchronization contracts for provider-agnostic task reconciliation.
  *
- * Replaces the legacy Claude Code-specific TodoWrite integration with a
- * provider-agnostic system. Any provider adapter can implement
- * AdapterTaskSyncProvider to sync its external task system with CLEO as SSoT.
- *
- * @task T5800
+ * Defines the interface for syncing external issue/task systems (Linear, Jira,
+ * GitHub Issues, GitLab, etc.) with CLEO as SSoT. Provider adapters normalize
+ * their native formats into ExternalTask[], and the reconciliation engine
+ * handles diffing, creating, updating, and linking.
  */
 
 // ---------------------------------------------------------------------------
@@ -22,37 +21,63 @@ export type ExternalTaskStatus = 'pending' | 'active' | 'completed' | 'removed';
 export interface ExternalTask {
   /** Provider-assigned identifier for this task (opaque to core). */
   externalId: string;
-  /** Mapped CLEO task ID, or null if the task is new / unmatched. */
-  cleoTaskId: string | null;
   /** Human-readable title. */
   title: string;
   /** Normalized status. */
   status: ExternalTaskStatus;
   /** Optional description text. */
   description?: string;
+  /** Optional priority mapping (provider decides how to map). */
+  priority?: 'critical' | 'high' | 'medium' | 'low';
+  /** Optional task type mapping. */
+  type?: 'epic' | 'task' | 'subtask';
   /** Optional labels/tags from the provider. */
   labels?: string[];
+  /** Optional URL to the external task (for linking). */
+  url?: string;
+  /** Optional parent external ID (for hierarchy). */
+  parentExternalId?: string;
   /** Arbitrary provider-specific metadata (opaque to core). */
   providerMeta?: Record<string, unknown>;
 }
 
 // ---------------------------------------------------------------------------
-// Sync session state
+// External task link (DB-backed tracking)
 // ---------------------------------------------------------------------------
 
+/** How an external task link was established. */
+export type ExternalLinkType = 'created' | 'matched' | 'manual';
+
+/** Direction of the sync that established the link. */
+export type SyncDirection = 'inbound' | 'outbound' | 'bidirectional';
+
 /**
- * Persistent state for a sync session between CLEO and a provider.
- * Stored per-provider under `.cleo/sync/<providerId>-session.json`.
+ * A link between a CLEO task and an external provider task.
+ * Stored in the external_task_links table in tasks.db.
  */
-export interface SyncSessionState {
-  /** CLEO task IDs that were injected into the provider's task list. */
-  injectedTaskIds: string[];
-  /** Optional phase context when tasks were injected. */
-  injectedPhase?: string;
-  /** Per-task metadata at injection time. */
-  taskMetadata?: Record<string, { phase?: string }>;
-  /** ISO timestamp of the last successful reconciliation. */
-  lastSyncAt?: string;
+export interface ExternalTaskLink {
+  /** Link ID (UUID). */
+  id: string;
+  /** CLEO task ID. */
+  taskId: string;
+  /** Provider identifier (e.g. 'linear', 'jira', 'github'). */
+  providerId: string;
+  /** Provider-assigned external task ID. */
+  externalId: string;
+  /** URL to the external task. */
+  externalUrl?: string | null;
+  /** Title at time of last sync. */
+  externalTitle?: string | null;
+  /** How this link was established. */
+  linkType: ExternalLinkType;
+  /** Sync direction. */
+  syncDirection: SyncDirection;
+  /** Provider-specific metadata (JSON). */
+  metadata?: Record<string, unknown>;
+  /** When the link was first established. */
+  linkedAt: string;
+  /** When the external task was last synchronized. */
+  lastSyncAt?: string | null;
 }
 
 // ---------------------------------------------------------------------------
@@ -75,7 +100,7 @@ export type ConflictPolicy = 'cleo-wins' | 'provider-wins' | 'latest-wins' | 're
 
 /** Options for the reconciliation engine. */
 export interface ReconcileOptions {
-  /** Provider ID (e.g. 'claude-code', 'cursor'). */
+  /** Provider ID (e.g. 'linear', 'jira', 'github'). */
   providerId: string;
   /** Working directory (project root). */
   cwd?: string;
@@ -90,7 +115,13 @@ export interface ReconcileOptions {
 }
 
 /** The type of action the reconciliation engine will take. */
-export type ReconcileActionType = 'complete' | 'activate' | 'create' | 'remove' | 'skip' | 'conflict';
+export type ReconcileActionType =
+  | 'create'
+  | 'update'
+  | 'complete'
+  | 'activate'
+  | 'skip'
+  | 'conflict';
 
 /** A single reconciliation action (planned or applied). */
 export interface ReconcileAction {
@@ -98,12 +129,14 @@ export interface ReconcileAction {
   type: ReconcileActionType;
   /** The CLEO task ID affected (null for creates before they happen). */
   cleoTaskId: string | null;
-  /** The external task that triggered this action. */
+  /** The external task ID that triggered this action. */
   externalId: string;
   /** Human-readable description of the action. */
   summary: string;
   /** Whether this action was actually applied. */
   applied: boolean;
+  /** The link ID if a link was created or updated. */
+  linkId?: string;
   /** Error message if the action failed during apply. */
   error?: string;
 }
@@ -118,16 +151,17 @@ export interface ReconcileResult {
   actions: ReconcileAction[];
   /** Summary counts. */
   summary: {
+    created: number;
+    updated: number;
     completed: number;
     activated: number;
-    created: number;
-    removed: number;
     skipped: number;
     conflicts: number;
+    total: number;
     applied: number;
   };
-  /** Whether sync session state was cleared after apply. */
-  sessionCleared: boolean;
+  /** Links created or updated during this reconciliation. */
+  linksAffected: number;
 }
 
 // ---------------------------------------------------------------------------
@@ -138,9 +172,29 @@ export interface ReconcileResult {
  * Interface that provider adapters implement to expose their external
  * task system to the reconciliation engine.
  *
- * Provider-specific parsing lives here — core never sees native formats.
+ * Provider-specific parsing lives in the adapter — core never sees native formats.
+ * Consumers implement this interface to integrate their issue tracker with CLEO.
+ *
+ * @example
+ * ```typescript
+ * class LinearAdapter implements ExternalTaskProvider {
+ *   async getExternalTasks(projectDir: string): Promise<ExternalTask[]> {
+ *     const issues = await linearClient.issues({ projectId: '...' });
+ *     return issues.map(issue => ({
+ *       externalId: issue.id,
+ *       title: issue.title,
+ *       status: mapLinearStatus(issue.state),
+ *       description: issue.description,
+ *       priority: mapLinearPriority(issue.priority),
+ *       labels: issue.labels.map(l => l.name),
+ *       url: issue.url,
+ *       providerMeta: { linearId: issue.identifier },
+ *     }));
+ *   }
+ * }
+ * ```
  */
-export interface AdapterTaskSyncProvider {
+export interface ExternalTaskProvider {
   /**
    * Read the provider's current task state and return normalized ExternalTasks.
    *
@@ -150,18 +204,14 @@ export interface AdapterTaskSyncProvider {
   getExternalTasks(projectDir: string): Promise<ExternalTask[]>;
 
   /**
-   * Optionally push CLEO task state back to the provider.
+   * Optionally push CLEO task state back to the provider (outbound sync).
    * Not all providers support bidirectional sync.
    *
    * @param tasks - Current CLEO tasks to push.
    * @param projectDir - Project root directory.
    */
-  pushTaskState?(tasks: ReadonlyArray<{ id: string; title: string; status: string }>, projectDir: string): Promise<void>;
-
-  /**
-   * Clean up provider-specific sync artifacts (e.g. state files).
-   *
-   * @param projectDir - Project root directory.
-   */
-  cleanup?(projectDir: string): Promise<void>;
+  pushTaskState?(
+    tasks: ReadonlyArray<{ id: string; title: string; status: string }>,
+    projectDir: string,
+  ): Promise<void>;
 }

package/src/task.ts

@@ -22,6 +22,7 @@
  */
 
 import type { TaskStatus } from './status-registry.js';
+
 export type { TaskStatus };
 
 /** Task priority levels. */

package/dist/todowrite.d.ts

@@ -1,53 +0,0 @@
-/**
- * TodoWrite types for Claude TodoWrite state merge operations.
- *
- * @task T4551
- */
-/** TodoWrite item status as exported by Claude. */
-export type TodoWriteItemStatus = 'pending' | 'in_progress' | 'completed';
-/** TodoWrite item as exported by Claude. */
-export interface TodoWriteItem {
-    content: string;
-    status: TodoWriteItemStatus;
-    activeForm?: string;
-}
-/** TodoWrite state file format. */
-export interface TodoWriteState {
-    todos: TodoWriteItem[];
-}
-/** Sync session state for TodoWrite integration. */
-export interface TodoWriteSyncSessionState {
-    injected_tasks: string[];
-    injectedPhase?: string;
-    task_metadata?: Record<string, {
-        phase?: string;
-    }>;
-}
-/** Detected changes from TodoWrite state analysis. */
-export interface TodoWriteChangeSet {
-    completed: string[];
-    progressed: string[];
-    newTasks: string[];
-    removed: string[];
-}
-/** Action type for a TodoWrite merge change. */
-export type TodoWriteChangeAction = 'complete' | 'create' | 'update';
-/** A single change applied during TodoWrite merge. */
-export interface TodoWriteChange {
-    taskId: string;
-    action: TodoWriteChangeAction;
-    details?: string;
-}
-/** Result of a TodoWrite merge operation. */
-export interface TodoWriteMergeResult {
-    dryRun: boolean;
-    changes: {
-        completed: number;
-        progressed: number;
-        new: number;
-        removed: number;
-        applied: number;
-    };
-    sessionCleared?: boolean;
-}
-//# sourceMappingURL=todowrite.d.ts.map

package/dist/todowrite.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"todowrite.d.ts","sourceRoot":"","sources":["../src/todowrite.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,mDAAmD;AACnD,MAAM,MAAM,mBAAmB,GAAG,SAAS,GAAG,aAAa,GAAG,WAAW,CAAC;AAE1E,4CAA4C;AAC5C,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,mBAAmB,CAAC;IAC5B,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,mCAAmC;AACnC,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,aAAa,EAAE,CAAC;CACxB;AAED,oDAAoD;AACpD,MAAM,WAAW,yBAAyB;IACxC,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACpD;AAED,sDAAsD;AACtD,MAAM,WAAW,kBAAkB;IACjC,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,gDAAgD;AAChD,MAAM,MAAM,qBAAqB,GAAG,UAAU,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAErE,sDAAsD;AACtD,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,qBAAqB,CAAC;IAC9B,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,6CAA6C;AAC7C,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,OAAO,CAAC;IAChB,OAAO,EAAE;QACP,SAAS,EAAE,MAAM,CAAC;QAClB,UAAU,EAAE,MAAM,CAAC;QACnB,GAAG,EAAE,MAAM,CAAC;QACZ,OAAO,EAAE,MAAM,CAAC;QAChB,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC;IACF,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B"}

package/dist/todowrite.js

@@ -1,7 +0,0 @@
-/**
- * TodoWrite types for Claude TodoWrite state merge operations.
- *
- * @task T4551
- */
-export {};
-//# sourceMappingURL=todowrite.js.map

package/dist/todowrite.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"todowrite.js","sourceRoot":"","sources":["../src/todowrite.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}

package/src/todowrite.ts

@@ -1,58 +0,0 @@
-/**
- * TodoWrite types for Claude TodoWrite state merge operations.
- *
- * @task T4551
- */
-
-/** TodoWrite item status as exported by Claude. */
-export type TodoWriteItemStatus = 'pending' | 'in_progress' | 'completed';
-
-/** TodoWrite item as exported by Claude. */
-export interface TodoWriteItem {
-  content: string;
-  status: TodoWriteItemStatus;
-  activeForm?: string;
-}
-
-/** TodoWrite state file format. */
-export interface TodoWriteState {
-  todos: TodoWriteItem[];
-}
-
-/** Sync session state for TodoWrite integration. */
-export interface TodoWriteSyncSessionState {
-  injected_tasks: string[];
-  injectedPhase?: string;
-  task_metadata?: Record<string, { phase?: string }>;
-}
-
-/** Detected changes from TodoWrite state analysis. */
-export interface TodoWriteChangeSet {
-  completed: string[];
-  progressed: string[];
-  newTasks: string[];
-  removed: string[];
-}
-
-/** Action type for a TodoWrite merge change. */
-export type TodoWriteChangeAction = 'complete' | 'create' | 'update';
-
-/** A single change applied during TodoWrite merge. */
-export interface TodoWriteChange {
-  taskId: string;
-  action: TodoWriteChangeAction;
-  details?: string;
-}
-
-/** Result of a TodoWrite merge operation. */
-export interface TodoWriteMergeResult {
-  dryRun: boolean;
-  changes: {
-    completed: number;
-    progressed: number;
-    new: number;
-    removed: number;
-    applied: number;
-  };
-  sessionCleared?: boolean;
-}