specweave 0.13.6 → 0.15.0

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

@@ -1,132 +1,203 @@
-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";
+/**
+ * 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 { 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) {
-  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;
+    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;
 }
-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;
+/**
+ * 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, promptTokens, responseTokens = 2000) {
+    // 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 / 1000000) * modelPricing.input;
+    const outputCost = (responseTokens / 1000000) * 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, 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."
-  );
+    // 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.');
 }
-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
+/**
+ * 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) {
+    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) {
+                // 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
+        };
     }
-    if (config.storeReflections) {
-      try {
-        saveReflection(reflectionResult, incrementId, taskId);
-      } catch (storageError) {
-        console.warn(`Failed to store reflection: ${storageError.message}`);
-      }
+    catch (error) {
+        // 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, taskId, projectRoot) {
+    // Load and validate configuration
+    const config = loadAndValidateReflectionConfig(projectRoot);
+    // Get modified files from git
+    const modifiedFiles = getModifiedFiles(projectRoot);
     return {
-      success: true,
-      result: reflectionResult
-    };
-  } catch (error) {
-    return {
-      success: false,
-      error: {
-        message: error.message || "Unknown error during reflection",
-        code: "REFLECTION_ERROR",
-        details: error.stack
-      }
+        incrementId,
+        taskId,
+        modifiedFiles,
+        config
     };
-  }
-}
-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);
+/**
+ * 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, taskId, projectRoot) {
+    const context = createReflectionContext(incrementId, taskId, projectRoot);
+    return runSelfReflection(context);
 }
-export {
-  createReflectionContext,
-  runReflectionAuto,
-  runSelfReflection
-};
+//# sourceMappingURL=run-self-reflection.js.map

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

@@ -1,102 +1,144 @@
 #!/usr/bin/env node
-import fs from "fs-extra";
-import path from "path";
-import { execSync } from "child_process";
+/**
+ * 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
+ */
+import fs from 'fs-extra';
+import path from 'path';
+import { execSync } from 'child_process';
+/**
+ * Main function - sync living docs for given increment
+ */
 async function syncLivingDocs(incrementId) {
-  try {
-    console.log(`
-\u{1F4DA} Checking living docs sync for increment: ${incrementId}`);
-    const configPath = path.join(process.cwd(), ".specweave", "config.json");
-    let config = {};
-    if (fs.existsSync(configPath)) {
-      config = JSON.parse(await fs.readFile(configPath, "utf-8"));
+    try {
+        console.log(`\n📚 Checking living docs sync for increment: ${incrementId}`);
+        // 1. Load config
+        const configPath = path.join(process.cwd(), '.specweave', 'config.json');
+        let config = {};
+        if (fs.existsSync(configPath)) {
+            config = JSON.parse(await fs.readFile(configPath, 'utf-8'));
+        }
+        // 2. Check if sync enabled
+        const syncEnabled = config.hooks?.post_task_completion?.sync_living_docs ?? false;
+        if (!syncEnabled) {
+            console.log('ℹ️  Living docs sync disabled in config');
+            console.log('   To enable: Set hooks.post_task_completion.sync_living_docs = true');
+            return;
+        }
+        console.log('✅ Living docs sync enabled');
+        // 3. Detect changed docs via git diff
+        const changedDocs = detectChangedDocs();
+        if (changedDocs.length === 0) {
+            console.log('ℹ️  No living docs changed (no git diff in .specweave/docs/)');
+            return;
+        }
+        console.log(`📄 Detected ${changedDocs.length} changed doc(s):`);
+        changedDocs.forEach((doc) => console.log(`   - ${doc}`));
+        // 4. Sync to GitHub if configured
+        await syncToGitHub(incrementId, changedDocs);
+        console.log('✅ Living docs sync complete\n');
     }
-    const syncEnabled = config.hooks?.post_task_completion?.sync_living_docs ?? false;
-    if (!syncEnabled) {
-      console.log("\u2139\uFE0F  Living docs sync disabled in config");
-      console.log("   To enable: Set hooks.post_task_completion.sync_living_docs = true");
-      return;
+    catch (error) {
+        console.error('❌ Error syncing living docs:', error);
+        // Don't exit with error - this is best-effort
     }
-    console.log("\u2705 Living docs sync enabled");
-    const changedDocs = detectChangedDocs();
-    if (changedDocs.length === 0) {
-      console.log("\u2139\uFE0F  No living docs changed (no git diff in .specweave/docs/)");
-      return;
-    }
-    console.log(`\u{1F4C4} Detected ${changedDocs.length} changed doc(s):`);
-    changedDocs.forEach((doc) => console.log(`   - ${doc}`));
-    await syncToGitHub(incrementId, changedDocs);
-    console.log("\u2705 Living docs sync complete\n");
-  } catch (error) {
-    console.error("\u274C Error syncing living docs:", error);
-  }
 }
+/**
+ * Detect changed documentation files via git diff
+ */
 function detectChangedDocs() {
-  try {
-    const output = execSync("git diff --name-only .specweave/docs/ 2>/dev/null || true", {
-      encoding: "utf-8",
-      cwd: process.cwd()
-    }).trim();
-    if (!output) {
-      return [];
+    try {
+        // Get changed files in .specweave/docs/
+        const output = execSync('git diff --name-only .specweave/docs/ 2>/dev/null || true', {
+            encoding: 'utf-8',
+            cwd: process.cwd(),
+        }).trim();
+        if (!output) {
+            return [];
+        }
+        // Filter to only .md files
+        const files = output
+            .split('\n')
+            .filter((f) => f.endsWith('.md'))
+            .filter((f) => f.length > 0);
+        return files;
+    }
+    catch (error) {
+        console.warn('⚠️  Could not detect git changes:', error);
+        return [];
     }
-    const files = output.split("\n").filter((f) => f.endsWith(".md")).filter((f) => f.length > 0);
-    return files;
-  } catch (error) {
-    console.warn("\u26A0\uFE0F  Could not detect git changes:", error);
-    return [];
-  }
 }
+/**
+ * Sync changed docs to GitHub
+ */
 async function syncToGitHub(incrementId, changedDocs) {
-  try {
-    console.log("\n\u{1F504} Syncing to GitHub...");
-    const {
-      loadIncrementMetadata,
-      detectRepo,
-      collectLivingDocs,
-      updateIssueLivingDocs,
-      postArchitectureComment
-    } = await import("../../../specweave-github/lib/github-issue-updater.js");
-    const metadata = await loadIncrementMetadata(incrementId);
-    if (!metadata?.github?.issue) {
-      console.log("\u2139\uFE0F  No GitHub issue linked, skipping GitHub sync");
-      return;
-    }
-    const repoInfo = await detectRepo();
-    if (!repoInfo) {
-      console.log("\u26A0\uFE0F  Could not detect GitHub repository, skipping GitHub sync");
-      return;
+    try {
+        console.log('\n🔄 Syncing to GitHub...');
+        // Dynamic import to avoid circular dependencies
+        const { loadIncrementMetadata, detectRepo, collectLivingDocs, updateIssueLivingDocs, postArchitectureComment } = await import('../../../specweave-github/lib/github-issue-updater.js');
+        // 1. Load metadata
+        const metadata = await loadIncrementMetadata(incrementId);
+        if (!metadata?.github?.issue) {
+            console.log('ℹ️  No GitHub issue linked, skipping GitHub sync');
+            return;
+        }
+        // 2. Detect repository
+        const repoInfo = await detectRepo();
+        if (!repoInfo) {
+            console.log('⚠️  Could not detect GitHub repository, skipping GitHub sync');
+            return;
+        }
+        const { owner, repo } = repoInfo;
+        const issueNumber = metadata.github.issue;
+        console.log(`   Syncing to ${owner}/${repo}#${issueNumber}`);
+        // 3. Collect all living docs
+        const livingDocs = await collectLivingDocs(incrementId);
+        // 4. Update issue with living docs section
+        if (livingDocs.specs.length > 0 || livingDocs.architecture.length > 0 || livingDocs.diagrams.length > 0) {
+            await updateIssueLivingDocs(issueNumber, livingDocs, owner, repo);
+        }
+        // 5. Post comments for newly created architecture docs
+        for (const docPath of changedDocs) {
+            if (docPath.includes('/architecture/')) {
+                await postArchitectureComment(issueNumber, docPath, owner, repo);
+            }
+        }
+        console.log('✅ GitHub sync complete');
     }
-    const { owner, repo } = repoInfo;
-    const issueNumber = metadata.github.issue;
-    console.log(`   Syncing to ${owner}/${repo}#${issueNumber}`);
-    const livingDocs = await collectLivingDocs(incrementId);
-    if (livingDocs.specs.length > 0 || livingDocs.architecture.length > 0 || livingDocs.diagrams.length > 0) {
-      await updateIssueLivingDocs(issueNumber, livingDocs, owner, repo);
+    catch (error) {
+        console.error('❌ Error syncing to GitHub:', error);
+        console.error('   (Non-blocking - continuing...)');
     }
-    for (const docPath of changedDocs) {
-      if (docPath.includes("/architecture/")) {
-        await postArchitectureComment(issueNumber, docPath, owner, repo);
-      }
-    }
-    console.log("\u2705 GitHub sync complete");
-  } catch (error) {
-    console.error("\u274C Error syncing to GitHub:", error);
-    console.error("   (Non-blocking - continuing...)");
-  }
 }
+// CLI entry point
 const isMainModule = import.meta.url === `file://${process.argv[1]}`;
 if (isMainModule) {
-  const incrementId = process.argv[2];
-  if (!incrementId) {
-    console.error("\u274C Usage: sync-living-docs <incrementId>");
-    console.error("   Example: sync-living-docs 0006-llm-native-i18n");
-    process.exit(1);
-  }
-  syncLivingDocs(incrementId).catch((error) => {
-    console.error("\u274C Fatal error:", error);
-  });
+    const incrementId = process.argv[2];
+    if (!incrementId) {
+        console.error('❌ Usage: sync-living-docs <incrementId>');
+        console.error('   Example: sync-living-docs 0006-llm-native-i18n');
+        process.exit(1);
+    }
+    syncLivingDocs(incrementId).catch((error) => {
+        console.error('❌ Fatal error:', error);
+        // Don't exit with error code - best-effort sync
+    });
 }
-export {
-  syncLivingDocs
-};
+export { syncLivingDocs };
+//# sourceMappingURL=sync-living-docs.js.map