ai-sdlc 0.2.0 → 0.3.0-alpha.1

package/dist/agents/review.js

@@ -2,10 +2,12 @@ import { execSync, spawn, spawnSync } from 'child_process';
 import path from 'path';
 import fs from 'fs';
 import { z } from 'zod';
+import { ProcessManager } from '../core/process-manager.js';
 import { parseStory, updateStoryStatus, appendToSection, updateStoryField, isAtMaxRetries, appendReviewHistory, snapshotMaxRetries, getEffectiveMaxRetries, getEffectiveMaxImplementationRetries } from '../core/story.js';
 import { runAgentQuery } from '../core/client.js';
 import { getLogger } from '../core/logger.js';
 import { loadConfig, DEFAULT_TIMEOUTS } from '../core/config.js';
+import { extractStructuredResponseSync } from '../core/llm-utils.js';
 import { ReviewDecision, ReviewSeverity } from '../types/index.js';
 import { sanitizeInput, truncateText } from '../cli/formatting.js';
 import { detectTestDuplicationPatterns } from './test-pattern-detector.js';
@@ -172,6 +174,7 @@ async function runCommandAsync(command, workingDir, timeout, onProgress) {
             cwd: workingDir,
             stdio: ['pipe', 'pipe', 'pipe'],
         });
+        ProcessManager.getInstance().registerChild(child);
         const timeoutId = setTimeout(() => {
             killed = true;
             child.kill('SIGTERM');
@@ -252,7 +255,7 @@ Output your review as a JSON object with this structure:
   "issues": [
     {
       "severity": "blocker" | "critical" | "major" | "minor",
-      "category": "code_quality" | "security" | "requirements" | "testing" | etc,
+      "category": "code_quality" | "security" | "requirements" | "testing" | "test_alignment" | etc,
       "description": "Detailed description of the issue",
       "file": "path/to/file.ts" (if applicable),
       "line": 42 (if applicable),
@@ -263,7 +266,7 @@ Output your review as a JSON object with this structure:
 }
 
 Severity guidelines:
-- blocker: Must be fixed before merging (security holes, broken functionality)
+- blocker: Must be fixed before merging (security holes, broken functionality, test misalignment)
 - critical: Should be fixed before merging (major bugs, poor practices)
 - major: Should be addressed soon (code quality, maintainability)
 - minor: Nice to have improvements (style, optimizations)
@@ -304,6 +307,56 @@ Evaluate:
 - Is documentation adequate for users and maintainers?
 - Does the implementation align with the story goals?
 
+## Test-Implementation Alignment (BLOCKER category)
+
+**CRITICAL PRE-REVIEW REQUIREMENT**: Tests have already been executed and passed. However, passing tests don't guarantee correctness if they verify outdated behavior.
+
+During code review, you MUST verify test alignment:
+
+1. **For each changed production file, identify its test file**
+   - Check if tests exist for modified functions/modules
+   - Read the test assertions carefully
+
+2. **Verify tests match NEW behavior, not OLD**
+   - Do test assertions expect the current implementation behavior?
+   - If production code changed from sync to async, do tests use await?
+   - If function signature changed, do tests call it correctly?
+   - If return values changed, do tests expect the new values?
+
+3. **Flag misalignment as BLOCKER**
+   - If tests reference changed code but still expect old behavior:
+     - This is a **BLOCKER** severity issue
+     - Category MUST be: \`"test_alignment"\`
+     - Specify which test files need updating and why
+     - Provide example of correct assertion for new behavior
+
+**Example of misaligned test (BLOCKER):**
+\`\`\`typescript
+// Production code changed from sync to async
+async function loadConfig(): Promise<Config> {
+  return await fetchConfig();
+}
+
+// Test still expects sync behavior - MISSING await (BLOCKER)
+test('loads config', () => {
+  const config = loadConfig(); // ❌ Missing await! Returns Promise<Config>, not Config
+  expect(config.port).toBe(3000); // ❌ Checking Promise.port, not config.port
+});
+
+// Correct aligned test:
+test('loads config', async () => {
+  const config = await loadConfig(); // ✅ Awaits async function
+  expect(config.port).toBe(3000);     // ✅ Checks actual config
+});
+\`\`\`
+
+**When to flag test_alignment issues:**
+- Tests verify old function signatures that no longer exist
+- Tests expect old return value formats that changed
+- Tests miss new error conditions introduced
+- Tests pass but don't exercise the new code paths
+- Mock expectations don't match the new implementation calls
+
 ## CRITICAL DEDUPLICATION INSTRUCTIONS:
 
 1. **DO NOT repeat the same underlying issue from different perspectives**
@@ -363,26 +416,25 @@ const PO_REVIEW_PROMPT = `You are a product owner validating the implementation.
 ${REVIEW_OUTPUT_FORMAT}`;
 /**
  * Parse review response and extract structured issues
+ * Uses extractStructuredResponseSync for robust parsing with multiple strategies:
+ * 1. Direct JSON parse
+ * 2. JSON within markdown code blocks
+ * 3. JSON with leading/trailing text stripped
+ * 4. YAML format fallback
+ *
  * Security: Uses zod schema validation to prevent malicious JSON
  */
 function parseReviewResponse(response, reviewType) {
-    try {
-        // Try to extract JSON from the response
-        const jsonMatch = response.match(/\{[\s\S]*\}/);
-        if (!jsonMatch) {
-            // Fallback: no JSON found, analyze text
-            return parseTextReview(response, reviewType);
-        }
-        const parsed = JSON.parse(jsonMatch[0]);
-        // Security: Validate against zod schema before using the data
-        const validationResult = ReviewResponseSchema.safeParse(parsed);
-        if (!validationResult.success) {
-            // Log validation errors for debugging
-            console.warn('Review response failed schema validation:', validationResult.error);
-            // Fallback to text analysis
-            return parseTextReview(response, reviewType);
-        }
-        const validated = validationResult.data;
+    const logger = getLogger();
+    // Use the robust extraction utility with all strategies
+    const extractionResult = extractStructuredResponseSync(response, ReviewResponseSchema, false);
+    if (extractionResult.success && extractionResult.data) {
+        const validated = extractionResult.data;
+        logger.debug('review', `Successfully parsed review response using strategy: ${extractionResult.strategy}`, {
+            reviewType,
+            strategy: extractionResult.strategy,
+            issueCount: validated.issues.length,
+        });
         // Map validated data to ReviewIssue format (additional sanitization)
         const issues = validated.issues.map((issue) => ({
             severity: issue.severity,
@@ -398,11 +450,13 @@ function parseReviewResponse(response, reviewType) {
             issues,
         };
     }
-    catch (error) {
-        // Fallback to text analysis if JSON parsing fails
-        console.warn('Review response parsing error:', error);
-        return parseTextReview(response, reviewType);
-    }
+    // All extraction strategies failed - log raw response for debugging and use text fallback
+    logger.warn('review', 'All extraction strategies failed for review response', {
+        reviewType,
+        error: extractionResult.error,
+        responsePreview: response.substring(0, 200),
+    });
+    return parseTextReview(response, reviewType);
 }
 /**
  * Fallback: Parse text-based review response (for when LLM doesn't return JSON)
@@ -572,6 +626,170 @@ export function getSourceCodeChanges(workingDir) {
         return ['unknown'];
     }
 }
+/**
+ * Get configuration file changes from git diff
+ *
+ * Detects changes to configuration files including:
+ * - .claude/ directory (Agent SDK skills, CLAUDE.md)
+ * - .github/ directory (workflows, actions, issue templates)
+ * - Root config files (tsconfig.json, package.json, .gitignore, vitest.config.ts, etc.)
+ *
+ * Uses spawnSync for security (prevents command injection).
+ *
+ * @param workingDir - Working directory to run git diff in
+ * @returns Array of configuration file paths that have changed, or ['unknown'] if git fails
+ */
+export function getConfigurationChanges(workingDir) {
+    try {
+        // Security: Use spawnSync with explicit args (not shell) to prevent injection
+        const result = spawnSync('git', ['diff', '--name-only', 'HEAD~1'], {
+            cwd: workingDir,
+            encoding: 'utf-8',
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        if (result.status !== 0) {
+            // Git command failed - fail open (assume changes exist)
+            return ['unknown'];
+        }
+        const output = result.stdout.toString();
+        return output
+            .split('\n')
+            .filter(f => f.trim())
+            .filter(f => {
+            // Configuration directories
+            if (f.startsWith('.claude/'))
+                return true;
+            if (f.startsWith('.github/'))
+                return true;
+            // Root configuration files (common patterns)
+            const rootConfigs = [
+                'tsconfig.json',
+                'package.json',
+                'package-lock.json',
+                '.gitignore',
+                '.gitattributes',
+                'vitest.config.ts',
+                'vitest.config.js',
+                'jest.config.js',
+                'jest.config.ts',
+                '.eslintrc',
+                '.eslintrc.js',
+                '.eslintrc.json',
+                '.prettierrc',
+                '.prettierrc.js',
+                '.prettierrc.json',
+                'Makefile',
+                'Dockerfile',
+                'docker-compose.yml',
+                '.env.example',
+            ];
+            return rootConfigs.includes(f);
+        });
+    }
+    catch {
+        // If git diff fails, assume there are changes (fail open, not closed)
+        return ['unknown'];
+    }
+}
+/**
+ * Get documentation file changes from git diff
+ *
+ * Detects changes to documentation files including:
+ * - Markdown files (.md) anywhere in the project (excluding story files)
+ * - docs/ directory (any file type)
+ *
+ * Uses spawnSync for security (prevents command injection).
+ *
+ * @param workingDir - Working directory to run git diff in
+ * @returns Array of documentation file paths that have changed, or ['unknown'] if git fails
+ */
+export function getDocumentationChanges(workingDir) {
+    try {
+        // Security: Use spawnSync with explicit args (not shell) to prevent injection
+        const result = spawnSync('git', ['diff', '--name-only', 'HEAD~1'], {
+            cwd: workingDir,
+            encoding: 'utf-8',
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        if (result.status !== 0) {
+            // Git command failed - fail open (assume changes exist)
+            return ['unknown'];
+        }
+        const output = result.stdout.toString();
+        return output
+            .split('\n')
+            .filter(f => f.trim())
+            .filter(f => {
+            // Markdown files (excluding story files in .ai-sdlc/stories/)
+            if (f.endsWith('.md') && !f.startsWith('.ai-sdlc/stories/'))
+                return true;
+            // Files in docs/ directory (any file type - images, diagrams, etc.)
+            if (f.startsWith('docs/'))
+                return true;
+            return false;
+        });
+    }
+    catch {
+        // If git diff fails, assume there are changes (fail open, not closed)
+        return ['unknown'];
+    }
+}
+/**
+ * Determine the effective content type for validation
+ *
+ * Resolves the final content type based on story frontmatter fields:
+ * 1. If requires_source_changes === false, treat as 'configuration'
+ * 2. If requires_source_changes === true, treat as 'code'
+ * 3. Otherwise, use content_type field (default: 'code' for backward compatibility)
+ *
+ * @param story - Story with frontmatter to analyze
+ * @returns The effective content type to use for validation
+ */
+export function determineEffectiveContentType(story) {
+    const frontmatter = story.frontmatter;
+    // Manual override takes precedence
+    if (frontmatter.requires_source_changes === false) {
+        return 'configuration';
+    }
+    if (frontmatter.requires_source_changes === true) {
+        return 'code';
+    }
+    // Use explicit content_type or default to 'code'
+    return frontmatter.content_type || 'code';
+}
+/**
+ * Check if test files exist in git diff
+ *
+ * Returns true if any test files have been modified/added, false otherwise.
+ * Uses spawnSync for security (prevents command injection).
+ *
+ * @param workingDir - Working directory to run git diff in
+ * @returns True if test files exist in changes, false otherwise
+ */
+export function hasTestFiles(workingDir) {
+    try {
+        // Security: Use spawnSync with explicit args (not shell) to prevent injection
+        const result = spawnSync('git', ['diff', '--name-only', 'HEAD~1'], {
+            cwd: workingDir,
+            encoding: 'utf-8',
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        if (result.status !== 0) {
+            // Git command failed - fail open (assume tests exist to avoid false blocks)
+            return true;
+        }
+        const output = result.stdout.toString();
+        const files = output.split('\n').filter(f => f.trim());
+        // Check if any files match test patterns
+        return files.some(f => f.includes('.test.') ||
+            f.includes('.spec.') ||
+            f.includes('__tests__/'));
+    }
+    catch {
+        // If git diff fails, assume tests exist (fail open, not closed)
+        return true;
+    }
+}
 /**
  * Generate executive summary from review issues (1-3 sentences)
  *
@@ -728,67 +946,194 @@ export async function runReviewAgent(storyPath, sdlcRoot, options) {
                 feedback: errorMsg,
             };
         }
-        // PRE-CHECK GATE: Detect documentation-only implementations before running expensive LLM reviews
-        const sourceChanges = getSourceCodeChanges(workingDir);
-        if (sourceChanges.length === 0) {
-            // No source code changes detected - check if we can recover
+        // PRE-CHECK GATE: Content type-aware validation before running expensive LLM reviews
+        const contentType = determineEffectiveContentType(story);
+        logger.info('review', 'Running content-type-specific validation', {
+            storyId: story.frontmatter.id,
+            contentType,
+            explicitContentType: story.frontmatter.content_type,
+            requiresSourceChanges: story.frontmatter.requires_source_changes,
+        });
+        // Validation flags
+        let validationFailed = false;
+        let validationReason = '';
+        let validationCategory = 'implementation';
+        // Check source code changes for 'code' and 'mixed' types
+        if (contentType === 'code' || contentType === 'mixed') {
+            const sourceChanges = getSourceCodeChanges(workingDir);
+            if (sourceChanges.length === 0) {
+                validationFailed = true;
+                validationReason = contentType === 'mixed'
+                    ? 'Mixed story requires both source AND configuration changes - no source code was modified.'
+                    : 'Implementation wrote documentation/planning only - no source code was modified.';
+                logger.warn('review', 'Source code validation failed', {
+                    storyId: story.frontmatter.id,
+                    contentType,
+                    sourceChangesFound: sourceChanges.length,
+                });
+            }
+            else {
+                logger.info('review', 'Source code changes detected', {
+                    storyId: story.frontmatter.id,
+                    fileCount: sourceChanges.length,
+                });
+            }
+        }
+        // Check configuration changes for 'configuration' and 'mixed' types
+        if (!validationFailed && (contentType === 'configuration' || contentType === 'mixed')) {
+            const configChanges = getConfigurationChanges(workingDir);
+            if (configChanges.length === 0) {
+                validationFailed = true;
+                validationReason = contentType === 'mixed'
+                    ? 'Mixed story requires both source AND configuration changes. No configuration file changes detected.'
+                    : 'Configuration story requires changes to config files (.claude/, .github/, or root config files). No configuration changes detected.';
+                logger.warn('review', 'Configuration validation failed', {
+                    storyId: story.frontmatter.id,
+                    contentType,
+                    configChangesFound: configChanges.length,
+                });
+            }
+            else {
+                logger.info('review', 'Configuration changes detected', {
+                    storyId: story.frontmatter.id,
+                    fileCount: configChanges.length,
+                });
+            }
+        }
+        // Check documentation changes for 'documentation' type
+        if (!validationFailed && contentType === 'documentation') {
+            const docChanges = getDocumentationChanges(workingDir);
+            if (docChanges.length === 0) {
+                validationFailed = true;
+                validationReason = 'Documentation story requires changes to markdown files (.md) or docs/ directory. No documentation changes detected.';
+                logger.warn('review', 'Documentation validation failed', {
+                    storyId: story.frontmatter.id,
+                    contentType,
+                    docChangesFound: docChanges.length,
+                });
+            }
+            else {
+                logger.info('review', 'Documentation changes detected', {
+                    storyId: story.frontmatter.id,
+                    fileCount: docChanges.length,
+                });
+            }
+        }
+        // Handle validation failure (if any)
+        if (validationFailed) {
             const retryCount = story.frontmatter.implementation_retry_count || 0;
             const maxRetries = getEffectiveMaxImplementationRetries(story, config);
             if (retryCount < maxRetries) {
                 // RECOVERABLE: Trigger implementation recovery
-                logger.warn('review', 'No source code changes detected - triggering implementation recovery', {
+                logger.warn('review', 'Validation failed - triggering implementation recovery', {
                     storyId: story.frontmatter.id,
                     retryCount,
                     maxRetries,
+                    contentType,
                 });
                 await updateStoryField(story, 'implementation_complete', false);
-                await updateStoryField(story, 'last_restart_reason', 'No source code changes detected. Implementation wrote documentation only.');
+                // Set restart reason based on content type
+                const restartReason = contentType === 'configuration'
+                    ? 'Configuration story requires changes to config files (.claude/, .github/, or root config files). No configuration changes detected.'
+                    : contentType === 'mixed'
+                        ? 'Mixed story requires both source AND configuration changes - no source code was modified.'
+                        : contentType === 'documentation'
+                            ? 'Documentation story requires changes to markdown files (.md) or docs/ directory. No documentation changes detected.'
+                            : 'No source code changes detected. Implementation wrote documentation only.';
+                await updateStoryField(story, 'last_restart_reason', restartReason);
+                // Create user-friendly recovery description
+                const recoveryDescription = contentType === 'configuration'
+                    ? 'No configuration file modifications detected. Re-running implementation phase.'
+                    : contentType === 'mixed'
+                        ? 'No source code modifications detected. Re-running implementation phase.'
+                        : contentType === 'documentation'
+                            ? 'No documentation file modifications detected. Re-running implementation phase.'
+                            : 'No source code modifications detected. Re-running implementation phase.';
                 return {
                     success: true,
                     story: parseStory(storyPath),
-                    changesMade: ['Detected documentation-only implementation', 'Triggered implementation recovery'],
+                    changesMade: ['Detected incomplete implementation', 'Triggered implementation recovery'],
                     passed: false,
                     decision: ReviewDecision.RECOVERY,
                     reviewType: 'pre-check',
                     issues: [{
                             severity: 'critical',
-                            category: 'implementation',
-                            description: 'No source code modifications detected. Re-running implementation phase.',
+                            category: validationCategory,
+                            description: recoveryDescription,
                         }],
-                    feedback: 'Implementation recovery triggered - no source changes found.',
+                    feedback: `Implementation recovery triggered - ${validationReason}`,
                 };
             }
             else {
                 // NON-RECOVERABLE: Max retries reached
                 const maxRetriesDisplay = Number.isFinite(maxRetries) ? maxRetries : '∞';
-                logger.error('review', 'No source code changes detected and max implementation retries reached', {
+                logger.error('review', 'Validation failed and max implementation retries reached', {
                     storyId: story.frontmatter.id,
                     retryCount,
                     maxRetries,
+                    contentType,
                 });
                 return {
                     success: true,
                     story: parseStory(storyPath),
-                    changesMade: ['Detected documentation-only implementation', 'Max retries reached'],
+                    changesMade: ['Detected incomplete implementation', 'Max retries reached'],
                     passed: false,
                     decision: ReviewDecision.FAILED,
                     severity: ReviewSeverity.CRITICAL,
                     reviewType: 'pre-check',
                     issues: [{
                             severity: 'blocker',
-                            category: 'implementation',
-                            description: `Implementation phase wrote documentation/planning only - no source code was modified. This has occurred ${retryCount} time(s) (max: ${maxRetriesDisplay}). Manual intervention required.`,
-                            suggestedFix: 'Review the story requirements and implementation plan. The agent may be confused about what needs to be built. Consider simplifying the story or providing more explicit guidance.',
+                            category: validationCategory,
+                            description: `${validationReason} This has occurred ${retryCount} time(s) (max: ${maxRetriesDisplay}). Manual intervention required.`,
+                            suggestedFix: 'Review the story requirements and implementation plan. Verify the content_type field matches the expected implementation. Consider simplifying the story or providing more explicit guidance.',
                         }],
-                    feedback: 'Implementation failed to produce code changes after multiple attempts.',
+                    feedback: 'Implementation failed validation after multiple attempts.',
                 };
             }
         }
-        // Source changes exist - proceed with normal review flow
-        logger.info('review', 'Source code changes detected - proceeding with verification', {
+        // Validation passed - proceed with normal review flow
+        logger.info('review', 'Content validation passed - proceeding with verification', {
             storyId: story.frontmatter.id,
-            fileCount: sourceChanges.length,
+            contentType,
         });
+        // PRE-CHECK GATE: Check if test files exist (only for code/mixed types)
+        // Documentation and configuration stories don't require test files
+        const requiresTests = contentType === 'code' || contentType === 'mixed';
+        if (requiresTests) {
+            const testsExist = hasTestFiles(workingDir);
+            if (!testsExist) {
+                logger.warn('review', 'No test files detected in implementation changes', {
+                    storyId: story.frontmatter.id,
+                });
+                return {
+                    success: true,
+                    story: parseStory(storyPath),
+                    changesMade: ['No test files found for implementation'],
+                    passed: false,
+                    decision: ReviewDecision.REJECTED,
+                    severity: ReviewSeverity.CRITICAL,
+                    reviewType: 'pre-check',
+                    issues: [{
+                            severity: 'blocker',
+                            category: 'testing',
+                            description: 'No tests found for this implementation. All implementations must include tests.',
+                            suggestedFix: 'Add test files (*.test.ts, *.spec.ts, or files in __tests__/ directory) that verify the implementation.',
+                        }],
+                    feedback: formatIssuesForDisplay([{
+                            severity: 'blocker',
+                            category: 'testing',
+                            description: 'No tests found for this implementation. All implementations must include tests.',
+                            suggestedFix: 'Add test files (*.test.ts, *.spec.ts, or files in __tests__/ directory) that verify the implementation.',
+                        }]),
+                };
+            }
+        }
+        else {
+            logger.info('review', 'Test file check skipped for non-code content type', {
+                storyId: story.frontmatter.id,
+                contentType,
+            });
+        }
         // Run build and tests BEFORE reviews (async with progress)
         changesMade.push('Running build and test verification...');
         const verification = await runVerificationAsync(workingDir, config, options?.onVerificationProgress);
@@ -835,7 +1180,7 @@ export async function runReviewAgent(storyPath, sdlcRoot, options) {
                     severity: 'blocker',
                     category: 'testing',
                     description: `Tests must pass before code review can proceed.\n\nCommand: ${config.testCommand}\n\nTest output:\n\`\`\`\n${testOutput}${truncationNote}\n\`\`\``,
-                    suggestedFix: 'Fix failing tests before review can proceed.',
+                    suggestedFix: 'Fix failing tests before review can proceed. If tests are failing after implementation changes, verify that tests were updated to match the new behavior (not just the old behavior).',
                 });
                 verificationContext += `\n## Test Results ❌\nTest command \`${config.testCommand}\` FAILED:\n\`\`\`\n${testOutput}${truncationNote}\n\`\`\`\n`;
             }