/**
 * TaskStateEngine - Internal state management engine
 * Pure state logic extracted from TaskManager
 *
 * @internal - Only used by TaskManager and related components
 *
 * Responsibilities:
 * - State transition validation
 * - State history validation
 * - Next state calculation
 * - Progress tracking
 * - State sequence management
 *
 * Design Principles:
 * - Pure logic (no I/O operations)
 * - Stateless (static methods)
 * - Single source of truth for state sequence
 *
 * @requirement REFACTOR-EXTRACT-STATE-ENGINE - Phase 1: Extract state logic from TaskManager
 */
import { type WorkflowState } from '@shadel/workflow-core';
/**
 * TaskStateEngine - Pure state management logic
 *
 * This component encapsulates all state-related logic extracted from TaskManager.
 * It provides static methods for state validation, progression, and history validation.
 *
 * Key Features:
 * - Single source of truth for state sequence
 * - Strict sequential state progression (+1 step only)
 * - State history integrity validation
 * - Progress calculation
 *
 * Usage:
 * ```typescript
 * // Validate transition
 * const isValid = TaskStateEngine.isValidTransition('UNDERSTANDING', 'DESIGNING'); // true
 *
 * // Get next state
 * const next = TaskStateEngine.getNextState('UNDERSTANDING'); // 'DESIGNING'
 *
 * // Get progress
 * const progress = TaskStateEngine.getProgress('IMPLEMENTING'); // 40
 * ```
 */
export declare class TaskStateEngine {
    /**
     * State sequence - Single source of truth
     *
     * This array defines the complete workflow state sequence.
     * It is used by TaskManager, TaskValidator, and other components
     * to ensure consistent state handling across the system.
     *
     * States must progress sequentially:
     * UNDERSTANDING → DESIGNING → IMPLEMENTING → TESTING → REVIEWING → READY_TO_COMMIT
     *
     * @internal - Private to prevent external modification
     */
    private static readonly STATE_SEQUENCE;
    /**
     * Get state index in sequence
     *
     * Returns the index of a state in the STATE_SEQUENCE array.
     * Used for state comparison and transition validation.
     *
     * @param state - Workflow state to get index for
     * @returns Index in STATE_SEQUENCE (0-5), or -1 if invalid state
     *
     * @example
     * ```typescript
     * TaskStateEngine.getStateIndex('UNDERSTANDING'); // 0
     * TaskStateEngine.getStateIndex('DESIGNING'); // 1
     * TaskStateEngine.getStateIndex('INVALID'); // -1
     * ```
     */
    static getStateIndex(state: WorkflowState): number;
    /**
     * Get all valid workflow states
     *
     * Returns a copy of the STATE_SEQUENCE array containing all valid workflow states.
     * This provides a safe way to access the state sequence without exposing the internal array.
     *
     * @returns Array of all valid states (copy of STATE_SEQUENCE)
     *
     * @example
     * ```typescript
     * const states = TaskStateEngine.getAllStates();
     * // ['UNDERSTANDING', 'DESIGNING', 'IMPLEMENTING', 'TESTING', 'REVIEWING', 'READY_TO_COMMIT']
     * ```
     */
    static getAllStates(): WorkflowState[];
    /**
     * Validate if state transition is allowed
     *
     * Implements strict sequential progression validation.
     * States must progress forward by exactly 1 step (+1 step only).
     *
     * Rules:
     * - Cannot move backward (UNDERSTANDING ← DESIGNING is invalid)
     * - Cannot skip states (UNDERSTANDING → IMPLEMENTING is invalid)
     * - Cannot stay at same state (UNDERSTANDING → UNDERSTANDING is invalid)
     * - Must progress by exactly 1 step (UNDERSTANDING → DESIGNING is valid)
     *
     * @param from - Current state
     * @param to - Target state
     * @returns true if transition is valid (toIndex === fromIndex + 1), false otherwise
     *
     * @example
     * ```typescript
     * TaskStateEngine.isValidTransition('UNDERSTANDING', 'DESIGNING'); // true
     * TaskStateEngine.isValidTransition('UNDERSTANDING', 'IMPLEMENTING'); // false (skipped)
     * TaskStateEngine.isValidTransition('DESIGNING', 'UNDERSTANDING'); // false (backward)
     * TaskStateEngine.isValidTransition('UNDERSTANDING', 'UNDERSTANDING'); // false (same)
     * ```
     *
     * @requirement BUG-FIX-001 - Sequential state progression
     */
    static isValidTransition(from: WorkflowState, to: WorkflowState): boolean;
    /**
     * Get next valid state in sequence
     *
     * Returns the state that follows the current state in the workflow sequence.
     * Returns null if the current state is the final state (READY_TO_COMMIT).
     *
     * @param current - Current workflow state
     * @returns Next state in sequence, or null if at final state
     *
     * @example
     * ```typescript
     * TaskStateEngine.getNextState('UNDERSTANDING'); // 'DESIGNING'
     * TaskStateEngine.getNextState('DESIGNING'); // 'IMPLEMENTING'
     * TaskStateEngine.getNextState('READY_TO_COMMIT'); // null
     * ```
     *
     * @requirement BUG-FIX-001 - State progression guidance
     */
    static getNextState(current: WorkflowState): WorkflowState | null;
    /**
     * Get workflow progress as percentage
     *
     * Calculates the progress through the workflow as a percentage (0-100).
     * Progress is based on the position of the current state in the sequence.
     *
     * Formula: (currentIndex / (totalStates - 1)) * 100
     *
     * @param currentState - Current workflow state
     * @returns Progress percentage (0-100), or 0 if invalid state
     *
     * @example
     * ```typescript
     * TaskStateEngine.getProgress('UNDERSTANDING'); // 0
     * TaskStateEngine.getProgress('IMPLEMENTING'); // 40
     * TaskStateEngine.getProgress('READY_TO_COMMIT'); // 100
     * TaskStateEngine.getProgress('INVALID'); // 0
     * ```
     */
    static getProgress(currentState: WorkflowState): number;
    /**
     * Validate state history integrity
     *
     * Detects manual file edits that forge invalid state progressions.
     * This is a pure function that validates workflow data without any I/O operations.
     *
     * Validates:
     * - Current state is not in history (should only have completed steps)
     * - History follows sequential progression
     * - No state regression
     * - No state skipping (unless explicitly allowed)
     *
     * @param workflow - Workflow data object with currentState and stateHistory
     * @throws Error if history is invalid with detailed error message
     *
     * @example
     * ```typescript
     * // Valid history
     * TaskStateEngine.validateStateHistory({
     *   currentState: 'DESIGNING',
     *   stateHistory: [{ state: 'UNDERSTANDING', enteredAt: '...' }]
     * }); // OK
     *
     * // Invalid: current state in history
     * TaskStateEngine.validateStateHistory({
     *   currentState: 'DESIGNING',
     *   stateHistory: [{ state: 'DESIGNING', enteredAt: '...' }]
     * }); // Throws error
     * ```
     *
     * @requirement BUG-FIX-009 - Prevent state forgery
     * @requirement BUG-FIX-012-VALIDATION - Check current state in history FIRST (most critical check)
     */
    static validateStateHistory(workflow: {
        currentState: WorkflowState;
        stateHistory?: Array<{
            state: WorkflowState;
            enteredAt: string;
        }>;
    }): void;
}