prjct-cli 1.7.5 → 1.8.0

package/core/agentic/prompt-builder.ts

@@ -12,6 +12,7 @@
 import fs from 'node:fs/promises'
 import path from 'node:path'
 import { outcomeAnalyzer } from '../outcomes'
+import type { CommandContextEntry } from '../schemas/command-context'
 import { queueStorage, stateStorage } from '../storage'
 import type {
   LearnedPatterns,
@@ -28,6 +29,7 @@ import type {
 import { getErrorMessage, isNotFoundError } from '../types/fs'
 import { fileExists } from '../utils/fs-helpers'
 import { PACKAGE_ROOT } from '../utils/version'
+import { loadCommandContextConfig, resolveCommandContextFull } from './command-context'
 import {
   DEFAULT_BUDGETS,
   filterSkillsByDomains,
@@ -144,18 +146,14 @@ class PromptBuilder {
 
   /**
    * Get additional modules needed for SMART commands (PRJ-94)
-   * Returns array of module names that should be injected
+   * Now config-driven via command-context.config.json (PRJ-298)
    */
-  getModulesForCommand(commandName: string): string[] {
-    const smartCommands: Record<string, string[]> = {
-      task: ['CLAUDE-intelligence.md', 'CLAUDE-storage.md'],
-      ship: ['CLAUDE-intelligence.md', 'CLAUDE-storage.md'],
-      bug: ['CLAUDE-intelligence.md'],
-      done: ['CLAUDE-storage.md'],
-      work: ['CLAUDE-intelligence.md', 'CLAUDE-storage.md'],
-      spec: ['CLAUDE-intelligence.md'],
-    }
-    return smartCommands[commandName] || []
+  getModulesForCommand(_commandName: string, commandContext?: CommandContextEntry): string[] {
+    if (commandContext) {
+      return commandContext.modules
+    }
+    // Fallback if called without config (shouldn't happen after PRJ-298)
+    return []
   }
 
   /**
@@ -411,21 +409,20 @@ class PromptBuilder {
     // Store context for use in helper methods
     this._currentContext = context
 
-    // Agent assignment (CONDITIONAL - only for code-modifying commands)
+    // PRJ-298: Config-driven command context (replaces 4 hardcoded lists)
     const commandName = template.frontmatter?.name?.replace('p:', '') || ''
-    const agentCommands = [
-      'now',
-      'build',
-      'feature',
-      'design',
-      'fix',
-      'bug',
-      'test',
-      'work',
-      'cleanup',
-      'spec',
-    ]
-    const needsAgent = agentCommands.includes(commandName)
+    let commandContext: CommandContextEntry
+    try {
+      const config = await loadCommandContextConfig()
+      const resolved = resolveCommandContextFull(config, commandName, template)
+      commandContext = resolved.entry
+    } catch {
+      // Fallback: sensible defaults if config fails to load
+      commandContext = { agents: true, patterns: true, checklist: false, modules: [] }
+    }
+
+    // Agent assignment (config-driven)
+    const needsAgent = commandContext.agents
 
     if (agent && needsAgent) {
       parts.push(`# AGENT: ${agent.name}\n`)
@@ -591,21 +588,8 @@ class PromptBuilder {
       )
     }
 
-    // OPTIMIZED: Only include patterns for code-modifying commands
-    const codeCommands = [
-      'now',
-      'build',
-      'feature',
-      'design',
-      'cleanup',
-      'fix',
-      'bug',
-      'test',
-      'init',
-      'spec',
-      'work',
-    ]
-    const needsPatterns = codeCommands.includes(commandName)
+    // OPTIMIZED: Only include patterns for code-modifying commands (config-driven, PRJ-298)
+    const needsPatterns = commandContext.patterns
 
     // Include code patterns analysis for code-modifying commands
     const codePatternsContent = state?.codePatterns || ''
@@ -636,8 +620,8 @@ class PromptBuilder {
     // CRITICAL: Compressed rules
     parts.push(this.buildCriticalRules())
 
-    // PRJ-94: Inject additional modules for SMART commands
-    const additionalModules = this.getModulesForCommand(commandName)
+    // PRJ-94/PRJ-298: Inject additional modules for SMART commands (config-driven)
+    const additionalModules = this.getModulesForCommand(commandName, commandContext)
     if (additionalModules.length > 0) {
       for (const moduleName of additionalModules) {
         const moduleContent = await this.loadModule(moduleName)
@@ -698,19 +682,8 @@ class PromptBuilder {
       )
     }
 
-    // P4.1: Quality Checklists
-    const checklistCommands = [
-      'now',
-      'build',
-      'feature',
-      'design',
-      'fix',
-      'bug',
-      'cleanup',
-      'spec',
-      'work',
-    ]
-    if (checklistCommands.includes(commandName)) {
+    // P4.1: Quality Checklists (config-driven, PRJ-298)
+    if (commandContext.checklist) {
       const routing = await this.loadChecklistRouting()
       const checklists = await this.loadChecklists()
 

package/core/commands/command-data.ts

@@ -176,6 +176,23 @@ export const COMMANDS: CommandMeta[] = [
       'Per-package CLAUDE.md generation',
     ],
   },
+  {
+    name: 'perf',
+    group: 'core',
+    description: 'Performance dashboard - startup, memory, context, and handoff metrics',
+    usage: { claude: '/p:perf', terminal: 'prjct perf [days]' },
+    params: '[days]',
+    implemented: true,
+    hasTemplate: false,
+    requiresProject: true,
+    features: [
+      'Startup time tracking',
+      'Memory usage snapshots',
+      'Context correctness rate',
+      'Subtask handoff rate',
+      'Command duration breakdown',
+    ],
+  },
   {
     name: 'suggest',
     group: 'core',

package/core/commands/commands.ts

@@ -27,6 +27,7 @@ import { AnalysisCommands } from './analysis'
 import { AnalyticsCommands } from './analytics'
 import { ContextCommands } from './context'
 import { MaintenanceCommands } from './maintenance'
+import { PerformanceCommands } from './performance'
 import { PlanningCommands } from './planning'
 import { SetupCommands } from './setup'
 import { ShippingCommands } from './shipping'
@@ -42,6 +43,7 @@ class PrjctCommands {
   private planning: PlanningCommands
   private shipping: ShippingCommands
   private analytics: AnalyticsCommands
+  private performanceCmds: PerformanceCommands
   private maintenance: MaintenanceCommands
   private analysis: AnalysisCommands
   private setupCmds: SetupCommands
@@ -58,6 +60,7 @@ class PrjctCommands {
     this.planning = new PlanningCommands()
     this.shipping = new ShippingCommands()
     this.analytics = new AnalyticsCommands()
+    this.performanceCmds = new PerformanceCommands()
     this.maintenance = new MaintenanceCommands()
     this.analysis = new AnalysisCommands()
     this.setupCmds = new SetupCommands()
@@ -140,6 +143,12 @@ class PrjctCommands {
     return this.analytics.help(topic, projectPath)
   }
 
+  // ========== Performance Commands ==========
+
+  async perf(period: string = '7', projectPath: string = process.cwd()): Promise<CommandResult> {
+    return this.performanceCmds.perf(period, projectPath)
+  }
+
   // ========== Maintenance Commands ==========
 
   async cleanup(

package/core/commands/performance.ts

@@ -0,0 +1,114 @@
+/**
+ * Performance Commands: perf
+ * Dashboard for CLI performance metrics
+ *
+ * @see PRJ-297
+ */
+
+import chalk from 'chalk'
+import performanceTracker from '../infrastructure/performance-tracker'
+import type { CommandResult } from '../types'
+import { getErrorMessage } from '../types/fs'
+import { configManager, out, PrjctCommandsBase } from './base'
+
+// Target thresholds for display
+const TARGETS = {
+  startup: { max: 500, unit: 'ms' },
+  heapMB: { max: 80, unit: 'MB' },
+  contextRate: { min: 100, unit: '%' },
+  handoffRate: { min: 100, unit: '%' },
+}
+
+function statusIcon(value: number, target: number, mode: 'below' | 'above'): string {
+  if (mode === 'below') {
+    return value <= target ? chalk.green('✓') : chalk.yellow('⚠')
+  }
+  return value >= target ? chalk.green('✓') : chalk.yellow('⚠')
+}
+
+export class PerformanceCommands extends PrjctCommandsBase {
+  /**
+   * prjct perf - Performance dashboard
+   */
+  async perf(period: string = '7', projectPath: string = process.cwd()): Promise<CommandResult> {
+    try {
+      const initResult = await this.ensureProjectInit(projectPath)
+      if (!initResult.success) return initResult
+
+      const projectId = await configManager.getProjectId(projectPath)
+      if (!projectId) {
+        out.failWithHint('NO_PROJECT_ID')
+        return { success: false, error: 'No project ID found' }
+      }
+
+      const days = parseInt(period, 10) || 7
+      const report = await performanceTracker.getReport(projectId, days)
+
+      const hasData =
+        report.startup ||
+        report.memory ||
+        report.contextCorrectness ||
+        report.subtaskHandoff ||
+        report.commandDurations
+
+      if (!hasData) {
+        console.log(`\n${chalk.dim('No performance data yet.')}`)
+        console.log(`${chalk.dim('Metrics are collected automatically as you use the CLI.')}\n`)
+        return { success: true, message: 'No data' }
+      }
+
+      console.log(`\n${chalk.cyan('Performance Report')} ${chalk.dim(`(last ${days} days)`)}`)
+      console.log('═'.repeat(55))
+
+      // Startup time
+      if (report.startup) {
+        const icon = statusIcon(report.startup.avg, TARGETS.startup.max, 'below')
+        console.log(
+          `  Startup:     avg ${chalk.bold(`${report.startup.avg}ms`)} ${chalk.dim(`(min ${report.startup.min}, max ${report.startup.max}, n=${report.startup.count})`)} ${icon} ${chalk.dim(`target: <${TARGETS.startup.max}ms`)}`
+        )
+      }
+
+      // Memory
+      if (report.memory) {
+        const icon = statusIcon(report.memory.peakHeapMB, TARGETS.heapMB.max, 'below')
+        console.log(
+          `  Memory:      avg ${chalk.bold(`${report.memory.avgHeapMB}MB`)} heap, peak ${report.memory.peakHeapMB}MB, rss ${report.memory.avgRssMB}MB ${icon} ${chalk.dim(`target: <${TARGETS.heapMB.max}MB`)}`
+        )
+      }
+
+      // Context correctness
+      if (report.contextCorrectness) {
+        const icon = statusIcon(report.contextCorrectness.rate, TARGETS.contextRate.min, 'above')
+        console.log(
+          `  Context:     ${chalk.bold(`${report.contextCorrectness.rate}%`)} tasks received sync ${chalk.dim(`(${report.contextCorrectness.receivedSync}/${report.contextCorrectness.total})`)} ${icon} ${chalk.dim(`target: ${TARGETS.contextRate.min}%`)}`
+        )
+      }
+
+      // Subtask handoff
+      if (report.subtaskHandoff) {
+        const icon = statusIcon(report.subtaskHandoff.rate, TARGETS.handoffRate.min, 'above')
+        console.log(
+          `  Handoff:     ${chalk.bold(`${report.subtaskHandoff.rate}%`)} subtasks with output ${chalk.dim(`(${report.subtaskHandoff.outputPopulated}/${report.subtaskHandoff.total})`)} ${icon} ${chalk.dim(`target: ${TARGETS.handoffRate.min}%`)}`
+        )
+      }
+
+      // Command durations
+      if (report.commandDurations && Object.keys(report.commandDurations).length > 0) {
+        console.log(`\n  ${chalk.dim('Command Durations:')}`)
+        for (const [cmd, summary] of Object.entries(report.commandDurations)) {
+          console.log(
+            `    ${cmd.padEnd(12)} avg ${chalk.bold(`${summary.avg}ms`)} ${chalk.dim(`(min ${summary.min}, max ${summary.max}, n=${summary.count})`)}`
+          )
+        }
+      }
+
+      console.log('═'.repeat(55))
+      console.log('')
+
+      return { success: true }
+    } catch (error) {
+      out.fail(getErrorMessage(error))
+      return { success: false, error: getErrorMessage(error) }
+    }
+  }
+}

package/core/commands/register.ts

@@ -13,6 +13,7 @@ import { AnalyticsCommands } from './analytics'
 import { CATEGORIES, COMMANDS } from './command-data'
 import { ContextCommands } from './context'
 import { MaintenanceCommands } from './maintenance'
+import { PerformanceCommands } from './performance'
 import { PlanningCommands } from './planning'
 import { commandRegistry } from './registry'
 import { SetupCommands } from './setup'
@@ -25,6 +26,7 @@ const workflow = new WorkflowCommands()
 const planning = new PlanningCommands()
 const shipping = new ShippingCommands()
 const analytics = new AnalyticsCommands()
+const performance = new PerformanceCommands()
 const maintenance = new MaintenanceCommands()
 const analysis = new AnalysisCommands()
 const setup = new SetupCommands()
@@ -73,6 +75,9 @@ export function registerAllCommands(): void {
   commandRegistry.registerMethod('dash', analytics, 'dash', getMeta('dash'))
   commandRegistry.registerMethod('help', analytics, 'help', getMeta('help'))
 
+  // Performance commands
+  commandRegistry.registerMethod('perf', performance, 'perf', getMeta('perf'))
+
   // Maintenance commands
   commandRegistry.registerMethod('cleanup', maintenance, 'cleanup', getMeta('cleanup'))
   commandRegistry.registerMethod('design', maintenance, 'design', getMeta('design'))
@@ -105,6 +110,7 @@ export {
   planning,
   shipping,
   analytics,
+  performance,
   maintenance,
   analysis,
   setup,

package/core/commands/workflow.ts

@@ -10,7 +10,14 @@
 
 import commandExecutor from '../agentic/command-executor'
 import { templateExecutor } from '../agentic/template-executor'
+import {
+  type FibonacciPoint,
+  isValidPoint,
+  pointsToMinutes,
+  pointsToTimeRange,
+} from '../domain/fibonacci'
 import { linearService } from '../integrations/linear'
+import outcomeRecorder from '../outcomes/recorder'
 import { generateUUID } from '../schemas'
 import { queueStorage, stateStorage } from '../storage'
 import type { CommandResult } from '../types'
@@ -132,6 +139,20 @@ export class WorkflowCommands extends PrjctCommandsBase {
           task,
           agenticMode: true,
           availableAgents,
+          // Fibonacci estimation helpers for templates
+          fibonacci: {
+            isValidPoint,
+            pointsToMinutes,
+            pointsToTimeRange,
+            storeEstimate: async (points: FibonacciPoint) => {
+              const minutes = pointsToMinutes(points)
+              await stateStorage.updateCurrentTask(projectId, {
+                estimatedPoints: points,
+                estimatedMinutes: minutes.typical,
+              })
+              return minutes
+            },
+          },
         }
       } else {
         // Read from storage (JSON is source of truth)
@@ -187,9 +208,44 @@ export class WorkflowCommands extends PrjctCommandsBase {
 
       const task = currentTask.description
       let duration = ''
+      let actualMinutes = 0
       if (currentTask.startedAt) {
         const started = new Date(currentTask.startedAt)
         duration = dateHelper.calculateDuration(started)
+        actualMinutes = Math.round((Date.now() - started.getTime()) / 60_000)
+      }
+
+      // Record outcome with estimation data if available
+      const estimatedMinutes = (currentTask as { estimatedMinutes?: number }).estimatedMinutes
+      const estimatedPoints = (currentTask as { estimatedPoints?: number }).estimatedPoints
+      try {
+        await outcomeRecorder.record(projectId, {
+          sessionId: currentTask.sessionId,
+          command: 'done',
+          task,
+          startedAt: currentTask.startedAt,
+          completedAt: dateHelper.getTimestamp(),
+          estimatedDuration: estimatedMinutes ? formatMinutesToDuration(estimatedMinutes) : '0m',
+          actualDuration: duration || '0m',
+          variance: estimatedMinutes ? formatVariance(actualMinutes - estimatedMinutes) : '+0m',
+          completedAsPlanned: true,
+          qualityScore: 3,
+          tags: [(currentTask as { linearId?: string }).linearId].filter(Boolean) as string[],
+        })
+      } catch {
+        // Outcome recording failure should not block workflow
+      }
+
+      // Build variance display
+      let varianceDisplay = ''
+      if (estimatedPoints && estimatedMinutes) {
+        const diff = actualMinutes - estimatedMinutes
+        const pct =
+          estimatedMinutes > 0
+            ? Math.round(((actualMinutes - estimatedMinutes) / estimatedMinutes) * 100)
+            : 0
+        const sign = diff >= 0 ? '+' : ''
+        varianceDisplay = ` | est: ${estimatedPoints}pt (${formatMinutesToDuration(estimatedMinutes)}) → ${sign}${pct}%`
       }
 
       // Write-through: Complete task (JSON → MD → Event)
@@ -204,16 +260,16 @@ export class WorkflowCommands extends PrjctCommandsBase {
           if (apiKey && creds.linear?.teamId) {
             await linearService.initializeFromApiKey(apiKey, creds.linear.teamId)
             await linearService.markDone(linearId)
-            out.done(`${task}${duration ? ` (${duration})` : ''} → Linear ✓`)
+            out.done(`${task}${duration ? ` (${duration}${varianceDisplay})` : ''} → Linear ✓`)
           } else {
-            out.done(`${task}${duration ? ` (${duration})` : ''}`)
+            out.done(`${task}${duration ? ` (${duration}${varianceDisplay})` : ''}`)
           }
         } catch {
           // Linear sync failed silently - don't block the workflow
-          out.done(`${task}${duration ? ` (${duration})` : ''}`)
+          out.done(`${task}${duration ? ` (${duration}${varianceDisplay})` : ''}`)
         }
       } else {
-        out.done(`${task}${duration ? ` (${duration})` : ''}`)
+        out.done(`${task}${duration ? ` (${duration}${varianceDisplay})` : ''}`)
       }
       showStateInfo('completed')
       showNextSteps('done')
@@ -221,6 +277,9 @@ export class WorkflowCommands extends PrjctCommandsBase {
       await this.logToMemory(projectPath, 'task_completed', {
         task,
         duration,
+        estimatedPoints,
+        estimatedMinutes,
+        actualMinutes,
         timestamp: dateHelper.getTimestamp(),
       })
 
@@ -417,3 +476,27 @@ export class WorkflowCommands extends PrjctCommandsBase {
     }
   }
 }
+
+// =============================================================================
+// Helpers
+// =============================================================================
+
+/** Format minutes to a human-readable duration string */
+function formatMinutesToDuration(minutes: number): string {
+  if (minutes < 60) return `${minutes}m`
+  const hours = Math.floor(minutes / 60)
+  const mins = minutes % 60
+  return mins > 0 ? `${hours}h ${mins}m` : `${hours}h`
+}
+
+/** Format a variance in minutes to a string like "+30m" or "-15m" */
+function formatVariance(diffMinutes: number): string {
+  const sign = diffMinutes >= 0 ? '+' : '-'
+  const abs = Math.abs(diffMinutes)
+  if (abs >= 60) {
+    const hours = Math.floor(abs / 60)
+    const mins = abs % 60
+    return mins > 0 ? `${sign}${hours}h ${mins}m` : `${sign}${hours}h`
+  }
+  return `${sign}${abs}m`
+}

package/core/config/command-context.config.json

@@ -0,0 +1,66 @@
+{
+  "version": "1.0.0",
+  "description": "Maps commands to context sections for prompt injection. Wildcard * ensures new commands get sensible defaults instead of zero context.",
+  "commands": {
+    "now": { "agents": true, "patterns": true, "checklist": true, "modules": [] },
+    "build": { "agents": true, "patterns": true, "checklist": true, "modules": [] },
+    "feature": { "agents": true, "patterns": true, "checklist": true, "modules": [] },
+    "design": { "agents": true, "patterns": true, "checklist": true, "modules": [] },
+    "fix": { "agents": true, "patterns": true, "checklist": true, "modules": [] },
+    "bug": {
+      "agents": true,
+      "patterns": true,
+      "checklist": true,
+      "modules": ["CLAUDE-intelligence.md"]
+    },
+    "test": { "agents": true, "patterns": true, "checklist": false, "modules": [] },
+    "work": {
+      "agents": true,
+      "patterns": true,
+      "checklist": true,
+      "modules": ["CLAUDE-intelligence.md", "CLAUDE-storage.md"]
+    },
+    "cleanup": { "agents": true, "patterns": true, "checklist": true, "modules": [] },
+    "spec": {
+      "agents": true,
+      "patterns": true,
+      "checklist": true,
+      "modules": ["CLAUDE-intelligence.md"]
+    },
+    "init": { "agents": false, "patterns": true, "checklist": false, "modules": [] },
+    "task": {
+      "agents": false,
+      "patterns": false,
+      "checklist": false,
+      "modules": ["CLAUDE-intelligence.md", "CLAUDE-storage.md"]
+    },
+    "ship": {
+      "agents": false,
+      "patterns": true,
+      "checklist": true,
+      "modules": ["CLAUDE-intelligence.md", "CLAUDE-storage.md"]
+    },
+    "done": {
+      "agents": false,
+      "patterns": false,
+      "checklist": true,
+      "modules": ["CLAUDE-storage.md"]
+    },
+    "review": { "agents": true, "patterns": true, "checklist": true, "modules": [] },
+    "refactor": {
+      "agents": true,
+      "patterns": true,
+      "checklist": true,
+      "modules": ["CLAUDE-intelligence.md"]
+    },
+    "sync": { "agents": false, "patterns": false, "checklist": false, "modules": [] },
+    "dash": { "agents": false, "patterns": false, "checklist": false, "modules": [] },
+    "next": { "agents": false, "patterns": false, "checklist": false, "modules": [] },
+    "pause": { "agents": false, "patterns": false, "checklist": false, "modules": [] },
+    "resume": { "agents": false, "patterns": false, "checklist": false, "modules": [] },
+    "idea": { "agents": false, "patterns": false, "checklist": false, "modules": [] },
+    "history": { "agents": false, "patterns": false, "checklist": false, "modules": [] },
+    "status": { "agents": false, "patterns": false, "checklist": false, "modules": [] },
+    "*": { "agents": true, "patterns": true, "checklist": false, "modules": [] }
+  }
+}

package/core/domain/fibonacci.ts

@@ -0,0 +1,128 @@
+/**
+ * Fibonacci Estimation Module
+ *
+ * Provides Fibonacci-based story point estimation with
+ * points-to-time conversion and historical suggestion.
+ */
+
+import outcomeRecorder from '../outcomes/recorder'
+
+// =============================================================================
+// Constants
+// =============================================================================
+
+/** Valid Fibonacci story points */
+export const FIBONACCI_POINTS = [1, 2, 3, 5, 8, 13, 21] as const
+export type FibonacciPoint = (typeof FIBONACCI_POINTS)[number]
+
+/** Default points-to-minutes mapping */
+const DEFAULT_MINUTES_MAP: Record<FibonacciPoint, { min: number; max: number; typical: number }> = {
+  1: { min: 5, max: 15, typical: 10 },
+  2: { min: 15, max: 30, typical: 20 },
+  3: { min: 30, max: 60, typical: 45 },
+  5: { min: 60, max: 120, typical: 90 },
+  8: { min: 120, max: 240, typical: 180 },
+  13: { min: 240, max: 480, typical: 360 },
+  21: { min: 480, max: 960, typical: 720 },
+}
+
+// =============================================================================
+// Validation
+// =============================================================================
+
+/** Check if a number is a valid Fibonacci point */
+export const isValidPoint = (n: number): n is FibonacciPoint =>
+  FIBONACCI_POINTS.includes(n as FibonacciPoint)
+
+// =============================================================================
+// Points-to-Time Conversion
+// =============================================================================
+
+/** Get the time range for a given point value */
+export const pointsToMinutes = (
+  points: FibonacciPoint
+): { min: number; max: number; typical: number } => {
+  return DEFAULT_MINUTES_MAP[points]
+}
+
+/** Format a minute count as a human-readable duration */
+export const formatMinutes = (minutes: number): string => {
+  if (minutes < 60) return `${minutes}m`
+  const hours = Math.floor(minutes / 60)
+  const mins = minutes % 60
+  return mins > 0 ? `${hours}h ${mins}m` : `${hours}h`
+}
+
+/** Get a human-readable time range for a point value */
+export const pointsToTimeRange = (points: FibonacciPoint): string => {
+  const range = pointsToMinutes(points)
+  return `${formatMinutes(range.min)}–${formatMinutes(range.max)}`
+}
+
+// =============================================================================
+// Historical Suggestion
+// =============================================================================
+
+/**
+ * Suggest a point estimate based on historical outcomes for similar task types.
+ * Returns null if not enough data (< 3 outcomes).
+ */
+export const suggestFromHistory = async (
+  projectId: string,
+  taskType: string
+): Promise<{ points: FibonacciPoint; basedOn: number } | null> => {
+  const outcomes = await outcomeRecorder.getAll(projectId)
+
+  // Filter by task type tag
+  const relevant = outcomes.filter((o) => o.tags?.includes(taskType))
+
+  if (relevant.length < 3) return null
+
+  // Calculate average actual duration in minutes
+  const totalMinutes = relevant.reduce((sum, o) => {
+    return sum + parseDuration(o.actualDuration)
+  }, 0)
+  const avgMinutes = totalMinutes / relevant.length
+
+  // Find closest Fibonacci point by typical time
+  const closest = findClosestPoint(avgMinutes)
+
+  return { points: closest, basedOn: relevant.length }
+}
+
+// =============================================================================
+// Helpers
+// =============================================================================
+
+/** Find the Fibonacci point whose typical time is closest to the given minutes */
+export const findClosestPoint = (minutes: number): FibonacciPoint => {
+  let closest: FibonacciPoint = 1
+  let smallestDiff = Number.POSITIVE_INFINITY
+
+  for (const point of FIBONACCI_POINTS) {
+    const diff = Math.abs(DEFAULT_MINUTES_MAP[point].typical - minutes)
+    if (diff < smallestDiff) {
+      smallestDiff = diff
+      closest = point
+    }
+  }
+
+  return closest
+}
+
+/** Parse a duration string like "2h 30m" to minutes */
+const parseDuration = (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)
+  }
+
+  return minutes
+}