@cleocode/core 2026.3.39 → 2026.3.41

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cleocode/core",
-  "version": "2026.3.39",
+  "version": "2026.3.41",
   "description": "CLEO core business logic kernel — tasks, sessions, memory, orchestration, lifecycle, with bundled SQLite store",
   "type": "module",
   "main": "./dist/index.js",
@@ -36,7 +36,7 @@
     "write-file-atomic": "^6.0.0",
     "yaml": "^2.8.2",
     "zod": "^3.25.76",
-    "@cleocode/contracts": "2026.3.39"
+    "@cleocode/contracts": "2026.3.41"
   },
   "engines": {
     "node": ">=24.0.0"

package/src/admin/export.ts

@@ -10,7 +10,7 @@ import { writeFile } from 'node:fs/promises';
 import type { Task } from '@cleocode/contracts';
 import { getAccessor } from '../store/data-accessor.js';
 
-export type ExportFormat = 'json' | 'csv' | 'tsv' | 'markdown' | 'todowrite';
+export type ExportFormat = 'json' | 'csv' | 'tsv' | 'markdown';
 
 function taskToCsvRow(task: Task, delimiter: string): string {
   const escapeField = (val: string) => {
@@ -38,16 +38,6 @@ function taskToMarkdown(task: Task): string {
   return `- [${status}] **${task.id}** ${priority} ${task.title}`;
 }
 
-function taskToTodoWrite(task: Task): Record<string, unknown> {
-  return {
-    id: task.id,
-    content: task.title,
-    status:
-      task.status === 'done' ? 'completed' : task.status === 'active' ? 'in_progress' : 'pending',
-    priority: task.priority === 'critical' ? 'high' : task.priority,
-  };
-}
-
 export interface ExportParams {
   format?: ExportFormat;
   output?: string;
@@ -132,13 +122,8 @@ export async function exportTasks(params: ExportParams): Promise<ExportResult> {
       content = lines.join('\n');
       break;
     }
-    case 'todowrite': {
-      const items = tasks.map(taskToTodoWrite);
-      content = JSON.stringify(items, null, 2);
-      break;
-    }
     default:
-      throw new Error(`Unknown format: ${format}. Valid: json, csv, tsv, markdown, todowrite`);
+      throw new Error(`Unknown format: ${format}. Valid: json, csv, tsv, markdown`);
   }
 
   if (params.output) {

package/src/cleo.ts

@@ -18,9 +18,9 @@ import path from 'node:path';
 import type {
   DataAccessor,
   ExternalTask,
+  ExternalTaskLink,
   ReconcileOptions,
   ReconcileResult,
-  SyncSessionState,
   Task,
   TaskPriority,
   TaskSize,
@@ -80,7 +80,11 @@ import {
 } from './orchestration/index.js';
 // Reconciliation (sync)
 import { reconcile } from './reconciliation/index.js';
-import { clearSyncState, readSyncState, writeSyncState } from './reconciliation/sync-state.js';
+import {
+  getLinksByProvider,
+  getLinksByTaskId,
+  removeLinksByProvider,
+} from './reconciliation/link-store.js';
 
 // Release
 import {
@@ -303,6 +307,7 @@ export interface NexusAPI {
 }
 
 export interface SyncAPI {
+  /** Reconcile external tasks with CLEO as SSoT. */
   reconcile(params: {
     externalTasks: ExternalTask[];
     providerId: string;
@@ -311,9 +316,12 @@ export interface SyncAPI {
     defaultPhase?: string;
     defaultLabels?: string[];
   }): Promise<ReconcileResult>;
-  readState(providerId: string): Promise<SyncSessionState | null>;
-  writeState(providerId: string, state: SyncSessionState): Promise<void>;
-  clearState(providerId: string): Promise<void>;
+  /** Get all external task links for a provider. */
+  getLinks(providerId: string): Promise<ExternalTaskLink[]>;
+  /** Get all external task links for a CLEO task. */
+  getTaskLinks(taskId: string): Promise<ExternalTaskLink[]>;
+  /** Remove all external task links for a provider. */
+  removeProviderLinks(providerId: string): Promise<number>;
 }
 
 // ============================================================================
@@ -580,9 +588,9 @@ export class Cleo {
           },
           store,
         ),
-      readState: (providerId) => readSyncState(providerId, root),
-      writeState: (providerId, state) => writeSyncState(providerId, state, root),
-      clearState: (providerId) => clearSyncState(providerId, root),
+      getLinks: (providerId) => getLinksByProvider(providerId, root),
+      getTaskLinks: (taskId) => getLinksByTaskId(taskId, root),
+      removeProviderLinks: (providerId) => removeLinksByProvider(providerId, root),
     };
   }
 }

package/src/inject/index.ts

@@ -1,5 +1,7 @@
 /**
- * TodoWrite injection core module.
+ * Task injection core module.
+ *
+ * Selects and formats tasks for injection into external systems.
  *
  * ARCHITECTURE NOTE: Instruction injection is a CAAMP domain responsibility.
  * Once @cleocode/caamp is available as a dependency, the injection formatting
@@ -15,8 +17,6 @@ import type { Task, TaskFile } from '@cleocode/contracts';
 import type { DataAccessor } from '../store/data-accessor.js';
 import { getAccessor } from '../store/data-accessor.js';
 
-// CLEO-native injection (CAAMP InstructionInjector not yet available as separate package)
-
 /**
  * Select tasks eligible for injection based on filters.
  * This is CLEO-specific task selection logic (stays in CLEO).
@@ -59,11 +59,11 @@ function selectTasksForInjection(
 }
 
 /**
- * Format tasks for TodoWrite injection.
+ * Format tasks for injection.
  * Format: [T###] [!]? [BLOCKED]? <title>
  * @task T4539
  */
-function formatForTodoWrite(tasks: Task[]): Array<{ id: string; text: string; status: string }> {
+function formatForInjection(tasks: Task[]): Array<{ id: string; text: string; status: string }> {
   return tasks.map((t) => {
     let prefix = `[${t.id}]`;
     if (t.priority === 'critical' || t.priority === 'high') prefix += ' [!]';
@@ -72,7 +72,7 @@ function formatForTodoWrite(tasks: Task[]): Array<{ id: string; text: string; st
   });
 }
 
-/** Inject tasks into TodoWrite format. */
+/** Inject tasks for external consumption. */
 export async function injectTasks(
   opts: {
     maxTasks?: number;
@@ -97,7 +97,7 @@ export async function injectTasks(
   } as TaskFile;
 
   const selectedTasks = selectTasksForInjection(data, opts);
-  const formatted = formatForTodoWrite(selectedTasks);
+  const formatted = formatForInjection(selectedTasks);
 
   const phase = opts.phase ?? projectMeta?.currentPhase ?? null;
 

package/src/internal.ts

@@ -28,12 +28,6 @@ export { exportTasksPackage } from './admin/export-tasks.js';
 export { computeHelp } from './admin/help.js';
 export { importTasks } from './admin/import.js';
 export { importTasksPackage } from './admin/import-tasks.js';
-// Alias for cleo compatibility (admin sync status)
-export {
-  clearSyncState,
-  getSyncStatus,
-  getSyncStatus as getAdminSyncStatus,
-} from './admin/sync.js';
 // ADRs
 export { findAdrs } from './adrs/find.js';
 export { listAdrs, showAdr, syncAdrsToDb, validateAllAdrs } from './adrs/index.js';
@@ -206,10 +200,13 @@ export { listPhases, showPhase } from './pipeline/index.js';
 export { getNodeUpgradeInstructions, getNodeVersionInfo } from './platform.js';
 // Reconciliation (additional)
 export {
-  clearSyncState as clearProviderSyncState,
-  readSyncState,
-  writeSyncState,
-} from './reconciliation/sync-state.js';
+  createLink,
+  getLinkByExternalId,
+  getLinksByProvider,
+  getLinksByTaskId,
+  removeLinksByProvider,
+  touchLink,
+} from './reconciliation/link-store.js';
 // Release
 export { channelToDistTag, describeChannel, resolveChannelFromBranch } from './release/channel.js';
 export type { PRResult } from './release/github-pr.js';
@@ -338,7 +335,13 @@ export { computeChecksum, readJson } from './store/json.js';
 export { createSession, getActiveSession } from './store/session-store.js';
 export { getDb, getNativeDb } from './store/sqlite.js';
 export { createTask } from './store/task-store.js';
-export { auditLog, releaseManifests, taskDependencies, tasks } from './store/tasks-schema.js';
+export {
+  auditLog,
+  externalTaskLinks,
+  releaseManifests,
+  taskDependencies,
+  tasks,
+} from './store/tasks-schema.js';
 export { AuditLogInsertSchema } from './store/validation-schemas.js';
 export type {
   AnalyzeArchiveOptions,
@@ -384,18 +387,6 @@ export {
 // Task work (additional)
 export type { TaskWorkHistoryEntry } from './task-work/index.js';
 export { getTaskHistory } from './task-work/index.js';
-export type {
-  ChangeSet as TodoWriteChangeSet,
-  SyncSessionState,
-  TodoWriteItem,
-  TodoWriteMergeOptions,
-  TodoWriteMergeResult,
-  TodoWriteState,
-} from './task-work/todowrite-merge.js';
-export {
-  analyzeChanges as analyzeTodoWriteChanges,
-  mergeTodoWriteState,
-} from './task-work/todowrite-merge.js';
 // Tasks (additional)
 export { validateLabels } from './tasks/add.js';
 export { getCriticalPath } from './tasks/graph-ops.js';

package/src/reconciliation/index.ts

@@ -1,8 +1,17 @@
 /**
  * Provider-agnostic task reconciliation module.
  *
- * @task T5800
+ * Provides the reconciliation engine for syncing external task systems
+ * (Linear, Jira, GitHub Issues, etc.) with CLEO as SSoT, plus DB-backed
+ * link tracking via the external_task_links table.
  */
 
+export {
+  createLink,
+  getLinkByExternalId,
+  getLinksByProvider,
+  getLinksByTaskId,
+  removeLinksByProvider,
+  touchLink,
+} from './link-store.js';
 export { reconcile } from './reconciliation-engine.js';
-export { clearSyncState, readSyncState, writeSyncState } from './sync-state.js';

package/src/reconciliation/link-store.ts

@@ -0,0 +1,174 @@
+/**
+ * External task link persistence — DB-backed link tracking for reconciliation.
+ *
+ * Manages the external_task_links table in tasks.db. Used by the reconciliation
+ * engine to match external tasks to existing CLEO tasks and track sync history.
+ */
+
+import { randomUUID } from 'node:crypto';
+import type { ExternalTaskLink } from '@cleocode/contracts';
+import { and, eq } from 'drizzle-orm';
+import { getDb } from '../store/sqlite.js';
+import { externalTaskLinks } from '../store/tasks-schema.js';
+
+// ---------------------------------------------------------------------------
+// Read operations
+// ---------------------------------------------------------------------------
+
+/**
+ * Find all links for a given provider.
+ */
+export async function getLinksByProvider(
+  providerId: string,
+  cwd?: string,
+): Promise<ExternalTaskLink[]> {
+  const db = await getDb(cwd);
+  const rows = await db
+    .select()
+    .from(externalTaskLinks)
+    .where(eq(externalTaskLinks.providerId, providerId));
+  return rows.map(rowToLink);
+}
+
+/**
+ * Find a link by provider + external ID.
+ */
+export async function getLinkByExternalId(
+  providerId: string,
+  externalId: string,
+  cwd?: string,
+): Promise<ExternalTaskLink | null> {
+  const db = await getDb(cwd);
+  const rows = await db
+    .select()
+    .from(externalTaskLinks)
+    .where(
+      and(
+        eq(externalTaskLinks.providerId, providerId),
+        eq(externalTaskLinks.externalId, externalId),
+      ),
+    );
+  return rows.length > 0 ? rowToLink(rows[0]!) : null;
+}
+
+/**
+ * Find all links for a given CLEO task.
+ */
+export async function getLinksByTaskId(taskId: string, cwd?: string): Promise<ExternalTaskLink[]> {
+  const db = await getDb(cwd);
+  const rows = await db
+    .select()
+    .from(externalTaskLinks)
+    .where(eq(externalTaskLinks.taskId, taskId));
+  return rows.map(rowToLink);
+}
+
+// ---------------------------------------------------------------------------
+// Write operations
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a new external task link.
+ */
+export async function createLink(
+  params: {
+    taskId: string;
+    providerId: string;
+    externalId: string;
+    externalUrl?: string;
+    externalTitle?: string;
+    linkType: ExternalTaskLink['linkType'];
+    syncDirection?: ExternalTaskLink['syncDirection'];
+    metadata?: Record<string, unknown>;
+  },
+  cwd?: string,
+): Promise<ExternalTaskLink> {
+  const db = await getDb(cwd);
+  const now = new Date().toISOString();
+  const id = randomUUID();
+
+  await db.insert(externalTaskLinks).values({
+    id,
+    taskId: params.taskId,
+    providerId: params.providerId,
+    externalId: params.externalId,
+    externalUrl: params.externalUrl ?? null,
+    externalTitle: params.externalTitle ?? null,
+    linkType: params.linkType,
+    syncDirection: params.syncDirection ?? 'inbound',
+    metadataJson: params.metadata ? JSON.stringify(params.metadata) : '{}',
+    linkedAt: now,
+    lastSyncAt: now,
+  });
+
+  return {
+    id,
+    taskId: params.taskId,
+    providerId: params.providerId,
+    externalId: params.externalId,
+    externalUrl: params.externalUrl ?? null,
+    externalTitle: params.externalTitle ?? null,
+    linkType: params.linkType,
+    syncDirection: params.syncDirection ?? 'inbound',
+    metadata: params.metadata,
+    linkedAt: now,
+    lastSyncAt: now,
+  };
+}
+
+/**
+ * Update the lastSyncAt and optionally the title/metadata for an existing link.
+ */
+export async function touchLink(
+  linkId: string,
+  updates?: {
+    externalTitle?: string;
+    metadata?: Record<string, unknown>;
+  },
+  cwd?: string,
+): Promise<void> {
+  const db = await getDb(cwd);
+  const now = new Date().toISOString();
+  const values: Record<string, unknown> = { lastSyncAt: now };
+  if (updates?.externalTitle !== undefined) {
+    values.externalTitle = updates.externalTitle;
+  }
+  if (updates?.metadata !== undefined) {
+    values.metadataJson = JSON.stringify(updates.metadata);
+  }
+
+  await db.update(externalTaskLinks).set(values).where(eq(externalTaskLinks.id, linkId));
+}
+
+/**
+ * Remove all links for a provider (used during provider deregistration).
+ */
+export async function removeLinksByProvider(providerId: string, cwd?: string): Promise<number> {
+  const db = await getDb(cwd);
+  const result = await db
+    .delete(externalTaskLinks)
+    .where(eq(externalTaskLinks.providerId, providerId));
+  return Number(result.changes);
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function rowToLink(row: typeof externalTaskLinks.$inferSelect): ExternalTaskLink {
+  return {
+    id: row.id,
+    taskId: row.taskId,
+    providerId: row.providerId,
+    externalId: row.externalId,
+    externalUrl: row.externalUrl,
+    externalTitle: row.externalTitle,
+    linkType: row.linkType as ExternalTaskLink['linkType'],
+    syncDirection: row.syncDirection as ExternalTaskLink['syncDirection'],
+    metadata: row.metadataJson
+      ? (JSON.parse(row.metadataJson) as Record<string, unknown>)
+      : undefined,
+    linkedAt: row.linkedAt,
+    lastSyncAt: row.lastSyncAt,
+  };
+}