/**
 * "What next?" answered the same way every time (autopilot-priority/AC-1..AC-7).
 *
 * The ready set is `backlog/` items whose `depends_on` ids are all in `done/` and
 * that `start --roadmap-item` would take (`promotionRefusal`); the
 * order is `priority` (a rank: 1 is first) with unranked items last, then file
 * name. Read-only by construction — nothing here writes, so the one thing a
 * driver that works the backlog must never do, promote, is out of its reach.
 *
 * Reads the PRIMARY checkout's roadmap (`roadmapRoot`), like every roadmap lookup
 * that decides status.
 *
 * With `autopilot`, items whose `run` is `attended` — or unreadable — are left for a
 * person (autopilot-or-attended-field/AC-1..AC-3); without it they are offered as before,
 * because a person can pick them (AC-4).
 *
 * @module
 */
import { type Milestone } from './milestones.js';
import { type RoadmapItem } from './paths.js';
export interface NextCandidate {
    file: string;
    id: string | null;
    title: string | null;
    priority: number | null;
}
export interface Skipped {
    file: string;
    reason: 'bad-priority' | 'blocked' | 'promoted' | 'attended' | 'bad-run';
    detail: string;
}
/**
 * Why `start --roadmap-item` refuses this item, or null when it would take it.
 *
 * Shared with `findPromotable` for the reason `parsePriority` is shared with `rank`:
 * on 2026-10-04 `next` offered an item un-parked by hand with its link still set,
 * `start` refused it, and autopilot asked again once a minute for five hours
 * (autopilot-start-failure-blocks-queue/AC-12).
 */
export declare function promotionRefusal(item: Pick<RoadmapItem, 'promotedTo'>): string | null;
export interface NextResult {
    next: NextCandidate | null;
    ready: NextCandidate[];
    skipped: Skipped[];
    /** Every backlog item with no rank, blocked ones included, by file name (triage-sets-priority/AC-13). */
    unranked: {
        file: string;
        title: string | null;
    }[];
    /** Every backlog item whose `run` is malformed, in either mode — what the warning reads (autopilot-or-attended-field/AC-5). */
    badRun: {
        file: string;
        detail: string;
    }[];
    /** The current milestone the ready order prefers; null without a usable milestones file (roadmap-milestones/AC-11). */
    milestone: Milestone | null;
    /** Set when a milestones file exists but cannot be used, so the order is today's (AC-2). */
    milestonesWarning: string | null;
}
export type RunMode = 'autopilot' | 'attended';
export interface PickOptions {
    /** Leave `run: attended` and malformed-`run` items out of the ready order. */
    autopilot?: boolean;
}
/**
 * Read one item's `run`. Absent or null reads as `autopilot`, so a repo that never sets
 * it sees no change (autopilot-or-attended-field/AC-2); any other value is `'bad'`.
 */
export declare function parseRun(raw: unknown): RunMode | 'bad';
/**
 * Read one item's `priority`: a positive integer, `null` when absent or null, or
 * `'bad'` for anything else.
 *
 * Shared with `roadmap rank` so the command that writes ranks and the one that
 * reads them cannot disagree about what a malformed rank is.
 */
export declare function parsePriority(raw: unknown): number | null | 'bad';
/** Priority ascending, unranked last, then file name — total, so the pick is stable. */
export declare function compareCandidates(a: NextCandidate, b: NextCandidate): number;
export declare function pickNext(cwd: string, opts?: PickOptions): NextResult;
/**
 * `pickNext` against an explicit roadmap root — what `aidlc roadmap view` calls, so the
 * board marks as ready exactly what `roadmap next` would offer (html-roadmap-view/AC-17).
 */
export declare function pickNextAt(root: string, opts?: PickOptions): NextResult;
//# sourceMappingURL=next.d.ts.map