@cleocode/contracts 2.0.0

package/dist/status-registry.js

@@ -0,0 +1,125 @@
+/**
+ * Unified Status Registry — single source of truth for all status enums.
+ *
+ * ADR-018: All status constants and types MUST be defined here.
+ * No other file may define status enum arrays as constants.
+ *
+ * Dependency direction:
+ *   status-registry.ts → schema.ts, types/task.ts, validation/engine.ts,
+ *                         mcp/lib/security.ts, dispatch/lib/security.ts, ...
+ */
+// === WORKFLOW NAMESPACE ===
+// Statuses for entities representing work being performed.
+export const TASK_STATUSES = [
+    'pending',
+    'active',
+    'blocked',
+    'done',
+    'cancelled',
+    'archived',
+];
+export const SESSION_STATUSES = ['active', 'ended', 'orphaned', 'suspended'];
+export const LIFECYCLE_PIPELINE_STATUSES = [
+    'active',
+    'completed',
+    'blocked',
+    'failed',
+    'cancelled',
+    'aborted',
+];
+export const LIFECYCLE_STAGE_STATUSES = [
+    'not_started',
+    'in_progress',
+    'blocked',
+    'completed',
+    'skipped',
+    'failed',
+];
+// === GOVERNANCE NAMESPACE ===
+// Statuses for decisions and approvals.
+export const ADR_STATUSES = ['proposed', 'accepted', 'superseded', 'deprecated'];
+export const GATE_STATUSES = ['pending', 'passed', 'failed', 'waived'];
+// === MANIFEST NAMESPACE ===
+// Statuses for protocol output artifacts.
+// NOTE: 'complete' was the old value — it is now 'completed' everywhere.
+export const MANIFEST_STATUSES = ['completed', 'partial', 'blocked', 'archived'];
+// === TERMINAL STATE SETS ===
+export const TERMINAL_TASK_STATUSES = new Set([
+    'done',
+    'cancelled',
+    'archived',
+]);
+export const TERMINAL_PIPELINE_STATUSES = new Set([
+    'completed',
+    'failed',
+    'cancelled',
+    'aborted',
+]);
+export const TERMINAL_STAGE_STATUSES = new Set([
+    'completed',
+    'skipped',
+    'failed',
+]);
+export const STATUS_REGISTRY = {
+    task: TASK_STATUSES,
+    session: SESSION_STATUSES,
+    lifecycle_pipeline: LIFECYCLE_PIPELINE_STATUSES,
+    lifecycle_stage: LIFECYCLE_STAGE_STATUSES,
+    adr: ADR_STATUSES,
+    gate: GATE_STATUSES,
+    manifest: MANIFEST_STATUSES,
+};
+export function isValidStatus(entityType, value) {
+    return STATUS_REGISTRY[entityType].includes(value);
+}
+// === DISPLAY ICONS ===
+// Typed Record maps — exhaustiveness is enforced by the compiler.
+// All icon consumers MUST import from here instead of hardcoding comparisons.
+/**
+ * Pipeline status → Unicode progress icon.
+ * Used wherever lifecycle pipeline status is rendered to a terminal.
+ */
+export const PIPELINE_STATUS_ICONS = {
+    active: '\u25b6', // pipeline is running
+    completed: '\u2713', // all stages done successfully
+    blocked: '\u23f8', // cannot advance; waiting
+    failed: '\u2717', // terminal failure
+    cancelled: '\u2298', // user-initiated abandonment
+    aborted: '\u23f9', // system-forced termination
+};
+/**
+ * Stage status → Unicode progress icon.
+ * Used wherever pipeline stage status is rendered to a terminal.
+ */
+export const STAGE_STATUS_ICONS = {
+    not_started: '\u23f9', // not yet entered
+    in_progress: '\u25b6', // actively running
+    blocked: '\u23f8', // paused / waiting
+    completed: '\u2713', // finished successfully
+    skipped: '\u23ed', // intentionally bypassed
+    failed: '\u2717', // terminal failure
+};
+/**
+ * Task status → Unicode symbol (rich terminal / Unicode-enabled).
+ * Falls back to TASK_STATUS_SYMBOLS_ASCII when Unicode is unavailable.
+ */
+export const TASK_STATUS_SYMBOLS_UNICODE = {
+    pending: '\u25cb', // ○  not yet started
+    active: '\u25c9', // ◉  in progress
+    blocked: '\u2297', // ⊗  cannot advance
+    done: '\u2713', // ✓  complete
+    cancelled: '\u2717', // ✗  abandoned
+    archived: '\u25a3', // ▣  stored, inactive
+};
+/**
+ * Task status → ASCII fallback symbol (non-Unicode terminals, CI output).
+ */
+export const TASK_STATUS_SYMBOLS_ASCII = {
+    pending: '-',
+    active: '*',
+    blocked: 'x',
+    done: '+',
+    cancelled: '~',
+    archived: '#',
+};
+//# sourceMappingURL=status-registry.js.map

package/dist/status-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"status-registry.js","sourceRoot":"","sources":["../src/status-registry.ts"],"names":[],"mappings":"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"}

package/dist/task-record.d.ts

@@ -0,0 +1,67 @@
+/**
+ * TaskRecord — string-widened version of Task for JSON serialization in dispatch/LAFS layer.
+ *
+ * Union-typed fields (status, priority, origin, etc.) are widened to string
+ * so that the dispatch layer does not need to validate enum membership.
+ *
+ * @task T4657
+ * @epic T4654
+ */
+import type { TaskVerification } from './task.js';
+/** A single task relation entry (string-widened version). */
+export interface TaskRecordRelation {
+    taskId: string;
+    type: string;
+    reason?: string;
+}
+/** Validation history entry. */
+export interface ValidationHistoryEntry {
+    round: number;
+    agent: string;
+    result: string;
+    timestamp: string;
+}
+/** String-widened Task for JSON serialization in dispatch/LAFS layer. */
+export interface TaskRecord {
+    id: string;
+    title: string;
+    description: string;
+    status: string;
+    priority: string;
+    type?: string;
+    phase?: string;
+    createdAt: string;
+    updatedAt: string | null;
+    completedAt?: string | null;
+    cancelledAt?: string | null;
+    parentId?: string | null;
+    position?: number | null;
+    positionVersion?: number;
+    depends?: string[];
+    relates?: TaskRecordRelation[];
+    files?: string[];
+    acceptance?: string[];
+    notes?: string[];
+    labels?: string[];
+    size?: string | null;
+    epicLifecycle?: string | null;
+    noAutoComplete?: boolean | null;
+    verification?: TaskVerification | null;
+    origin?: string | null;
+    createdBy?: string | null;
+    validatedBy?: string | null;
+    testedBy?: string | null;
+    lifecycleState?: string | null;
+    validationHistory?: ValidationHistoryEntry[];
+    blockedBy?: string[];
+    cancellationReason?: string;
+}
+/** Minimal task representation for find results. */
+export interface MinimalTaskRecord {
+    id: string;
+    title: string;
+    status: string;
+    priority: string;
+    parentId?: string | null;
+}
+//# sourceMappingURL=task-record.d.ts.map

package/dist/task-record.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"task-record.d.ts","sourceRoot":"","sources":["../src/task-record.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAElD,6DAA6D;AAC7D,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,gCAAgC;AAChC,MAAM,WAAW,sBAAsB;IACrC,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,yEAAyE;AACzE,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,OAAO,CAAC,EAAE,kBAAkB,EAAE,CAAC;IAC/B,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,cAAc,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IAChC,YAAY,CAAC,EAAE,gBAAgB,GAAG,IAAI,CAAC;IACvC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,iBAAiB,CAAC,EAAE,sBAAsB,EAAE,CAAC;IAC7C,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,oDAAoD;AACpD,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B"}

package/dist/task-record.js

@@ -0,0 +1,11 @@
+/**
+ * TaskRecord — string-widened version of Task for JSON serialization in dispatch/LAFS layer.
+ *
+ * Union-typed fields (status, priority, origin, etc.) are widened to string
+ * so that the dispatch layer does not need to validate enum membership.
+ *
+ * @task T4657
+ * @epic T4654
+ */
+export {};
+//# sourceMappingURL=task-record.js.map

package/dist/task-record.js.map

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

package/dist/task-sync.d.ts

@@ -0,0 +1,143 @@
+/**
+ * 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
+ */
+/** 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>;
+}
+/**
+ * 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;
+}
+/**
+ * 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';
+/** 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;
+}
+/**
+ * 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>;
+}
+//# sourceMappingURL=task-sync.d.ts.map

package/dist/task-sync.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"task-sync.d.ts","sourceRoot":"","sources":["../src/task-sync.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAMH,oEAAoE;AACpE,MAAM,MAAM,kBAAkB,GAAG,SAAS,GAAG,QAAQ,GAAG,WAAW,GAAG,SAAS,CAAC;AAEhF;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,mEAAmE;IACnE,UAAU,EAAE,MAAM,CAAC;IACnB,mEAAmE;IACnE,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,4BAA4B;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,yBAAyB;IACzB,MAAM,EAAE,kBAAkB,CAAC;IAC3B,iCAAiC;IACjC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,8CAA8C;IAC9C,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,6DAA6D;IAC7D,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACxC;AAMD;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,sEAAsE;IACtE,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,uDAAuD;IACvD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,2CAA2C;IAC3C,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAClD,2DAA2D;IAC3D,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAMD;;;;;;;GAOG;AACH,MAAM,MAAM,cAAc,GAAG,WAAW,GAAG,eAAe,GAAG,aAAa,GAAG,aAAa,CAAC;AAM3F,6CAA6C;AAC7C,MAAM,WAAW,gBAAgB;IAC/B,kDAAkD;IAClD,UAAU,EAAE,MAAM,CAAC;IACnB,wCAAwC;IACxC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,sDAAsD;IACtD,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,2DAA2D;IAC3D,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC,6CAA6C;IAC7C,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,8CAA8C;IAC9C,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;CAC1B;AAED,8DAA8D;AAC9D,MAAM,MAAM,mBAAmB,GAAG,UAAU,GAAG,UAAU,GAAG,QAAQ,GAAG,QAAQ,GAAG,MAAM,GAAG,UAAU,CAAC;AAEtG,2DAA2D;AAC3D,MAAM,WAAW,eAAe;IAC9B,2BAA2B;IAC3B,IAAI,EAAE,mBAAmB,CAAC;IAC1B,uEAAuE;IACvE,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,oDAAoD;IACpD,UAAU,EAAE,MAAM,CAAC;IACnB,gDAAgD;IAChD,OAAO,EAAE,MAAM,CAAC;IAChB,gDAAgD;IAChD,OAAO,EAAE,OAAO,CAAC;IACjB,uDAAuD;IACvD,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,2CAA2C;AAC3C,MAAM,WAAW,eAAe;IAC9B,kCAAkC;IAClC,MAAM,EAAE,OAAO,CAAC;IAChB,oCAAoC;IACpC,UAAU,EAAE,MAAM,CAAC;IACnB,6CAA6C;IAC7C,OAAO,EAAE,eAAe,EAAE,CAAC;IAC3B,sBAAsB;IACtB,OAAO,EAAE;QACP,SAAS,EAAE,MAAM,CAAC;QAClB,SAAS,EAAE,MAAM,CAAC;QAClB,OAAO,EAAE,MAAM,CAAC;QAChB,OAAO,EAAE,MAAM,CAAC;QAChB,OAAO,EAAE,MAAM,CAAC;QAChB,SAAS,EAAE,MAAM,CAAC;QAClB,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC;IACF,0DAA0D;IAC1D,cAAc,EAAE,OAAO,CAAC;CACzB;AAMD;;;;;GAKG;AACH,MAAM,WAAW,uBAAuB;IACtC;;;;;OAKG;IACH,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAAC;IAE9D;;;;;;OAMG;IACH,aAAa,CAAC,CAAC,KAAK,EAAE,aAAa,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEvH;;;;OAIG;IACH,OAAO,CAAC,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7C"}

package/dist/task-sync.js

@@ -0,0 +1,11 @@
+/**
+ * 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
+ */
+export {};
+//# sourceMappingURL=task-sync.js.map

package/dist/task-sync.js.map

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

package/dist/task.d.ts

@@ -0,0 +1,294 @@
+/**
+ * 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 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;
+}
+/**
+ * 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[]>;
+}
+//# sourceMappingURL=task.d.ts.map