specweave 0.23.0 → 0.23.2

package/plugins/specweave/lib/hooks/run-self-reflection.js.bak

@@ -0,0 +1,132 @@
+import { loadAndValidateReflectionConfig } from "./reflection-config-loader";
+import { getModifiedFiles, getModifiedFilesSummary } from "./git-diff-analyzer";
+import { buildReflectionPrompt, estimatePromptTokens } from "./reflection-prompt-builder";
+import { parseReflectionMarkdown, validateReflectionResult } from "./reflection-parser";
+import { saveReflection } from "./reflection-storage";
+import {
+  ReflectionMode,
+  ReflectionModel
+} from "./types/reflection-types";
+function shouldRunReflection(context) {
+  const { config, modifiedFiles } = context;
+  if (!config.enabled) {
+    return false;
+  }
+  if (config.mode === ReflectionMode.DISABLED) {
+    return false;
+  }
+  if (config.mode === ReflectionMode.MANUAL) {
+    return false;
+  }
+  if (modifiedFiles.length === 0) {
+    return false;
+  }
+  return true;
+}
+function estimateReflectionCost(model, promptTokens, responseTokens = 2e3) {
+  const pricing = {
+    [ReflectionModel.HAIKU]: { input: 0.8, output: 4 },
+    [ReflectionModel.SONNET]: { input: 3, output: 15 },
+    [ReflectionModel.OPUS]: { input: 15, output: 75 }
+  };
+  const modelPricing = pricing[model];
+  const inputCost = promptTokens / 1e6 * modelPricing.input;
+  const outputCost = responseTokens / 1e6 * modelPricing.output;
+  return inputCost + outputCost;
+}
+async function invokeReflectiveReviewerAgent(prompt, model) {
+  throw new Error(
+    "Agent invocation not implemented yet. This function will be implemented in hook integration (T-008). Call this from the post-task-completion hook using the Task tool."
+  );
+}
+async function runSelfReflection(context) {
+  const { incrementId, taskId, modifiedFiles, config } = context;
+  const startTime = Date.now();
+  try {
+    if (!shouldRunReflection(context)) {
+      return {
+        success: true,
+        result: void 0,
+        error: void 0
+      };
+    }
+    const prompt = buildReflectionPrompt({
+      taskId,
+      taskName: `Task ${taskId}`,
+      // Will be enhanced with actual task name in hook
+      modifiedFiles,
+      config,
+      incrementId,
+      includeFullDiff: false
+      // Use simplified prompt for token efficiency
+    });
+    const promptTokens = estimatePromptTokens(prompt);
+    const estimatedCost = estimateReflectionCost(config.model, promptTokens);
+    const agentResponse = await invokeReflectiveReviewerAgent(prompt, config.model);
+    const endTime = Date.now();
+    const reflectionTime = Math.round((endTime - startTime) / 1e3);
+    const reflectionResult = parseReflectionMarkdown(
+      agentResponse,
+      `Task ${taskId}`,
+      config.model,
+      reflectionTime,
+      estimatedCost
+    );
+    const fileStats = getModifiedFilesSummary(modifiedFiles);
+    reflectionResult.filesModified = {
+      count: fileStats.count,
+      linesAdded: fileStats.linesAdded,
+      linesRemoved: fileStats.linesRemoved
+    };
+    const validation = validateReflectionResult(reflectionResult);
+    if (!validation.valid) {
+      return {
+        success: false,
+        error: {
+          message: "Reflection validation failed",
+          code: "VALIDATION_ERROR",
+          details: validation.errors
+        }
+      };
+    }
+    if (config.storeReflections) {
+      try {
+        saveReflection(reflectionResult, incrementId, taskId);
+      } catch (storageError) {
+        console.warn(`Failed to store reflection: ${storageError.message}`);
+      }
+    }
+    return {
+      success: true,
+      result: reflectionResult
+    };
+  } catch (error) {
+    return {
+      success: false,
+      error: {
+        message: error.message || "Unknown error during reflection",
+        code: "REFLECTION_ERROR",
+        details: error.stack
+      }
+    };
+  }
+}
+function createReflectionContext(incrementId, taskId, projectRoot) {
+  const config = loadAndValidateReflectionConfig(projectRoot);
+  const modifiedFiles = getModifiedFiles(projectRoot);
+  return {
+    incrementId,
+    taskId,
+    modifiedFiles,
+    config
+  };
+}
+async function runReflectionAuto(incrementId, taskId, projectRoot) {
+  const context = createReflectionContext(incrementId, taskId, projectRoot);
+  return runSelfReflection(context);
+}
+export {
+  createReflectionContext,
+  runReflectionAuto,
+  runSelfReflection
+};

package/plugins/specweave/lib/hooks/run-self-reflection.ts.bak

@@ -0,0 +1,258 @@
+/**
+ * Core Reflection Engine
+ *
+ * Orchestrates the self-reflection process:
+ * 1. Load configuration
+ * 2. Get modified files
+ * 3. Build prompt
+ * 4. Invoke reflective-reviewer agent
+ * 5. Parse response
+ * 6. Store reflection
+ *
+ * @module run-self-reflection
+ */
+
+import { loadAndValidateReflectionConfig } from './reflection-config-loader';
+import { getModifiedFiles, getModifiedFilesSummary } from './git-diff-analyzer';
+import { buildReflectionPrompt, estimatePromptTokens } from './reflection-prompt-builder';
+import { parseReflectionMarkdown, validateReflectionResult } from './reflection-parser';
+import { saveReflection } from './reflection-storage';
+import {
+  ReflectionContext,
+  ReflectionExecutionResult,
+  ReflectionMode,
+  ReflectionModel
+} from './types/reflection-types';
+
+/**
+ * Check if reflection should run for the current context
+ *
+ * @param context Reflection context with config and modified files
+ * @returns True if reflection should run
+ */
+function shouldRunReflection(context: ReflectionContext): boolean {
+  const { config, modifiedFiles } = context;
+
+  // Check if reflection is enabled
+  if (!config.enabled) {
+    return false;
+  }
+
+  // Check mode
+  if (config.mode === ReflectionMode.DISABLED) {
+    return false;
+  }
+
+  if (config.mode === ReflectionMode.MANUAL) {
+    // Manual mode requires explicit invocation
+    // This function is only called in auto mode, so skip
+    return false;
+  }
+
+  // Check if there are modified files to analyze
+  if (modifiedFiles.length === 0) {
+    return false;
+  }
+
+  return true;
+}
+
+/**
+ * Estimate reflection cost based on model and prompt size
+ *
+ * @param model Reflection model (haiku, sonnet, opus)
+ * @param promptTokens Estimated prompt token count
+ * @param responseTokens Estimated response token count (default: 2000)
+ * @returns Estimated cost in USD
+ */
+function estimateReflectionCost(
+  model: ReflectionModel,
+  promptTokens: number,
+  responseTokens: number = 2000
+): number {
+  // Pricing per 1M tokens (as of Nov 2025)
+  const pricing = {
+    [ReflectionModel.HAIKU]: { input: 0.80, output: 4.00 },
+    [ReflectionModel.SONNET]: { input: 3.00, output: 15.00 },
+    [ReflectionModel.OPUS]: { input: 15.00, output: 75.00 }
+  };
+
+  const modelPricing = pricing[model];
+  const inputCost = (promptTokens / 1_000_000) * modelPricing.input;
+  const outputCost = (responseTokens / 1_000_000) * modelPricing.output;
+
+  return inputCost + outputCost;
+}
+
+/**
+ * Invoke reflective-reviewer agent to analyze code
+ *
+ * @param prompt Reflection prompt
+ * @param model Model to use (haiku, sonnet, opus)
+ * @returns Agent response (markdown reflection)
+ */
+async function invokeReflectiveReviewerAgent(
+  prompt: string,
+  model: ReflectionModel
+): Promise<string> {
+  // NOTE: This is a placeholder for agent invocation
+  // In the real implementation, this would use Claude Code's Task tool
+  // to invoke the specweave:reflective-reviewer:reflective-reviewer agent
+  //
+  // For now, we'll return a mock response to enable testing
+  // The actual implementation will be in the hook integration (T-008)
+
+  throw new Error(
+    'Agent invocation not implemented yet. ' +
+    'This function will be implemented in hook integration (T-008). ' +
+    'Call this from the post-task-completion hook using the Task tool.'
+  );
+}
+
+/**
+ * Run self-reflection analysis
+ * Main entry point for the reflection system
+ *
+ * @param context Reflection context with increment, task, and files
+ * @returns Reflection execution result (success or error)
+ */
+export async function runSelfReflection(
+  context: ReflectionContext
+): Promise<ReflectionExecutionResult> {
+  const { incrementId, taskId, modifiedFiles, config } = context;
+  const startTime = Date.now();
+
+  try {
+    // Step 1: Check if reflection should run
+    if (!shouldRunReflection(context)) {
+      return {
+        success: true,
+        result: undefined,
+        error: undefined
+      };
+    }
+
+    // Step 2: Build reflection prompt
+    const prompt = buildReflectionPrompt({
+      taskId,
+      taskName: `Task ${taskId}`, // Will be enhanced with actual task name in hook
+      modifiedFiles,
+      config,
+      incrementId,
+      includeFullDiff: false // Use simplified prompt for token efficiency
+    });
+
+    // Step 3: Estimate cost
+    const promptTokens = estimatePromptTokens(prompt);
+    const estimatedCost = estimateReflectionCost(config.model, promptTokens);
+
+    // Step 4: Invoke reflective-reviewer agent
+    const agentResponse = await invokeReflectiveReviewerAgent(prompt, config.model);
+
+    // Step 5: Parse response
+    const endTime = Date.now();
+    const reflectionTime = Math.round((endTime - startTime) / 1000); // seconds
+
+    const reflectionResult = parseReflectionMarkdown(
+      agentResponse,
+      `Task ${taskId}`,
+      config.model,
+      reflectionTime,
+      estimatedCost
+    );
+
+    // Step 6: Add file modification stats
+    const fileStats = getModifiedFilesSummary(modifiedFiles);
+    reflectionResult.filesModified = {
+      count: fileStats.count,
+      linesAdded: fileStats.linesAdded,
+      linesRemoved: fileStats.linesRemoved
+    };
+
+    // Step 7: Validate reflection result
+    const validation = validateReflectionResult(reflectionResult);
+    if (!validation.valid) {
+      return {
+        success: false,
+        error: {
+          message: 'Reflection validation failed',
+          code: 'VALIDATION_ERROR',
+          details: validation.errors
+        }
+      };
+    }
+
+    // Step 8: Store reflection (if enabled)
+    if (config.storeReflections) {
+      try {
+        saveReflection(reflectionResult, incrementId, taskId);
+      } catch (storageError: any) {
+        // Storage failure shouldn't fail the entire reflection
+        console.warn(`Failed to store reflection: ${storageError.message}`);
+      }
+    }
+
+    // Step 9: Return success
+    return {
+      success: true,
+      result: reflectionResult
+    };
+
+  } catch (error: any) {
+    // Graceful degradation: Return error but don't throw
+    return {
+      success: false,
+      error: {
+        message: error.message || 'Unknown error during reflection',
+        code: 'REFLECTION_ERROR',
+        details: error.stack
+      }
+    };
+  }
+}
+
+/**
+ * Create reflection context from hook environment
+ * Helper function for hook integration
+ *
+ * @param incrementId Increment identifier
+ * @param taskId Task identifier
+ * @param projectRoot Project root directory (optional, auto-detected)
+ * @returns Reflection context ready for runSelfReflection
+ */
+export function createReflectionContext(
+  incrementId: string,
+  taskId: string,
+  projectRoot?: string
+): ReflectionContext {
+  // Load and validate configuration
+  const config = loadAndValidateReflectionConfig(projectRoot);
+
+  // Get modified files from git
+  const modifiedFiles = getModifiedFiles(projectRoot);
+
+  return {
+    incrementId,
+    taskId,
+    modifiedFiles,
+    config
+  };
+}
+
+/**
+ * Run reflection with automatic context creation
+ * Convenience function for hook integration
+ *
+ * @param incrementId Increment identifier
+ * @param taskId Task identifier
+ * @param projectRoot Project root directory (optional)
+ * @returns Reflection execution result
+ */
+export async function runReflectionAuto(
+  incrementId: string,
+  taskId: string,
+  projectRoot?: string
+): Promise<ReflectionExecutionResult> {
+  const context = createReflectionContext(incrementId, taskId, projectRoot);
+  return runSelfReflection(context);
+}

package/plugins/specweave/lib/hooks/sync-cache.js.bak

@@ -0,0 +1,294 @@
+#!/usr/bin/env node
+/**
+ * Sync Performance Cache Module
+ *
+ * Provides caching layer for living docs sync to meet <500ms target.
+ * Caches:
+ * - Parsed tasks.md content
+ * - File modification timestamps
+ * - US-Task mappings
+ *
+ * Part of increment 0047-us-task-linkage (T-012).
+ */
+
+import fs from 'fs-extra';
+import path from 'path';
+import crypto from 'crypto';
+
+/**
+ * In-memory cache with TTL
+ */
+class SyncCache {
+  constructor() {
+    this.cache = new Map();
+    this.ttl = 60000; // 60 seconds default TTL
+  }
+
+  /**
+   * Get cached value
+   *
+   * @param {string} key - Cache key
+   * @returns {any|null} Cached value or null if expired/missing
+   */
+  get(key) {
+    const entry = this.cache.get(key);
+
+    if (!entry) {
+      return null;
+    }
+
+    // Check if expired
+    if (Date.now() > entry.expiry) {
+      this.cache.delete(key);
+      return null;
+    }
+
+    return entry.value;
+  }
+
+  /**
+   * Set cached value
+   *
+   * @param {string} key - Cache key
+   * @param {any} value - Value to cache
+   * @param {number} ttl - Time to live in milliseconds (optional)
+   */
+  set(key, value, ttl = this.ttl) {
+    this.cache.set(key, {
+      value,
+      expiry: Date.now() + ttl
+    });
+  }
+
+  /**
+   * Invalidate cache entry
+   *
+   * @param {string} key - Cache key
+   */
+  invalidate(key) {
+    this.cache.delete(key);
+  }
+
+  /**
+   * Clear all cache
+   */
+  clear() {
+    this.cache.clear();
+  }
+
+  /**
+   * Get cache size
+   *
+   * @returns {number} Number of cached entries
+   */
+  size() {
+    return this.cache.size;
+  }
+}
+
+// Global cache instance
+const globalCache = new SyncCache();
+
+/**
+ * Get file hash for change detection
+ *
+ * @param {string} filePath - Path to file
+ * @returns {string} SHA256 hash of file content
+ */
+export function getFileHash(filePath) {
+  try {
+    const content = fs.readFileSync(filePath, 'utf-8');
+    return crypto.createHash('sha256').update(content).digest('hex');
+  } catch (error) {
+    return null;
+  }
+}
+
+/**
+ * Get cached parsed tasks.md
+ *
+ * @param {string} tasksPath - Path to tasks.md
+ * @param {Function} parser - Parser function to call if cache miss
+ * @returns {any} Parsed tasks (from cache or fresh)
+ */
+export function getCachedTasks(tasksPath, parser) {
+  // Generate cache key from file path + hash
+  const fileHash = getFileHash(tasksPath);
+
+  if (!fileHash) {
+    // File doesn't exist, call parser directly
+    return parser(tasksPath);
+  }
+
+  const cacheKey = `tasks:${tasksPath}:${fileHash}`;
+
+  // Try to get from cache
+  const cached = globalCache.get(cacheKey);
+
+  if (cached) {
+    // Cache hit
+    return cached;
+  }
+
+  // Cache miss - parse and cache
+  const parsed = parser(tasksPath);
+  globalCache.set(cacheKey, parsed);
+
+  return parsed;
+}
+
+/**
+ * Get cached US file metadata
+ *
+ * @param {string} usFilePath - Path to US file
+ * @returns {object|null} Metadata object or null if file doesn't exist
+ */
+export function getCachedUSMetadata(usFilePath) {
+  try {
+    const stats = fs.statSync(usFilePath);
+    const cacheKey = `us-metadata:${usFilePath}`;
+
+    const cached = globalCache.get(cacheKey);
+
+    if (cached && cached.mtime === stats.mtimeMs) {
+      // File hasn't changed, return cached metadata
+      return cached.metadata;
+    }
+
+    // File changed or not in cache - read and cache
+    const content = fs.readFileSync(usFilePath, 'utf-8');
+    const metadata = {
+      mtime: stats.mtimeMs,
+      metadata: {
+        path: usFilePath,
+        size: content.length,
+        tasksSectionExists: content.includes('## Tasks'),
+        acCount: (content.match(/- \[[x ]\] \*\*AC-US\d+-\d{2}\*\*/g) || []).length
+      }
+    };
+
+    globalCache.set(cacheKey, metadata);
+
+    return metadata.metadata;
+  } catch (error) {
+    return null;
+  }
+}
+
+/**
+ * Batch file operations to reduce I/O
+ *
+ * @param {Array<{path: string, content: string}>} updates - Files to update
+ * @returns {Promise<void>}
+ */
+export async function batchFileUpdates(updates) {
+  // Group updates by directory to optimize disk I/O
+  const updatesByDir = new Map();
+
+  updates.forEach(({ path: filePath, content }) => {
+    const dir = path.dirname(filePath);
+
+    if (!updatesByDir.has(dir)) {
+      updatesByDir.set(dir, []);
+    }
+
+    updatesByDir.get(dir).push({ path: filePath, content });
+  });
+
+  // Write files sequentially within same directory (better disk I/O)
+  for (const [dir, fileUpdates] of updatesByDir.entries()) {
+    // Ensure directory exists once per directory
+    await fs.ensureDir(dir);
+
+    // Write all files in this directory
+    await Promise.all(
+      fileUpdates.map(({ path: filePath, content }) =>
+        fs.writeFile(filePath, content, 'utf-8')
+      )
+    );
+  }
+}
+
+/**
+ * Check if sync is needed for a US file
+ *
+ * @param {string} usFilePath - Path to US file
+ * @param {Array} tasks - Tasks for this US
+ * @param {string} tasksPath - Path to tasks.md
+ * @returns {boolean} True if sync is needed
+ */
+export function needsSync(usFilePath, tasks, tasksPath) {
+  try {
+    // Check if US file exists
+    if (!fs.existsSync(usFilePath)) {
+      return false; // File doesn't exist, can't sync
+    }
+
+    // Get file modification times
+    const usStats = fs.statSync(usFilePath);
+    const tasksStats = fs.statSync(tasksPath);
+
+    // If tasks.md is newer than US file, sync is needed
+    if (tasksStats.mtimeMs > usStats.mtimeMs) {
+      return true;
+    }
+
+    // Check cache for last sync result
+    const cacheKey = `sync-result:${usFilePath}`;
+    const cached = globalCache.get(cacheKey);
+
+    if (cached) {
+      // Compare task list with cached
+      const currentTaskIds = tasks.map(t => t.id).sort().join(',');
+      const cachedTaskIds = cached.taskIds;
+
+      if (currentTaskIds === cachedTaskIds) {
+        // Task list unchanged, no sync needed
+        return false;
+      }
+    }
+
+    // Default: sync is needed
+    return true;
+  } catch (error) {
+    // If error checking, assume sync is needed
+    return true;
+  }
+}
+
+/**
+ * Record sync result for incremental sync
+ *
+ * @param {string} usFilePath - Path to US file
+ * @param {Array} tasks - Tasks that were synced
+ */
+export function recordSync(usFilePath, tasks) {
+  const cacheKey = `sync-result:${usFilePath}`;
+  const taskIds = tasks.map(t => t.id).sort().join(',');
+
+  globalCache.set(cacheKey, {
+    taskIds,
+    timestamp: Date.now()
+  });
+}
+
+/**
+ * Get cache statistics
+ *
+ * @returns {object} Cache stats
+ */
+export function getCacheStats() {
+  return {
+    size: globalCache.size(),
+    entries: Array.from(globalCache.cache.keys())
+  };
+}
+
+/**
+ * Clear cache (for testing)
+ */
+export function clearCache() {
+  globalCache.clear();
+}
+
+export default globalCache;

package/plugins/specweave/lib/hooks/sync-living-docs.d.js.bak

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/plugins/specweave/lib/hooks/sync-living-docs.d.ts.bak

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+/**
+ * SpecWeave Living Docs Auto-Sync
+ *
+ * Automatically syncs living documentation after task completion.
+ *
+ * Usage:
+ *   node dist/hooks/lib/sync-living-docs.js <incrementId>
+ *
+ * Example:
+ *   node dist/hooks/lib/sync-living-docs.js 0006-llm-native-i18n
+ *
+ * What it does:
+ * 1. Checks if sync_living_docs enabled in config
+ * 2. Detects changed docs via git diff
+ * 3. Invokes /sync-docs update command (future implementation)
+ * 4. Logs sync actions
+ *
+ * @author SpecWeave Team
+ * @version 1.0.0
+ */
+/**
+ * Main function - sync living docs for given increment
+ */
+declare function syncLivingDocs(incrementId: string): Promise<void>;
+export { syncLivingDocs };
+//# sourceMappingURL=sync-living-docs.d.ts.map