prjct-cli 1.13.0 → 1.14.0

package/core/domain/velocity.ts

@@ -0,0 +1,470 @@
+/**
+ * Velocity Engine (PRJ-296)
+ *
+ * Sprint-based velocity calculation with:
+ * - Sprint aggregation from outcomes data
+ * - Trend detection (improving/stable/declining)
+ * - Estimation accuracy tracking
+ * - Over/under estimation pattern detection
+ * - Completion projections
+ */
+
+import {
+  type CompletionProjection,
+  DEFAULT_VELOCITY_CONFIG,
+  type EstimationPattern,
+  type SprintVelocity,
+  type VelocityConfig,
+  type VelocityMetrics,
+  type VelocityTrend,
+} from '../schemas/velocity'
+import type { Outcome } from '../types'
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/** Day-of-week index (0=Sunday, 1=Monday, ..., 6=Saturday) */
+const DAY_INDEX: Record<string, number> = {
+  sunday: 0,
+  monday: 1,
+  tuesday: 2,
+  wednesday: 3,
+  thursday: 4,
+  friday: 5,
+  saturday: 6,
+}
+
+// =============================================================================
+// Sprint Boundary Calculation
+// =============================================================================
+
+/**
+ * Get the sprint start date for a given date based on config.
+ * Sprints align to calendar boundaries (e.g., every Monday for 7-day sprints).
+ */
+export function getSprintStart(date: Date, config: VelocityConfig): Date {
+  const resolved = resolveConfig(config)
+  const startDayIdx = DAY_INDEX[resolved.startDay]
+  const d = new Date(date)
+  d.setHours(0, 0, 0, 0)
+
+  // Roll back to the most recent start day
+  const currentDay = d.getDay()
+  const diff = (currentDay - startDayIdx + 7) % 7
+  d.setDate(d.getDate() - diff)
+
+  return d
+}
+
+/**
+ * Get sprint end date from sprint start.
+ */
+export function getSprintEnd(sprintStart: Date, config: VelocityConfig): Date {
+  const resolved = resolveConfig(config)
+  const end = new Date(sprintStart)
+  end.setDate(end.getDate() + resolved.sprintLengthDays - 1)
+  end.setHours(23, 59, 59, 999)
+  return end
+}
+
+/**
+ * Assign a sprint number to a date.
+ * Sprint 1 is the earliest sprint in the data set.
+ */
+function getSprintNumber(date: Date, earliestDate: Date, config: VelocityConfig): number {
+  const resolved = resolveConfig(config)
+  const sprintStart = getSprintStart(date, config)
+  const firstSprintStart = getSprintStart(earliestDate, config)
+
+  const diffMs = sprintStart.getTime() - firstSprintStart.getTime()
+  const diffDays = Math.round(diffMs / (1000 * 60 * 60 * 24))
+
+  return Math.floor(diffDays / resolved.sprintLengthDays) + 1
+}
+
+// =============================================================================
+// Core Engine
+// =============================================================================
+
+/**
+ * Calculate velocity metrics from outcome data.
+ */
+export function calculateVelocity(
+  outcomes: Outcome[],
+  config: VelocityConfig = DEFAULT_VELOCITY_CONFIG
+): VelocityMetrics {
+  const resolved = resolveConfig(config)
+
+  if (outcomes.length === 0) {
+    return {
+      sprints: [],
+      averageVelocity: 0,
+      velocityTrend: 'stable',
+      estimationAccuracy: 0,
+      overEstimated: [],
+      underEstimated: [],
+      lastUpdated: new Date().toISOString(),
+    }
+  }
+
+  // Parse outcomes into sprint buckets
+  const sprintBuckets = bucketBySprint(outcomes, config)
+  const sprints = buildSprintVelocities(sprintBuckets, resolved.accuracyTolerance)
+
+  // Use last N sprints for rolling metrics
+  const windowSprints = sprints.slice(-resolved.windowSize)
+
+  const averageVelocity = calculateAverageVelocity(windowSprints)
+  const velocityTrend = detectTrend(windowSprints)
+  const estimationAccuracy = calculateOverallAccuracy(outcomes, resolved.accuracyTolerance)
+
+  // Detect estimation patterns
+  const { overEstimated, underEstimated } = detectEstimationPatterns(outcomes)
+
+  return {
+    sprints,
+    averageVelocity,
+    velocityTrend,
+    estimationAccuracy,
+    overEstimated,
+    underEstimated,
+    lastUpdated: new Date().toISOString(),
+  }
+}
+
+/**
+ * Project completion date given remaining points and current velocity.
+ */
+export function projectCompletion(
+  totalPoints: number,
+  averageVelocity: number,
+  config: VelocityConfig = DEFAULT_VELOCITY_CONFIG
+): CompletionProjection {
+  const resolved = resolveConfig(config)
+
+  if (averageVelocity <= 0) {
+    return {
+      totalPoints,
+      sprints: 0,
+      estimatedDate: '',
+    }
+  }
+
+  const sprints = Math.ceil(totalPoints / averageVelocity)
+  const daysRemaining = sprints * resolved.sprintLengthDays
+  const estimatedDate = new Date()
+  estimatedDate.setDate(estimatedDate.getDate() + daysRemaining)
+
+  return {
+    totalPoints,
+    sprints,
+    estimatedDate: estimatedDate.toISOString(),
+  }
+}
+
+// =============================================================================
+// Sprint Bucketing
+// =============================================================================
+
+interface SprintBucket {
+  sprintNumber: number
+  startDate: Date
+  endDate: Date
+  outcomes: Outcome[]
+}
+
+function bucketBySprint(outcomes: Outcome[], config: VelocityConfig): Map<number, SprintBucket> {
+  const buckets = new Map<number, SprintBucket>()
+
+  // Find earliest outcome date
+  const dates = outcomes.map((o) => new Date(o.completedAt))
+  const earliest = new Date(Math.min(...dates.map((d) => d.getTime())))
+
+  for (const outcome of outcomes) {
+    const completedDate = new Date(outcome.completedAt)
+    const sprintNum = getSprintNumber(completedDate, earliest, config)
+
+    if (!buckets.has(sprintNum)) {
+      const start = getSprintStart(completedDate, config)
+      const end = getSprintEnd(start, config)
+      buckets.set(sprintNum, {
+        sprintNumber: sprintNum,
+        startDate: start,
+        endDate: end,
+        outcomes: [],
+      })
+    }
+
+    buckets.get(sprintNum)!.outcomes.push(outcome)
+  }
+
+  return buckets
+}
+
+function buildSprintVelocities(
+  buckets: Map<number, SprintBucket>,
+  accuracyTolerance: number
+): SprintVelocity[] {
+  const sprints: SprintVelocity[] = []
+
+  for (const [, bucket] of buckets) {
+    const points = bucket.outcomes.reduce((sum, o) => {
+      return sum + derivePoints(o)
+    }, 0)
+
+    const variances = bucket.outcomes.filter((o) => o.variance).map((o) => parseVariancePercent(o))
+
+    const avgVariance =
+      variances.length > 0 ? Math.round(variances.reduce((a, b) => a + b, 0) / variances.length) : 0
+
+    const accurateCount = variances.filter((v) => Math.abs(v) <= accuracyTolerance).length
+    const estimationAccuracy =
+      variances.length > 0 ? Math.round((accurateCount / variances.length) * 100) : 0
+
+    sprints.push({
+      sprintNumber: bucket.sprintNumber,
+      startDate: bucket.startDate.toISOString(),
+      endDate: bucket.endDate.toISOString(),
+      pointsCompleted: points,
+      tasksCompleted: bucket.outcomes.length,
+      avgVariance,
+      estimationAccuracy,
+    })
+  }
+
+  // Sort by sprint number
+  return sprints.sort((a, b) => a.sprintNumber - b.sprintNumber)
+}
+
+// =============================================================================
+// Trend Detection
+// =============================================================================
+
+/**
+ * Detect velocity trend using simple linear regression on points per sprint.
+ * Requires at least 3 sprints for meaningful trend detection.
+ */
+export function detectTrend(sprints: SprintVelocity[]): VelocityTrend {
+  if (sprints.length < 3) return 'stable'
+
+  const points = sprints.map((s) => s.pointsCompleted)
+  const n = points.length
+
+  // Simple linear regression slope
+  let sumX = 0
+  let sumY = 0
+  let sumXY = 0
+  let sumX2 = 0
+  for (let i = 0; i < n; i++) {
+    sumX += i
+    sumY += points[i]
+    sumXY += i * points[i]
+    sumX2 += i * i
+  }
+
+  const slope = (n * sumXY - sumX * sumY) / (n * sumX2 - sumX * sumX)
+  const avgVelocity = sumY / n
+
+  // Normalize slope as percentage of average velocity
+  if (avgVelocity === 0) return 'stable'
+
+  const normalizedSlope = slope / avgVelocity
+
+  // Thresholds: >10% per sprint = improving, <-10% = declining
+  if (normalizedSlope > 0.1) return 'improving'
+  if (normalizedSlope < -0.1) return 'declining'
+  return 'stable'
+}
+
+// =============================================================================
+// Estimation Accuracy
+// =============================================================================
+
+function calculateOverallAccuracy(outcomes: Outcome[], tolerance: number): number {
+  const withEstimates = outcomes.filter((o) => o.variance)
+  if (withEstimates.length === 0) return 0
+
+  const accurate = withEstimates.filter((o) => {
+    const variancePct = parseVariancePercent(o)
+    return Math.abs(variancePct) <= tolerance
+  })
+
+  return Math.round((accurate.length / withEstimates.length) * 100)
+}
+
+function calculateAverageVelocity(sprints: SprintVelocity[]): number {
+  if (sprints.length === 0) return 0
+  const total = sprints.reduce((sum, s) => sum + s.pointsCompleted, 0)
+  return Math.round((total / sprints.length) * 10) / 10
+}
+
+// =============================================================================
+// Estimation Pattern Detection
+// =============================================================================
+
+function detectEstimationPatterns(outcomes: Outcome[]): {
+  overEstimated: EstimationPattern[]
+  underEstimated: EstimationPattern[]
+} {
+  // Group by tags/categories
+  const byCategory = new Map<string, { variances: number[]; count: number }>()
+
+  for (const outcome of outcomes) {
+    if (!outcome.variance) continue
+    const variancePct = parseVariancePercent(outcome)
+
+    // Use tags as categories, fall back to 'uncategorized'
+    const categories = outcome.tags && outcome.tags.length > 0 ? outcome.tags : ['uncategorized']
+
+    for (const category of categories) {
+      if (!byCategory.has(category)) {
+        byCategory.set(category, { variances: [], count: 0 })
+      }
+      const entry = byCategory.get(category)!
+      entry.variances.push(variancePct)
+      entry.count++
+    }
+  }
+
+  const overEstimated: EstimationPattern[] = []
+  const underEstimated: EstimationPattern[] = []
+
+  for (const [category, data] of byCategory) {
+    if (data.count < 2) continue // Need at least 2 data points
+
+    const avg = Math.round(data.variances.reduce((a, b) => a + b, 0) / data.variances.length)
+
+    if (avg > 10) {
+      // Actual took longer than estimated → under-estimated
+      underEstimated.push({ category, avgVariance: avg, taskCount: data.count })
+    } else if (avg < -10) {
+      // Actual was faster than estimated → over-estimated
+      overEstimated.push({ category, avgVariance: Math.abs(avg), taskCount: data.count })
+    }
+  }
+
+  // Sort by severity
+  overEstimated.sort((a, b) => b.avgVariance - a.avgVariance)
+  underEstimated.sort((a, b) => b.avgVariance - a.avgVariance)
+
+  return { overEstimated, underEstimated }
+}
+
+// =============================================================================
+// Helpers
+// =============================================================================
+
+/**
+ * Parse variance from an outcome into a percentage.
+ * Handles both string format ("+30m") and the presence of estimatedDuration.
+ */
+function parseVariancePercent(outcome: Outcome): number {
+  if (!outcome.variance) return 0
+
+  const estimated = parseDurationMinutes(outcome.estimatedDuration)
+  const actual = parseDurationMinutes(outcome.actualDuration)
+
+  if (estimated <= 0) return 0
+
+  return Math.round(((actual - estimated) / estimated) * 100)
+}
+
+/**
+ * Parse duration string to minutes.
+ * Supports: "2h", "30m", "1h 30m", "2h30m", "90m", "45s" (→ 1m)
+ */
+export function parseDurationMinutes(duration: string): number {
+  let minutes = 0
+
+  const hourMatch = duration.match(/(\d+)h/)
+  if (hourMatch) {
+    minutes += Number.parseInt(hourMatch[1], 10) * 60
+  }
+
+  const minMatch = duration.match(/(\d+)m/)
+  if (minMatch) {
+    minutes += Number.parseInt(minMatch[1], 10)
+  }
+
+  const secMatch = duration.match(/(\d+)s/)
+  if (secMatch && minutes === 0) {
+    // Only count seconds if no hours/minutes (round up to 1 min)
+    minutes = 1
+  }
+
+  return minutes
+}
+
+/**
+ * Format velocity for LLM context injection.
+ */
+export function formatVelocityContext(metrics: VelocityMetrics): string {
+  if (metrics.sprints.length === 0) {
+    return 'No velocity data available yet.'
+  }
+
+  const lines: string[] = []
+  lines.push(
+    `Project velocity: ${metrics.averageVelocity} pts/sprint (trend: ${metrics.velocityTrend})`
+  )
+  lines.push(`Estimation accuracy: ${metrics.estimationAccuracy}%`)
+
+  for (const pattern of metrics.underEstimated) {
+    lines.push(
+      `⚠ "${pattern.category}" tasks historically take ${pattern.avgVariance}% longer than estimated`
+    )
+  }
+
+  for (const pattern of metrics.overEstimated) {
+    lines.push(
+      `"${pattern.category}" tasks typically finish ${pattern.avgVariance}% faster than estimated`
+    )
+  }
+
+  return lines.join('\n')
+}
+
+/** Fibonacci points with typical minutes for points derivation */
+const FIBONACCI_MINUTES: Array<{ points: number; typical: number }> = [
+  { points: 1, typical: 10 },
+  { points: 2, typical: 20 },
+  { points: 3, typical: 45 },
+  { points: 5, typical: 90 },
+  { points: 8, typical: 180 },
+  { points: 13, typical: 360 },
+  { points: 21, typical: 720 },
+]
+
+/**
+ * Derive story points from an outcome's estimated duration.
+ * Maps to nearest Fibonacci point using the standard points-to-minutes table.
+ */
+function derivePoints(outcome: Outcome): number {
+  if (!outcome.estimatedDuration) return 0
+
+  const minutes = parseDurationMinutes(outcome.estimatedDuration)
+  if (minutes <= 0) return 0
+
+  let closest = FIBONACCI_MINUTES[0]
+  let smallestDiff = Number.POSITIVE_INFINITY
+
+  for (const entry of FIBONACCI_MINUTES) {
+    const diff = Math.abs(entry.typical - minutes)
+    if (diff < smallestDiff) {
+      smallestDiff = diff
+      closest = entry
+    }
+  }
+
+  return closest.points
+}
+
+function resolveConfig(config: VelocityConfig): Required<VelocityConfig> {
+  return {
+    sprintLengthDays: config.sprintLengthDays ?? 7,
+    startDay: config.startDay ?? 'monday',
+    windowSize: config.windowSize ?? 6,
+    accuracyTolerance: config.accuracyTolerance ?? 20,
+  }
+}

package/core/index.ts

@@ -156,6 +156,7 @@ async function main(): Promise<void> {
           }),
         help: (p) => commands.help(p || ''),
         perf: (p) => commands.perf(p || '7'),
+        velocity: (p) => commands.velocity(p || '0'),
         // Maintenance
         recover: () => commands.recover(),
         undo: () => commands.undo(),

package/core/schemas/index.ts

@@ -49,3 +49,5 @@ export {
 export * from './shipped'
 // State (current task + queue)
 export * from './state'
+// Velocity (sprint-based tracking)
+export * from './velocity'

package/core/schemas/velocity.ts

@@ -0,0 +1,103 @@
+/**
+ * Velocity Schema (PRJ-296)
+ *
+ * Defines the structure for velocity tracking:
+ * - Sprint-based velocity with configurable sprint length
+ * - Estimation accuracy trends
+ * - Over/under estimation patterns
+ * - Completion projections
+ *
+ * @version 1.0.0
+ */
+
+import { z } from 'zod'
+
+// =============================================================================
+// Zod Schemas - Source of Truth
+// =============================================================================
+
+export const VelocityTrendSchema = z.enum(['improving', 'stable', 'declining'])
+
+export const SprintVelocitySchema = z.object({
+  sprintNumber: z.number(),
+  startDate: z.string(), // ISO8601
+  endDate: z.string(), // ISO8601
+  pointsCompleted: z.number(),
+  tasksCompleted: z.number(),
+  avgVariance: z.number(), // Average estimation variance (%)
+  estimationAccuracy: z.number(), // % of tasks within tolerance
+})
+
+export const EstimationPatternSchema = z.object({
+  category: z.string(), // task type or domain
+  avgVariance: z.number(), // positive = over, negative = under
+  taskCount: z.number(),
+})
+
+export const CompletionProjectionSchema = z.object({
+  totalPoints: z.number(),
+  sprints: z.number(),
+  estimatedDate: z.string(), // ISO8601
+})
+
+export const VelocityMetricsSchema = z.object({
+  sprints: z.array(SprintVelocitySchema),
+  averageVelocity: z.number(),
+  velocityTrend: VelocityTrendSchema,
+  estimationAccuracy: z.number(), // 0-100%
+  overEstimated: z.array(EstimationPatternSchema),
+  underEstimated: z.array(EstimationPatternSchema),
+  lastUpdated: z.string(), // ISO8601
+})
+
+export const VelocityConfigSchema = z.object({
+  sprintLengthDays: z.number().min(1).max(90).default(7),
+  startDay: z
+    .enum(['monday', 'tuesday', 'wednesday', 'thursday', 'friday', 'saturday', 'sunday'])
+    .default('monday'),
+  windowSize: z.number().min(1).max(52).default(6), // number of sprints for rolling average
+  accuracyTolerance: z.number().min(0).max(100).default(20), // ±% for "accurate" estimate
+})
+
+// =============================================================================
+// Inferred Types
+// =============================================================================
+
+export type VelocityTrend = z.infer<typeof VelocityTrendSchema>
+export type SprintVelocity = z.infer<typeof SprintVelocitySchema>
+export type EstimationPattern = z.infer<typeof EstimationPatternSchema>
+export type CompletionProjection = z.infer<typeof CompletionProjectionSchema>
+export type VelocityMetrics = z.infer<typeof VelocityMetricsSchema>
+export type VelocityConfig = z.input<typeof VelocityConfigSchema>
+
+// =============================================================================
+// Defaults
+// =============================================================================
+
+export const DEFAULT_VELOCITY_CONFIG: VelocityConfig = {
+  sprintLengthDays: 7,
+  startDay: 'monday',
+  windowSize: 6,
+  accuracyTolerance: 20,
+}
+
+export const DEFAULT_VELOCITY_METRICS: VelocityMetrics = {
+  sprints: [],
+  averageVelocity: 0,
+  velocityTrend: 'stable',
+  estimationAccuracy: 0,
+  overEstimated: [],
+  underEstimated: [],
+  lastUpdated: '',
+}
+
+// =============================================================================
+// Validation Helpers
+// =============================================================================
+
+export const parseVelocityMetrics = (data: unknown): VelocityMetrics =>
+  VelocityMetricsSchema.parse(data)
+
+export const safeParseVelocityMetrics = (data: unknown) => VelocityMetricsSchema.safeParse(data)
+
+export const parseVelocityConfig = (data: unknown) => VelocityConfigSchema.parse(data)

package/core/storage/index.ts

@@ -79,8 +79,9 @@ export { metricsStorage } from './metrics-storage'
 export { queueStorage } from './queue-storage'
 export { shippedStorage } from './shipped-storage'
 export { stateStorage } from './state-storage'
-
 // ========== GRANULAR STORAGE (Legacy) ==========
 export { getStorage } from './storage'
 // ========== AGGREGATE STORAGE (Recommended) ==========
 export { StorageManager } from './storage-manager'
+export type { VelocityStoreData } from './velocity-storage'
+export { velocityStorage } from './velocity-storage'