import type { CadenceState } from '@manehorizons/cadence-types';
export interface NextAction {
    command: string;
    reason: string;
    /**
     * Ranked next moves (1-3 entries), most-recommended first. Phase 206 T1 —
     * strictly additive alongside `command`/`reason` above, which keep their
     * pre-206 meaning and values for existing callers (`status.ts`,
     * `quickstart/build.ts`). `legalMoves[0]` always mirrors `{command,
     * reason}` unless a richer hint (e.g. an in-flight milestone or a
     * promotable recommendation) surfaces a better-ranked alternative ahead of
     * it — see each `nextAction` branch below for the exact ranking per loop
     * position.
     */
    legalMoves: LegalMove[];
}
/**
 * One ranked next move (phase 206 T1). `position` is a short, stable,
 * machine-readable move kind — NOT the loop position (`state.loopPosition`
 * is already reported alongside this by callers that need it) — so a
 * downstream consumer (e.g. the `cadence next` CLI, phase 206 T2+) can
 * switch on *what kind* of move this is even when several ranked
 * alternatives share the same loop position (e.g. IDLE's
 * continue-milestone / promote-recommendation / draft-new alternatives).
 */
export interface LegalMove {
    /**
     * Stable move-kind slug, e.g. `'approve-draft'`, `'approve-spec'`,
     * `'record-task'`, `'settle'`, `'continue-milestone'`,
     * `'promote-recommendation'`, `'draft-new'`.
     */
    position: string;
    /** Exact CLI invocation for this move. */
    command: string;
    /** Short human-readable reason for this move. */
    reason: string;
    /**
     * BUILD-only: task ids (`T-N`) without a terminal DONE/DONE_WITH_CONCERNS
     * outcome yet, in draft order. Empty for every move outside BUILD.
     */
    remainingTasks: string[];
    /**
     * What (if anything) blocks this move from closing out right now — AC ids
     * still lacking coverage, BLOCKED/NEEDS_CONTEXT task ids, or similar.
     * Empty when nothing blocks it.
     */
    blockedOn: string[];
}
/**
 * Optional, occupancy-derived hints the impure service/CLI layer computes and
 * passes in so `nextAction` can stay pure-over-state (no I/O). v1.19 phase 86.
 */
export interface NextActionHints {
    /**
     * The worktree-aware next free phase number (`max(observed)+1` over local +
     * sibling + upstream), resolved best-effort by `resolveNextFreePhase`. When
     * present, the IDLE suggestion substitutes it so the operator's first pick
     * already clears sibling/upstream claims the v1.18 guard would refuse.
     */
    nextPhaseNumber?: number;
    /**
     * Phase 137 — BUILD-state task progress, resolved best-effort by reading
     * the active draft + PROGRESS.json. `firstPendingTaskId` is the first
     * draft task (in file order) with no recorded outcome, or `null` when
     * every task already has one. Absent entirely when it couldn't be
     * computed (e.g. the draft file is unreadable) — the BUILD case then
     * falls back to the pre-137 compound message rather than blocking.
     */
    build?: {
        firstPendingTaskId: string | null;
        /**
         * Phase 206 T1 — all task ids (`T-N`) without a terminal
         * DONE/DONE_WITH_CONCERNS outcome yet, in draft order. Optional: when
         * absent, `legalMoves`'s `remainingTasks` falls back to just
         * `[firstPendingTaskId]` (or `[]` when every task is done).
         */
        remainingTaskIds?: string[];
        /**
         * Phase 206 T1 — AC ids whose linked tasks don't all carry a
         * terminal-pass outcome yet (mirrors `deriveAcResults`'s non-`pass`
         * verdicts in `status.ts`). Optional: absent means "not computed",
         * not "none outstanding" — `legalMoves`'s `blockedOn` falls back to
         * `[]` in that case.
         */
        unresolvedAcs?: string[];
    };
    /**
     * Phase 206 T1 — IDLE-only, best-effort facts about what's available to
     * do next beyond a bare `draft new`, resolved from the milestone /
     * recommendation ledgers. Absent (or both sub-fields absent) falls back
     * to the plain draft-new suggestion as the only legal move — the "empty
     * ledgers" case.
     */
    ledger?: {
        /**
         * The next undrafted phase in a milestone the operator is already
         * mid-executing, if any. Ranks above `topRecommendation` when both are
         * present — continuing in-flight work outranks starting something new.
         */
        milestoneNextPhase?: {
            phaseNumber: number;
            title: string;
        };
        /**
         * The highest-ranked unconverted recommendation available to promote,
         * if any (real rec id — never a placeholder).
         */
        topRecommendation?: {
            id: string;
            title: string;
        };
    };
}
export declare function nextAction(state: CadenceState, hints?: NextActionHints): NextAction;
//# sourceMappingURL=progress.d.ts.map