@cleocode/contracts 2.0.0

package/src/task-sync.ts

@@ -0,0 +1,167 @@
+/**
+ * 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
+ */
+
+// ---------------------------------------------------------------------------
+// External task representation (provider-agnostic)
+// ---------------------------------------------------------------------------
+
+/** Normalized status for tasks coming from an external provider. */
+export type ExternalTaskStatus = 'pending' | 'active' | 'completed' | 'removed';
+
+/**
+ * A task as reported by an external provider, normalized to a common shape.
+ * Provider-specific adapters translate their native format into this.
+ */
+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 labels/tags from the provider. */
+  labels?: string[];
+  /** Arbitrary provider-specific metadata (opaque to core). */
+  providerMeta?: Record<string, unknown>;
+}
+
+// ---------------------------------------------------------------------------
+// Sync session state
+// ---------------------------------------------------------------------------
+
+/**
+ * Persistent state for a sync session between CLEO and a provider.
+ * Stored per-provider under `.cleo/sync/<providerId>-session.json`.
+ */
+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;
+}
+
+// ---------------------------------------------------------------------------
+// Conflict resolution
+// ---------------------------------------------------------------------------
+
+/**
+ * Policy for resolving conflicts between CLEO and provider state.
+ *
+ * - `cleo-wins`: CLEO state takes precedence (default).
+ * - `provider-wins`: Provider state takes precedence.
+ * - `latest-wins`: Most recently modified value wins.
+ * - `report-only`: Report conflicts without applying changes.
+ */
+export type ConflictPolicy = 'cleo-wins' | 'provider-wins' | 'latest-wins' | 'report-only';
+
+// ---------------------------------------------------------------------------
+// Reconciliation options and results
+// ---------------------------------------------------------------------------
+
+/** Options for the reconciliation engine. */
+export interface ReconcileOptions {
+  /** Provider ID (e.g. 'claude-code', 'cursor'). */
+  providerId: string;
+  /** Working directory (project root). */
+  cwd?: string;
+  /** If true, compute actions without applying them. */
+  dryRun?: boolean;
+  /** Conflict resolution policy. Defaults to 'cleo-wins'. */
+  conflictPolicy?: ConflictPolicy;
+  /** Default phase for newly created tasks. */
+  defaultPhase?: string;
+  /** Default labels for newly created tasks. */
+  defaultLabels?: string[];
+}
+
+/** The type of action the reconciliation engine will take. */
+export type ReconcileActionType = 'complete' | 'activate' | 'create' | 'remove' | 'skip' | 'conflict';
+
+/** A single reconciliation action (planned or applied). */
+export interface ReconcileAction {
+  /** What kind of change. */
+  type: ReconcileActionType;
+  /** The CLEO task ID affected (null for creates before they happen). */
+  cleoTaskId: string | null;
+  /** The external task that triggered this action. */
+  externalId: string;
+  /** Human-readable description of the action. */
+  summary: string;
+  /** Whether this action was actually applied. */
+  applied: boolean;
+  /** Error message if the action failed during apply. */
+  error?: string;
+}
+
+/** Result of a full reconciliation run. */
+export interface ReconcileResult {
+  /** Whether this was a dry run. */
+  dryRun: boolean;
+  /** Provider that was reconciled. */
+  providerId: string;
+  /** Individual actions taken (or planned). */
+  actions: ReconcileAction[];
+  /** Summary counts. */
+  summary: {
+    completed: number;
+    activated: number;
+    created: number;
+    removed: number;
+    skipped: number;
+    conflicts: number;
+    applied: number;
+  };
+  /** Whether sync session state was cleared after apply. */
+  sessionCleared: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Provider adapter interface
+// ---------------------------------------------------------------------------
+
+/**
+ * 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.
+ */
+export interface AdapterTaskSyncProvider {
+  /**
+   * Read the provider's current task state and return normalized ExternalTasks.
+   *
+   * @param projectDir - Project root directory.
+   * @returns Array of external tasks in normalized form.
+   */
+  getExternalTasks(projectDir: string): Promise<ExternalTask[]>;
+
+  /**
+   * Optionally push CLEO task state back to the provider.
+   * 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>;
+}

package/src/task.ts

@@ -0,0 +1,387 @@
+/**
+ * Task type definitions matching todo.schema.json (v2.10.0).
+ *
+ * Consolidates types from src/types/task.ts and packages/contracts/src/task-types.ts.
+ *
+ * ## Type Safety Design
+ *
+ * - {@link Task} represents a fully-materialized task as stored in the database.
+ *   Fields that CLEO's anti-hallucination rules require at runtime are marked as
+ *   required (non-optional) so the type system enforces what the business rules demand.
+ *
+ * - {@link TaskCreate} represents the input for creating a new task. Only fields the
+ *   caller MUST supply are required; everything else has sensible defaults applied
+ *   by the `addTask` function.
+ *
+ * - {@link CompletedTask} and {@link CancelledTask} are discriminated union types
+ *   that narrow `Task` for status-specific contexts where additional fields become
+ *   required (e.g., `completedAt` is required when `status = 'done'`).
+ *
+ * @epic T4454
+ * @task T4456
+ */
+
+import type { TaskStatus } from './status-registry.js';
+export type { TaskStatus };
+
+/** Task priority levels. */
+export type TaskPriority = 'critical' | 'high' | 'medium' | 'low';
+
+/** Task type in hierarchy. */
+export type TaskType = 'epic' | 'task' | 'subtask';
+
+/** Task size (scope, NOT time). */
+export type TaskSize = 'small' | 'medium' | 'large';
+
+/** Epic lifecycle states. */
+export type EpicLifecycle = 'backlog' | 'planning' | 'active' | 'review' | 'released' | 'archived';
+
+/** Task origin (provenance). */
+export type TaskOrigin =
+  | 'internal'
+  | 'bug-report'
+  | 'feature-request'
+  | 'security'
+  | 'technical-debt'
+  | 'dependency'
+  | 'regression';
+
+/** Verification agent types. */
+export type VerificationAgent =
+  | 'planner'
+  | 'coder'
+  | 'testing'
+  | 'qa'
+  | 'cleanup'
+  | 'security'
+  | 'docs';
+
+/** Verification gate names. */
+export type VerificationGate =
+  | 'implemented'
+  | 'testsPassed'
+  | 'qaPassed'
+  | 'cleanupDone'
+  | 'securityPassed'
+  | 'documented';
+
+/** Verification failure log entry. */
+export interface VerificationFailure {
+  round: number;
+  agent: string;
+  reason: string;
+  timestamp: string;
+}
+
+/** Task verification state. */
+export interface TaskVerification {
+  passed: boolean;
+  round: number;
+  gates: Partial<Record<VerificationGate, boolean | null>>;
+  lastAgent: VerificationAgent | null;
+  lastUpdated: string | null;
+  failureLog: VerificationFailure[];
+}
+
+/** Task provenance tracking. */
+export interface TaskProvenance {
+  createdBy: string | null;
+  modifiedBy: string | null;
+  sessionId: string | null;
+}
+
+/** A single task relation entry. */
+export interface TaskRelation {
+  taskId: string;
+  type: string;
+  reason?: string;
+}
+
+/**
+ * A single CLEO task as stored in the database.
+ *
+ * Fields marked as required are enforced by CLEO's anti-hallucination validation
+ * at runtime. Making them required here ensures the type system catches violations
+ * at compile time rather than deferring to runtime checks.
+ */
+export interface Task {
+  /** Unique task identifier. Must match pattern `T\d{3,}` (e.g., T001, T5800). */
+  id: string;
+
+  /** Human-readable task title. Required, max 120 characters. */
+  title: string;
+
+  /**
+   * Task description. **Required** — CLEO's anti-hallucination rules reject tasks
+   * without a description, and require it to differ from the title.
+   */
+  description: string;
+
+  /** Current task status. Must be a valid {@link TaskStatus} enum value. */
+  status: TaskStatus;
+
+  /** Task priority level. Defaults to `'medium'` on creation. */
+  priority: TaskPriority;
+
+  /** Task type in hierarchy. Inferred from parent context if not specified. */
+  type?: TaskType;
+
+  /** ID of the parent task. `null` for root-level tasks. */
+  parentId?: string | null;
+
+  /** Sort position within sibling scope. */
+  position?: number | null;
+
+  /** Optimistic concurrency version for position changes. */
+  positionVersion?: number;
+
+  /** Relative scope sizing (small/medium/large). NOT a time estimate. */
+  size?: TaskSize | null;
+
+  /** Phase slug this task belongs to. */
+  phase?: string;
+
+  /** File paths associated with this task. */
+  files?: string[];
+
+  /** Acceptance criteria for completion. */
+  acceptance?: string[];
+
+  /** IDs of tasks this task depends on. */
+  depends?: string[];
+
+  /** Related task entries (non-dependency relationships). */
+  relates?: TaskRelation[];
+
+  /** Epic lifecycle state. Only meaningful when `type = 'epic'`. */
+  epicLifecycle?: EpicLifecycle | null;
+
+  /** When true, epic will not auto-complete when all children are done. */
+  noAutoComplete?: boolean | null;
+
+  /** Reason the task is blocked (free-form text). */
+  blockedBy?: string;
+
+  /** Timestamped notes appended during task lifecycle. */
+  notes?: string[];
+
+  /** Classification labels for filtering and grouping. */
+  labels?: string[];
+
+  /** Task origin/provenance category. */
+  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. */
+  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.
+   */
+  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.
+   */
+  cancelledAt?: string;
+
+  /**
+   * Reason for cancellation. Required when `status = 'cancelled'`.
+   * See {@link CancelledTask} for the status-narrowed type where this is required.
+   */
+  cancellationReason?: string;
+
+  /** Verification pipeline state. */
+  verification?: TaskVerification | null;
+
+  /** Provenance tracking (who created/modified, which session). */
+  provenance?: TaskProvenance | null;
+}
+
+// ---------------------------------------------------------------------------
+// Input types for task creation
+// ---------------------------------------------------------------------------
+
+/**
+ * Input type for creating a new task via `addTask()`.
+ *
+ * Only the fields the caller MUST provide are required. All other fields
+ * have sensible defaults applied by the creation logic:
+ * - `status` defaults to `'pending'`
+ * - `priority` defaults to `'medium'`
+ * - `type` is inferred from parent context
+ * - `size` defaults to `'medium'`
+ */
+export interface TaskCreate {
+  /** Human-readable task title. Required, max 120 characters. */
+  title: string;
+
+  /**
+   * Task description. **Required** — CLEO's anti-hallucination rules reject tasks
+   * without a description, and require it to differ from the title.
+   */
+  description: string;
+
+  /** Initial status. Defaults to `'pending'`. */
+  status?: TaskStatus;
+
+  /** Priority level. Defaults to `'medium'`. */
+  priority?: TaskPriority;
+
+  /** Task type. Inferred from parent context if not specified. */
+  type?: TaskType;
+
+  /** Parent task ID for hierarchy placement. */
+  parentId?: string | null;
+
+  /** Relative scope sizing. Defaults to `'medium'`. */
+  size?: TaskSize;
+
+  /** Phase slug to assign. Inherited from project.currentPhase if not specified. */
+  phase?: string;
+
+  /** Classification labels. */
+  labels?: string[];
+
+  /** File paths associated with this task. */
+  files?: string[];
+
+  /** Acceptance criteria. */
+  acceptance?: string[];
+
+  /** IDs of tasks this task depends on. */
+  depends?: string[];
+
+  /** Initial note to attach. */
+  notes?: string;
+
+  /** Sort position. Auto-calculated if not specified. */
+  position?: number;
+}
+
+// ---------------------------------------------------------------------------
+// Status-narrowed types (discriminated unions)
+// ---------------------------------------------------------------------------
+
+/**
+ * A task with `status = 'done'`. Narrows {@link Task} to require `completedAt`.
+ *
+ * Use this type when you need to guarantee a completed task has its completion
+ * timestamp — for example, in cycle-time calculations or archive operations.
+ */
+export type CompletedTask = Task & {
+  /** Discriminant: status is always `'done'` for a completed task. */
+  status: 'done';
+  /** ISO 8601 timestamp of completion. Required for done tasks. */
+  completedAt: string;
+};
+
+/**
+ * A task with `status = 'cancelled'`. Narrows {@link Task} to require
+ * `cancelledAt` and `cancellationReason`.
+ *
+ * Use this type when processing cancelled tasks where the cancellation
+ * metadata is guaranteed to be present.
+ */
+export type CancelledTask = Task & {
+  /** Discriminant: status is always `'cancelled'` for a cancelled task. */
+  status: 'cancelled';
+  /** ISO 8601 timestamp of cancellation. Required for cancelled tasks. */
+  cancelledAt: string;
+  /** Reason for cancellation. Required for cancelled tasks (min 5 chars). */
+  cancellationReason: string;
+};
+
+/** Phase status. */
+export type PhaseStatus = 'pending' | 'active' | 'completed';
+
+/** Phase definition. */
+export interface Phase {
+  order: number;
+  name: string;
+  description?: string;
+  status: PhaseStatus;
+  startedAt?: string | null;
+  completedAt?: string | null;
+}
+
+/** Phase transition record. */
+export interface PhaseTransition {
+  phase: string;
+  transitionType: 'started' | 'completed' | 'rollback';
+  timestamp: string;
+  taskCount: number;
+  fromPhase?: string | null;
+  reason?: string;
+}
+
+/** Release status. */
+export type ReleaseStatus = 'planned' | 'active' | 'released';
+
+/** Release definition. */
+export interface Release {
+  version: string;
+  status: ReleaseStatus;
+  targetDate?: string | null;
+  releasedAt?: string | null;
+  tasks: string[];
+  notes?: string | null;
+  changelog?: string | null;
+}
+
+/** Project metadata. */
+export interface ProjectMeta {
+  name: string;
+  currentPhase?: string | null;
+  phases: Record<string, Phase>;
+  phaseHistory?: PhaseTransition[];
+  releases?: Release[];
+}
+
+/** File metadata (_meta block). */
+export interface FileMeta {
+  schemaVersion: string;
+  specVersion?: string;
+  checksum: string;
+  configVersion: string;
+  lastSessionId?: string | null;
+  activeSession?: string | null;
+  activeSessionCount?: number;
+  sessionsFile?: string | null;
+  generation?: number;
+}
+
+/** Session note in taskWork block. */
+export interface SessionNote {
+  note: string;
+  timestamp: string;
+  conversationId?: string | null;
+  agent?: string | null;
+}
+
+/** Task work state. */
+export interface TaskWorkState {
+  currentTask?: string | null;
+  currentPhase?: string | null;
+  blockedUntil?: string | null;
+  sessionNote?: string | null;
+  sessionNotes?: SessionNote[];
+  nextAction?: string | null;
+  primarySession?: string | null;
+}
+
+/** Root task data structure. */
+export interface TaskFile {
+  version: string;
+  project: ProjectMeta;
+  lastUpdated: string;
+  _meta: FileMeta;
+  taskWork?: TaskWorkState;
+  focus?: TaskWorkState;
+  tasks: Task[];
+  labels?: Record<string, string[]>;
+}

package/src/tessera.ts

@@ -0,0 +1,35 @@
+/**
+ * Tessera Type Definitions
+ *
+ * Tessera templates extend WarpChain with variable bindings,
+ * archetype classification, and instantiation inputs for
+ * parameterized pipeline creation.
+ *
+ * @task T5408
+ */
+
+import type { WarpChain } from './warp-chain.js';
+
+/** A variable declaration within a Tessera template. */
+export interface TesseraVariable {
+  name: string;
+  type: 'string' | 'number' | 'boolean' | 'taskId' | 'epicId';
+  description: string;
+  required: boolean;
+  default?: unknown;
+}
+
+/** A parameterized WarpChain template with variable bindings. */
+export interface TesseraTemplate extends WarpChain {
+  variables: Record<string, TesseraVariable>;
+  archetypes: string[];
+  defaultValues: Record<string, unknown>;
+  category: 'lifecycle' | 'hotfix' | 'research' | 'security-audit' | 'custom';
+}
+
+/** Input for instantiating a Tessera template into a concrete chain. */
+export interface TesseraInstantiationInput {
+  templateId: string;
+  epicId: string;
+  variables: Record<string, unknown>;
+}

package/src/todowrite.ts

@@ -0,0 +1,58 @@
+/**
+ * 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;
+}

package/src/transport.ts

@@ -0,0 +1,12 @@
+/**
+ * Transport provider interface for CLEO provider adapters.
+ * Allows providers to supply custom inter-agent transport mechanisms.
+ * @task T5240
+ */
+
+export interface AdapterTransportProvider {
+  /** Create a transport instance for inter-agent communication */
+  createTransport(): unknown;
+  /** Name of this transport type for logging/debugging */
+  readonly transportName: string;
+}