specweave 0.23.0 → 0.23.2

package/plugins/specweave/lib/hooks/prepare-reflection-context.ts.bak

@@ -0,0 +1,178 @@
+/**
+ * Prepare Reflection Context
+ *
+ * Prepares context for reflection and saves to temp file
+ * Used by post-task-completion hook to prepare for reflection invocation
+ *
+ * @module prepare-reflection-context
+ */
+
+import fs from 'fs-extra';
+import path from 'path';
+import { createReflectionContext } from './run-self-reflection';
+import { getModifiedFilesSummary } from './git-diff-analyzer';
+
+/**
+ * Prepare reflection context and save to temp file
+ * This allows the hook to prepare data without actually invoking the agent
+ *
+ * @param incrementId Increment identifier
+ * @param taskId Task identifier
+ * @param projectRoot Project root directory (optional)
+ * @returns Path to saved context file or null if reflection should be skipped
+ */
+export function prepareReflectionContext(
+  incrementId: string,
+  taskId: string,
+  projectRoot?: string
+): string | null {
+  try {
+    const context = createReflectionContext(incrementId, taskId, projectRoot);
+
+    // Check if reflection should run
+    if (!context.config.enabled || context.modifiedFiles.length === 0) {
+      return null;
+    }
+
+    // Create temp directory for reflection context
+    const rootDir = projectRoot || process.cwd();
+    const tempDir = path.join(rootDir, '.specweave', 'increments', incrementId, 'logs', 'reflections', '.temp');
+    fs.mkdirpSync(tempDir);
+
+    // Save context to temp file
+    const contextFile = path.join(tempDir, 'reflection-context.json');
+
+    const fileStats = getModifiedFilesSummary(context.modifiedFiles);
+
+    const contextData = {
+      incrementId: context.incrementId,
+      taskId: context.taskId,
+      modifiedFiles: context.modifiedFiles.map(f => ({
+        file: f.file,
+        linesAdded: f.linesAdded,
+        linesRemoved: f.linesRemoved
+        // Exclude diff content to save space
+      })),
+      fileSummary: {
+        count: fileStats.count,
+        linesAdded: fileStats.linesAdded,
+        linesRemoved: fileStats.linesRemoved
+      },
+      config: context.config,
+      timestamp: new Date().toISOString()
+    };
+
+    fs.writeJsonSync(contextFile, contextData, { spaces: 2 });
+
+    return contextFile;
+  } catch (error: any) {
+    console.error(`Failed to prepare reflection context: ${error.message}`);
+    return null;
+  }
+}
+
+/**
+ * Check if reflection context exists for an increment
+ *
+ * @param incrementId Increment identifier
+ * @param projectRoot Project root directory (optional)
+ * @returns True if context file exists
+ */
+export function hasReflectionContext(
+  incrementId: string,
+  projectRoot?: string
+): boolean {
+  const rootDir = projectRoot || process.cwd();
+  const contextFile = path.join(
+    rootDir,
+    '.specweave',
+    'increments',
+    incrementId,
+    'logs',
+    'reflections',
+    '.temp',
+    'reflection-context.json'
+  );
+
+  return fs.existsSync(contextFile);
+}
+
+/**
+ * Read reflection context from file
+ *
+ * @param incrementId Increment identifier
+ * @param projectRoot Project root directory (optional)
+ * @returns Context data or null if not found
+ */
+export function readReflectionContext(
+  incrementId: string,
+  projectRoot?: string
+): any | null {
+  const rootDir = projectRoot || process.cwd();
+  const contextFile = path.join(
+    rootDir,
+    '.specweave',
+    'increments',
+    incrementId,
+    'logs',
+    'reflections',
+    '.temp',
+    'reflection-context.json'
+  );
+
+  if (!fs.existsSync(contextFile)) {
+    return null;
+  }
+
+  try {
+    return fs.readJsonSync(contextFile);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Clear reflection context after reflection completes
+ *
+ * @param incrementId Increment identifier
+ * @param projectRoot Project root directory (optional)
+ */
+export function clearReflectionContext(
+  incrementId: string,
+  projectRoot?: string
+): void {
+  const rootDir = projectRoot || process.cwd();
+  const tempDir = path.join(
+    rootDir,
+    '.specweave',
+    'increments',
+    incrementId,
+    'logs',
+    'reflections',
+    '.temp'
+  );
+
+  if (fs.existsSync(tempDir)) {
+    fs.removeSync(tempDir);
+  }
+}
+
+// CLI entry point for hook integration
+if (require.main === module) {
+  const incrementId = process.argv[2];
+  const taskId = process.argv[3];
+
+  if (!incrementId || !taskId) {
+    console.error('Usage: node prepare-reflection-context.js <increment-id> <task-id>');
+    process.exit(1);
+  }
+
+  const contextFile = prepareReflectionContext(incrementId, taskId);
+
+  if (contextFile) {
+    console.log(`Reflection context prepared: ${contextFile}`);
+    console.log('✨ Reflection ready. Run /specweave:reflect to analyze your work.');
+  } else {
+    console.log('Reflection skipped (disabled or no changes).');
+  }
+}

package/plugins/specweave/lib/hooks/reflection-config-loader.d.ts.bak

@@ -0,0 +1,45 @@
+/**
+ * Reflection Configuration Loader
+ *
+ * Loads and validates reflection configuration from .specweave/config.json
+ * Merges user config with defaults, validates against schema
+ *
+ * @module reflection-config-loader
+ */
+import { ReflectionConfig } from './types/reflection-types';
+/**
+ * Find .specweave directory by traversing up from current directory
+ * @param startDir Starting directory (defaults to cwd)
+ * @returns Path to .specweave directory or null if not found
+ */
+export declare function findSpecweaveRoot(startDir?: string): string | null;
+/**
+ * Load reflection configuration from .specweave/config.json
+ * Falls back to defaults if config file doesn't exist or reflection section is missing
+ *
+ * @param projectRoot Path to project root (optional, auto-detected if not provided)
+ * @returns Merged reflection configuration
+ * @throws Error if config file exists but has invalid JSON
+ */
+export declare function loadReflectionConfig(projectRoot?: string): ReflectionConfig;
+/**
+ * Validate reflection configuration against constraints
+ * Checks for logical inconsistencies (e.g., all categories disabled)
+ *
+ * @param config Reflection configuration to validate
+ * @returns Validation result with errors array
+ */
+export declare function validateReflectionConfig(config: ReflectionConfig): {
+    valid: boolean;
+    errors: string[];
+};
+/**
+ * Load and validate reflection configuration
+ * Throws error if configuration is invalid
+ *
+ * @param projectRoot Path to project root (optional, auto-detected if not provided)
+ * @returns Valid reflection configuration
+ * @throws Error if configuration is invalid
+ */
+export declare function loadAndValidateReflectionConfig(projectRoot?: string): ReflectionConfig;
+//# sourceMappingURL=reflection-config-loader.d.ts.map

package/plugins/specweave/lib/hooks/reflection-config-loader.js.bak

@@ -0,0 +1,92 @@
+import fs from "fs-extra";
+import path from "path";
+import { DEFAULT_REFLECTION_CONFIG } from "./types/reflection-types";
+function findSpecweaveRoot(startDir = process.cwd()) {
+  let currentDir = startDir;
+  const root = path.parse(currentDir).root;
+  while (currentDir !== root) {
+    const specweavePath = path.join(currentDir, ".specweave");
+    if (fs.existsSync(specweavePath)) {
+      return currentDir;
+    }
+    currentDir = path.dirname(currentDir);
+  }
+  return null;
+}
+function loadReflectionConfig(projectRoot) {
+  const rootDir = projectRoot || findSpecweaveRoot();
+  if (!rootDir) {
+    return { ...DEFAULT_REFLECTION_CONFIG };
+  }
+  const configPath = path.join(rootDir, ".specweave", "config.json");
+  if (!fs.existsSync(configPath)) {
+    return { ...DEFAULT_REFLECTION_CONFIG };
+  }
+  try {
+    const configContent = fs.readFileSync(configPath, "utf-8");
+    const config = JSON.parse(configContent);
+    const userReflectionConfig = config.reflection || {};
+    const mergedConfig = {
+      enabled: userReflectionConfig.enabled ?? DEFAULT_REFLECTION_CONFIG.enabled,
+      mode: userReflectionConfig.mode ?? DEFAULT_REFLECTION_CONFIG.mode,
+      depth: userReflectionConfig.depth ?? DEFAULT_REFLECTION_CONFIG.depth,
+      model: userReflectionConfig.model ?? DEFAULT_REFLECTION_CONFIG.model,
+      categories: {
+        security: userReflectionConfig.categories?.security ?? DEFAULT_REFLECTION_CONFIG.categories.security,
+        quality: userReflectionConfig.categories?.quality ?? DEFAULT_REFLECTION_CONFIG.categories.quality,
+        testing: userReflectionConfig.categories?.testing ?? DEFAULT_REFLECTION_CONFIG.categories.testing,
+        performance: userReflectionConfig.categories?.performance ?? DEFAULT_REFLECTION_CONFIG.categories.performance,
+        technicalDebt: userReflectionConfig.categories?.technicalDebt ?? DEFAULT_REFLECTION_CONFIG.categories.technicalDebt
+      },
+      criticalThreshold: userReflectionConfig.criticalThreshold ?? DEFAULT_REFLECTION_CONFIG.criticalThreshold,
+      storeReflections: userReflectionConfig.storeReflections ?? DEFAULT_REFLECTION_CONFIG.storeReflections,
+      autoCreateFollowUpTasks: userReflectionConfig.autoCreateFollowUpTasks ?? DEFAULT_REFLECTION_CONFIG.autoCreateFollowUpTasks,
+      soundNotifications: userReflectionConfig.soundNotifications ?? DEFAULT_REFLECTION_CONFIG.soundNotifications
+    };
+    return mergedConfig;
+  } catch (error) {
+    if (error instanceof SyntaxError) {
+      throw new Error(`Invalid JSON in config file: ${configPath}. ${error.message}`);
+    }
+    throw error;
+  }
+}
+function validateReflectionConfig(config) {
+  const errors = [];
+  if (config.enabled && config.mode !== "disabled") {
+    const hasEnabledCategory = Object.values(config.categories).some((enabled) => enabled);
+    if (!hasEnabledCategory) {
+      errors.push("At least one analysis category must be enabled when reflection is active");
+    }
+  }
+  if (!config.enabled && config.mode === "auto") {
+    errors.push('Reflection mode cannot be "auto" when reflection is disabled');
+  }
+  if (config.soundNotifications && !config.enabled) {
+    errors.push("Sound notifications require reflection to be enabled");
+  }
+  if (config.autoCreateFollowUpTasks && !config.storeReflections) {
+    errors.push("Auto-create follow-up tasks requires storeReflections to be enabled");
+  }
+  return {
+    valid: errors.length === 0,
+    errors
+  };
+}
+function loadAndValidateReflectionConfig(projectRoot) {
+  const config = loadReflectionConfig(projectRoot);
+  const validation = validateReflectionConfig(config);
+  if (!validation.valid) {
+    throw new Error(
+      `Invalid reflection configuration:
+${validation.errors.map((e) => `  - ${e}`).join("\n")}`
+    );
+  }
+  return config;
+}
+export {
+  findSpecweaveRoot,
+  loadAndValidateReflectionConfig,
+  loadReflectionConfig,
+  validateReflectionConfig
+};

package/plugins/specweave/lib/hooks/reflection-config-loader.ts.bak

@@ -0,0 +1,156 @@
+/**
+ * Reflection Configuration Loader
+ *
+ * Loads and validates reflection configuration from .specweave/config.json
+ * Merges user config with defaults, validates against schema
+ *
+ * @module reflection-config-loader
+ */
+
+import fs from 'fs-extra';
+import path from 'path';
+import { DEFAULT_REFLECTION_CONFIG, ReflectionConfig } from './types/reflection-types';
+
+/**
+ * Find .specweave directory by traversing up from current directory
+ * @param startDir Starting directory (defaults to cwd)
+ * @returns Path to .specweave directory or null if not found
+ */
+export function findSpecweaveRoot(startDir: string = process.cwd()): string | null {
+  let currentDir = startDir;
+  const root = path.parse(currentDir).root;
+
+  while (currentDir !== root) {
+    const specweavePath = path.join(currentDir, '.specweave');
+    if (fs.existsSync(specweavePath)) {
+      return currentDir;
+    }
+    currentDir = path.dirname(currentDir);
+  }
+
+  return null;
+}
+
+/**
+ * Load reflection configuration from .specweave/config.json
+ * Falls back to defaults if config file doesn't exist or reflection section is missing
+ *
+ * @param projectRoot Path to project root (optional, auto-detected if not provided)
+ * @returns Merged reflection configuration
+ * @throws Error if config file exists but has invalid JSON
+ */
+export function loadReflectionConfig(projectRoot?: string): ReflectionConfig {
+  // Auto-detect project root if not provided
+  const rootDir = projectRoot || findSpecweaveRoot();
+
+  if (!rootDir) {
+    // No .specweave directory found, return defaults
+    return { ...DEFAULT_REFLECTION_CONFIG };
+  }
+
+  const configPath = path.join(rootDir, '.specweave', 'config.json');
+
+  // Config file doesn't exist, return defaults
+  if (!fs.existsSync(configPath)) {
+    return { ...DEFAULT_REFLECTION_CONFIG };
+  }
+
+  try {
+    // Read and parse config file
+    const configContent = fs.readFileSync(configPath, 'utf-8');
+    const config = JSON.parse(configContent);
+
+    // Extract reflection section (may be undefined)
+    const userReflectionConfig = config.reflection || {};
+
+    // Deep merge with defaults (user config overrides defaults)
+    const mergedConfig: ReflectionConfig = {
+      enabled: userReflectionConfig.enabled ?? DEFAULT_REFLECTION_CONFIG.enabled,
+      mode: userReflectionConfig.mode ?? DEFAULT_REFLECTION_CONFIG.mode,
+      depth: userReflectionConfig.depth ?? DEFAULT_REFLECTION_CONFIG.depth,
+      model: userReflectionConfig.model ?? DEFAULT_REFLECTION_CONFIG.model,
+      categories: {
+        security: userReflectionConfig.categories?.security ?? DEFAULT_REFLECTION_CONFIG.categories.security,
+        quality: userReflectionConfig.categories?.quality ?? DEFAULT_REFLECTION_CONFIG.categories.quality,
+        testing: userReflectionConfig.categories?.testing ?? DEFAULT_REFLECTION_CONFIG.categories.testing,
+        performance: userReflectionConfig.categories?.performance ?? DEFAULT_REFLECTION_CONFIG.categories.performance,
+        technicalDebt: userReflectionConfig.categories?.technicalDebt ?? DEFAULT_REFLECTION_CONFIG.categories.technicalDebt,
+      },
+      criticalThreshold: userReflectionConfig.criticalThreshold ?? DEFAULT_REFLECTION_CONFIG.criticalThreshold,
+      storeReflections: userReflectionConfig.storeReflections ?? DEFAULT_REFLECTION_CONFIG.storeReflections,
+      autoCreateFollowUpTasks: userReflectionConfig.autoCreateFollowUpTasks ?? DEFAULT_REFLECTION_CONFIG.autoCreateFollowUpTasks,
+      soundNotifications: userReflectionConfig.soundNotifications ?? DEFAULT_REFLECTION_CONFIG.soundNotifications,
+    };
+
+    return mergedConfig;
+  } catch (error) {
+    // Invalid JSON or other error
+    if (error instanceof SyntaxError) {
+      throw new Error(`Invalid JSON in config file: ${configPath}. ${error.message}`);
+    }
+    throw error;
+  }
+}
+
+/**
+ * Validate reflection configuration against constraints
+ * Checks for logical inconsistencies (e.g., all categories disabled)
+ *
+ * @param config Reflection configuration to validate
+ * @returns Validation result with errors array
+ */
+export function validateReflectionConfig(config: ReflectionConfig): {
+  valid: boolean;
+  errors: string[];
+} {
+  const errors: string[] = [];
+
+  // Check: If reflection enabled, at least one category must be enabled
+  if (config.enabled && config.mode !== 'disabled') {
+    const hasEnabledCategory = Object.values(config.categories).some(enabled => enabled);
+    if (!hasEnabledCategory) {
+      errors.push('At least one analysis category must be enabled when reflection is active');
+    }
+  }
+
+  // Check: Mode cannot be 'auto' if reflection is disabled
+  if (!config.enabled && config.mode === 'auto') {
+    errors.push('Reflection mode cannot be "auto" when reflection is disabled');
+  }
+
+  // Check: Sound notifications require reflection to be enabled
+  if (config.soundNotifications && !config.enabled) {
+    errors.push('Sound notifications require reflection to be enabled');
+  }
+
+  // Check: Auto-create follow-up tasks requires storeReflections
+  if (config.autoCreateFollowUpTasks && !config.storeReflections) {
+    errors.push('Auto-create follow-up tasks requires storeReflections to be enabled');
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors
+  };
+}
+
+/**
+ * Load and validate reflection configuration
+ * Throws error if configuration is invalid
+ *
+ * @param projectRoot Path to project root (optional, auto-detected if not provided)
+ * @returns Valid reflection configuration
+ * @throws Error if configuration is invalid
+ */
+export function loadAndValidateReflectionConfig(projectRoot?: string): ReflectionConfig {
+  const config = loadReflectionConfig(projectRoot);
+  const validation = validateReflectionConfig(config);
+
+  if (!validation.valid) {
+    throw new Error(
+      `Invalid reflection configuration:\n${validation.errors.map(e => `  - ${e}`).join('\n')}`
+    );
+  }
+
+  return config;
+}

package/plugins/specweave/lib/hooks/reflection-parser.d.ts.bak

@@ -0,0 +1,33 @@
+/**
+ * Reflection Parser
+ *
+ * Parses markdown output from reflective-reviewer agent
+ * Extracts structured data (issues, metrics, lessons learned, etc.)
+ *
+ * @module reflection-parser
+ */
+import { ReflectionResult, ReflectionModel } from './types/reflection-types';
+/**
+ * Parse complete reflection result from markdown
+ * Main parsing function
+ *
+ * @param markdown Reflection markdown from reflective-reviewer agent
+ * @param taskName Task name for result
+ * @param model Model used for reflection
+ * @param reflectionTime Time taken in seconds
+ * @param estimatedCost Estimated cost in USD
+ * @returns Complete ReflectionResult object
+ */
+export declare function parseReflectionMarkdown(markdown: string, taskName: string, model?: ReflectionModel, reflectionTime?: number, estimatedCost?: number): ReflectionResult;
+/**
+ * Validate parsed reflection result
+ * Checks for required fields and data quality
+ *
+ * @param result Parsed reflection result
+ * @returns Validation result with errors
+ */
+export declare function validateReflectionResult(result: ReflectionResult): {
+    valid: boolean;
+    errors: string[];
+};
+//# sourceMappingURL=reflection-parser.d.ts.map