prjct-cli 0.12.1 → 0.13.0

package/packages/web/lib/services/stats.server.ts

@@ -1,27 +1,110 @@
 /**
  * Stats Service (Server-only)
  *
- * Direct data access for Server Components.
- * No API calls needed - reads directly from filesystem.
+ * MD-First Architecture: Reads directly from MD files.
+ * No JSON fallback - MD is the source of truth.
  */
 
 import 'server-only'
 import { cache } from 'react'
 import { exec } from 'child_process'
 import { promisify } from 'util'
-import {
-  loadUnifiedJsonData,
-  hasJsonState,
-  type UnifiedJsonData,
-  type StateJson,
-  type QueueJson,
-  type MetricsJson,
-  type ProjectInsights,
-} from '@/lib/json-loader'
-import { getProjectStats as getLegacyStats, type ProjectStats } from '@/lib/parse-prjct-files'
+import { getProjectStats as getMdStats, type ProjectStats, type SessionDay } from '@/lib/parse-prjct-files'
 import { getProjects } from './projects.server'
 
-export type { UnifiedJsonData, StateJson, QueueJson, MetricsJson, ProjectInsights }
+// Types for MD-based stats
+export interface StateJson {
+  currentTask: {
+    id?: string
+    description: string
+    startedAt?: string
+    sessionId?: string
+    feature?: string
+    agent?: string
+  } | null
+  previousTask?: {
+    id?: string
+    description: string
+    status: string
+    startedAt?: string
+    pausedAt?: string
+  } | null
+  lastUpdated?: string
+}
+
+export interface QueueTask {
+  id: string
+  description: string
+  priority: 'low' | 'medium' | 'high' | 'critical'
+  type: 'feature' | 'bug' | 'improvement' | 'chore'
+  completed: boolean
+  createdAt: string
+  completedAt?: string
+  section: 'active' | 'backlog' | 'previously_active'
+  agent?: string
+  originFeature?: string
+}
+
+export interface QueueJson {
+  tasks: QueueTask[]
+  lastUpdated: string
+}
+
+export interface MetricsJson {
+  recentActivity?: Array<{ timestamp: string; type?: string; description?: string; action?: string }>
+  velocity?: { tasksPerDay?: number }
+  currentSprint?: { tasksCompleted?: number }
+}
+
+export interface Blocker {
+  task: string
+  reason: string
+  since: string
+  daysBlocked: number
+}
+
+export interface ProjectInsights {
+  healthScore: number
+  estimateAccuracy: number
+  blockers: Blocker[]
+  recommendations: string[]
+}
+
+export interface RoadmapFeature {
+  name: string
+  status?: 'pending' | 'active' | 'shipped' | 'completed'
+  tasks: Array<{
+    description: string
+    completed: boolean
+  }>
+}
+
+export interface ShippedItem {
+  name: string
+  date?: string
+  shippedAt?: string
+  duration?: string
+}
+
+export interface UnifiedJsonData {
+  state: StateJson | null
+  queue: QueueJson | null
+  metrics: MetricsJson | null
+  insights: ProjectInsights
+  agents: Array<{
+    name: string
+    role?: string
+    description?: string
+    successRate?: number
+    tasksCompleted?: number
+    bestFor?: string[]
+  }>
+  ideas: { ideas: Array<{ text: string; status?: string; priority?: string }> } | null
+  roadmap: { features: RoadmapFeature[] } | null
+  shipped: { items: ShippedItem[] } | null
+  outcomes: Array<{ type: string }>
+  hasJsonData: boolean
+}
 
 // Activity type for recent activity tracking
 export interface RecentActivity {
@@ -86,8 +169,7 @@ export interface StatsResult {
 const DEFAULT_INSIGHTS: ProjectInsights = {
   healthScore: 0,
   estimateAccuracy: 0,
-  topBlockers: [],
-  patternsDetected: [],
+  blockers: [],
   recommendations: ['Run /p:sync to initialize project']
 }
 
@@ -106,47 +188,273 @@ const EMPTY_STATS_RESULT: StatsResult = {
 }
 
 /**
- * Get project stats - cached per request
+ * Calculate estimate accuracy from sessions
+ * Returns percentage of tasks completed within ±20% of estimate
  */
-export const getStats = cache(async (projectId: string): Promise<StatsResult> => {
-  const hasJson = await hasJsonState(projectId)
-
-  if (hasJson) {
-    const jsonData = await loadUnifiedJsonData(projectId)
-    return {
-      state: jsonData.state,
-      queue: jsonData.queue,
-      metrics: jsonData.metrics,
-      insights: jsonData.insights,
-      agents: jsonData.agents,
-      ideas: jsonData.ideas,
-      roadmap: jsonData.roadmap,
-      shipped: jsonData.shipped,
-      outcomes: jsonData.outcomes,
-      hasData: jsonData.hasJsonData,
-      isLegacy: false
+function calculateEstimateAccuracy(sessions: SessionDay[]): number {
+  let tasksWithEstimate = 0
+  let accurateTasks = 0
+
+  for (const session of sessions) {
+    for (const event of session.events) {
+      // Look for task_complete events with estimate and actual duration
+      if (event.type === 'task_complete' || event.type === 'session_completed') {
+        const e = event as { estimate?: string | number; duration?: string | number; actual?: number }
+        if (e.estimate && (e.duration || e.actual)) {
+          tasksWithEstimate++
+
+          // Parse estimate (e.g., "2h" -> 7200 seconds, or raw number)
+          const estimateSec = typeof e.estimate === 'number'
+            ? e.estimate
+            : parseTimeToSeconds(String(e.estimate))
+
+          // Parse actual
+          const actualSec = typeof e.actual === 'number'
+            ? e.actual
+            : typeof e.duration === 'number'
+              ? e.duration
+              : parseTimeToSeconds(String(e.duration || '0'))
+
+          if (estimateSec > 0 && actualSec > 0) {
+            const ratio = actualSec / estimateSec
+            // Within ±20% is "accurate"
+            if (ratio >= 0.8 && ratio <= 1.2) {
+              accurateTasks++
+            }
+          }
+        }
+      }
+    }
+  }
+
+  return tasksWithEstimate > 0
+    ? Math.round((accurateTasks / tasksWithEstimate) * 100)
+    : 0
+}
+
+/**
+ * Parse time string to seconds (e.g., "2h" -> 7200, "30m" -> 1800)
+ */
+function parseTimeToSeconds(time: string): number {
+  const hours = time.match(/(\d+(?:\.\d+)?)\s*h/i)
+  const minutes = time.match(/(\d+(?:\.\d+)?)\s*m/i)
+  const seconds = time.match(/(\d+(?:\.\d+)?)\s*s/i)
+
+  let total = 0
+  if (hours) total += parseFloat(hours[1]) * 3600
+  if (minutes) total += parseFloat(minutes[1]) * 60
+  if (seconds) total += parseFloat(seconds[1])
+
+  // If just a number, assume seconds
+  if (total === 0 && /^\d+$/.test(time.trim())) {
+    total = parseInt(time.trim())
+  }
+
+  return total
+}
+
+/**
+ * Extract blockers from timeline events
+ */
+function extractBlockers(timeline: Array<{ ts: string; type: string }>): Blocker[] {
+  const blockers: Blocker[] = []
+  const now = new Date()
+
+  for (const event of timeline) {
+    // Look for pause events with reason "blocked"
+    if (event.type === 'pause' || event.type === 'session_paused') {
+      const e = event as { reason?: string; note?: string; task?: string; ts: string }
+      if (e.reason === 'blocked') {
+        const pauseDate = new Date(e.ts)
+        const daysBlocked = Math.floor((now.getTime() - pauseDate.getTime()) / (1000 * 60 * 60 * 24))
+
+        blockers.push({
+          task: e.task || 'Unknown task',
+          reason: e.note || 'Blocked',
+          since: e.ts,
+          daysBlocked
+        })
+      }
     }
   }
 
-  // Fallback to legacy markdown parsing
+  // Only return unresolved blockers (check if there's a resume after the pause)
+  // For now, return all - we'll refine this when we have resume tracking
+  return blockers.slice(0, 5) // Top 5 blockers
+}
+
+/**
+ * Get project stats - cached per request
+ *
+ * MD-First Architecture: MD files are the source of truth.
+ * No JSON fallback - all data comes from MD.
+ */
+export const getStats = cache(async (projectId: string): Promise<StatsResult> => {
   try {
-    const legacyStats = await getLegacyStats(projectId)
-    return {
-      ...EMPTY_STATS_RESULT,
-      insights: {
-        ...DEFAULT_INSIGHTS,
-        healthScore: 50,
-        recommendations: ['Run /p:sync to enable JSON format']
-      },
-      hasData: true,
-      isLegacy: true,
-      legacyStats
+    const mdStats = await getMdStats(projectId)
+
+    // Check if we have meaningful data
+    const hasData = Boolean(
+      mdStats.currentTask ||
+      mdStats.queue.length > 0 ||
+      mdStats.shipped.length > 0 ||
+      mdStats.timeline.length > 0 ||
+      mdStats.summary.totalEvents > 0
+    )
+
+    if (hasData) {
+      // Calculate real metrics
+      const estimateAccuracy = calculateEstimateAccuracy(mdStats.sessions)
+      const blockers = extractBlockers(mdStats.timeline)
+
+      return {
+        ...EMPTY_STATS_RESULT,
+        insights: {
+          healthScore: calculateHealthScoreV2(mdStats, estimateAccuracy, blockers),
+          estimateAccuracy,
+          blockers,
+          recommendations: generateRecommendations(mdStats, estimateAccuracy, blockers)
+        },
+        hasData: true,
+        isLegacy: true,
+        legacyStats: mdStats
+      }
     }
   } catch {
-    return EMPTY_STATS_RESULT
+    // MD parsing failed - return empty stats
   }
+
+  return EMPTY_STATS_RESULT
 })
 
+/**
+ * Calculate health score V2 - based on real data
+ *
+ * Formula:
+ * - estimateAccuracy (25): % of tasks within ±20% of estimate
+ * - completionRate (25): tasks completed / tasks started (last 7 days)
+ * - noBlockers (25): penalize if blocked tasks exist
+ * - recentActivity (25): days active in last week
+ */
+function calculateHealthScoreV2(
+  stats: ProjectStats,
+  estimateAccuracy: number,
+  blockers: Blocker[]
+): number {
+  const { timeline, sessions, currentTask } = stats
+
+  // Estimate accuracy score (0-25)
+  // If no estimates yet, give benefit of doubt (15/25)
+  const accuracyScore = estimateAccuracy > 0
+    ? Math.round((estimateAccuracy / 100) * 25)
+    : 15
+
+  // Completion rate (0-25)
+  const recentSessions = sessions.slice(0, 7)
+  let tasksStarted = 0
+  let tasksCompleted = 0
+  for (const session of recentSessions) {
+    tasksStarted += session.tasksStarted
+    tasksCompleted += session.tasksCompleted
+  }
+  const completionRate = tasksStarted > 0 ? tasksCompleted / tasksStarted : 0
+  const completionScore = Math.round(Math.min(1, completionRate) * 25)
+
+  // No blockers score (0-25)
+  // Full points if no blockers, -5 per blocker, -10 per blocker > 3 days
+  let blockerPenalty = 0
+  for (const blocker of blockers) {
+    blockerPenalty += blocker.daysBlocked > 3 ? 10 : 5
+  }
+  const blockerScore = Math.max(0, 25 - blockerPenalty)
+
+  // Activity score (0-25)
+  // Count unique active days in last 7 days
+  const lastWeek = new Date()
+  lastWeek.setDate(lastWeek.getDate() - 7)
+  const recentDays = new Set(
+    timeline
+      .filter(e => new Date(e.ts) > lastWeek)
+      .map(e => e.ts.split('T')[0])
+  )
+  // Bonus for having current task
+  const activityBase = Math.min(7, recentDays.size) * 3 // up to 21
+  const currentTaskBonus = currentTask ? 4 : 0
+  const activityScore = Math.min(25, activityBase + currentTaskBonus)
+
+  return Math.min(100, accuracyScore + completionScore + blockerScore + activityScore)
+}
+
+/**
+ * Legacy health score calculation (kept for fallback)
+ */
+function calculateHealthFromMd(stats: ProjectStats): number {
+  const { metrics, currentTask, queue, timeline } = stats
+  const velocity = metrics?.velocity?.tasksPerDay ?? 0
+  const hasCurrentTask = Boolean(currentTask)
+  const queueSize = queue?.length ?? 0
+  const recentActivity = timeline?.slice(0, 7).length ?? 0
+
+  const velocityScore = Math.min(30, velocity * 15)
+  const taskScore = hasCurrentTask ? 20 : 0
+  const queueScore = queueSize > 0 && queueSize < 15 ? 20 : queueSize === 0 ? 5 : 10
+  const activityScore = Math.min(30, recentActivity * 5)
+
+  return Math.min(100, Math.round(velocityScore + taskScore + queueScore + activityScore))
+}
+
+/**
+ * Generate recommendations based on MD stats and insights
+ */
+function generateRecommendations(
+  stats: ProjectStats,
+  estimateAccuracy: number,
+  blockers: Blocker[]
+): string[] {
+  const recommendations: string[] = []
+
+  // Blocker-based recommendations (highest priority)
+  if (blockers.length > 0) {
+    const oldestBlocker = blockers.reduce((a, b) => a.daysBlocked > b.daysBlocked ? a : b)
+    if (oldestBlocker.daysBlocked > 3) {
+      recommendations.push(`Blocker "${oldestBlocker.reason}" is ${oldestBlocker.daysBlocked} days old - needs attention`)
+    } else {
+      recommendations.push(`${blockers.length} blocked task(s) - review blockers`)
+    }
+  }
+
+  // Estimate accuracy recommendations
+  if (estimateAccuracy > 0 && estimateAccuracy < 50) {
+    recommendations.push('Estimates often off - consider adding 30% buffer')
+  } else if (estimateAccuracy >= 80) {
+    recommendations.push('Great estimation accuracy - keep it up!')
+  }
+
+  // Task state recommendations
+  if (!stats.currentTask) {
+    recommendations.push('Start a task with /p:now')
+  }
+
+  if (stats.queue.length === 0) {
+    recommendations.push('Add tasks to queue with /p:next')
+  }
+
+  if (stats.ideas.pending.length > 10) {
+    recommendations.push('Review and prioritize pending ideas')
+  }
+
+  if (stats.agents.length === 0) {
+    recommendations.push('Run /p:sync to generate agents')
+  }
+
+  // Default positive message
+  if (recommendations.length === 0) {
+    recommendations.push('Keep shipping!')
+  }
+
+  return recommendations.slice(0, 4) // Max 4 recommendations
+}
+
 /**
  * Calculate streak from metrics (pure function, no mutation)
  */
@@ -183,16 +491,6 @@ export function calculateStreak(metrics: MetricsJson | null): number {
   return firstGapIndex === -1 ? days.length : firstGapIndex
 }
 
-/**
- * Get health emoji based on score
- */
-export function getHealthEmoji(score: number): string {
-  if (score >= 80) return '🔥'
-  if (score >= 60) return '💪'
-  if (score >= 40) return '👍'
-  if (score >= 20) return '🌱'
-  return '💤'
-}
 
 /**
  * Get insight message based on stats
@@ -231,7 +529,7 @@ export function getWeeklyVelocityData(metrics: MetricsJson | null): number[] {
     date.setDate(date.getDate() - (6 - i))
     const dateStr = date.toISOString().split('T')[0]
 
-    return metrics.recentActivity.filter((e: { timestamp: string }) =>
+    return (metrics.recentActivity || []).filter((e: { timestamp: string }) =>
       e.timestamp?.startsWith(dateStr)
     ).length
   })

package/packages/web/package.json

@@ -11,7 +11,6 @@
     "lint": "eslint"
   },
   "dependencies": {
-    "@ai-sdk/openai": "^2.0.80",
     "@radix-ui/react-alert-dialog": "^1.1.15",
     "@radix-ui/react-dialog": "^1.1.15",
     "@radix-ui/react-dropdown-menu": "^2.1.16",
@@ -24,7 +23,6 @@
     "@xterm/addon-fit": "^0.10.0",
     "@xterm/addon-web-links": "^0.11.0",
     "@xterm/xterm": "^5.5.0",
-    "ai": "^5.0.108",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "lucide-react": "^0.556.0",

package/templates/commands/decision.md

@@ -0,0 +1,226 @@
+---
+allowed-tools: [Read, Write, Bash]
+description: 'Log architectural or important decisions'
+timestamp-rule: 'GetTimestamp() for ALL timestamps'
+architecture: 'MD-first - MD files are source of truth'
+---
+
+# /p:decision - Log Important Decisions
+
+## Architecture: MD-First
+
+**Source of Truth**: `planning/decisions.md`
+
+MD files are the source of truth. Write directly to MD files.
+
+## Context Variables
+- `{projectId}`: From `.prjct/prjct.config.json`
+- `{globalPath}`: `~/.prjct-cli/projects/{projectId}`
+- `{decisionsPath}`: `{globalPath}/planning/decisions.md`
+- `{memoryPath}`: `{globalPath}/memory/context.jsonl`
+- `{decision}`: User-provided decision (required)
+- `{reasoning}`: User-provided reasoning (optional)
+- `{alternatives}`: User-provided alternatives considered (optional)
+
+## Decision Format
+
+Capture WHY decisions were made to avoid repeating mistakes:
+
+```
+/p:decision "Use REST instead of GraphQL"
+  --reason "Simpler for this use case, team familiarity"
+  --alternatives "GraphQL, gRPC"
+```
+
+Or interactive prompt:
+```
+Decision: Use REST instead of GraphQL
+
+Why did you make this decision?
+> Simpler for this use case, team familiarity
+
+What alternatives did you consider?
+> GraphQL, gRPC
+```
+
+## Step 1: Read Config
+
+READ: `.prjct/prjct.config.json`
+EXTRACT: `projectId`
+
+IF file not found:
+  OUTPUT: "No prjct project. Run /p:init first."
+  STOP
+
+## Step 2: Validate Input
+
+IF {decision} is empty:
+  ASK: "What decision did you make?"
+  SET: {decision} = user response
+
+IF {reasoning} is empty:
+  ASK: "Why did you make this decision?"
+  SET: {reasoning} = user response
+
+IF {alternatives} is empty:
+  ASK: "What alternatives did you consider? (optional, press Enter to skip)"
+  SET: {alternatives} = user response OR "none documented"
+
+## Step 3: Generate Decision Entry
+
+GENERATE: {decisionId} = "dec_" + 8 random alphanumeric chars
+SET: {now} = GetTimestamp()
+
+## Step 4: Read/Create Decisions File
+
+READ: `{decisionsPath}` (or create default if not exists)
+
+Default structure:
+```markdown
+# Decisions
+
+Architecture decisions and their reasoning.
+
+## Recent
+
+_No decisions logged yet_
+
+## Archive
+
+_No archived decisions_
+```
+
+## Step 5: Update Decisions File (MD)
+
+Parse existing content and add new decision under "## Recent" section:
+
+```markdown
+# Decisions
+
+Architecture decisions and their reasoning.
+
+## Recent
+
+### {decision}
+- **ID**: {decisionId}
+- **Date**: {now}
+- **Reasoning**: {reasoning}
+- **Alternatives**: {alternatives}
+- **Context**: {current task from now.md if active}
+
+{...existing recent decisions}
+
+## Archive
+
+{...existing archive}
+```
+
+WRITE: `{decisionsPath}`
+
+## Step 6: Log to Memory
+
+APPEND to: `{memoryPath}`
+
+Single line (JSONL):
+```json
+{"timestamp":"{now}","action":"decision_logged","decisionId":"{decisionId}","decision":"{decision}","reasoning":"{reasoning}","alternatives":"{alternatives}"}
+```
+
+## Output
+
+SUCCESS:
+```
+📝 Decision logged: {decision}
+
+ID: {decisionId}
+Reasoning: {reasoning}
+Alternatives: {alternatives}
+
+Next:
+• Continue working on your task
+• /p:recap - Review decisions made
+```
+
+## Error Handling
+
+| Error | Response | Action |
+|-------|----------|--------|
+| No project | "No prjct project" | STOP |
+| No decision provided | Ask for decision | WAIT |
+| Write fails | Log warning | CONTINUE |
+
+## Examples
+
+### Example 1: Full Decision with All Fields
+**Input:** `/p:decision "Use Zustand for state management" --reason "Lighter than Redux, better DX" --alternatives "Redux, MobX, Jotai"`
+
+**Output:**
+```
+📝 Decision logged: Use Zustand for state management
+
+ID: dec_abc12345
+Reasoning: Lighter than Redux, better DX
+Alternatives: Redux, MobX, Jotai
+
+Next: Continue working | /p:recap
+```
+
+### Example 2: Interactive Mode
+**Input:** `/p:decision`
+
+**Prompt flow:**
+```
+What decision did you make?
+> Use PostgreSQL instead of MongoDB
+
+Why did you make this decision?
+> Need relational data with joins, better ACID compliance
+
+What alternatives did you consider? (Enter to skip)
+> MongoDB, SQLite
+```
+
+**Output:**
+```
+📝 Decision logged: Use PostgreSQL instead of MongoDB
+
+ID: dec_xyz98765
+Reasoning: Need relational data with joins, better ACID compliance
+Alternatives: MongoDB, SQLite
+
+Next: Continue working | /p:recap
+```
+
+### Example 3: Quick Decision (minimal)
+**Input:** `/p:decision "Skip tests for MVP"`
+
+**Prompt:**
+```
+Why did you make this decision?
+> Time constraint, will add before launch
+```
+
+**Output:**
+```
+📝 Decision logged: Skip tests for MVP
+
+ID: dec_qrs45678
+Reasoning: Time constraint, will add before launch
+Alternatives: none documented
+
+Next: Continue working | /p:recap
+```
+
+## Use Cases
+
+When to log a decision:
+- Choosing between technologies/libraries
+- Architectural pattern selection
+- Trade-off decisions (speed vs quality)
+- Deviation from best practices (and why)
+- Postponing technical debt intentionally
+
+This creates institutional memory to avoid:
+- Repeating the same debates
+- Forgetting why something was done a certain way
+- Making inconsistent choices across the codebase