import type { SpecScope, SpecType } from '../common/primitives.js';
/**
 * A single week's throughput data point.
 * weekLabel: ISO week string, e.g. "2026-W12"
 */
export interface ThroughputPoint {
    weekLabel: string;
    weekStart: string;
    weekEnd: string;
    specsCompleted: number;
    specIds: string[];
}
/**
 * Lead time statistics grouped by scope.
 * Lead time = done timestamp - created timestamp (in hours).
 */
export interface LeadTimeStats {
    avgHours: number;
    medianHours: number;
    minHours: number;
    maxHours: number;
    /** Number of specs used to compute these stats */
    sampleSize: number;
    /** Breakdown by scope */
    byScope: Record<SpecScope, LeadTimeScopeStats>;
}
export interface LeadTimeScopeStats {
    avgHours: number;
    sampleSize: number;
}
/**
 * Cycle time statistics.
 * Cycle time = done timestamp - implementing timestamp (in hours).
 */
export interface CycleTimeStats {
    avgHours: number;
    medianHours: number;
    sampleSize: number;
}
/**
 * A single burndown data point for one week.
 */
export interface BurndownPoint {
    weekLabel: string;
    weekStart: string;
    weekEnd: string;
    /** Specs completed (done) up to and including this week */
    completedCumulative: number;
    /** Specs completed in this specific week */
    completedThisWeek: number;
    /** Specs created up to and including this week */
    createdCumulative: number;
    /** Backlog: total created - total completed */
    backlog: number;
}
/**
 * Flow efficiency: time spent in active states vs total lead time.
 */
export interface FlowEfficiencyStats {
    /** 0.0-1.0 ratio of active time to total time */
    efficiency: number;
    /** Average hours spent in active states (implementing, review) */
    avgActiveHours: number;
    /** Average total lead time hours */
    avgTotalHours: number;
    sampleSize: number;
}
/**
 * WIP (Work In Progress) snapshot.
 */
export interface WipSnapshot {
    current: number;
    specIds: string[];
    avgAgeHours: number;
}
/**
 * Full velocity report for a project.
 */
export interface VelocityReport {
    projectId: string;
    projectPath: string;
    generatedAt: string;
    /** Number of weeks analyzed */
    weeks: number;
    /** Applied filters */
    filters: VelocityFilters;
    /** Average specs completed per week */
    avgThroughputPerWeek: number;
    throughput: ThroughputPoint[];
    leadTime: LeadTimeStats | null;
    cycleTime: CycleTimeStats | null;
    wip: WipSnapshot;
    flowEfficiency: FlowEfficiencyStats | null;
    burndown: BurndownPoint[];
    /** Human-readable summary line */
    summary: string;
    /** Total specs done in the period */
    totalDone: number;
    /** Total specs in the project */
    totalSpecs: number;
}
/**
 * Trend comparison: last N weeks vs previous N weeks.
 */
export interface VelocityTrend {
    projectId: string;
    projectPath: string;
    generatedAt: string;
    compareWeeks: number;
    recent: VelocityPeriodStats;
    previous: VelocityPeriodStats;
    throughputDelta: number;
    leadTimeDelta: number | null;
    trend: 'improving' | 'stable' | 'declining';
    summary: string;
}
export interface VelocityPeriodStats {
    label: string;
    fromDate: string;
    toDate: string;
    avgThroughputPerWeek: number;
    avgLeadTimeHours: number | null;
    totalDone: number;
}
/**
 * Input filters for velocity tools.
 */
export interface VelocityFilters {
    weeks: number;
    scope?: SpecScope;
    type?: SpecType;
}
/** Input args for velocity_report tool */
export interface VelocityReportInput {
    projectPath: string;
    weeks?: number;
    scope?: SpecScope;
    type?: SpecType;
}
/** Input args for velocity_trend tool */
export interface VelocityTrendInput {
    projectPath: string;
    compareWeeks?: number;
    scope?: SpecScope;
    type?: SpecType;
}
/**
 * Velocity profile derived from recent spec actuals.
 * Used to convert devHours estimates into real calendar days.
 * SPEC-555
 */
export interface VelocityProfile {
    /** SPECs completed per calendar day (in the window) */
    specsPerDay: number;
    /** Productive dev hours per calendar day */
    hoursPerDay: number;
    /** Average actual devHours by difficulty (1-5) */
    avgHoursByDifficulty: Record<1 | 2 | 3 | 4 | 5, number>;
    /** ISO date of last calculation */
    calibrationDate: string;
    /** Window used to calculate (default 30 days) */
    windowDays: number;
    /** Number of done specs used for calibration */
    sampleSize: number;
    /** Confidence based on sample size: high >20, medium 5-20, low <5 */
    confidence: 'high' | 'medium' | 'low';
}
//# sourceMappingURL=velocity.d.ts.map