/**
 * instance-completion migration (instance-complete-never-fires AC-9..AC-13,
 * AC-16, AC-19, safe tier): stamp `completed_at` on instances that have already
 * reached their completion moment, and move any roadmap item whose
 * `promoted_to` names one of them into `done/`.
 *
 * Exists because `on-instance-complete` was suppressed for the whole time the
 * old fired-once guard read `retrospective.md` — see that instance's
 * `reproduction.md`. Two consequences have to be repaired, and they are the two
 * halves of this migration:
 *
 *  - **The guard's new key is unpopulated.** Nothing wrote `completed_at`
 *    before this change, so every already-completed instance would look
 *    un-fired to the new guard and re-emit on its next `aidlc transition`.
 *    Stamping them is a *prerequisite* of the guard change, not a tidy-up
 *    (AC-16). The value written is the completion timestamp `completionInfo`
 *    derives from phase state, never `now` — a backfill that stamped today
 *    would claim work finished when it was repaired.
 *  - **Roadmap items were left behind.** `roadmap-done` never ran, so items sit
 *    outside `done/` for instances that shipped (AC-9, AC-11).
 *
 * Safe tier, not confirm. `roadmap-layout` is confirm because it rewrites
 * frontmatter it has to *interpret*; this one moves a file whose destination is
 * already stated by data — the item names its instance, and the instance has
 * demonstrably completed. There is no judgement to confirm, and putting it in
 * the confirm tier would make `aidlc doctor` exit 1 until someone answered,
 * which is the kind of soft gate this project's guidance says to avoid.
 *
 * Completion is answered by `completionInfo`, never by a local "is the last
 * phase complete?" test (AC-19): that naive form is wrong for
 * maintenance-terminal templates, which complete on maintenance *entry*.
 * `roadmap-layout` depends on the same helper for the same reason, so the
 * migration and `aidlc transition` cannot disagree.
 *
 * It never emits `on-instance-complete`. Re-delivering a weeks-old event has no
 * consumer left, and would re-ask for retrospectives that already exist. The
 * observable effects are repaired directly instead.
 *
 * Nothing here routes through `aidlc transition`, so the ownership gate cannot
 * block it (AC-13) — the recorded phase owner of a completed instance is
 * typically an agent session that no longer exists.
 */
import type { Migration } from '../types.js';
import type { DoctorContext } from '../types.js';
import { type RoadmapItem, type UnparseableItem } from '../../roadmap/paths.js';
/** An instance whose `completed_at` is missing and should be stamped. */
export interface CompletionStamp {
    instance: string;
    /** Completion timestamp derived from phase state — never `now`. */
    completedAt: string;
}
/** A roadmap item stranded outside `done/` by a suppressed event. */
export interface StrandedItem {
    item: RoadmapItem;
    instance: string;
    /**
     * Found by the instance's `roadmap-item.md` id because the item's `promoted_to` was
     * null, so filing it also links it (roadmap-item-loses-promoted-to/AC-7).
     */
    link: boolean;
}
export interface CompletionPlan {
    stamps: CompletionStamp[];
    stranded: StrandedItem[];
    /**
     * Roadmap items whose frontmatter will not parse, so `promoted_to` cannot be
     * read and the item is invisible to every roadmap lookup.
     *
     * Reported rather than ignored. Five of this project's 49 items were in this
     * state on 2026-09-01 — every one a title starting with a backtick, which YAML
     * reserves as an indicator character — and because `readItem` returns null
     * silently, they were absent from browse, from `findAllByPromotedTo`, and from
     * the `roadmap-done` action, with nothing anywhere saying so. That silence is
     * a second, independent cause of the symptom this migration repairs, so a
     * migration that also ignored them would reproduce the failure it exists to
     * fix. Only a human can repair the frontmatter, so these are surfaced, never
     * auto-corrected.
     */
    unparseable: UnparseableItem[];
}
/**
 * Everything the migration would do, computed without writing.
 *
 * The single source of pending-ness, shared verbatim by dry-run and real runs —
 * the rule stated in `../types.ts`. Instances are walked in sorted order so the
 * plan never depends on directory read order.
 */
export declare function planInstanceCompletion(ctx: DoctorContext): CompletionPlan;
export declare const instanceCompletion: Migration;
//# sourceMappingURL=instance-completion.d.ts.map