import type { SopCheckResult } from './sop-types.js';
/**
 * SOP phase advancement with gate enforcement — Feature A, Slice 3 (range 3).
 *
 * `advanceSop` moves a SOP to a target phase only if (a) the move does not skip
 * ahead in the declared phase order, and (b) every gate guarding that phase
 * passes. A forward skip throws SopPhaseSkipError (SOP_PHASE_SKIP); a
 * fail/blocked gate throws SopGateBlockedError (SOP_GATE_BLOCKED). Both block
 * UNCONDITIONALLY in all modes — a gate is an objective check, not a
 * confirmation prompt, so a mode could never silently skip it (that would
 * defeat "don't drop steps"). The only escape is an explicit bypass
 * (allowIncomplete), which the CLI gates behind --reason / --confirm / a cap.
 *
 * The SOP *definition* is global (`~/.peaks/sops/`), but run-state is
 * PER-PROJECT (`<project>/.peaks/sop-state/<id>.json`) so the same authored SOP
 * tracks independent progress in every project it runs in.
 *
 * This is a standalone command path: it does NOT touch the built-in request
 * artifact transition machinery or mode-enforcement, so those keep their exact
 * behavior (preserved behavior P2/P3).
 */
export type BlockedGate = {
    gateId: string;
    result: SopCheckResult;
    reason?: string;
};
export type SopHistoryEntry = {
    phase: string;
    bypassed: boolean;
    reason?: string;
};
export type SopState = {
    currentPhase: string | null;
    history: SopHistoryEntry[];
};
export type AdvanceSopResult = {
    id: string;
    phase: string;
    bypassed: boolean;
    previousPhase: string | null;
    /** false when --dry-run evaluated the gates without recording the advance. */
    applied: boolean;
};
export type AdvanceSopOptions = {
    projectRoot: string;
    id: string;
    toPhase: string;
    allowCommands?: boolean;
    allowIncomplete?: boolean;
    reason?: string;
    commandTimeoutMs?: number;
    /** Evaluate gates (still blocks on failure) but do not write state.json. */
    dryRun?: boolean;
};
export declare class SopAdvanceError extends Error {
    readonly code: string;
    constructor(code: string, message: string);
}
export declare class SopGateBlockedError extends Error {
    readonly code = "SOP_GATE_BLOCKED";
    readonly blockedGates: BlockedGate[];
    constructor(toPhase: string, blockedGates: BlockedGate[]);
}
export declare class SopPhaseSkipError extends Error {
    readonly code = "SOP_PHASE_SKIP";
    readonly fromPhase: string | null;
    readonly toPhase: string;
    readonly expectedNext: string;
    constructor(fromPhase: string | null, toPhase: string, expectedNext: string);
}
declare const EMPTY_STATE: SopState;
export declare function readSopState(projectRoot: string, id: string): Promise<SopState>;
export declare function advanceSop(options: AdvanceSopOptions): Promise<AdvanceSopResult>;
export { EMPTY_STATE };