specweave 0.10.1 → 0.12.0

package/plugins/specweave/lib/hooks/reflection-prompt-builder.ts

@@ -0,0 +1,306 @@
+/**
+ * Reflection Prompt Builder
+ *
+ * Builds comprehensive prompts for the reflective-reviewer agent
+ * Includes modified files context, configuration, task information
+ *
+ * @module reflection-prompt-builder
+ */
+
+import { ReflectionConfig, ReflectionDepth, GitDiffInfo } from './types/reflection-types';
+
+/**
+ * Build analysis instructions based on configuration
+ * @param config Reflection configuration
+ * @returns Markdown-formatted analysis instructions
+ */
+function buildAnalysisInstructions(config: ReflectionConfig): string {
+  const { depth, categories } = config;
+
+  const instructions: string[] = [];
+
+  // Depth-specific instructions
+  switch (depth) {
+    case ReflectionDepth.QUICK:
+      instructions.push('**Analysis Mode**: QUICK (<15s)');
+      instructions.push('- Focus on CRITICAL and HIGH severity issues only');
+      instructions.push('- Skip lessons learned section');
+      instructions.push('- Provide concise feedback (1-2 sentences per issue)');
+      break;
+
+    case ReflectionDepth.STANDARD:
+      instructions.push('**Analysis Mode**: STANDARD (<30s)');
+      instructions.push('- Full analysis across all enabled categories');
+      instructions.push('- Include lessons learned');
+      instructions.push('- Provide actionable feedback with code examples');
+      break;
+
+    case ReflectionDepth.DEEP:
+      instructions.push('**Analysis Mode**: DEEP (<60s)');
+      instructions.push('- Comprehensive analysis with detailed explanations');
+      instructions.push('- Include architectural recommendations');
+      instructions.push('- Suggest refactoring opportunities');
+      instructions.push('- Analyze code metrics (complexity, coupling, cohesion)');
+      break;
+  }
+
+  instructions.push('');
+  instructions.push('**Enabled Analysis Categories**:');
+
+  // Category-specific instructions
+  if (categories.security) {
+    instructions.push('- ✅ **Security**: OWASP Top 10 vulnerabilities (SQL injection, XSS, secrets, etc.)');
+  }
+  if (categories.quality) {
+    instructions.push('- ✅ **Quality**: Code duplication, complexity, error handling, naming conventions');
+  }
+  if (categories.testing) {
+    instructions.push('- ✅ **Testing**: Edge cases, error paths, integration/E2E coverage');
+  }
+  if (categories.performance) {
+    instructions.push('- ✅ **Performance**: N+1 queries, algorithmic complexity, caching opportunities');
+  }
+  if (categories.technicalDebt) {
+    instructions.push('- ✅ **Technical Debt**: TODOs, deprecated APIs, temporary hacks');
+  }
+
+  return instructions.join('\n');
+}
+
+/**
+ * Build file context section with modified files
+ * @param modifiedFiles Array of modified files
+ * @param includeFullDiff Whether to include full diff content (default: false for large changes)
+ * @returns Markdown-formatted file context
+ */
+function buildFileContext(
+  modifiedFiles: GitDiffInfo[],
+  includeFullDiff: boolean = false
+): string {
+  const context: string[] = [];
+
+  context.push('## Modified Files Context');
+  context.push('');
+  context.push(`**Files Changed**: ${modifiedFiles.length}`);
+
+  const totalAdded = modifiedFiles.reduce((sum, f) => sum + f.linesAdded, 0);
+  const totalRemoved = modifiedFiles.reduce((sum, f) => sum + f.linesRemoved, 0);
+
+  context.push(`**Lines Added**: +${totalAdded}`);
+  context.push(`**Lines Removed**: -${totalRemoved}`);
+  context.push('');
+
+  // List all modified files with stats
+  context.push('### File Summary');
+  context.push('');
+  for (const file of modifiedFiles) {
+    context.push(`- \`${file.file}\`: +${file.linesAdded} -${file.linesRemoved}`);
+  }
+  context.push('');
+
+  // Include diff content if requested and not too large
+  if (includeFullDiff) {
+    context.push('### Detailed Changes');
+    context.push('');
+
+    for (const file of modifiedFiles) {
+      context.push(`#### ${file.file}`);
+      context.push('');
+      context.push('```diff');
+      // Truncate very large diffs (max 100 lines per file)
+      const diffLines = file.content.split('\n').slice(0, 100);
+      context.push(diffLines.join('\n'));
+      if (file.content.split('\n').length > 100) {
+        context.push('... (diff truncated)');
+      }
+      context.push('```');
+      context.push('');
+    }
+  }
+
+  return context.join('\n');
+}
+
+/**
+ * Build task information section
+ * @param taskId Task identifier (e.g., "T-005")
+ * @param taskName Human-readable task name
+ * @returns Markdown-formatted task context
+ */
+function buildTaskContext(taskId: string, taskName?: string): string {
+  const context: string[] = [];
+
+  context.push('## Task Information');
+  context.push('');
+  context.push(`**Task ID**: ${taskId}`);
+
+  if (taskName) {
+    context.push(`**Task Name**: ${taskName}`);
+  }
+
+  context.push('');
+
+  return context.join('\n');
+}
+
+/**
+ * Build the complete reflection prompt
+ * Main function for creating agent prompts
+ *
+ * @param options Prompt options
+ * @returns Complete markdown-formatted prompt for reflective-reviewer agent
+ */
+export function buildReflectionPrompt(options: {
+  taskId: string;
+  taskName?: string;
+  modifiedFiles: GitDiffInfo[];
+  config: ReflectionConfig;
+  incrementId?: string;
+  includeFullDiff?: boolean;
+}): string {
+  const {
+    taskId,
+    taskName,
+    modifiedFiles,
+    config,
+    incrementId,
+    includeFullDiff = false
+  } = options;
+
+  const sections: string[] = [];
+
+  // Header
+  sections.push('# Self-Reflection Request');
+  sections.push('');
+  sections.push('You are a senior software engineer performing self-reflection on recently completed work.');
+  sections.push('Analyze the following code changes and provide comprehensive, actionable feedback.');
+  sections.push('');
+
+  // Task context
+  sections.push(buildTaskContext(taskId, taskName));
+
+  // Increment context (if provided)
+  if (incrementId) {
+    sections.push(`**Increment**: ${incrementId}`);
+    sections.push('');
+  }
+
+  // Analysis instructions
+  sections.push('---');
+  sections.push('');
+  sections.push(buildAnalysisInstructions(config));
+  sections.push('');
+
+  // File context
+  sections.push('---');
+  sections.push('');
+  sections.push(buildFileContext(modifiedFiles, includeFullDiff));
+
+  // Analysis request
+  sections.push('---');
+  sections.push('');
+  sections.push('## Analysis Request');
+  sections.push('');
+  sections.push('Please analyze the modified files and provide a comprehensive self-reflection following the exact format specified in the reflective-reviewer agent documentation.');
+  sections.push('');
+  sections.push('**Required Sections**:');
+  sections.push('1. ✅ What Was Accomplished');
+  sections.push('2. 🎯 Quality Assessment (Strengths + Issues)');
+  sections.push('3. 🔧 Recommended Follow-Up Actions (Priority 1/2/3)');
+
+  if (config.depth !== ReflectionDepth.QUICK) {
+    sections.push('4. 📚 Lessons Learned');
+    sections.push('5. 📊 Metrics (Code Quality, Security, Test Coverage, Technical Debt, Performance)');
+  }
+
+  sections.push('');
+  sections.push('**Critical Requirements**:');
+  sections.push('- ✅ Be SPECIFIC: Always include file paths and line numbers');
+  sections.push('- ✅ Be CONSTRUCTIVE: Provide code examples for fixes, not just criticism');
+  sections.push('- ✅ Be ACTIONABLE: Every issue should have a clear next step');
+  sections.push('- ✅ Be BALANCED: Mention both strengths and issues');
+  sections.push('- ✅ Be HONEST: Don\'t sugarcoat issues, but acknowledge strengths');
+
+  sections.push('');
+  sections.push(`**Severity Threshold**: Flag issues with severity >= ${config.criticalThreshold}`);
+
+  sections.push('');
+  sections.push('---');
+  sections.push('');
+  sections.push('**Please provide your self-reflection analysis now.**');
+
+  return sections.join('\n');
+}
+
+/**
+ * Estimate token count for prompt (rough approximation)
+ * Used for cost estimation
+ *
+ * @param prompt Reflection prompt
+ * @returns Estimated token count (1 token ≈ 4 characters)
+ */
+export function estimatePromptTokens(prompt: string): number {
+  // Rough approximation: 1 token ≈ 4 characters
+  return Math.ceil(prompt.length / 4);
+}
+
+/**
+ * Truncate large diffs to fit within token budget
+ * Preserves most recent changes (bottom of diff)
+ *
+ * @param modifiedFiles Array of modified files
+ * @param maxTokens Maximum tokens to use (default: 8000)
+ * @returns Truncated array of modified files
+ */
+export function truncateModifiedFiles(
+  modifiedFiles: GitDiffInfo[],
+  maxTokens: number = 8000
+): GitDiffInfo[] {
+  const maxChars = maxTokens * 4; // Approximate token-to-char ratio
+  let currentChars = 0;
+  const truncated: GitDiffInfo[] = [];
+
+  for (const file of modifiedFiles) {
+    const fileChars = file.content.length + file.file.length + 50; // File metadata
+
+    if (currentChars + fileChars > maxChars) {
+      // Truncate this file's diff
+      const remainingChars = maxChars - currentChars;
+      if (remainingChars > 200) {
+        // Only include if we can show at least 200 chars
+        const truncatedContent = file.content.slice(0, remainingChars - 50) + '\n... (diff truncated)';
+        truncated.push({
+          ...file,
+          content: truncatedContent
+        });
+      }
+      break;
+    }
+
+    truncated.push(file);
+    currentChars += fileChars;
+  }
+
+  return truncated;
+}
+
+/**
+ * Build a simplified prompt for very large changes
+ * Used when full diff exceeds reasonable token budget
+ *
+ * @param options Prompt options (same as buildReflectionPrompt)
+ * @returns Simplified prompt with file list only (no diffs)
+ */
+export function buildSimplifiedPrompt(options: {
+  taskId: string;
+  taskName?: string;
+  modifiedFiles: GitDiffInfo[];
+  config: ReflectionConfig;
+  incrementId?: string;
+}): string {
+  // Build prompt without full diff content
+  return buildReflectionPrompt({
+    ...options,
+    includeFullDiff: false
+  });
+}

package/plugins/specweave/lib/hooks/reflection-storage.ts

@@ -0,0 +1,369 @@
+/**
+ * Reflection Storage Manager
+ *
+ * Writes reflection results to markdown files in increment logs
+ * Stores reflections in .specweave/increments/{id}/logs/reflections/
+ *
+ * @module reflection-storage
+ */
+
+import fs from 'fs-extra';
+import path from 'path';
+import { ReflectionResult, IssueSeverity } from './types/reflection-types';
+
+/**
+ * Generate markdown content from reflection result
+ * Follows the exact format specified in reflective-reviewer agent
+ *
+ * @param result Reflection result object
+ * @returns Markdown-formatted reflection content
+ */
+export function generateReflectionMarkdown(result: ReflectionResult): string {
+  const sections: string[] = [];
+
+  // Header
+  sections.push(`# Self-Reflection: ${result.taskName}`);
+  sections.push('');
+  sections.push(`**Completed**: ${result.completed}`);
+
+  if (result.duration) {
+    sections.push(`**Duration**: ${result.duration}`);
+  }
+
+  sections.push(`**Files Modified**: ${result.filesModified.count} files, +${result.filesModified.linesAdded} -${result.filesModified.linesRemoved}`);
+  sections.push('');
+  sections.push('---');
+  sections.push('');
+
+  // What Was Accomplished
+  sections.push('## ✅ What Was Accomplished');
+  sections.push('');
+
+  if (result.accomplishments.length > 0) {
+    for (const accomplishment of result.accomplishments) {
+      sections.push(`- ${accomplishment}`);
+    }
+  } else {
+    sections.push('(No accomplishments recorded)');
+  }
+
+  sections.push('');
+  sections.push('---');
+  sections.push('');
+
+  // Quality Assessment
+  sections.push('## 🎯 Quality Assessment');
+  sections.push('');
+
+  // Strengths
+  sections.push('### ✅ Strengths');
+  sections.push('');
+
+  if (result.strengths.length > 0) {
+    for (const strength of result.strengths) {
+      sections.push(`- ✅ ${strength}`);
+    }
+  } else {
+    sections.push('(No strengths recorded)');
+  }
+
+  sections.push('');
+
+  // Issues Identified
+  sections.push('### ⚠️ Issues Identified');
+  sections.push('');
+
+  if (result.issues.length === 0) {
+    sections.push('✅ No critical issues detected. Code follows best practices.');
+  } else {
+    // Group issues by severity
+    const criticalIssues = result.issues.filter(i => i.severity === IssueSeverity.CRITICAL);
+    const highIssues = result.issues.filter(i => i.severity === IssueSeverity.HIGH);
+    const mediumIssues = result.issues.filter(i => i.severity === IssueSeverity.MEDIUM);
+    const lowIssues = result.issues.filter(i => i.severity === IssueSeverity.LOW);
+
+    const issueGroups = [
+      { issues: criticalIssues, severity: IssueSeverity.CRITICAL },
+      { issues: highIssues, severity: IssueSeverity.HIGH },
+      { issues: mediumIssues, severity: IssueSeverity.MEDIUM },
+      { issues: lowIssues, severity: IssueSeverity.LOW }
+    ];
+
+    for (const group of issueGroups) {
+      if (group.issues.length === 0) continue;
+
+      for (const issue of group.issues) {
+        sections.push(`**${issue.severity} (${issue.category})**`);
+        sections.push(`- ❌ ${issue.description}`);
+        sections.push(`  - **Impact**: ${issue.impact}`);
+        sections.push(`  - **Recommendation**: ${issue.recommendation}`);
+
+        if (issue.location) {
+          const locationStr = issue.location.line
+            ? `${issue.location.file}:${issue.location.line}`
+            : issue.location.file;
+          sections.push(`  - **Location**: \`${locationStr}\``);
+
+          if (issue.location.snippet) {
+            sections.push('  - **Code Snippet**:');
+            sections.push('    ```');
+            sections.push(`    ${issue.location.snippet}`);
+            sections.push('    ```');
+          }
+        }
+
+        sections.push('');
+      }
+    }
+  }
+
+  sections.push('---');
+  sections.push('');
+
+  // Recommended Follow-Up Actions
+  sections.push('## 🔧 Recommended Follow-Up Actions');
+  sections.push('');
+
+  const hasActions =
+    result.recommendedActions.priority1.length > 0 ||
+    result.recommendedActions.priority2.length > 0 ||
+    result.recommendedActions.priority3.length > 0;
+
+  if (!hasActions) {
+    sections.push('✅ No follow-up actions required. Ready to proceed.');
+  } else {
+    if (result.recommendedActions.priority1.length > 0) {
+      sections.push('**Priority 1 (MUST FIX - before closing increment)**:');
+      for (let i = 0; i < result.recommendedActions.priority1.length; i++) {
+        sections.push(`${i + 1}. ${result.recommendedActions.priority1[i]}`);
+      }
+      sections.push('');
+    }
+
+    if (result.recommendedActions.priority2.length > 0) {
+      sections.push('**Priority 2 (SHOULD FIX - this increment)**:');
+      for (let i = 0; i < result.recommendedActions.priority2.length; i++) {
+        sections.push(`${i + 1}. ${result.recommendedActions.priority2[i]}`);
+      }
+      sections.push('');
+    }
+
+    if (result.recommendedActions.priority3.length > 0) {
+      sections.push('**Priority 3 (NICE TO HAVE - future increment)**:');
+      for (let i = 0; i < result.recommendedActions.priority3.length; i++) {
+        sections.push(`${i + 1}. ${result.recommendedActions.priority3[i]}`);
+      }
+      sections.push('');
+    }
+  }
+
+  sections.push('---');
+  sections.push('');
+
+  // Lessons Learned (optional - may be empty for QUICK depth)
+  const hasLessons =
+    result.lessonsLearned.whatWentWell.length > 0 ||
+    result.lessonsLearned.whatCouldImprove.length > 0 ||
+    result.lessonsLearned.forNextTime.length > 0;
+
+  if (hasLessons) {
+    sections.push('## 📚 Lessons Learned');
+    sections.push('');
+
+    if (result.lessonsLearned.whatWentWell.length > 0) {
+      sections.push('**What went well**:');
+      for (const lesson of result.lessonsLearned.whatWentWell) {
+        sections.push(`- ${lesson}`);
+      }
+      sections.push('');
+    }
+
+    if (result.lessonsLearned.whatCouldImprove.length > 0) {
+      sections.push('**What could improve**:');
+      for (const lesson of result.lessonsLearned.whatCouldImprove) {
+        sections.push(`- ${lesson}`);
+      }
+      sections.push('');
+    }
+
+    if (result.lessonsLearned.forNextTime.length > 0) {
+      sections.push('**For next time**:');
+      for (const lesson of result.lessonsLearned.forNextTime) {
+        sections.push(`- ${lesson}`);
+      }
+      sections.push('');
+    }
+
+    sections.push('---');
+    sections.push('');
+  }
+
+  // Metrics
+  sections.push('## 📊 Metrics');
+  sections.push('');
+  sections.push(`- **Code Quality**: ${result.metrics.codeQuality}/10`);
+  sections.push(`- **Security**: ${result.metrics.security}/10`);
+
+  if (result.metrics.testCoverage !== undefined) {
+    sections.push(`- **Test Coverage**: ${result.metrics.testCoverage}%`);
+  } else {
+    sections.push(`- **Test Coverage**: N/A`);
+  }
+
+  sections.push(`- **Technical Debt**: ${result.metrics.technicalDebt}`);
+  sections.push(`- **Performance**: ${result.metrics.performance.replace(/_/g, ' ')}`);
+  sections.push('');
+
+  // Related Tasks (optional)
+  if (result.relatedTasks && result.relatedTasks.length > 0) {
+    sections.push('---');
+    sections.push('');
+    sections.push('## 🔗 Related Tasks');
+    sections.push('');
+    for (const task of result.relatedTasks) {
+      sections.push(`- ${task}`);
+    }
+    sections.push('');
+  }
+
+  // Footer
+  sections.push('---');
+  sections.push('');
+  sections.push('**Auto-generated by**: SpecWeave Self-Reflection System');
+  sections.push(`**Model**: Claude 3.5 ${result.metadata.model.charAt(0).toUpperCase() + result.metadata.model.slice(1)}`);
+  sections.push(`**Reflection Time**: ${result.metadata.reflectionTime} seconds`);
+  sections.push(`**Estimated Cost**: ~$${result.metadata.estimatedCost.toFixed(3)}`);
+  sections.push('');
+
+  return sections.join('\n');
+}
+
+/**
+ * Get reflection log directory for an increment
+ * @param incrementId Increment identifier (e.g., "0016-self-reflection-system")
+ * @param projectRoot Project root directory (optional, auto-detected if not provided)
+ * @returns Path to reflection logs directory
+ */
+export function getReflectionLogDir(
+  incrementId: string,
+  projectRoot?: string
+): string {
+  const rootDir = projectRoot || process.cwd();
+  return path.join(
+    rootDir,
+    '.specweave',
+    'increments',
+    incrementId,
+    'logs',
+    'reflections'
+  );
+}
+
+/**
+ * Generate filename for reflection log
+ * @param taskId Task identifier (e.g., "T-005")
+ * @param timestamp Optional timestamp (defaults to current date)
+ * @returns Filename (e.g., "task-T-005-reflection-2025-11-10.md")
+ */
+export function getReflectionFilename(
+  taskId: string,
+  timestamp?: Date
+): string {
+  const date = timestamp || new Date();
+  const dateStr = date.toISOString().split('T')[0]; // YYYY-MM-DD
+  const sanitizedTaskId = taskId.replace(/[^a-zA-Z0-9-]/g, '-');
+  return `task-${sanitizedTaskId}-reflection-${dateStr}.md`;
+}
+
+/**
+ * Save reflection result to markdown file
+ * Creates directory structure if it doesn't exist
+ *
+ * @param result Reflection result to save
+ * @param incrementId Increment identifier
+ * @param taskId Task identifier
+ * @param projectRoot Project root directory (optional)
+ * @returns Path to saved reflection file
+ * @throws Error if file cannot be written
+ */
+export function saveReflection(
+  result: ReflectionResult,
+  incrementId: string,
+  taskId: string,
+  projectRoot?: string
+): string {
+  // Ensure reflection logs directory exists
+  const logDir = getReflectionLogDir(incrementId, projectRoot);
+  fs.mkdirpSync(logDir);
+
+  // Generate filename
+  const filename = getReflectionFilename(taskId);
+  const filepath = path.join(logDir, filename);
+
+  // Generate markdown content
+  const markdown = generateReflectionMarkdown(result);
+
+  // Write to file
+  try {
+    fs.writeFileSync(filepath, markdown, 'utf-8');
+    return filepath;
+  } catch (error: any) {
+    throw new Error(`Failed to save reflection: ${error.message}`);
+  }
+}
+
+/**
+ * List all reflection files for an increment
+ * @param incrementId Increment identifier
+ * @param projectRoot Project root directory (optional)
+ * @returns Array of reflection file paths (sorted by date, newest first)
+ */
+export function listReflections(
+  incrementId: string,
+  projectRoot?: string
+): string[] {
+  const logDir = getReflectionLogDir(incrementId, projectRoot);
+
+  if (!fs.existsSync(logDir)) {
+    return [];
+  }
+
+  const files = fs.readdirSync(logDir)
+    .filter(file => file.endsWith('.md'))
+    .map(file => path.join(logDir, file))
+    .sort((a, b) => {
+      // Sort by modification time (newest first)
+      const statA = fs.statSync(a);
+      const statB = fs.statSync(b);
+      return statB.mtime.getTime() - statA.mtime.getTime();
+    });
+
+  return files;
+}
+
+/**
+ * Read reflection from file
+ * @param filepath Path to reflection markdown file
+ * @returns Markdown content as string
+ * @throws Error if file cannot be read
+ */
+export function readReflection(filepath: string): string {
+  try {
+    return fs.readFileSync(filepath, 'utf-8');
+  } catch (error: any) {
+    throw new Error(`Failed to read reflection: ${error.message}`);
+  }
+}
+
+/**
+ * Delete reflection file
+ * @param filepath Path to reflection markdown file
+ * @throws Error if file cannot be deleted
+ */
+export function deleteReflection(filepath: string): void {
+  try {
+    fs.removeSync(filepath);
+  } catch (error: any) {
+    throw new Error(`Failed to delete reflection: ${error.message}`);
+  }
+}