@cleocode/core 2026.3.38 → 2026.3.40

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,56 +268,89 @@ 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;
           }
         }
       } catch (err) {
-        action.error =
-          err instanceof Error ? err.message : String(err);
+        action.error = err instanceof Error ? err.message : String(err);
       }
     }
-
-    // Clear sync session state after successful apply
-    await clearSyncState(providerId, cwd);
   }
 
   return {
@@ -310,6 +358,6 @@ export async function reconcile(
     providerId,
     actions,
     summary,
-    sessionCleared: !dryRun,
+    linksAffected,
   };
 }

package/src/release/__tests__/artifacts.test.d.ts

@@ -4,4 +4,4 @@
  * @epic T4545
  */
 export {};
-//# sourceMappingURL=artifacts.test.d.ts.map
+//# sourceMappingURL=artifacts.test.d.ts.map

package/src/release/__tests__/cancel-release.test.d.ts

@@ -7,4 +7,4 @@
  * @task T5602
  */
 export {};
-//# sourceMappingURL=cancel-release.test.d.ts.map
+//# sourceMappingURL=cancel-release.test.d.ts.map

package/src/release/__tests__/changelog-writer.test.d.ts

@@ -3,4 +3,4 @@
  * @task T5579
  */
 export {};
-//# sourceMappingURL=changelog-writer.test.d.ts.map
+//# sourceMappingURL=changelog-writer.test.d.ts.map

package/src/release/__tests__/push-policy.test.d.ts

@@ -11,4 +11,4 @@
  * @task T4276
  */
 export {};
-//# sourceMappingURL=push-policy.test.d.ts.map
+//# sourceMappingURL=push-policy.test.d.ts.map

package/src/release/__tests__/release.test.d.ts

@@ -8,4 +8,4 @@
  * Release operations now route through release-engine.ts via the dispatch layer.
  */
 export {};
-//# sourceMappingURL=release.test.d.ts.map
+//# sourceMappingURL=release.test.d.ts.map

package/src/release/guards.ts

@@ -8,9 +8,9 @@
  * @epic T4454
  */
 
+import type { Task, TaskRef } from '@cleocode/contracts';
 import type { DataAccessor } from '../store/data-accessor.js';
 import { getAccessor } from '../store/data-accessor.js';
-import type { Task, TaskRef } from '@cleocode/contracts';
 
 /** Epic completeness result. */
 export interface EpicCompletenessResult {

package/src/release/release-manifest.ts

@@ -13,9 +13,9 @@ import { existsSync, renameSync } from 'node:fs';
 import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { and, count, desc, eq } from 'drizzle-orm';
-import * as schema from '../store/tasks-schema.js';
 import { createPage } from '../pagination.js';
 import { getCleoDirAbsolute, getProjectRoot } from '../paths.js';
+import * as schema from '../store/tasks-schema.js';
 import { parseChangelogBlocks, writeChangelogSection } from './changelog-writer.js';
 import type { ReleaseChannel } from './channel.js';
 import { resolveChannelFromBranch } from './channel.js';
@@ -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',
@@ -764,9 +819,7 @@ export async function runReleaseGates(
     gates.push({
       name: 'build_artifact',
       status: distExists ? 'passed' : 'failed',
-      message: distExists
-        ? 'Build artifacts present'
-        : 'dist/ not built — run: pnpm run build',
+      message: distExists ? 'Build artifacts present' : 'dist/ not built — run: pnpm run build',
     });
   }
 
@@ -826,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/remote/index.ts

@@ -11,12 +11,8 @@
 import { execFile } from 'node:child_process';
 import { resolve } from 'node:path';
 import { promisify } from 'node:util';
-import {
-  cleoGitCommand,
-  isCleoGitInitialized,
-  makeCleoGitEnv,
-} from '../store/git-checkpoint.js';
 import { getCleoDirAbsolute } from '../paths.js';
+import { cleoGitCommand, isCleoGitInitialized, makeCleoGitEnv } from '../store/git-checkpoint.js';
 
 const execFileAsync = promisify(execFile);
 

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/scaffold.ts

@@ -17,9 +17,9 @@ import { access, mkdir, readFile, writeFile } from 'node:fs/promises';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { promisify } from 'node:util';
-import { saveJson } from './store/json.js';
 import { generateProjectHash } from './nexus/hash.js';
 import { getCleoDirAbsolute, getCleoHome, getCleoTemplatesDir, getConfigPath } from './paths.js';
+import { saveJson } from './store/json.js';
 
 const execFileAsync = promisify(execFile);
 
@@ -528,7 +528,11 @@ export async function ensureProjectContext(
     if (existsSync(schemaPath)) {
       const AjvModule = await import('ajv');
       const ajvMod = AjvModule as Record<string, unknown>;
-      const AjvClass = (typeof ajvMod.default === 'function' ? ajvMod.default : AjvModule.default) as new (opts?: Record<string, unknown>) => { validate(schema: unknown, data: unknown): boolean; errors?: unknown[] | null };
+      const AjvClass = (
+        typeof ajvMod.default === 'function' ? ajvMod.default : AjvModule.default
+      ) as new (
+        opts?: Record<string, unknown>,
+      ) => { validate(schema: unknown, data: unknown): boolean; errors?: unknown[] | null };
       const schema = JSON.parse(readFileSync(schemaPath, 'utf-8'));
       const ajv = new AjvClass({ strict: false });
       const valid = ajv.validate(schema, context);

package/src/security/input-sanitization.ts

@@ -12,13 +12,13 @@
  * @epic T3125
  */
 
-import { isAbsolute, normalize, relative, resolve } from 'path';
 import {
   LIFECYCLE_STAGE_STATUSES,
   MANIFEST_STATUSES,
   SESSION_STATUSES,
   TASK_STATUSES,
 } from '@cleocode/contracts';
+import { isAbsolute, normalize, relative, resolve } from 'path';
 import { TASK_PRIORITIES } from '../store/tasks-schema.js';
 import { normalizeTaskId } from '../tasks/id-generator.js';
 

package/src/sequence/__tests__/allocate.test.d.ts

@@ -3,4 +3,4 @@
  * @task T5184
  */
 export {};
-//# sourceMappingURL=allocate.test.d.ts.map
+//# sourceMappingURL=allocate.test.d.ts.map

package/src/sequence/index.ts

@@ -6,12 +6,12 @@
 
 import { existsSync, readFileSync, renameSync } from 'node:fs';
 import { join } from 'node:path';
+import type { Task } from '@cleocode/contracts';
+import { ExitCode } from '@cleocode/contracts';
+import { CleoError } from '../errors.js';
 import { createDataAccessor, type DataAccessor } from '../store/data-accessor.js';
 import { setMetaValue } from '../store/sqlite-data-accessor.js';
 import { schemaMeta } from '../store/tasks-schema.js';
-import { ExitCode } from '@cleocode/contracts';
-import type { Task } from '@cleocode/contracts';
-import { CleoError } from '../errors.js';
 
 const SEQUENCE_META_KEY = 'task_id_sequence';
 
@@ -172,7 +172,10 @@ export async function showSequence(cwd?: string): Promise<Record<string, unknown
   };
 }
 
-async function loadAllTasks(cwd?: string, accessor?: DataAccessor): Promise<Array<Pick<Task, 'id'>>> {
+async function loadAllTasks(
+  cwd?: string,
+  accessor?: DataAccessor,
+): Promise<Array<Pick<Task, 'id'>>> {
   let localAccessor: DataAccessor | null = null;
   const activeAccessor = accessor ?? (await createDataAccessor(undefined, cwd));
   if (!accessor) {

package/src/sessions/__tests__/briefing-blocked.test.d.ts

@@ -3,4 +3,4 @@
  * @task T5069
  */
 export {};
-//# sourceMappingURL=briefing-blocked.test.d.ts.map
+//# sourceMappingURL=briefing-blocked.test.d.ts.map