/**
 * Workflow-Driven Handoff
 *
 * Replaces hardcoded handoff files with workflow-driven logic.
 * Reads phase requirements from workflow definitions.
 *
 * Provides functions to:
 * - Find current phase in a workflow
 * - Determine next phase (forward or rejection loop)
 * - Check gate conditions based on gate type
 * - Format session file updates for phase transitions
 */
import type { WorkflowDefinition, WorkflowPhase } from './workflow-schema.js';
/**
 * Context for gate checks - provides test results, verdicts, etc.
 */
export interface GateContext {
    /** For tests_fail gate: are tests currently failing? */
    testsRed?: boolean;
    /** For tests_pass gate: are all tests passing? */
    testsGreen?: boolean;
    /** Number of passing tests */
    testPassCount?: number;
    /** Number of failing tests */
    testFailCount?: number;
    /** For approval gate: approved or rejected */
    verdict?: 'approved' | 'rejected';
}
/**
 * Options for getNextPhase to handle rejection loops
 */
export interface NextPhaseOptions {
    /** For approval gates: determines forward vs loop-back */
    verdict?: 'approved' | 'rejected';
}
/**
 * Result of checking a gate condition
 */
export interface GateCheckResult {
    /** Whether the gate check passed */
    passed: boolean;
    /** Gate type that was checked (undefined if phase has no gate) */
    gateType?: string;
    /** Human-readable message (especially on failure) */
    message?: string;
}
/**
 * Context for handoff operations
 */
export interface HandoffContext {
    /** Story ID being worked on */
    storyId: string;
    /** Current workflow name */
    workflowName: string;
    /** Current phase name */
    currentPhase: string;
    /** Session file path */
    sessionFile: string;
}
/**
 * Result of a handoff operation
 */
export interface HandoffResult {
    /** Whether handoff succeeded */
    success: boolean;
    /** Next phase to transition to */
    nextPhase?: string;
    /** Next agent to invoke */
    nextAgent?: string;
    /** Error message if failed */
    error?: string;
}
/**
 * Parameters for formatting phase transition
 */
export interface PhaseTransitionParams {
    workflowName: string;
    fromPhase: string;
    toPhase: string;
    startedAt: string;
    endedAt: string;
    isRejection?: boolean;
}
/**
 * Find a phase by name in a workflow definition
 *
 * @param workflow - The workflow definition to search
 * @param phaseName - Name of the phase to find
 * @returns The phase definition or null if not found
 *
 * @example
 * ```typescript
 * const phase = findCurrentPhase(workflow, 'red');
 * if (phase) {
 *   console.log(`Found phase: ${phase.name}, agent: ${phase.agent}`);
 * }
 * ```
 */
export declare function findCurrentPhase(workflow: WorkflowDefinition, phaseName: string): WorkflowPhase | null;
/**
 * Get the next phase in the workflow
 *
 * For normal progression, returns the next phase in sequence.
 * For rejection (verdict='rejected'), returns the phase to loop back to
 * (typically the most recent phase with a tests_pass gate).
 *
 * @param workflow - The workflow definition
 * @param currentPhaseName - Name of the current phase
 * @param options - Options for handling rejection loops
 * @returns The next phase or null if at end/not found
 *
 * @example
 * ```typescript
 * // Normal progression
 * const next = getNextPhase(workflow, 'red');
 *
 * // Rejection loop
 * const next = getNextPhase(workflow, 'review', { verdict: 'rejected' });
 * ```
 */
export declare function getNextPhase(workflow: WorkflowDefinition, currentPhaseName: string, options?: NextPhaseOptions): WorkflowPhase | null;
/**
 * Check if a gate condition is satisfied
 *
 * Gate types:
 * - tests_fail: testsRed must be true
 * - tests_pass: testsGreen must be true
 * - approval: verdict must be provided (approved or rejected)
 * - manual: always passes
 * - (none): always passes
 *
 * @param workflow - The workflow definition
 * @param phaseName - Name of the phase to check
 * @param context - Gate check context with test results, verdicts, etc.
 * @returns Gate check result
 *
 * @example
 * ```typescript
 * const result = checkGate(workflow, 'red', { testsRed: true });
 * if (result.passed) {
 *   // Proceed with handoff
 * }
 * ```
 */
export declare function checkGate(workflow: WorkflowDefinition, phaseName: string, context: GateContext): GateCheckResult;
/**
 * Format the workflow tracking section for a session file update
 *
 * @param params - Phase transition parameters
 * @returns Markdown string for the workflow tracking section
 *
 * @example
 * ```typescript
 * const markdown = formatPhaseTransition({
 *   workflowName: 'tdd',
 *   fromPhase: 'red',
 *   toPhase: 'green',
 *   startedAt: '2026-01-13T14:00:00Z',
 *   endedAt: '2026-01-13T14:30:00Z'
 * });
 * ```
 */
export declare function formatPhaseTransition(params: PhaseTransitionParams): string;
/**
 * Calculate duration between two ISO 8601 timestamps
 *
 * @param startedAt - Start timestamp
 * @param endedAt - End timestamp
 * @returns Formatted duration string (e.g., "30m", "2h 30m", "45s")
 */
export declare function calculateDuration(startedAt: string, endedAt: string): string;
/**
 * Handoff mode type - auto triggers immediately, manual prompts first
 */
export type HandoffMode = 'auto' | 'manual';
/**
 * Handoff behavior based on mode
 */
export interface HandoffBehavior {
    /** What action to take */
    action: 'immediate' | 'prompt';
    /** Whether user confirmation is required */
    requiresConfirmation: boolean;
    /** Message to show user (for prompt action) */
    message?: string;
}
/**
 * Entry for handoff history tracking
 */
export interface HandoffHistoryEntry {
    phase: string;
    agent: string;
    timestamp: string;
    handoffMode: HandoffMode;
}
/**
 * Read handoff mode from Cyclist settings file
 * Returns 'manual' as default if file doesn't exist or is invalid
 *
 * @param settingsPath - Path to the settings file (JSON or YAML)
 * @returns The handoff mode setting
 */
export declare function readHandoffMode(settingsPath: string): HandoffMode;
/**
 * Parse handoff mode from JSON string
 * Handles both new format (handoff_mode) and legacy format (auto_handoff boolean)
 *
 * @param jsonContent - JSON string containing settings
 * @returns The handoff mode setting
 */
export declare function parseHandoffModeFromJson(jsonContent: string): HandoffMode;
/**
 * Parse handoff mode from YAML string
 * Handles both new format (handoff_mode) and legacy format (auto_handoff boolean)
 *
 * @param yamlContent - YAML string containing settings
 * @returns The handoff mode setting
 */
export declare function parseHandoffModeFromYaml(yamlContent: string): HandoffMode;
/**
 * Get handoff behavior based on mode
 *
 * @param mode - The handoff mode setting
 * @returns Behavior configuration for the mode
 */
export declare function getHandoffBehavior(mode: HandoffMode): HandoffBehavior;
/**
 * Format handoff history entry for session file
 * Creates a markdown section with table row for the handoff
 *
 * @param entry - Handoff history entry to format
 * @returns Markdown string for the handoff history section
 */
export declare function formatHandoffHistory(entry: HandoffHistoryEntry): string;
/**
 * Threshold for context percentage to trigger context clear
 * When auto mode is enabled and context exceeds this threshold, emit CONTEXT_CLEAR
 */
export declare const CONTEXT_CLEAR_THRESHOLD = 60;
/**
 * Parameters for context clear marker decision
 */
export interface ContextClearParams {
    /** Current handoff mode from settings */
    handoffMode: HandoffMode;
    /** Current context usage percentage (0-100) */
    contextPercent: number;
    /** Next agent to load after clear (for marker value) */
    nextAgent?: string;
}
/**
 * Determine if CONTEXT_CLEAR marker should be emitted
 *
 * Returns true when:
 * - handoffMode is 'auto'
 * - contextPercent exceeds CONTEXT_CLEAR_THRESHOLD
 *
 * @param params - Context clear parameters
 * @returns true if CONTEXT_CLEAR should be emitted
 */
export declare function shouldEmitContextClear(params: ContextClearParams): boolean;
/**
 * Format the CYCLIST marker for context clear or regular handoff
 *
 * When auto mode and high context: returns CONTEXT_CLEAR marker
 * Otherwise: returns regular HANDOFF marker
 *
 * @param params - Context clear parameters including nextAgent
 * @returns Marker string (<!-- CYCLIST:CONTEXT_CLEAR:/agent --> or <!-- CYCLIST:HANDOFF:/agent -->)
 */
export declare function formatContextClearMarker(params: ContextClearParams): string;
/**
 * Format a human-readable output message for context clear handoffs
 *
 * Includes context percentage and the marker for Cyclist to detect
 *
 * @param params - Context clear parameters
 * @returns Formatted output string for display
 */
export declare function formatContextClearOutput(params: ContextClearParams): string;
//# sourceMappingURL=handoff.d.ts.map