/**
 * Valid phase sequence for goal state machine.
 * Phases must be completed in order; no gaps allowed.
 */
export declare const VALID_PHASES: readonly string[];
export interface GoalCheckpoint {
    status: "pending" | "in_progress" | "complete" | "failed";
    attempts: number;
    completed_at: string | null;
    error: string | null;
}
export interface GoalGroup {
    id?: string;
    title?: string;
    scope?: string;
    status: "pending" | "in_progress" | "complete";
    phase?: string | null;
    dependencies?: string[];
}
export interface GoalState {
    /** Schema version (v2 adds groups and timestamps) */
    version?: string;
    goal_id: string;
    /** Overall goal status (active/complete/archived) */
    status?: string;
    /** Current phase in the state machine */
    current_phase?: string;
    /** Per-phase checkpoints with status and timing */
    checkpoints: Record<string, GoalCheckpoint>;
    /** Optional group topology for structuring sub-goals */
    groups?: Record<string, GoalGroup>;
    created_at?: string;
    updated_at?: string;
}
/**
 * Dirty-state reasons that validate-state can reject and advance --heal can fix.
 * Sole writer for phase transitions remains `aiws goal advance` (contract §10).
 */
export type GoalDirtyReason = "all_checkpoints_complete_status_not_complete" | "status_active_current_phase_after_all_complete" | "status_complete_with_incomplete_checkpoints" | "complete_missing_completed_at" | "missing_required_checkpoints" | "current_phase_mismatch";
export interface GoalDirtyAnalysis {
    dirty: boolean;
    reasons: GoalDirtyReason[];
    details: string[];
    healable: boolean;
}
/**
 * Detect semantic dirty states beyond pure structural validation.
 * Examples: all checkpoints complete but overall status still active;
 * status complete while some phases pending; missing completed_at.
 */
export declare function analyzeGoalDirtyState(state: GoalState): GoalDirtyAnalysis;
export interface HealGoalStateResult {
    healed: boolean;
    state: GoalState;
    actions: string[];
    dirtyBefore: GoalDirtyAnalysis;
}
/**
 * Heal dirty goal state into a legal FSM snapshot.
 * Does not invent progress: only reconciles status/current_phase/completed_at/missing shells.
 * Phase boundary transitions after heal still go through advance.
 */
export declare function healGoalState(state: GoalState): HealGoalStateResult;
/**
 * Create a minimal valid initial goal state (all pending).
 */
export declare function createInitialGoalState(goalId: string): GoalState;
/**
 * Parse ws_goal.state from goal markdown frontmatter (simple, no full YAML dep).
 */
export declare function parseGoalMarkdownState(mdContent: string): {
    state: string | null;
    iteration: number | null;
};
/**
 * Find goals that have .md with active/paused but no .state.json (migration candidates §7.6).
 */
export declare function findGoalsNeedingMigration(goalDir: string): Promise<Array<{
    goalId: string;
    mdPath: string;
    mdState: string;
}>>;
/**
 * Migrate legacy goal .md → state.json (all checkpoints pending, current_phase null per §7.6).
 */
export declare function migrateGoalFromMarkdown(goalDir: string, goalId: string): Promise<{
    ok: boolean;
    statePath: string;
    message: string;
}>;
/**
 * Validate a goal state's structural integrity.
 *
 * Checks performed:
 * a) All required phase checkpoints exist
 * b) Phase sequence: no completed phase with a prior pending phase (no gaps)
 * c) Completed phases must have completed_at set
 * d) Group DAG has no cycles and all dependencies resolve to known groups
 * e) Group statuses are valid (pending/in_progress/complete)
 * f) Groups with a `phase` set must have that parent phase complete
 */
export declare function validateGoalState(state: GoalState, options?: {
    includeDirty?: boolean;
}): {
    valid: boolean;
    errors: string[];
    warnings: string[];
};
/**
 * Read and parse a goal state JSON file.
 * @param statePath - Full path to the state file (e.g., `.aiws/goals/G-014.state.json`)
 */
export declare function readGoalState(statePath: string): Promise<GoalState>;
/**
 * Atomically write a goal state to disk using tmp-file-then-rename.
 * @param statePath - Full path to the state file to write
 * @param state - The goal state to persist
 */
export declare function writeGoalState(statePath: string, state: GoalState): Promise<void>;
/**
 * Determine the next phase in the goal state machine.
 *
 * Logic:
 * 1. If current phase checkpoint is not `complete` → stay on that phase
 * 2. If groups exist: walk groups in topological order; find first pending group
 *    and its first pending phase
 * 3. If no groups: advance through the flat VALID_PHASES sequence
 * 4. If all phases (and groups) are complete → signal done
 */
export declare function computeNextPhase(state: GoalState): {
    phase: string;
    groupId: string | null;
    done: boolean;
    reason: string;
};
/**
 * Per-phase guidance descriptions for AI consumption.
 * Maps each VALID_PHASE to a brief "what to do in this phase" instruction.
 */
export declare const PHASE_GUIDANCE: Record<string, string>;
/**
 * Get next-actions guidance for the current phase of a goal state.
 * Returns a structured description telling the AI what to do next.
 */
export declare function getPhaseGuidance(goalId: string, state: GoalState): {
    phase: string;
    description: string;
    needsUserInput: boolean;
    blockers: string[];
};
/**
 * Collect pending (non-complete) phases from checkpoints.
 */
export declare function listPendingPhases(state: GoalState): string[];
/**
 * Find all goal state files in a directory.
 * Scans for `*.state.json` files.
 */
export declare function scanGoalStateFiles(goalDir: string): Promise<string[]>;
/**
 * Resolve a goal state file path from a directory and optional goal ID.
 * If goalId is provided, returns the path to `<goalId>.state.json`.
 * If not provided and exactly one `.state.json` exists, returns that path.
 */
export declare function resolveGoalStatePath(goalDir: string, goalId?: string): Promise<string | null>;