prjct-cli 1.12.0 → 1.14.0

package/core/agentic/orchestrator-executor.ts

@@ -21,15 +21,19 @@ import { promisify } from 'node:util'
 import { findRelevantFiles } from '../context-tools/files-tool'
 import { getRecentFiles } from '../context-tools/recent-tool'
 import { extractSignatures } from '../context-tools/signatures-tool'
+import { calculateVelocity, formatVelocityContext } from '../domain/velocity'
 import configManager from '../infrastructure/config-manager'
 import pathManager from '../infrastructure/path-manager'
-import { stateStorage } from '../storage'
+import outcomeRecorder from '../outcomes/recorder'
+import { DEFAULT_VELOCITY_CONFIG } from '../schemas/velocity'
+import { analysisStorage, stateStorage } from '../storage'
 import type {
   LoadedAgent,
   LoadedSkill,
   OrchestratorContext,
   OrchestratorSubtask,
   RealCodebaseContext,
+  SealedAnalysisContext,
 } from '../types'
 import { getErrorMessage, isNotFoundError } from '../types/fs'
 import domainClassifier, { type ProjectContext } from './domain-classifier'
@@ -76,8 +80,12 @@ export class OrchestratorExecutor {
     // Step 5: Load skills from agent frontmatter
     const skills = await this.loadSkills(agents)
 
-    // Step 6: Gather real codebase context proactively
-    const realContext = await this.gatherRealContext(taskDescription, projectPath)
+    // Step 6: Gather real codebase context, sealed analysis, and velocity in parallel
+    const [realContext, sealedAnalysis, velocityContext] = await Promise.all([
+      this.gatherRealContext(taskDescription, projectPath),
+      this.loadSealedAnalysis(projectId),
+      this.loadVelocityContext(projectId),
+    ])
 
     // Step 7: Determine if fragmentation is needed
     const requiresFragmentation = this.shouldFragment(domains, taskDescription)
@@ -101,6 +109,8 @@ export class OrchestratorExecutor {
         conventions: repoAnalysis?.conventions || [],
       },
       realContext,
+      sealedAnalysis,
+      velocityContext,
     }
   }
 
@@ -197,6 +207,52 @@ export class OrchestratorExecutor {
     }
   }
 
+  /**
+   * Load sealed/active analysis from analysis storage (PRJ-260).
+   * Returns sealed if available, otherwise draft as fallback.
+   * Returns null if no analysis exists (graceful degradation).
+   */
+  private async loadSealedAnalysis(projectId: string): Promise<SealedAnalysisContext | null> {
+    try {
+      const analysis = await analysisStorage.getActive(projectId)
+      if (!analysis) return null
+
+      return {
+        languages: analysis.languages,
+        frameworks: analysis.frameworks,
+        packageManager: analysis.packageManager,
+        sourceDir: analysis.sourceDir,
+        testDir: analysis.testDir,
+        fileCount: analysis.fileCount,
+        patterns: analysis.patterns,
+        antiPatterns: analysis.antiPatterns,
+        status: analysis.status ?? 'draft',
+        commitHash: analysis.commitHash,
+      }
+    } catch {
+      // Graceful degradation — analysis is optional enhancement
+      return null
+    }
+  }
+
+  /**
+   * Load velocity context for estimation guidance (PRJ-296).
+   * Returns formatted string for prompt injection, or null if no data.
+   */
+  private async loadVelocityContext(projectId: string): Promise<string | null> {
+    try {
+      const outcomes = await outcomeRecorder.getAll(projectId)
+      if (outcomes.length === 0) return null
+
+      const metrics = calculateVelocity(outcomes, DEFAULT_VELOCITY_CONFIG)
+      if (metrics.sprints.length === 0) return null
+
+      return formatVelocityContext(metrics)
+    } catch {
+      return null
+    }
+  }
+
   /**
    * Load repo-analysis.json for project context
    */

package/core/agentic/prompt-builder.ts

@@ -542,10 +542,50 @@ class PromptBuilder {
     // =========================================================================
 
     if (orchestratorContext) {
+      const sa = orchestratorContext.sealedAnalysis
       parts.push('\n## PROJECT ANALYSIS (Sealed)\n')
       parts.push(`**Ecosystem**: ${orchestratorContext.project.ecosystem}\n`)
       parts.push(`**Primary Domain**: ${orchestratorContext.primaryDomain}\n`)
-      parts.push(`**Domains**: ${orchestratorContext.detectedDomains.join(', ')}\n\n`)
+      parts.push(`**Domains**: ${orchestratorContext.detectedDomains.join(', ')}\n`)
+
+      // Inject sealed analysis data (PRJ-260)
+      if (sa) {
+        if (sa.languages.length > 0) {
+          parts.push(`**Languages**: ${sa.languages.join(', ')}\n`)
+        }
+        if (sa.frameworks.length > 0) {
+          parts.push(`**Frameworks**: ${sa.frameworks.join(', ')}\n`)
+        }
+        if (sa.packageManager) {
+          parts.push(`**Package Manager**: ${sa.packageManager}\n`)
+        }
+        if (sa.sourceDir) {
+          parts.push(`**Source Dir**: ${sa.sourceDir}\n`)
+        }
+        if (sa.testDir) {
+          parts.push(`**Test Dir**: ${sa.testDir}\n`)
+        }
+        parts.push(`**Files Analyzed**: ${sa.fileCount}\n`)
+        parts.push(
+          `**Analysis Status**: ${sa.status}${sa.commitHash ? ` (commit: ${sa.commitHash.slice(0, 8)})` : ''}\n`
+        )
+
+        if (sa.patterns.length > 0) {
+          parts.push('\n### Code Patterns (Follow These)\n')
+          for (const p of sa.patterns) {
+            parts.push(`- **${p.name}**: ${p.description}${p.location ? ` (${p.location})` : ''}\n`)
+          }
+        }
+
+        if (sa.antiPatterns.length > 0) {
+          parts.push('\n### Anti-Patterns (Avoid These)\n')
+          for (const ap of sa.antiPatterns) {
+            parts.push(`- **${ap.issue}** in \`${ap.file}\` — ${ap.suggestion}\n`)
+          }
+        }
+      }
+
+      parts.push('\n')
     }
 
     const needsPatterns = commandContext.patterns
@@ -648,6 +688,7 @@ class PromptBuilder {
     // =========================================================================
 
     if (projectPath) {
+      const sa = orchestratorContext?.sealedAnalysis
       const groundTruth: ProjectGroundTruth = {
         projectPath,
         language: orchestratorContext?.project?.ecosystem,
@@ -655,6 +696,10 @@ class PromptBuilder {
         domains: this.extractDomains(state),
         fileCount: context.files?.length || context.filteredSize || 0,
         availableAgents: orchestratorContext?.agents?.map((a) => a.name) || [],
+        // Inject sealed analysis data for enriched grounding (PRJ-260)
+        analysisLanguages: sa?.languages || [],
+        analysisFrameworks: sa?.frameworks || [],
+        analysisPackageManager: sa?.packageManager,
       }
       parts.push(`\n${buildAntiHallucinationBlock(groundTruth)}\n`)
     } else {
@@ -721,6 +766,13 @@ class PromptBuilder {
       parts.push('\n')
     }
 
+    // Velocity context (PRJ-296) — estimation guidance from historical data
+    if (orchestratorContext?.velocityContext) {
+      parts.push('\n### VELOCITY (Historical Estimation Data)\n\n')
+      parts.push(orchestratorContext.velocityContext)
+      parts.push('\n\n')
+    }
+
     // Learned patterns
     if (learnedPatterns && Object.keys(learnedPatterns).some((k) => learnedPatterns[k])) {
       parts.push('\n## PROJECT DEFAULTS (apply automatically)\n')

package/core/commands/command-data.ts

@@ -193,6 +193,23 @@ export const COMMANDS: CommandMeta[] = [
       'Command duration breakdown',
     ],
   },
+  {
+    name: 'velocity',
+    group: 'core',
+    description: 'Sprint-based velocity dashboard with trend detection and projections',
+    usage: { claude: '/p:velocity', terminal: 'prjct velocity [backlogPoints]' },
+    params: '[backlogPoints]',
+    implemented: true,
+    hasTemplate: false,
+    requiresProject: true,
+    features: [
+      'Sprint-by-sprint velocity breakdown',
+      'Trend detection (improving/stable/declining)',
+      'Estimation accuracy tracking',
+      'Over/under estimation pattern detection',
+      'Completion projections for backlog',
+    ],
+  },
   {
     name: 'suggest',
     group: 'core',

package/core/commands/commands.ts

@@ -31,6 +31,7 @@ import { PerformanceCommands } from './performance'
 import { PlanningCommands } from './planning'
 import { SetupCommands } from './setup'
 import { ShippingCommands } from './shipping'
+import { VelocityCommands } from './velocity'
 import { WorkflowCommands } from './workflow'
 
 /**
@@ -47,6 +48,7 @@ class PrjctCommands {
   private maintenance: MaintenanceCommands
   private analysis: AnalysisCommands
   private setupCmds: SetupCommands
+  private velocityCmds: VelocityCommands
   private contextCmds: ContextCommands
 
   // Shared state
@@ -64,6 +66,7 @@ class PrjctCommands {
     this.maintenance = new MaintenanceCommands()
     this.analysis = new AnalysisCommands()
     this.setupCmds = new SetupCommands()
+    this.velocityCmds = new VelocityCommands()
     this.contextCmds = new ContextCommands()
 
     this.agent = null
@@ -149,6 +152,15 @@ class PrjctCommands {
     return this.performanceCmds.perf(period, projectPath)
   }
 
+  // ========== Velocity Commands ==========
+
+  async velocity(
+    backlogPoints: string = '0',
+    projectPath: string = process.cwd()
+  ): Promise<CommandResult> {
+    return this.velocityCmds.velocity(backlogPoints, projectPath)
+  }
+
   // ========== Maintenance Commands ==========
 
   async cleanup(

package/core/commands/register.ts

@@ -19,6 +19,7 @@ import { commandRegistry } from './registry'
 import { SetupCommands } from './setup'
 import { ShippingCommands } from './shipping'
 import { UninstallCommands } from './uninstall'
+import { VelocityCommands } from './velocity'
 import { WorkflowCommands } from './workflow'
 
 // Singleton instances of command groups
@@ -31,6 +32,7 @@ const maintenance = new MaintenanceCommands()
 const analysis = new AnalysisCommands()
 const setup = new SetupCommands()
 const context = new ContextCommands()
+const velocityCmd = new VelocityCommands()
 const uninstallCmd = new UninstallCommands()
 
 /**
@@ -78,6 +80,9 @@ export function registerAllCommands(): void {
   // Performance commands
   commandRegistry.registerMethod('perf', performance, 'perf', getMeta('perf'))
 
+  // Velocity commands
+  commandRegistry.registerMethod('velocity', velocityCmd, 'velocity', getMeta('velocity'))
+
   // Maintenance commands
   commandRegistry.registerMethod('cleanup', maintenance, 'cleanup', getMeta('cleanup'))
   commandRegistry.registerMethod('design', maintenance, 'design', getMeta('design'))
@@ -117,5 +122,6 @@ export {
   analysis,
   setup,
   context,
+  velocityCmd,
   uninstallCmd,
 }

package/core/commands/velocity.ts

@@ -0,0 +1,149 @@
+/**
+ * Velocity Commands: velocity
+ * Sprint-based velocity dashboard
+ *
+ * @see PRJ-296
+ */
+
+import chalk from 'chalk'
+import { calculateVelocity, projectCompletion } from '../domain/velocity'
+import outcomeRecorder from '../outcomes/recorder'
+import type { VelocityConfig } from '../schemas/velocity'
+import { DEFAULT_VELOCITY_CONFIG } from '../schemas/velocity'
+import { velocityStorage } from '../storage/velocity-storage'
+import type { CommandResult } from '../types'
+import { getErrorMessage } from '../types/fs'
+import { configManager, out, PrjctCommandsBase } from './base'
+
+export class VelocityCommands extends PrjctCommandsBase {
+  /**
+   * prjct velocity - Velocity dashboard
+   */
+  async velocity(
+    backlogPoints: string = '0',
+    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' }
+      }
+
+      // Load velocity config from project config (or defaults)
+      const config = await this.loadVelocityConfig(projectPath)
+
+      // Load all outcomes
+      const outcomes = await outcomeRecorder.getAll(projectId)
+
+      if (outcomes.length === 0) {
+        console.log(`\n${chalk.dim('No velocity data yet.')}`)
+        console.log(`${chalk.dim('Complete tasks with estimates to build velocity history.')}\n`)
+        return { success: true, message: 'No data' }
+      }
+
+      // Calculate velocity metrics
+      const metrics = calculateVelocity(outcomes, config)
+
+      // Save for context injection
+      await velocityStorage.saveMetrics(projectId, metrics)
+
+      // Render dashboard
+      console.log(
+        `\n${chalk.cyan('Sprint Velocity')} ${chalk.dim(`(last ${config.windowSize ?? 6} sprints)`)}`
+      )
+      console.log('═'.repeat(60))
+
+      // Sprint table
+      const recentSprints = metrics.sprints.slice(-(config.windowSize ?? 6))
+      for (const sprint of recentSprints) {
+        const accuracyColor =
+          sprint.estimationAccuracy >= 80
+            ? chalk.green
+            : sprint.estimationAccuracy >= 60
+              ? chalk.yellow
+              : chalk.red
+        console.log(
+          `  Sprint ${String(sprint.sprintNumber).padStart(2)}: ${chalk.bold(`${sprint.pointsCompleted} pts`)} | ${sprint.tasksCompleted} tasks | accuracy: ${accuracyColor(`${sprint.estimationAccuracy}%`)}`
+        )
+      }
+
+      console.log('')
+      const trendIcon =
+        metrics.velocityTrend === 'improving'
+          ? chalk.green('↑')
+          : metrics.velocityTrend === 'declining'
+            ? chalk.red('↓')
+            : chalk.dim('→')
+      console.log(
+        `  Average: ${chalk.bold(`${metrics.averageVelocity} pts/sprint`)} | Trend: ${trendIcon} ${metrics.velocityTrend}`
+      )
+      console.log(
+        `  Estimation accuracy: ${chalk.bold(`${metrics.estimationAccuracy}%`)} ${chalk.dim(`(±${config.accuracyTolerance ?? 20}% tolerance)`)}`
+      )
+
+      // Patterns
+      if (metrics.underEstimated.length > 0 || metrics.overEstimated.length > 0) {
+        console.log(`\n  ${chalk.dim('Patterns:')}`)
+        for (const p of metrics.underEstimated) {
+          console.log(
+            `    ${chalk.yellow('⚠')} ${p.category} tasks underestimated by avg ${chalk.bold(`${p.avgVariance}%`)}`
+          )
+        }
+        for (const p of metrics.overEstimated) {
+          console.log(
+            `    ${chalk.green('✓')} ${p.category} tasks estimated within ${chalk.bold(`${p.avgVariance}%`)}`
+          )
+        }
+      }
+
+      // Projection (if backlog points provided)
+      const points = parseInt(backlogPoints, 10)
+      if (points > 0 && metrics.averageVelocity > 0) {
+        const projection = projectCompletion(points, metrics.averageVelocity, config)
+        const dateStr = projection.estimatedDate
+          ? new Date(projection.estimatedDate).toLocaleDateString('en-US', {
+              month: 'short',
+              day: 'numeric',
+              year: 'numeric',
+            })
+          : 'unknown'
+        console.log(`\n  ${chalk.dim('Projection:')}`)
+        console.log(`    Backlog: ${chalk.bold(`${points} pts`)} remaining`)
+        console.log(
+          `    At current velocity: ~${projection.sprints} sprints (${projection.sprints * (config.sprintLengthDays ?? 7)} days)`
+        )
+        console.log(`    Estimated completion: ${chalk.bold(dateStr)}`)
+      }
+
+      console.log('═'.repeat(60))
+      console.log('')
+
+      return { success: true }
+    } catch (error) {
+      out.fail(getErrorMessage(error))
+      return { success: false, error: getErrorMessage(error) }
+    }
+  }
+
+  /**
+   * Load velocity config from project or use defaults.
+   * Velocity config can be added to prjct.config.json as { velocity: { sprintLengthDays, ... } }
+   */
+  private async loadVelocityConfig(projectPath: string): Promise<VelocityConfig> {
+    try {
+      const config = await configManager.readConfig(projectPath)
+      // Read velocity config from extended config (not typed in LocalConfig yet)
+      const raw = config as Record<string, unknown> | null
+      if (raw?.velocity && typeof raw.velocity === 'object') {
+        return { ...DEFAULT_VELOCITY_CONFIG, ...(raw.velocity as Partial<VelocityConfig>) }
+      }
+    } catch {
+      // Use defaults
+    }
+    return DEFAULT_VELOCITY_CONFIG
+  }
+}