/**
 * Linking a roadmap item to an instance, and parking it — the two roadmap steps an
 * agent was seen skipping or fumbling when they were prose (autopilot/AC-12..AC-16).
 *
 * On 2026-10-02 two unattended runs of the same worktree promote flow disagreed: one
 * moved and linked the item by hand, the other left it in `backlog/` with
 * `promoted_to: null`. A step that can be forgotten belongs in the command that
 * creates the instance, so `aidlc start --roadmap-item` does it.
 *
 * Every write goes to the PRIMARY checkout's roadmap (`roadmapRoot`), never a
 * worktree's copy: status is the primary checkout's directory, and a worktree's copy
 * is a snapshot of a branch.
 *
 * @module
 */
import { type RoadmapItem } from './paths.js';
export type PromoteLookup = {
    ok: true;
    item: RoadmapItem;
} | {
    ok: false;
    reason: 'not-found' | 'already-promoted';
    detail: string;
};
/**
 * Find the item `ref` names in the primary checkout's `backlog/` or `inbox/`.
 *
 * An item that already carries a `promoted_to` is refused: linking it again would
 * strand the first instance's link, and `roadmap-done` would then file the wrong one.
 */
export declare function findPromotable(cwd: string, ref: string): PromoteLookup;
/**
 * Rewrite the `promoted_to:` line inside the frontmatter, textually, so key order
 * and every other line survive — the same reason `writeHistoryEntry` edits text.
 *
 * @returns The rewritten contents, or null when there is no frontmatter or no
 *   `promoted_to:` key to edit.
 */
export declare function setPromotedTo(raw: string, instance: string): string | null;
/**
 * `raw` linked to `instance`, adding the `promoted_to:` line when the frontmatter has
 * none (failed-start-leaves-worktree/AC-1).
 *
 * On 2026-10-10 two agent-written items had no `promoted_to:` line, and refusing them
 * failed the start after the worktree existed. The key is appended as the last
 * frontmatter line, where `item_fields` such as `run:` already land; every other byte
 * is kept (AC-2). `setPromotedTo` still returns null for such an item, because
 * `linkForFiling` files it as it is.
 *
 * @returns The linked contents, or null when there is no frontmatter.
 */
export declare function linkPromotedTo(raw: string, instance: string): string | null;
/**
 * Link `item` to `instance`, move it to `in-progress/`, and copy it into the
 * instance's state directory as `roadmap-item.md`.
 *
 * The copy is written first, into a directory that belongs to the new instance, and
 * the item gets one write before its rename. So a failure leaves the item where it
 * was, and its text is put back if the write landed but the rename did not — a
 * linked item left in `backlog/` is refused as already promoted, and a retry of the
 * same start would fail (failed-start-leaves-worktree/AC-4).
 *
 * Nothing is committed: the move lands in the primary checkout, and committing it
 * is the caller's (the unattended rule's `roadmap-move-uncommitted`).
 *
 * @param stateDir - The `.aidlc/state` directory the instance lives in — a
 *   worktree's, in the worktree flow.
 * @param at - ISO date for the history entry.
 * @returns The item's new path.
 */
export declare function promoteItem(item: RoadmapItem, cwd: string, instance: string, stateDir: string, at: string): string;
/** One item found through an instance's own copy rather than its `promoted_to`. */
export interface CopyMatch {
    item: RoadmapItem;
    /** The `id` the copy and the item share. */
    id: string;
}
/**
 * Find the open items an instance's `roadmap-item.md` copy names by `id`, when the
 * item itself has lost its `promoted_to` (roadmap-item-loses-promoted-to/AC-1).
 *
 * On 2026-10-09 two items reached `in-progress/` with `promoted_to: null` while their
 * instances' copies carried the link, and `roadmap-done`, which looks by `promoted_to`
 * alone, filed nothing. The cause was not reproduced, so the instance's copy is the
 * fallback that makes the outcome right whatever the cause.
 *
 * The copy counts only when its own `promoted_to` names `instance` (AC-4): `promoteItem`
 * writes the copy after linking, so that is what proves it is this instance's. Only
 * items with `promoted_to: null` match (AC-3): an item linked to another instance is
 * that instance's to file. `done/` is skipped — there is nothing left to file there.
 *
 * The id is compared, never opened, as `matches` does: a value like `../../x` finds
 * nothing.
 */
export declare function findUnlinkedByCopy(cwd: string, instance: string): CopyMatch[];
/**
 * `item` with its `promoted_to` set to `instance`, unwritten (AC-2).
 *
 * Handed to `moveItem`, the link and the history entry land in its one write before the
 * rename, so a failed move leaves the item where it was with its text unchanged. An item
 * with no `promoted_to` key at all is filed as it is.
 */
export declare function linkForFiling(item: RoadmapItem, instance: string): RoadmapItem;
export type ParkResult = {
    ok: true;
    file: string;
    reason: string;
} | {
    ok: false;
    detail: string;
};
/**
 * Move the item promoted to `instance` into `hold/`, parked, with `reason`.
 *
 * Searches the primary checkout only, and only statuses that are still open: an item
 * already in `done/` or `hold/` has had its decision made.
 */
export declare function parkItem(cwd: string, instance: string, reason: string, at: string): ParkResult;
/**
 * Move the open item `ref` names (file name or id, as `findPromotable` matches) into
 * `hold/`, parked, whatever its `promoted_to`.
 *
 * For an item no instance can name: a start that failed before linking left
 * `promoted_to: null`, so `parkItem` finds nothing, and autopilot asked for that item
 * again every minute (autopilot-start-failure-blocks-queue/AC-7).
 */
export declare function parkItemByRef(cwd: string, ref: string, reason: string, at: string): ParkResult;
//# sourceMappingURL=promote.d.ts.map