prjct-cli 1.12.0 → 1.14.0

package/CHANGELOG.md

@@ -1,5 +1,94 @@
 # Changelog
 
+## [1.14.0] - 2026-02-09
+
+### Features
+
+- add sprint-based velocity calculation with trend detection (PRJ-296) (#156)
+
+
+## [1.14.0] - 2026-02-09
+
+### Features
+- **Velocity Dashboard**: New `prjct velocity` command with sprint-by-sprint breakdown, trend detection, and estimation accuracy (PRJ-296)
+- **Estimation Patterns**: Automatic detection of over/under estimation patterns by task category
+- **Completion Projections**: Given remaining backlog points, projects estimated sprints and completion date
+- **Velocity Context Injection**: Historical velocity data automatically injected into LLM task prompts for better estimation
+
+### Implementation Details
+
+**PRJ-296 — Sprint-Based Velocity Calculation**
+New velocity subsystem that aggregates completed task data (from outcomes.jsonl) into sprint periods, calculates rolling velocity metrics, detects trends, and identifies estimation patterns.
+
+Key changes:
+- `core/schemas/velocity.ts` — Zod schemas: SprintVelocity, VelocityMetrics, VelocityConfig, EstimationPattern, CompletionProjection
+- `core/domain/velocity.ts` — Velocity engine: sprint bucketing, linear regression trend detection, accuracy tracking, pattern detection, duration parsing, LLM context formatting
+- `core/storage/velocity-storage.ts` — Write-through storage extending StorageManager with markdown generation
+- `core/commands/velocity.ts` — Dashboard command with chalk-formatted output + registration
+- `core/types/agentic.ts` — Extended `OrchestratorContext` with `velocityContext` field
+- `core/agentic/orchestrator-executor.ts` — Loads velocity context in parallel via `Promise.all`
+- `core/agentic/prompt-builder.ts` — Injects velocity into Section 6 (task context)
+- `core/__tests__/domain/velocity.test.ts` — 35 new tests
+
+### Learnings
+- Derive story points from estimated duration via Fibonacci mapping when outcomes lack explicit point data
+- Linear regression slope normalized by average velocity works well for trend detection (>10% = improving, <-10% = declining)
+- Parallel loading pattern in orchestrator-executor (`Promise.all`) ensures zero-latency context enrichment
+
+### Test Plan
+
+#### For QA
+1. Run `prjct velocity` on a project with outcomes data — verify sprint-by-sprint breakdown with points, tasks, accuracy
+2. Run `prjct velocity` with no outcomes — verify graceful "No velocity data yet" message
+3. Run `prjct velocity 89` — verify completion projection (sprints remaining + date)
+4. Run `bun test core/__tests__/domain/velocity.test.ts` — 35 tests pass
+5. Run `bun test` — all 805 tests pass
+
+#### For Users
+- **What changed:** New `prjct velocity` command shows sprint velocity, estimation accuracy trends, and completion projections. Velocity data is automatically injected into task prompts for better LLM estimation.
+- **How to use:** Run `prjct velocity` after completing tasks with estimates. Add backlog points: `prjct velocity 89`
+- **Breaking changes:** None
+
+## [1.13.0] - 2026-02-09
+
+### Features
+
+- inject sealed analysis into task prompt context (PRJ-260) (#155)
+
+
+## [1.13.0] - 2026-02-09
+
+### Features
+- **Analysis Injection**: Sealed analysis (languages, frameworks, patterns, anti-patterns) now automatically injected into LLM prompt context (PRJ-260)
+- **Enriched Ground Truth**: Prompt section 3 renders full analysis data — languages, frameworks, package manager, source/test dirs, code patterns, and anti-patterns
+- **Enhanced Anti-Hallucination**: AVAILABLE tech list enriched with analysis data (case-insensitive dedup), package manager constraint added
+
+### Implementation Details
+
+**PRJ-260 — Inject Sync Analysis into Task Context**
+Connected the analysis pipeline (from PRJ-263) to the prompt assembly pipeline (from PRJ-301). `analysisStorage.getActive()` returns sealed analysis (or draft fallback), loaded in parallel with real codebase context for zero latency impact.
+
+Key changes:
+- `core/types/agentic.ts` — New `SealedAnalysisContext` interface, extended `OrchestratorContext` with `sealedAnalysis` field
+- `core/agentic/orchestrator-executor.ts` — Added `loadSealedAnalysis()`, loads in parallel with `gatherRealContext()`
+- `core/agentic/prompt-builder.ts` — Section 3 (ground truth) renders analysis data, Section 5 passes analysis to anti-hallucination
+- `core/agentic/anti-hallucination.ts` — Extended `ProjectGroundTruth` with `analysisLanguages`, `analysisFrameworks`, `analysisPackageManager`
+- `core/__tests__/agentic/analysis-injection.test.ts` — 14 new tests
+
+### Test Plan
+
+#### For QA
+1. Run `prjct sync` on a project with sealed analysis — verify prompt contains Languages, Frameworks, Patterns sections
+2. Run `prjct sync` on a project WITHOUT sealed analysis — verify no crash, fallback rules still present
+3. Check anti-hallucination block — verify AVAILABLE list includes analysis languages/frameworks (deduped)
+4. Run `bun test core/__tests__/agentic/analysis-injection.test.ts` — 14 tests pass
+5. Run `bun test` — all 770 tests pass
+
+#### For Users
+- **What changed:** AI prompts now include your project's detected languages, frameworks, code patterns, and anti-patterns from sealed analysis
+- **How to use:** Run `prjct sync` then `prjct seal` — improvements are automatic in subsequent task prompts
+- **Breaking changes:** None
+
 ## [1.12.0] - 2026-02-09
 
 ### Features

package/core/__tests__/agentic/analysis-injection.test.ts

@@ -0,0 +1,377 @@
+/**
+ * Analysis Injection Tests (PRJ-260)
+ *
+ * Tests for injecting sealed analysis data into task context:
+ * - Prompt builder renders analysis in ground_truth section
+ * - Anti-hallucination block enriched with analysis data
+ * - Graceful degradation when no analysis available
+ */
+
+import { beforeEach, describe, expect, it } from 'bun:test'
+import {
+  buildAntiHallucinationBlock,
+  type ProjectGroundTruth,
+} from '../../agentic/anti-hallucination'
+import promptBuilder from '../../agentic/prompt-builder'
+import type { OrchestratorContext, SealedAnalysisContext } from '../../types'
+
+// =============================================================================
+// Test Fixtures
+// =============================================================================
+
+const mockSealedAnalysis: SealedAnalysisContext = {
+  languages: ['TypeScript', 'JavaScript'],
+  frameworks: ['Hono', 'Zod'],
+  packageManager: 'bun',
+  sourceDir: 'core/',
+  testDir: 'core/__tests__/',
+  fileCount: 295,
+  patterns: [
+    {
+      name: 'StorageManager pattern',
+      description: 'All storage uses StorageManager base class with read/write/update',
+      location: 'core/storage/',
+    },
+    {
+      name: 'Zod schemas',
+      description: 'Runtime validation with Zod for all data structures',
+    },
+  ],
+  antiPatterns: [
+    {
+      issue: 'Direct fs.writeFile without StorageManager',
+      file: 'core/storage/legacy.ts',
+      suggestion: 'Use StorageManager.write() instead',
+    },
+  ],
+  status: 'sealed',
+  commitHash: 'abc123def456',
+}
+
+function makeOrchestratorContext(
+  sealedAnalysis: SealedAnalysisContext | null = mockSealedAnalysis
+): OrchestratorContext {
+  return {
+    detectedDomains: ['backend', 'testing'],
+    primaryDomain: 'backend',
+    agents: [],
+    skills: [],
+    requiresFragmentation: false,
+    subtasks: null,
+    project: {
+      id: 'test-project',
+      ecosystem: 'TypeScript',
+      conventions: ['Hono', 'Zod'],
+    },
+    sealedAnalysis,
+  }
+}
+
+// =============================================================================
+// Prompt Builder — Ground Truth Section
+// =============================================================================
+
+describe('Analysis Injection in Prompt Builder (PRJ-260)', () => {
+  beforeEach(() => {
+    promptBuilder.resetContext()
+  })
+
+  it('should render sealed analysis in ground truth section', async () => {
+    const template = {
+      frontmatter: { description: 'Test task' },
+      content: '## Instructions\nDo the work',
+    }
+    const context = { projectPath: '/test/project', files: ['a.ts'] }
+    const orcCtx = makeOrchestratorContext()
+
+    const prompt = await promptBuilder.build(
+      template,
+      context,
+      {},
+      null,
+      null,
+      null,
+      null,
+      null,
+      orcCtx
+    )
+
+    // Should contain analysis data
+    expect(prompt).toContain('Languages**: TypeScript, JavaScript')
+    expect(prompt).toContain('Frameworks**: Hono, Zod')
+    expect(prompt).toContain('Package Manager**: bun')
+    expect(prompt).toContain('Source Dir**: core/')
+    expect(prompt).toContain('Test Dir**: core/__tests__/')
+    expect(prompt).toContain('Files Analyzed**: 295')
+    expect(prompt).toContain('Analysis Status**: sealed')
+    expect(prompt).toContain('abc123de') // truncated commit hash
+  })
+
+  it('should render code patterns from sealed analysis', async () => {
+    const template = {
+      frontmatter: { description: 'Test' },
+      content: '## Do',
+    }
+    const context = { projectPath: '/test', files: [] }
+    const orcCtx = makeOrchestratorContext()
+
+    const prompt = await promptBuilder.build(
+      template,
+      context,
+      {},
+      null,
+      null,
+      null,
+      null,
+      null,
+      orcCtx
+    )
+
+    expect(prompt).toContain('Code Patterns (Follow These)')
+    expect(prompt).toContain('StorageManager pattern')
+    expect(prompt).toContain('All storage uses StorageManager base class')
+    expect(prompt).toContain('core/storage/')
+    expect(prompt).toContain('Zod schemas')
+  })
+
+  it('should render anti-patterns from sealed analysis', async () => {
+    const template = {
+      frontmatter: { description: 'Test' },
+      content: '## Do',
+    }
+    const context = { projectPath: '/test', files: [] }
+    const orcCtx = makeOrchestratorContext()
+
+    const prompt = await promptBuilder.build(
+      template,
+      context,
+      {},
+      null,
+      null,
+      null,
+      null,
+      null,
+      orcCtx
+    )
+
+    expect(prompt).toContain('Anti-Patterns (Avoid These)')
+    expect(prompt).toContain('Direct fs.writeFile without StorageManager')
+    expect(prompt).toContain('core/storage/legacy.ts')
+    expect(prompt).toContain('Use StorageManager.write() instead')
+  })
+
+  it('should gracefully handle null sealed analysis', async () => {
+    const template = {
+      frontmatter: { description: 'Test' },
+      content: '## Do',
+    }
+    const context = { projectPath: '/test', files: [] }
+    const orcCtx = makeOrchestratorContext(null)
+
+    const prompt = await promptBuilder.build(
+      template,
+      context,
+      {},
+      null,
+      null,
+      null,
+      null,
+      null,
+      orcCtx
+    )
+
+    // Should still have basic project analysis
+    expect(prompt).toContain('PROJECT ANALYSIS')
+    expect(prompt).toContain('Ecosystem**: TypeScript')
+    // Should NOT have analysis-specific fields
+    expect(prompt).not.toContain('Languages**:')
+    expect(prompt).not.toContain('Code Patterns (Follow These)')
+    expect(prompt).not.toContain('Anti-Patterns (Avoid These)')
+  })
+
+  it('should handle empty patterns and anti-patterns', async () => {
+    const template = {
+      frontmatter: { description: 'Test' },
+      content: '## Do',
+    }
+    const context = { projectPath: '/test', files: [] }
+    const emptyAnalysis: SealedAnalysisContext = {
+      ...mockSealedAnalysis,
+      patterns: [],
+      antiPatterns: [],
+    }
+    const orcCtx = makeOrchestratorContext(emptyAnalysis)
+
+    const prompt = await promptBuilder.build(
+      template,
+      context,
+      {},
+      null,
+      null,
+      null,
+      null,
+      null,
+      orcCtx
+    )
+
+    expect(prompt).toContain('Languages**: TypeScript, JavaScript')
+    expect(prompt).not.toContain('Code Patterns (Follow These)')
+    expect(prompt).not.toContain('Anti-Patterns (Avoid These)')
+  })
+
+  it('should handle no orchestrator context at all', async () => {
+    const template = {
+      frontmatter: { description: 'Test' },
+      content: '## Do',
+    }
+    const context = { projectPath: '/test', files: [] }
+
+    const prompt = await promptBuilder.build(
+      template,
+      context,
+      {},
+      null,
+      null,
+      null,
+      null,
+      null,
+      null
+    )
+
+    // Should not crash, should have fallback rules
+    expect(prompt).toContain('CONSTRAINTS')
+    expect(prompt).not.toContain('PROJECT ANALYSIS')
+  })
+})
+
+// =============================================================================
+// Anti-Hallucination Block — Analysis Enrichment
+// =============================================================================
+
+describe('Anti-Hallucination Block with Analysis (PRJ-260)', () => {
+  it('should include analysis languages in AVAILABLE list', () => {
+    const truth: ProjectGroundTruth = {
+      projectPath: '/test',
+      language: 'TypeScript',
+      techStack: ['Hono'],
+      analysisLanguages: ['TypeScript', 'JavaScript', 'Shell'],
+      analysisFrameworks: ['Hono', 'Vitest'],
+    }
+
+    const block = buildAntiHallucinationBlock(truth)
+
+    expect(block).toContain('AVAILABLE in this project:')
+    // TypeScript and Hono should not be duplicated
+    expect(block).toContain('JavaScript')
+    expect(block).toContain('Shell')
+    expect(block).toContain('Vitest')
+  })
+
+  it('should deduplicate analysis data with existing tech stack (case-insensitive)', () => {
+    const truth: ProjectGroundTruth = {
+      projectPath: '/test',
+      language: 'TypeScript',
+      framework: 'Hono',
+      techStack: ['Zod'],
+      analysisLanguages: ['typescript'], // lowercase duplicate
+      analysisFrameworks: ['hono', 'Zod'], // lowercase duplicates
+    }
+
+    const block = buildAntiHallucinationBlock(truth)
+
+    // Count occurrences — each should appear exactly once
+    const typescriptMatches = block.match(/typescript/gi)
+    expect(typescriptMatches?.length).toBe(1)
+
+    const honoMatches = block.match(/hono/gi)
+    expect(honoMatches?.length).toBe(1)
+  })
+
+  it('should show package manager from analysis', () => {
+    const truth: ProjectGroundTruth = {
+      projectPath: '/test',
+      analysisPackageManager: 'bun',
+    }
+
+    const block = buildAntiHallucinationBlock(truth)
+
+    expect(block).toContain('PACKAGE MANAGER: bun')
+  })
+
+  it('should work without any analysis data', () => {
+    const truth: ProjectGroundTruth = {
+      projectPath: '/test',
+      language: 'Python',
+    }
+
+    const block = buildAntiHallucinationBlock(truth)
+
+    expect(block).toContain('AVAILABLE in this project: Python')
+    expect(block).not.toContain('PACKAGE MANAGER:')
+  })
+
+  it('should handle empty analysis arrays gracefully', () => {
+    const truth: ProjectGroundTruth = {
+      projectPath: '/test',
+      analysisLanguages: [],
+      analysisFrameworks: [],
+    }
+
+    const block = buildAntiHallucinationBlock(truth)
+
+    // Should not contain AVAILABLE line (no tech to show)
+    expect(block).not.toContain('AVAILABLE in this project:')
+    expect(block).toContain('CONSTRAINTS')
+  })
+})
+
+// =============================================================================
+// SealedAnalysisContext Type
+// =============================================================================
+
+describe('SealedAnalysisContext type (PRJ-260)', () => {
+  it('should accept valid sealed analysis data', () => {
+    const analysis: SealedAnalysisContext = {
+      languages: ['TypeScript'],
+      frameworks: ['Hono'],
+      fileCount: 100,
+      patterns: [{ name: 'test', description: 'test pattern' }],
+      antiPatterns: [{ issue: 'test', file: 'test.ts', suggestion: 'fix it' }],
+      status: 'sealed',
+    }
+
+    expect(analysis.languages).toEqual(['TypeScript'])
+    expect(analysis.status).toBe('sealed')
+  })
+
+  it('should accept draft status', () => {
+    const analysis: SealedAnalysisContext = {
+      languages: [],
+      frameworks: [],
+      fileCount: 0,
+      patterns: [],
+      antiPatterns: [],
+      status: 'draft',
+    }
+
+    expect(analysis.status).toBe('draft')
+  })
+
+  it('should accept optional fields', () => {
+    const analysis: SealedAnalysisContext = {
+      languages: ['Python'],
+      frameworks: [],
+      fileCount: 50,
+      patterns: [],
+      antiPatterns: [],
+      status: 'sealed',
+      packageManager: 'pip',
+      sourceDir: 'src/',
+      testDir: 'tests/',
+      commitHash: 'abc123',
+    }
+
+    expect(analysis.packageManager).toBe('pip')
+    expect(analysis.commitHash).toBe('abc123')
+  })
+})