@cleocode/core 2026.3.39 → 2026.3.41

package/src/reconciliation/reconciliation-engine.ts

@@ -4,26 +4,28 @@
  * Takes normalized ExternalTask[] from any provider adapter and reconciles
  * them against CLEO's authoritative task state. CLEO is always the SSoT.
  *
- * Provider-specific parsing is NEVER done here — that lives in the adapter's
- * AdapterTaskSyncProvider implementation.
+ * Uses the external_task_links table in tasks.db to track which external
+ * tasks map to which CLEO tasks, enabling re-sync, update detection, and
+ * bidirectional traceability.
  *
- * @task T5800
+ * Provider-specific parsing is NEVER done here — that lives in the adapter's
+ * ExternalTaskProvider implementation.
  */
 
 import type {
   DataAccessor,
   ExternalTask,
+  ExternalTaskLink,
   ReconcileAction,
   ReconcileOptions,
   ReconcileResult,
-  SyncSessionState,
   Task,
 } from '@cleocode/contracts';
 import { getAccessor } from '../store/data-accessor.js';
 import { addTask } from '../tasks/add.js';
 import { completeTask } from '../tasks/complete.js';
 import { updateTask } from '../tasks/update.js';
-import { clearSyncState, readSyncState } from './sync-state.js';
+import { createLink, getLinksByProvider, touchLink } from './link-store.js';
 
 // ---------------------------------------------------------------------------
 // Internal helpers
@@ -40,119 +42,120 @@ function buildTaskMap(tasks: Task[]): Map<string, Task> {
   return map;
 }
 
+/**
+ * Build a lookup map from external ID to existing link for the provider.
+ */
+function buildLinkMap(links: ExternalTaskLink[]): Map<string, ExternalTaskLink> {
+  const map = new Map<string, ExternalTaskLink>();
+  for (const link of links) {
+    map.set(link.externalId, link);
+  }
+  return map;
+}
+
 /**
  * Compute reconciliation actions by diffing external tasks against CLEO state.
  */
 function computeActions(
   externalTasks: ExternalTask[],
   taskMap: Map<string, Task>,
-  injectedIds: Set<string>,
+  linkMap: Map<string, ExternalTaskLink>,
 ): ReconcileAction[] {
   const actions: ReconcileAction[] = [];
-  const seenCleoIds = new Set<string>();
 
   for (const ext of externalTasks) {
-    // Case 1: External task maps to an existing CLEO task
-    if (ext.cleoTaskId) {
-      seenCleoIds.add(ext.cleoTaskId);
-      const cleoTask = taskMap.get(ext.cleoTaskId);
+    const existingLink = linkMap.get(ext.externalId);
+
+    if (existingLink) {
+      // External task has an existing link to a CLEO task
+      const cleoTask = taskMap.get(existingLink.taskId);
 
       if (!cleoTask) {
-        // Mapped to a CLEO ID that doesn't exist — skip
+        // Linked CLEO task was deleted — skip
         actions.push({
           type: 'skip',
-          cleoTaskId: ext.cleoTaskId,
+          cleoTaskId: existingLink.taskId,
           externalId: ext.externalId,
-          summary: `CLEO task ${ext.cleoTaskId} not found — skipping`,
+          summary: `Linked CLEO task ${existingLink.taskId} no longer exists — skipping`,
           applied: false,
         });
         continue;
       }
 
-      // Already done in CLEO — skip
+      // Already terminal in CLEO — skip
       if (cleoTask.status === 'done' || cleoTask.status === 'cancelled') {
         actions.push({
           type: 'skip',
-          cleoTaskId: ext.cleoTaskId,
+          cleoTaskId: cleoTask.id,
           externalId: ext.externalId,
-          summary: `CLEO task ${ext.cleoTaskId} already ${cleoTask.status}`,
+          summary: `CLEO task ${cleoTask.id} already ${cleoTask.status}`,
           applied: false,
         });
         continue;
       }
 
-      // External says completed
+      // External says completed → complete CLEO task
       if (ext.status === 'completed') {
         actions.push({
           type: 'complete',
-          cleoTaskId: ext.cleoTaskId,
+          cleoTaskId: cleoTask.id,
           externalId: ext.externalId,
-          summary: `Complete ${ext.cleoTaskId} (${cleoTask.title})`,
+          summary: `Complete ${cleoTask.id} (${cleoTask.title})`,
           applied: false,
+          linkId: existingLink.id,
         });
         continue;
       }
 
-      // External says active, CLEO is pending/blocked
+      // External says active, CLEO is pending/blocked → activate
       if (
         ext.status === 'active' &&
         (cleoTask.status === 'pending' || cleoTask.status === 'blocked')
       ) {
         actions.push({
           type: 'activate',
-          cleoTaskId: ext.cleoTaskId,
+          cleoTaskId: cleoTask.id,
           externalId: ext.externalId,
-          summary: `Activate ${ext.cleoTaskId} (${cleoTask.title})`,
+          summary: `Activate ${cleoTask.id} (${cleoTask.title})`,
           applied: false,
+          linkId: existingLink.id,
         });
         continue;
       }
 
-      // External says removed
-      if (ext.status === 'removed') {
+      // Check if title or other properties changed → update
+      if (ext.title !== cleoTask.title) {
         actions.push({
-          type: 'remove',
-          cleoTaskId: ext.cleoTaskId,
+          type: 'update',
+          cleoTaskId: cleoTask.id,
           externalId: ext.externalId,
-          summary: `Task ${ext.cleoTaskId} removed from provider`,
+          summary: `Update ${cleoTask.id} title: "${cleoTask.title}" → "${ext.title}"`,
           applied: false,
+          linkId: existingLink.id,
         });
         continue;
       }
 
-      // No change needed
+      // No change needed — just touch the link timestamp
       actions.push({
         type: 'skip',
-        cleoTaskId: ext.cleoTaskId,
-        externalId: ext.externalId,
-        summary: `No change needed for ${ext.cleoTaskId}`,
-        applied: false,
-      });
-      continue;
-    }
-
-    // Case 2: New task (no cleoTaskId)
-    if (ext.status !== 'removed') {
-      actions.push({
-        type: 'create',
-        cleoTaskId: null,
+        cleoTaskId: cleoTask.id,
         externalId: ext.externalId,
-        summary: `Create new task: ${ext.title}`,
-        applied: false,
-      });
-    }
-  }
-
-  // Case 3: Injected tasks that are no longer present in external state
-  for (const injectedId of injectedIds) {
-    if (!seenCleoIds.has(injectedId)) {
-      actions.push({
-        type: 'remove',
-        cleoTaskId: injectedId,
-        externalId: `injected:${injectedId}`,
-        summary: `Injected task ${injectedId} no longer in provider`,
+        summary: `No change needed for ${cleoTask.id}`,
         applied: false,
+        linkId: existingLink.id,
       });
+    } else {
+      // No existing link — this is a new external task
+      if (ext.status !== 'removed') {
+        actions.push({
+          type: 'create',
+          cleoTaskId: null,
+          externalId: ext.externalId,
+          summary: `Create new task: ${ext.title}`,
+          applied: false,
+        });
+      }
     }
   }
 
@@ -183,39 +186,40 @@ export async function reconcile(
   const { tasks: allTasks } = await acc.queryTasks({});
   const taskMap = buildTaskMap(allTasks);
 
-  // Load sync session state for this provider
-  const syncState: SyncSessionState | null = await readSyncState(providerId, cwd);
-  const injectedIds = new Set(syncState?.injectedTaskIds ?? []);
+  // Load existing links for this provider
+  const existingLinks = await getLinksByProvider(providerId, cwd);
+  const linkMap = buildLinkMap(existingLinks);
 
   // Compute actions
-  const actions = computeActions(externalTasks, taskMap, injectedIds);
+  const actions = computeActions(externalTasks, taskMap, linkMap);
 
   // Summary counters
   const summary = {
+    created: 0,
+    updated: 0,
     completed: 0,
     activated: 0,
-    created: 0,
-    removed: 0,
     skipped: 0,
     conflicts: 0,
+    total: actions.length,
     applied: 0,
   };
 
   // Count by type
   for (const action of actions) {
     switch (action.type) {
+      case 'create':
+        summary.created++;
+        break;
+      case 'update':
+        summary.updated++;
+        break;
       case 'complete':
         summary.completed++;
         break;
       case 'activate':
         summary.activated++;
         break;
-      case 'create':
-        summary.created++;
-        break;
-      case 'remove':
-        summary.removed++;
-        break;
       case 'skip':
         summary.skipped++;
         break;
@@ -225,10 +229,17 @@ export async function reconcile(
     }
   }
 
+  let linksAffected = 0;
+
   // Apply actions if not dry-run
   if (!dryRun) {
     for (const action of actions) {
       if (action.type === 'skip' || action.type === 'conflict') {
+        // Touch link timestamps for skipped items that have links
+        if (action.linkId) {
+          const ext = externalTasks.find((e) => e.externalId === action.externalId);
+          await touchLink(action.linkId, { externalTitle: ext?.title }, cwd);
+        }
         continue;
       }
 
@@ -238,11 +249,15 @@ export async function reconcile(
             await completeTask(
               {
                 taskId: action.cleoTaskId!,
-                notes: `Completed via ${providerId} task sync`,
+                notes: `Completed via ${providerId} sync`,
               },
               cwd,
               acc,
             );
+            if (action.linkId) {
+              await touchLink(action.linkId, undefined, cwd);
+              linksAffected++;
+            }
             action.applied = true;
             summary.applied++;
             break;
@@ -253,39 +268,80 @@ export async function reconcile(
               {
                 taskId: action.cleoTaskId!,
                 status: 'active',
-                notes: `Activated during ${providerId} task sync`,
+                notes: `Activated via ${providerId} sync`,
               },
               cwd,
               acc,
             );
+            if (action.linkId) {
+              await touchLink(action.linkId, undefined, cwd);
+              linksAffected++;
+            }
             action.applied = true;
             summary.applied++;
             break;
           }
 
-          case 'create': {
-            // Find the external task for metadata
+          case 'update': {
             const ext = externalTasks.find((e) => e.externalId === action.externalId);
             if (!ext) break;
 
-            await addTask(
+            await updateTask(
               {
+                taskId: action.cleoTaskId!,
                 title: ext.title,
-                description: ext.description ?? `Created during ${providerId} task sync`,
-                labels: [...(defaultLabels ?? []), ...(ext.labels ?? []), 'sync-created'],
-                ...(defaultPhase ? { phase: defaultPhase, addPhase: true } : {}),
+                notes: `Updated via ${providerId} sync`,
               },
               cwd,
               acc,
             );
+            if (action.linkId) {
+              await touchLink(action.linkId, { externalTitle: ext.title }, cwd);
+              linksAffected++;
+            }
             action.applied = true;
             summary.applied++;
             break;
           }
 
-          case 'remove': {
-            // Removals are informational — we don't delete CLEO tasks
-            // just because a provider removed them. Log but don't act.
+          case 'create': {
+            const ext = externalTasks.find((e) => e.externalId === action.externalId);
+            if (!ext) break;
+
+            const result = await addTask(
+              {
+                title: ext.title,
+                description: ext.description ?? `Synced from ${providerId}`,
+                priority: ext.priority,
+                type: ext.type,
+                labels: [...(defaultLabels ?? []), ...(ext.labels ?? []), `sync:${providerId}`],
+                ...(defaultPhase ? { phase: defaultPhase, addPhase: true } : {}),
+              },
+              cwd,
+              acc,
+            );
+
+            // Create a link to track this external → CLEO task mapping
+            const newTaskId = result.task.id;
+            if (newTaskId) {
+              const link = await createLink(
+                {
+                  taskId: newTaskId,
+                  providerId,
+                  externalId: ext.externalId,
+                  externalUrl: ext.url,
+                  externalTitle: ext.title,
+                  linkType: 'created',
+                  syncDirection: 'inbound',
+                  metadata: ext.providerMeta,
+                },
+                cwd,
+              );
+              action.cleoTaskId = newTaskId;
+              action.linkId = link.id;
+              linksAffected++;
+            }
+
             action.applied = true;
             summary.applied++;
             break;
@@ -295,9 +351,6 @@ export async function reconcile(
         action.error = err instanceof Error ? err.message : String(err);
       }
     }
-
-    // Clear sync session state after successful apply
-    await clearSyncState(providerId, cwd);
   }
 
   return {
@@ -305,6 +358,6 @@ export async function reconcile(
     providerId,
     actions,
     summary,
-    sessionCleared: !dryRun,
+    linksAffected,
   };
 }

package/src/release/release-manifest.ts

@@ -95,6 +95,51 @@ function isValidVersion(version: string): boolean {
   return /^v?\d+\.\d+\.\d+(-[\w.]+)?(\+[\w.]+)?$/.test(version);
 }
 
+function validateCalVerWindow(
+  version: string,
+  now = new Date(),
+): { valid: boolean; message: string } {
+  const normalized = version.startsWith('v') ? version.slice(1) : version;
+  const base = normalized.split('-')[0] ?? normalized;
+  const parts = base.split('.');
+
+  if (parts.length !== 3) {
+    return { valid: false, message: `Invalid CalVer format: ${version}` };
+  }
+
+  const tagYear = Number.parseInt(parts[0] ?? '', 10);
+  const tagMonth = Number.parseInt(parts[1] ?? '', 10);
+  if (!Number.isInteger(tagYear) || !Number.isInteger(tagMonth)) {
+    return { valid: false, message: `Invalid CalVer date components: ${version}` };
+  }
+
+  const currentYear = now.getUTCFullYear();
+  const currentMonth = now.getUTCMonth() + 1;
+  const nextMonth = currentMonth === 12 ? 1 : currentMonth + 1;
+  const nextYear = currentMonth === 12 ? currentYear + 1 : currentYear;
+
+  const isPreRelease = normalized.includes('-');
+  if (isPreRelease) {
+    const valid =
+      (tagYear === currentYear || tagYear === nextYear) &&
+      (tagMonth === currentMonth || tagMonth === nextMonth);
+    return {
+      valid,
+      message: valid
+        ? `CalVer OK (pre-release): ${version}`
+        : `Pre-release ${version} outside allowed CalVer range ${currentYear}.${currentMonth} or ${nextYear}.${nextMonth}`,
+    };
+  }
+
+  const valid = tagYear === currentYear && tagMonth === currentMonth;
+  return {
+    valid,
+    message: valid
+      ? `CalVer OK (stable): ${version}`
+      : `${version} does not match current CalVer ${currentYear}.${currentMonth}`,
+  };
+}
+
 function normalizeVersion(version: string): string {
   return version.startsWith('v') ? version : `v${version}`;
 }
@@ -723,6 +768,16 @@ export async function runReleaseGates(
       : 'Invalid version format',
   });
 
+  const releaseConfig = loadReleaseConfig(cwd);
+  if (releaseConfig.versioningScheme === 'calver') {
+    const calver = validateCalVerWindow(normalizedVersion);
+    gates.push({
+      name: 'calver_window',
+      status: calver.valid ? 'passed' : 'failed',
+      message: calver.message,
+    });
+  }
+
   gates.push({
     name: 'has_tasks',
     status: releaseTasks.length > 0 ? 'passed' : 'failed',
@@ -824,7 +879,6 @@ export async function runReleaseGates(
     /* git not available — skip */
   }
 
-  const releaseConfig = loadReleaseConfig(cwd);
   const gitFlowCfg = getGitFlowConfig(releaseConfig);
   const channelCfg = getChannelConfig(releaseConfig);
 

package/src/routing/capability-matrix.ts

@@ -101,6 +101,10 @@ const CAPABILITY_MATRIX: OperationCapability[] = [
   { domain: 'tasks', operation: 'relates.add', gateway: 'mutate', mode: 'native' },
   { domain: 'tasks', operation: 'start', gateway: 'mutate', mode: 'native' },
   { domain: 'tasks', operation: 'stop', gateway: 'mutate', mode: 'native' },
+  // Sync sub-domain (provider-agnostic task reconciliation)
+  { domain: 'tasks', operation: 'sync.reconcile', gateway: 'mutate', mode: 'native' },
+  { domain: 'tasks', operation: 'sync.links', gateway: 'query', mode: 'native' },
+  { domain: 'tasks', operation: 'sync.links.remove', gateway: 'mutate', mode: 'native' },
 
   // === Session Domain ===
   // Query operations
@@ -278,11 +282,6 @@ const CAPABILITY_MATRIX: OperationCapability[] = [
   { domain: 'tools', operation: 'provider.supports', gateway: 'query', mode: 'native' },
   { domain: 'tools', operation: 'provider.hooks', gateway: 'query', mode: 'native' },
   { domain: 'tools', operation: 'provider.inject', gateway: 'mutate', mode: 'native' },
-  // TodoWrite operations
-  { domain: 'tools', operation: 'todowrite.status', gateway: 'query', mode: 'native' },
-  { domain: 'tools', operation: 'todowrite.sync', gateway: 'mutate', mode: 'native' },
-  { domain: 'tools', operation: 'todowrite.clear', gateway: 'mutate', mode: 'native' },
-
   // === Nexus Domain ===
   // Query operations
   { domain: 'nexus', operation: 'status', gateway: 'query', mode: 'native' },

package/src/store/tasks-schema.ts

@@ -645,6 +645,56 @@ export const adrRelations = sqliteTable(
   (table) => [primaryKey({ columns: [table.fromAdrId, table.toAdrId, table.relationType] })],
 );
 
+// === EXTERNAL TASK LINKS (provider-agnostic task reconciliation) ===
+
+/**
+ * Tracks links between CLEO tasks and external system tasks (Linear, Jira, GitHub, etc.).
+ * Used by the reconciliation engine to match external tasks to existing CLEO tasks,
+ * detect updates, and maintain bidirectional traceability.
+ *
+ * Each row represents one link: one CLEO task ↔ one external task from one provider.
+ * A CLEO task MAY have links from multiple providers (e.g., both Linear and GitHub).
+ * An external task SHOULD have at most one link per provider.
+ */
+export const externalTaskLinks = sqliteTable(
+  'external_task_links',
+  {
+    id: text('id').primaryKey(),
+    taskId: text('task_id')
+      .notNull()
+      .references(() => tasks.id, { onDelete: 'cascade' }),
+    /** Provider identifier (e.g. 'linear', 'jira', 'github', 'gitlab'). */
+    providerId: text('provider_id').notNull(),
+    /** Provider-assigned identifier for the external task (opaque to CLEO). */
+    externalId: text('external_id').notNull(),
+    /** Optional URL to the external task (for human navigation). */
+    externalUrl: text('external_url'),
+    /** Title of the external task at the time of last sync. */
+    externalTitle: text('external_title'),
+    /** How this link was established. */
+    linkType: text('link_type', {
+      enum: ['created', 'matched', 'manual'],
+    }).notNull(),
+    /** Direction of the sync that created this link. */
+    syncDirection: text('sync_direction', {
+      enum: ['inbound', 'outbound', 'bidirectional'],
+    })
+      .notNull()
+      .default('inbound'),
+    /** Arbitrary provider-specific metadata (JSON). */
+    metadataJson: text('metadata_json').default('{}'),
+    /** When the link was first established. */
+    linkedAt: text('linked_at').notNull().default(sql`(datetime('now'))`),
+    /** When the external task was last synchronized. */
+    lastSyncAt: text('last_sync_at'),
+  },
+  (table) => [
+    index('idx_ext_links_task_id').on(table.taskId),
+    index('idx_ext_links_provider_external').on(table.providerId, table.externalId),
+    index('idx_ext_links_provider_id').on(table.providerId),
+  ],
+);
+
 // === STATUS REGISTRY (ADR-018) ===
 
 export const statusRegistryTable = sqliteTable(
@@ -702,3 +752,5 @@ export type PipelineManifestRow = typeof pipelineManifest.$inferSelect;
 export type NewPipelineManifestRow = typeof pipelineManifest.$inferInsert;
 export type ReleaseManifestRow = typeof releaseManifests.$inferSelect;
 export type NewReleaseManifestRow = typeof releaseManifests.$inferInsert;
+export type ExternalTaskLinkRow = typeof externalTaskLinks.$inferSelect;
+export type NewExternalTaskLinkRow = typeof externalTaskLinks.$inferInsert;

package/src/task-work/index.ts

@@ -232,17 +232,3 @@ export async function getWorkHistory(
  * @task T5323
  */
 export const getTaskHistory = getWorkHistory;
-
-export type {
-  ChangeSet as TodoWriteChangeSet,
-  SyncSessionState,
-  TodoWriteItem,
-  TodoWriteMergeOptions,
-  TodoWriteMergeResult,
-  TodoWriteState,
-} from './todowrite-merge.js';
-// TodoWrite merge
-export {
-  analyzeChanges as analyzeTodoWriteChanges,
-  mergeTodoWriteState,
-} from './todowrite-merge.js';