interface Task extends Element {
  readonly type: 'task';
  
  // Content
  title: string;
  descriptionRef?: DocumentId;
  acceptanceCriteria?: string;
  
  // Workflow
  status: TaskStatus;
  priority: Priority;  // 1-5, 1 is highest
  complexity: Complexity;  // 1-5, 1 is simplest
  taskType: TaskTypeValue;
  closeReason?: string;
  
  // Assignment
  assignee?: EntityId;
  owner?: EntityId;
  
  // Scheduling
  deadline?: Timestamp;
  scheduledFor?: Timestamp;
  closedAt?: Timestamp;
  
  // Soft Delete
  deletedAt?: Timestamp;
  deletedBy?: EntityId;
  deleteReason?: string;
  
  // External Integration
  externalRef?: string;
}

const TaskStatus = {
  OPEN: 'open',              // Available for work
  IN_PROGRESS: 'in_progress', // Currently being worked on
  BLOCKED: 'blocked',         // Waiting on dependency
  DEFERRED: 'deferred',       // Deliberately postponed
  BACKLOG: 'backlog',         // Not ready, needs triage
  REVIEW: 'review',           // Awaiting merge/review
  CLOSED: 'closed',           // Completed and merged
  TOMBSTONE: 'tombstone',     // Soft-deleted
} as const;

// Status checks
isReadyForWork(task: Task): boolean
isBlocked(task: Task): boolean
isClosed(task: Task): boolean
isDeleted(task: Task): boolean
isBacklog(task: Task): boolean

// Display names
getStatusDisplayName(status: TaskStatus): string
// Returns: "Open", "In Progress", "Blocked", etc.

const Priority = {
  CRITICAL: 1,  // Production issues, security vulnerabilities
  HIGH: 2,      // Important features, significant bugs
  MEDIUM: 3,    // Standard work items (default)
  LOW: 4,       // Nice-to-have improvements
  MINIMAL: 5,   // Can be done when time permits
} as const;

type Priority = 1 | 2 | 3 | 4 | 5;

// Validate priority value
validatePriority(value: unknown): Priority

// Type guard
isValidPriority(value: unknown): value is Priority

// Display name
getPriorityDisplayName(priority: Priority): string
// Returns: "Critical", "High", "Medium", "Low", "Minimal"

const Complexity = {
  TRIVIAL: 1,      // Single-line changes, typo fixes
  SIMPLE: 2,       // Small, well-defined changes
  MEDIUM: 3,       // Moderate changes, some research needed
  COMPLEX: 4,      // Significant changes, multiple components
  VERY_COMPLEX: 5, // Large scope, architectural changes
} as const;

type Complexity = 1 | 2 | 3 | 4 | 5;

// Validate complexity value
validateComplexity(value: unknown): Complexity

// Type guard
isValidComplexity(value: unknown): value is Complexity

// Display name
getComplexityDisplayName(complexity: Complexity): string
// Returns: "Trivial", "Simple", "Medium", "Complex", "Very Complex"

const TaskTypeValue = {
  BUG: 'bug',         // Defect requiring fix
  FEATURE: 'feature', // New functionality
  TASK: 'task',       // General work item
  CHORE: 'chore',     // Maintenance, cleanup, technical debt
} as const;

type TaskTypeValue = 'bug' | 'feature' | 'task' | 'chore';

// Validate task type
validateTaskType(value: unknown): TaskTypeValue

// Type guard
isValidTaskType(value: unknown): value is TaskTypeValue

// Display name
getTaskTypeDisplayName(taskType: TaskTypeValue): string
// Returns: "Bug", "Feature", "Task", "Chore"

interface CreateTaskInput {
  title: string;
  createdBy: EntityId;
  
  // Optional fields
  id?: ElementId;  // Pre-generated ID for hierarchical tasks
  descriptionRef?: DocumentId;
  acceptanceCriteria?: string;
  status?: TaskStatus;  // default: 'open'
  priority?: Priority;  // default: 3
  complexity?: Complexity;  // default: 3
  taskType?: TaskTypeValue;  // default: 'task'
  assignee?: EntityId;
  owner?: EntityId;
  deadline?: Timestamp;
  scheduledFor?: Timestamp;
  externalRef?: string;
  tags?: string[];
  metadata?: Record<string, unknown>;
}

// Create a new task
await createTask(input: CreateTaskInput, config?: IdGeneratorConfig): Promise<Task>

interface UpdateTaskStatusInput {
  status: TaskStatus;
  closeReason?: string;  // Required when closing
}

// Update task status with transition validation
updateTaskStatus(task: Task, input: UpdateTaskStatusInput): Task

interface DeleteTaskInput {
  deletedBy: EntityId;
  deleteReason?: string;
}

// Soft-delete a task (transitions to tombstone status)
softDeleteTask(task: Task, input: DeleteTaskInput): Task

// Check if task is scheduled for the future
isScheduledForFuture(task: Task): boolean

// Check if task is past its deadline
isPastDeadline(task: Task): boolean

// Check if task has an assignee
isAssigned(task: Task): boolean

// Check if task has an owner
hasOwner(task: Task): boolean

// Filter by status
filterByStatus<T extends Task>(tasks: T[], status: TaskStatus): T[]

// Filter by priority
filterByPriority<T extends Task>(tasks: T[], priority: Priority): T[]

// Filter by assignee
filterByAssignee<T extends Task>(tasks: T[], assignee: EntityId | undefined): T[]

// Filter ready tasks
filterReadyTasks<T extends Task>(tasks: T[]): T[]

// Sort by priority (highest first)
sortByPriority<T extends Task>(tasks: T[]): T[]

// Sort by deadline (earliest first, null deadlines last)
sortByDeadline<T extends Task>(tasks: T[]): T[]

// Check if value is a valid Task
isTask(value: unknown): value is Task

// Comprehensive validation with detailed errors
validateTask(value: unknown): Task