specweave 0.24.8 → 0.24.9

package/plugins/specweave/lib/hooks/reflection-prompt-builder.js.bak

@@ -0,0 +1,182 @@
+import { ReflectionDepth } from "./types/reflection-types";
+function buildAnalysisInstructions(config) {
+  const { depth, categories } = config;
+  const 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**:");
+  if (categories.security) {
+    instructions.push("- \u2705 **Security**: OWASP Top 10 vulnerabilities (SQL injection, XSS, secrets, etc.)");
+  }
+  if (categories.quality) {
+    instructions.push("- \u2705 **Quality**: Code duplication, complexity, error handling, naming conventions");
+  }
+  if (categories.testing) {
+    instructions.push("- \u2705 **Testing**: Edge cases, error paths, integration/E2E coverage");
+  }
+  if (categories.performance) {
+    instructions.push("- \u2705 **Performance**: N+1 queries, algorithmic complexity, caching opportunities");
+  }
+  if (categories.technicalDebt) {
+    instructions.push("- \u2705 **Technical Debt**: TODOs, deprecated APIs, temporary hacks");
+  }
+  return instructions.join("\n");
+}
+function buildFileContext(modifiedFiles, includeFullDiff = false) {
+  const context = [];
+  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("");
+  context.push("### File Summary");
+  context.push("");
+  for (const file of modifiedFiles) {
+    context.push(`- \`${file.file}\`: +${file.linesAdded} -${file.linesRemoved}`);
+  }
+  context.push("");
+  if (includeFullDiff) {
+    context.push("### Detailed Changes");
+    context.push("");
+    for (const file of modifiedFiles) {
+      context.push(`#### ${file.file}`);
+      context.push("");
+      context.push("```diff");
+      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");
+}
+function buildTaskContext(taskId, taskName) {
+  const context = [];
+  context.push("## Task Information");
+  context.push("");
+  context.push(`**Task ID**: ${taskId}`);
+  if (taskName) {
+    context.push(`**Task Name**: ${taskName}`);
+  }
+  context.push("");
+  return context.join("\n");
+}
+function buildReflectionPrompt(options) {
+  const {
+    taskId,
+    taskName,
+    modifiedFiles,
+    config,
+    incrementId,
+    includeFullDiff = false
+  } = options;
+  const sections = [];
+  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("");
+  sections.push(buildTaskContext(taskId, taskName));
+  if (incrementId) {
+    sections.push(`**Increment**: ${incrementId}`);
+    sections.push("");
+  }
+  sections.push("---");
+  sections.push("");
+  sections.push(buildAnalysisInstructions(config));
+  sections.push("");
+  sections.push("---");
+  sections.push("");
+  sections.push(buildFileContext(modifiedFiles, includeFullDiff));
+  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. \u2705 What Was Accomplished");
+  sections.push("2. \u{1F3AF} Quality Assessment (Strengths + Issues)");
+  sections.push("3. \u{1F527} Recommended Follow-Up Actions (Priority 1/2/3)");
+  if (config.depth !== ReflectionDepth.QUICK) {
+    sections.push("4. \u{1F4DA} Lessons Learned");
+    sections.push("5. \u{1F4CA} Metrics (Code Quality, Security, Test Coverage, Technical Debt, Performance)");
+  }
+  sections.push("");
+  sections.push("**Critical Requirements**:");
+  sections.push("- \u2705 Be SPECIFIC: Always include file paths and line numbers");
+  sections.push("- \u2705 Be CONSTRUCTIVE: Provide code examples for fixes, not just criticism");
+  sections.push("- \u2705 Be ACTIONABLE: Every issue should have a clear next step");
+  sections.push("- \u2705 Be BALANCED: Mention both strengths and issues");
+  sections.push("- \u2705 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");
+}
+function estimatePromptTokens(prompt) {
+  return Math.ceil(prompt.length / 4);
+}
+function truncateModifiedFiles(modifiedFiles, maxTokens = 8e3) {
+  const maxChars = maxTokens * 4;
+  let currentChars = 0;
+  const truncated = [];
+  for (const file of modifiedFiles) {
+    const fileChars = file.content.length + file.file.length + 50;
+    if (currentChars + fileChars > maxChars) {
+      const remainingChars = maxChars - currentChars;
+      if (remainingChars > 200) {
+        const truncatedContent = file.content.slice(0, remainingChars - 50) + "\n... (diff truncated)";
+        truncated.push({
+          ...file,
+          content: truncatedContent
+        });
+      }
+      break;
+    }
+    truncated.push(file);
+    currentChars += fileChars;
+  }
+  return truncated;
+}
+function buildSimplifiedPrompt(options) {
+  return buildReflectionPrompt({
+    ...options,
+    includeFullDiff: false
+  });
+}
+export {
+  buildReflectionPrompt,
+  buildSimplifiedPrompt,
+  estimatePromptTokens,
+  truncateModifiedFiles
+};

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

@@ -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.d.ts.bak

@@ -0,0 +1,64 @@
+/**
+ * Reflection Storage Manager
+ *
+ * Writes reflection results to markdown files in increment logs
+ * Stores reflections in .specweave/increments/{id}/logs/reflections/
+ *
+ * @module reflection-storage
+ */
+import { ReflectionResult } 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 declare function generateReflectionMarkdown(result: ReflectionResult): string;
+/**
+ * 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 declare function getReflectionLogDir(incrementId: string, projectRoot?: string): string;
+/**
+ * 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 declare function getReflectionFilename(taskId: string, timestamp?: Date): string;
+/**
+ * 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 declare function saveReflection(result: ReflectionResult, incrementId: string, taskId: string, projectRoot?: string): string;
+/**
+ * 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 declare function listReflections(incrementId: string, projectRoot?: string): string[];
+/**
+ * Read reflection from file
+ * @param filepath Path to reflection markdown file
+ * @returns Markdown content as string
+ * @throws Error if file cannot be read
+ */
+export declare function readReflection(filepath: string): string;
+/**
+ * Delete reflection file
+ * @param filepath Path to reflection markdown file
+ * @throws Error if file cannot be deleted
+ */
+export declare function deleteReflection(filepath: string): void;
+//# sourceMappingURL=reflection-storage.d.ts.map