/**
 * Phase finding and plan index query handlers.
 *
 * Ported from get-shit-done/bin/lib/phase.cjs and core.cjs.
 * Provides find-phase (directory lookup with archived fallback)
 * and phase-plan-index (plan metadata with wave grouping).
 *
 * @example
 * ```typescript
 * import { findPhase, phasePlanIndex } from './phase.js';
 *
 * const found = await findPhase(['9'], '/project');
 * // { data: { found: true, directory: '.planning/phases/09-foundation', ... } }
 *
 * const index = await phasePlanIndex(['9'], '/project');
 * // { data: { phase: '09', plans: [...], waves: { '1': [...] }, ... } }
 * ```
 */
import type { QueryHandler } from './utils.js';
interface PhaseInfo {
    found: boolean;
    directory: string | null;
    phase_number: string | null;
    phase_name: string | null;
    phase_slug: string | null;
    plans: string[];
    summaries: string[];
    incomplete_plans: string[];
    has_research: boolean;
    has_context: boolean;
    has_verification: boolean;
    has_reviews: boolean;
    archived?: string;
    /**
     * #2893 — non-canonical plan filename warning (singular). Present only when
     * a plan-shaped file in this phase dir is not the canonical
     * `{padded_phase}-{NN}-PLAN.md` shape; the executor surfaces this so users
     * see a loud signal instead of plan_count: 0 with no clue why.
     */
    warning?: string;
}
/**
 * #2893 — canonical plan filename predicate and the diagnostic "looks like a
 * plan but isn't canonical" net. Centralised so every read site (find-phase,
 * phase-plan-index, phases list --type plans) emits the same warning message.
 *
 * Mirrors get-shit-done/bin/lib/phase.cjs lines 17–52.
 */
export declare const isCanonicalPlanFile: (f: string) => boolean;
/**
 * Build the canonical "non-canonical plan files" warning string used by every
 * SDK read site. Returns null when there are no offenders.
 *
 * Format mirrors describeNonCanonicalPlans in phase.cjs so consumers see the
 * same message regardless of which entry point they call.
 */
export declare function describeNonCanonicalPlans(dirFiles: string[], matchedFiles: string[]): string | null;
/**
 * Locate a phase by number without the QueryHandler wrapper.
 *
 * Returns the PhaseInfo (including phase_number, phase_slug) for the given
 * phase identifier, or null when the phase cannot be found.  Searches current
 * phases first, then archived milestone phase directories (newest-first) —
 * identical logic to the `findPhase` QueryHandler and the CJS
 * `findPhaseInternal` from core.cjs lines 838-874.
 *
 * Exported so that `commit.ts` can call it without going through the full
 * QueryHandler dispatch stack (which would require a registered query context).
 *
 * @param projectDir - Project root directory
 * @param phase      - Phase identifier string (e.g. "1", "02", "2.1")
 * @param workstream - Optional workstream scope
 */
export declare function findPhaseByNumber(projectDir: string, phase: string, workstream?: string): Promise<PhaseInfo | null>;
/**
 * Query handler for find-phase.
 *
 * Locates a phase directory by number/identifier, searching current phases
 * first, then archived milestone phases.
 *
 * Port of cmdFindPhase from phase.cjs lines 152-196, combined with
 * findPhaseInternal from core.cjs lines 1002-1038.
 *
 * @param args - args[0] is the phase identifier (required)
 * @param projectDir - Project root directory
 * @returns QueryResult with PhaseInfo
 * @throws GSDError with Validation classification if phase identifier missing
 */
export declare const findPhase: QueryHandler;
/**
 * Query handler for phase-plan-index.
 *
 * Returns plan metadata with wave grouping for a specific phase.
 *
 * Port of cmdPhasePlanIndex from phase.cjs lines 203-310.
 *
 * @param args - args[0] is the phase identifier (required)
 * @param projectDir - Project root directory
 * @returns QueryResult with { phase, plans[], waves{}, incomplete[], has_checkpoints }
 * @throws GSDError with Validation classification if phase identifier missing
 */
export declare const phasePlanIndex: QueryHandler;
export {};
//# sourceMappingURL=phase.d.ts.map