ai-sdlc 0.2.0-alpha.6 → 0.2.0-alpha.61

package/dist/agents/review.js

@@ -1,12 +1,16 @@
-import { execSync, spawn } from 'child_process';
+import { execSync, spawn, spawnSync } from 'child_process';
 import path from 'path';
 import fs from 'fs';
 import { z } from 'zod';
-import { parseStory, updateStoryStatus, appendToSection, updateStoryField, isAtMaxRetries, appendReviewHistory, snapshotMaxRetries, getEffectiveMaxRetries } from '../core/story.js';
+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';
 /**
  * Security: Validate Git branch name to prevent command injection
  * Only allows alphanumeric characters, hyphens, underscores, and forward slashes
@@ -93,7 +97,9 @@ const ReviewIssueSchema = z.object({
     // This handles LLM responses that return {"line": null} instead of omitting the field
     file: z.string().nullish().transform(v => v ?? undefined),
     line: z.number().int().positive().nullish().transform(v => v ?? undefined),
-    suggestedFix: z.string().max(2000).nullish().transform(v => v ?? undefined),
+    suggestedFix: z.string().max(5000).nullish().transform(v => v ?? undefined),
+    // Perspectives field for unified review (optional for backward compatibility)
+    perspectives: z.array(z.enum(['code', 'security', 'po'])).optional(),
 });
 const ReviewResponseSchema = z.object({
     passed: z.boolean(),
@@ -168,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');
@@ -248,23 +255,138 @@ 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),
-      "suggestedFix": "How to fix this issue"
+      "suggestedFix": "How to fix this issue",
+      "perspectives": ["code", "security", "po"] (which perspectives this issue relates to)
     }
   ]
 }
 
 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)
 
 If no issues found, return: {"passed": true, "issues": []}
 `;
+/**
+ * Unified Review Prompt - combines code, security, and product owner perspectives
+ * into a single collaborative review to eliminate duplicate issues.
+ */
+const UNIFIED_REVIEW_PROMPT = `You are a senior engineering team conducting a comprehensive collaborative review.
+
+You must evaluate the implementation from THREE perspectives simultaneously, but produce ONE unified set of issues:
+
+## Perspective 1: Code Quality (Senior Developer)
+Evaluate:
+- Code quality and maintainability
+- Following best practices and design patterns
+- Potential bugs or logic errors
+- Test coverage adequacy and test quality
+- Error handling completeness
+- Performance considerations
+
+## Perspective 2: Security (Security Engineer)
+Evaluate:
+- OWASP Top 10 vulnerabilities
+- Input validation and sanitization
+- Authentication and authorization issues
+- Data exposure risks
+- Command injection vulnerabilities
+- Secure coding practices
+
+## Perspective 3: Requirements (Product Owner)
+Evaluate:
+- Does it meet the acceptance criteria stated in the story?
+- Is the user experience appropriate and intuitive?
+- Are edge cases and error scenarios handled?
+- 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**
+   - If multiple perspectives notice the same problem, list it ONCE
+   - Use the \`perspectives\` array to indicate which perspectives it affects
+
+2. **Prioritize by actual impact, not by how many perspectives notice it**
+   - A issue seen by all 3 perspectives is still just ONE issue
+   - Focus on the distinct, actionable problems that need fixing
+
+3. **If the fundamental problem is "no implementation exists" or "functionality completely missing":**
+   - Report this as ONE blocker issue, not three separate issues
+   - Use perspectives: ["code", "security", "po"] to show all perspectives agree
+
+4. **Combine related issues into single, comprehensive descriptions:**
+   - Instead of: "No tests" (code) + "Untested security" (security) + "No validation tests" (po)
+   - Write: "No tests exist for the implementation" with perspectives: ["code", "security", "po"]
+
+5. **Each issue should have a clear, single suggested fix**
+   - Avoid vague suggestions like "improve everything"
+   - Be specific and actionable
+
+${REVIEW_OUTPUT_FORMAT}
+
+Remember: Your goal is to produce a clean, deduplicated list of actual distinct problems, not to maximize issue count.`;
+/**
+ * Legacy prompts - kept for reference only
+ * @deprecated These are replaced by UNIFIED_REVIEW_PROMPT which combines all three perspectives.
+ * The unified prompt reduces LLM calls from 3 to 1 and eliminates duplicate issues.
+ */
 const CODE_REVIEW_PROMPT = `You are a senior code reviewer. Review the implementation for:
 1. Code quality and maintainability
 2. Following best practices
@@ -272,6 +394,9 @@ const CODE_REVIEW_PROMPT = `You are a senior code reviewer. Review the implement
 4. Test coverage adequacy
 
 ${REVIEW_OUTPUT_FORMAT}`;
+/**
+ * @deprecated Use UNIFIED_REVIEW_PROMPT instead
+ */
 const SECURITY_REVIEW_PROMPT = `You are a security specialist. Review the implementation for:
 1. OWASP Top 10 vulnerabilities
 2. Input validation issues
@@ -279,6 +404,9 @@ const SECURITY_REVIEW_PROMPT = `You are a security specialist. Review the implem
 4. Data exposure risks
 
 ${REVIEW_OUTPUT_FORMAT}`;
+/**
+ * @deprecated Use UNIFIED_REVIEW_PROMPT instead
+ */
 const PO_REVIEW_PROMPT = `You are a product owner validating the implementation. Check:
 1. Does it meet the acceptance criteria?
 2. Is the user experience appropriate?
@@ -288,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,
@@ -316,17 +443,20 @@ function parseReviewResponse(response, reviewType) {
             file: issue.file,
             line: issue.line,
             suggestedFix: issue.suggestedFix,
+            perspectives: issue.perspectives,
         }));
         return {
             passed: validated.passed !== false && issues.filter(i => i.severity === 'blocker' || i.severity === 'critical').length === 0,
             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)
@@ -383,8 +513,35 @@ function determineReviewSeverity(issues) {
         return ReviewSeverity.LOW;
     }
 }
+/**
+ * Derive individual perspective pass/fail status from issues
+ *
+ * For backward compatibility with ReviewAttempt structure, determines whether
+ * each perspective (code, security, po) would pass based on issues flagged
+ * for that perspective.
+ *
+ * A perspective fails if it has any blocker or critical issues.
+ *
+ * @param issues - Array of review issues with perspectives field
+ * @returns Object with pass/fail status for each perspective
+ */
+export function deriveIndividualPassFailFromPerspectives(issues) {
+    // Check if any blocker/critical issues exist for each perspective
+    const codeIssues = issues.filter(i => i.perspectives?.includes('code') &&
+        (i.severity === 'blocker' || i.severity === 'critical'));
+    const securityIssues = issues.filter(i => i.perspectives?.includes('security') &&
+        (i.severity === 'blocker' || i.severity === 'critical'));
+    const poIssues = issues.filter(i => i.perspectives?.includes('po') &&
+        (i.severity === 'blocker' || i.severity === 'critical'));
+    return {
+        codeReviewPassed: codeIssues.length === 0,
+        securityReviewPassed: securityIssues.length === 0,
+        poReviewPassed: poIssues.length === 0,
+    };
+}
 /**
  * Aggregate issues from multiple reviews and determine overall pass/fail
+ * @deprecated No longer used with unified review. Kept for reference only.
  */
 function aggregateReviews(codeResult, securityResult, poResult) {
     const allIssues = [...codeResult.issues, ...securityResult.issues, ...poResult.issues];
@@ -399,6 +556,7 @@ function aggregateReviews(codeResult, securityResult, poResult) {
 }
 /**
  * Format issues for display in review notes
+ * Shows perspectives (code, security, po) when available
  */
 function formatIssuesForDisplay(issues) {
     if (issues.length === 0) {
@@ -417,7 +575,11 @@ function formatIssuesForDisplay(issues) {
         const icon = severity === 'blocker' ? '🛑' : severity === 'critical' ? '⚠️' : severity === 'major' ? '📋' : 'ℹ️';
         output += `\n#### ${icon} ${severity.toUpperCase()} (${issueList.length})\n\n`;
         for (const issue of issueList) {
-            output += `**${issue.category}**: ${issue.description}\n`;
+            // Format perspectives indicator if present
+            const perspectivesTag = issue.perspectives && issue.perspectives.length > 0
+                ? ` [${issue.perspectives.join(', ')}]`
+                : '';
+            output += `**${issue.category}**${perspectivesTag}: ${issue.description}\n`;
             if (issue.file) {
                 output += `  - File: \`${issue.file}\`${issue.line ? `:${issue.line}` : ''}\n`;
             }
@@ -429,6 +591,205 @@ function formatIssuesForDisplay(issues) {
     }
     return output;
 }
+/**
+ * Get source code changes from git diff
+ *
+ * Returns list of source files that have been modified (excludes tests and story files).
+ * Uses spawnSync for security (prevents command injection).
+ *
+ * @param workingDir - Working directory to run git diff in
+ * @returns Array of source file paths that have changed, or ['unknown'] if git fails
+ */
+export function getSourceCodeChanges(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 => /\.(ts|tsx|js|jsx)$/.test(f)) // Source files only
+            .filter(f => !f.includes('.test.')) // Exclude test files
+            .filter(f => !f.includes('.spec.')) // Exclude spec files
+            .filter(f => !f.startsWith('.ai-sdlc/')); // Exclude story files
+    }
+    catch {
+        // If git diff fails, assume there are changes (fail open, not closed)
+        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)
  *
@@ -526,9 +887,15 @@ export function generateReviewSummary(issues, terminalWidth) {
  * Now returns structured ReviewResult with pass/fail and issues.
  */
 export async function runReviewAgent(storyPath, sdlcRoot, options) {
+    const logger = getLogger();
+    const startTime = Date.now();
     const story = parseStory(storyPath);
     const changesMade = [];
     const workingDir = path.dirname(sdlcRoot);
+    logger.info('review', 'Starting review phase', {
+        storyId: story.frontmatter.id,
+        retryCount: story.frontmatter.retry_count || 0,
+    });
     // Security: Validate working directory before any operations
     try {
         validateWorkingDirectory(workingDir);
@@ -554,14 +921,14 @@ export async function runReviewAgent(storyPath, sdlcRoot, options) {
     const config = loadConfig(workingDir);
     try {
         // Snapshot max_retries from config (protects against mid-cycle config changes)
-        snapshotMaxRetries(story, config);
+        await snapshotMaxRetries(story, config);
         // Check if story has reached max retries
         if (isAtMaxRetries(story, config)) {
             const retryCount = story.frontmatter.retry_count || 0;
             const maxRetries = getEffectiveMaxRetries(story, config);
             const maxRetriesDisplay = Number.isFinite(maxRetries) ? maxRetries : '∞';
             const errorMsg = `Story has reached maximum retry limit (${retryCount}/${maxRetriesDisplay}). Manual intervention required.`;
-            updateStoryField(story, 'last_error', errorMsg);
+            await updateStoryField(story, 'last_error', errorMsg);
             changesMade.push(errorMsg);
             return {
                 success: false,
@@ -579,6 +946,194 @@ export async function runReviewAgent(storyPath, sdlcRoot, options) {
                 feedback: errorMsg,
             };
         }
+        // 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', 'Validation failed - triggering implementation recovery', {
+                    storyId: story.frontmatter.id,
+                    retryCount,
+                    maxRetries,
+                    contentType,
+                });
+                await updateStoryField(story, 'implementation_complete', false);
+                // 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 incomplete implementation', 'Triggered implementation recovery'],
+                    passed: false,
+                    decision: ReviewDecision.RECOVERY,
+                    reviewType: 'pre-check',
+                    issues: [{
+                            severity: 'critical',
+                            category: validationCategory,
+                            description: recoveryDescription,
+                        }],
+                    feedback: `Implementation recovery triggered - ${validationReason}`,
+                };
+            }
+            else {
+                // NON-RECOVERABLE: Max retries reached
+                const maxRetriesDisplay = Number.isFinite(maxRetries) ? maxRetries : '∞';
+                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 incomplete implementation', 'Max retries reached'],
+                    passed: false,
+                    decision: ReviewDecision.FAILED,
+                    severity: ReviewSeverity.CRITICAL,
+                    reviewType: 'pre-check',
+                    issues: [{
+                            severity: 'blocker',
+                            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 validation after multiple attempts.',
+                };
+            }
+        }
+        // Validation passed - proceed with normal review flow
+        logger.info('review', 'Content validation passed - proceeding with verification', {
+            storyId: story.frontmatter.id,
+            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);
@@ -625,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`;
             }
@@ -646,60 +1201,82 @@ export async function runReviewAgent(storyPath, sdlcRoot, options) {
                 feedback: formatIssuesForDisplay(verificationIssues),
             };
         }
-        // Verification passed - proceed with all reviews in parallel, passing verification context
-        changesMade.push('Verification passed - proceeding with code/security/PO reviews');
-        const [codeReview, securityReview, poReview] = await Promise.all([
-            runSubReview(story, CODE_REVIEW_PROMPT, 'Code Review', workingDir, verificationContext),
-            runSubReview(story, SECURITY_REVIEW_PROMPT, 'Security Review', workingDir, verificationContext),
-            runSubReview(story, PO_REVIEW_PROMPT, 'Product Owner Review', workingDir, verificationContext),
-        ]);
-        // Parse each review response into structured issues
-        const codeResult = parseReviewResponse(codeReview, 'Code Review');
-        const securityResult = parseReviewResponse(securityReview, 'Security Review');
-        const poResult = parseReviewResponse(poReview, 'Product Owner Review');
+        // Verification passed - proceed with unified collaborative review
+        changesMade.push('Verification passed - proceeding with unified collaborative review');
+        // Run test pattern detection if enabled
+        let testPatternIssues = [];
+        if (config.reviewConfig.detectTestAntipatterns !== false) {
+            try {
+                changesMade.push('Running test anti-pattern detection...');
+                testPatternIssues = await detectTestDuplicationPatterns(workingDir);
+                if (testPatternIssues.length > 0) {
+                    changesMade.push(`Detected ${testPatternIssues.length} test anti-pattern(s)`);
+                }
+                else {
+                    changesMade.push('No test anti-patterns detected');
+                }
+            }
+            catch (error) {
+                // Don't fail review if detection errors - just log and continue
+                const errorMsg = error instanceof Error ? error.message : String(error);
+                changesMade.push(`Test pattern detection error: ${errorMsg}`);
+            }
+        }
+        const unifiedReviewResponse = await runSubReview(story, UNIFIED_REVIEW_PROMPT, 'Unified Collaborative Review', workingDir, verificationContext);
+        // Parse unified review response into structured issues
+        const unifiedResult = parseReviewResponse(unifiedReviewResponse, 'Unified Review');
         // TDD Validation: Check TDD cycle completeness if TDD was enabled for this story
         const tddEnabled = story.frontmatter.tdd_enabled ?? config.tdd?.enabled ?? false;
         if (tddEnabled && story.frontmatter.tdd_test_history?.length) {
             const tddViolations = validateTDDCycles(story.frontmatter.tdd_test_history);
             if (tddViolations.length > 0) {
                 const tddIssues = generateTDDIssues(tddViolations);
-                codeResult.issues.push(...tddIssues);
-                codeResult.passed = false;
+                unifiedResult.issues.push(...tddIssues);
+                unifiedResult.passed = false;
                 changesMade.push(`TDD validation: ${tddViolations.length} violation(s) detected`);
             }
             else {
                 changesMade.push('TDD validation: All cycles completed correctly');
             }
         }
-        // Add verification issues to code result (they're code-quality related)
-        codeResult.issues.unshift(...verificationIssues);
+        // Add test pattern issues to unified result (they're code-quality related)
+        if (testPatternIssues.length > 0) {
+            unifiedResult.issues.push(...testPatternIssues);
+            unifiedResult.passed = false;
+        }
+        // Add verification issues to unified result (they're code-quality related)
+        unifiedResult.issues.unshift(...verificationIssues);
         if (verificationIssues.length > 0) {
-            codeResult.passed = false;
+            unifiedResult.passed = false;
         }
-        // Aggregate all issues and determine overall pass/fail
-        const { passed, allIssues, severity } = aggregateReviews(codeResult, securityResult, poResult);
-        // Compile review notes with structured format
+        // Determine overall pass/fail from unified review
+        const allIssues = unifiedResult.issues;
+        const blockerCount = allIssues.filter(i => i.severity === 'blocker').length;
+        const criticalCount = allIssues.filter(i => i.severity === 'critical').length;
+        const passed = blockerCount === 0 && criticalCount < 2;
+        const severity = determineReviewSeverity(allIssues);
+        // Derive individual perspective pass/fail for backward compatibility
+        const { codeReviewPassed, securityReviewPassed, poReviewPassed } = deriveIndividualPassFailFromPerspectives(allIssues);
+        // Compile review notes with structured format for unified review
         const reviewNotes = `
-### Code Review
-${formatIssuesForDisplay(codeResult.issues)}
+### Unified Collaborative Review
 
-### Security Review
-${formatIssuesForDisplay(securityResult.issues)}
+${formatIssuesForDisplay(allIssues)}
 
-### Product Owner Review
-${formatIssuesForDisplay(poResult.issues)}
+### Perspective Summary
+- Code Quality: ${codeReviewPassed ? '✅ Passed' : '❌ Failed'}
+- Security: ${securityReviewPassed ? '✅ Passed' : '❌ Failed'}
+- Requirements (PO): ${poReviewPassed ? '✅ Passed' : '❌ Failed'}
 
 ### Overall Result
 ${passed ? '✅ **PASSED** - All reviews approved' : '❌ **FAILED** - Issues must be addressed'}
 
 ---
-*Reviews completed: ${new Date().toISOString().split('T')[0]}*
+*Review completed: ${new Date().toISOString().split('T')[0]}*
 `;
         // Append reviews to story
-        appendToSection(story, 'Review Notes', reviewNotes);
-        changesMade.push('Added code review notes');
-        changesMade.push('Added security review notes');
-        changesMade.push('Added product owner review notes');
+        await appendToSection(story, 'Review Notes', reviewNotes);
+        changesMade.push('Added unified collaborative review notes');
         // Determine decision
         const decision = passed ? ReviewDecision.APPROVED : ReviewDecision.REJECTED;
         // Create review attempt record (omit undefined fields to avoid YAML serialization errors)
@@ -709,21 +1286,28 @@ ${passed ? '✅ **PASSED** - All reviews approved' : '❌ **FAILED** - Issues mu
             ...(passed ? {} : { severity }),
             feedback: passed ? 'All reviews passed' : formatIssuesForDisplay(allIssues),
             blockers: allIssues.filter(i => i.severity === 'blocker').map(i => i.description),
-            codeReviewPassed: codeResult.passed,
-            securityReviewPassed: securityResult.passed,
-            poReviewPassed: poResult.passed,
+            codeReviewPassed,
+            securityReviewPassed,
+            poReviewPassed,
         };
         // Append to review history
-        appendReviewHistory(story, reviewAttempt);
+        await appendReviewHistory(story, reviewAttempt);
         changesMade.push('Recorded review attempt in history');
         if (passed) {
-            updateStoryField(story, 'reviews_complete', true);
+            await updateStoryField(story, 'reviews_complete', true);
             changesMade.push('Marked reviews_complete: true');
         }
         else {
             changesMade.push(`Reviews failed with ${allIssues.length} issue(s) - rework required`);
             // Don't mark reviews_complete, this will trigger rework
         }
+        logger.info('review', 'Review phase complete', {
+            storyId: story.frontmatter.id,
+            durationMs: Date.now() - startTime,
+            passed,
+            decision,
+            issueCount: allIssues.length,
+        });
         return {
             success: true,
             story: parseStory(storyPath),
@@ -739,6 +1323,11 @@ ${passed ? '✅ **PASSED** - All reviews approved' : '❌ **FAILED** - Issues mu
     catch (error) {
         // Review agent failure - return FAILED decision (doesn't count as retry)
         const errorMsg = error instanceof Error ? error.message : String(error);
+        logger.error('review', 'Review phase failed', {
+            storyId: story.frontmatter.id,
+            durationMs: Date.now() - startTime,
+            error: errorMsg,
+        });
         return {
             success: false,
             story,
@@ -756,6 +1345,139 @@ ${passed ? '✅ **PASSED** - All reviews approved' : '❌ **FAILED** - Issues mu
         };
     }
 }
+/**
+ * Parse story content into sections by level-2 headers (##)
+ * Returns array of {title, content} objects
+ */
+export function parseContentSections(content) {
+    const sections = [];
+    const lines = content.split('\n');
+    let currentSection = null;
+    for (const line of lines) {
+        const headerMatch = line.match(/^##\s+(.+)$/);
+        if (headerMatch) {
+            if (currentSection)
+                sections.push(currentSection);
+            currentSection = { title: headerMatch[1], content: '' };
+        }
+        else if (currentSection) {
+            currentSection.content += line + '\n';
+        }
+    }
+    if (currentSection)
+        sections.push(currentSection);
+    return sections;
+}
+/**
+ * Remove unfinished checkboxes from content (per CLAUDE.md requirement)
+ * Removes lines with `- [ ]` or `* [ ]` patterns
+ * Preserves completed checkboxes `- [x]` and `- [X]`
+ */
+export function removeUnfinishedCheckboxes(content) {
+    const lines = content.split('\n');
+    const filteredLines = [];
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        // Match unchecked boxes: - [ ] or * [ ] with optional leading whitespace
+        const isUnchecked = /^\s*[-*] \[ \]/.test(line);
+        if (!isUnchecked) {
+            filteredLines.push(line);
+        }
+    }
+    return filteredLines.join('\n');
+}
+/**
+ * Generate GitHub blob URL for story file
+ * Parses remote URL and constructs link to story in repository
+ */
+export function getStoryFileURL(storyPath, branch, workingDir) {
+    try {
+        const remoteUrl = execSync('git remote get-url origin', { cwd: workingDir, encoding: 'utf-8' }).trim();
+        // Parse owner/repo from URL
+        // HTTPS: https://github.com/owner/repo.git
+        // SSH: git@github.com:owner/repo.git
+        const match = remoteUrl.match(/github\.com[:/]([^/]+)\/(.+?)(\.git)?$/);
+        if (!match)
+            return '';
+        const [, owner, repo] = match;
+        const relativePath = path.relative(workingDir, storyPath);
+        return `https://github.com/${owner}/${repo}/blob/${branch}/${relativePath}`;
+    }
+    catch {
+        return '';
+    }
+}
+/**
+ * Format PR description from story sections
+ * Includes: Story ID, User Story, Summary, Acceptance Criteria, Implementation Summary
+ * Removes unfinished checkboxes from all sections
+ */
+export function formatPRDescription(story, storyFileUrl) {
+    const sections = parseContentSections(story.content);
+    // Extract key sections
+    const userStory = sections.find(s => s.title === 'User Story')?.content || '';
+    const summary = sections.find(s => s.title === 'Summary')?.content || '';
+    const acceptanceCriteria = sections.find(s => s.title === 'Acceptance Criteria')?.content || '';
+    const implementationSummary = sections.find(s => s.title === 'Implementation Summary')?.content || '';
+    // Remove unfinished checkboxes from all sections
+    const cleanAcceptanceCriteria = removeUnfinishedCheckboxes(acceptanceCriteria);
+    const cleanImplementationSummary = removeUnfinishedCheckboxes(implementationSummary);
+    // Build PR body
+    let prBody = `## Story ID\n\n${story.frontmatter.id}\n\n`;
+    if (userStory.trim()) {
+        prBody += `## User Story\n\n${userStory.trim()}\n\n`;
+    }
+    if (summary.trim()) {
+        prBody += `## Summary\n\n${summary.trim()}\n\n`;
+    }
+    if (cleanAcceptanceCriteria.trim()) {
+        prBody += `## Acceptance Criteria\n\n${cleanAcceptanceCriteria.trim()}\n\n`;
+    }
+    if (cleanImplementationSummary.trim()) {
+        prBody += `## Implementation Summary\n\n${cleanImplementationSummary.trim()}\n\n`;
+    }
+    // Add story file link
+    if (storyFileUrl) {
+        prBody += `---\n\n📋 [View Full Story](${storyFileUrl})\n`;
+    }
+    return prBody;
+}
+/**
+ * Truncate PR body to respect GitHub's 65K character limit
+ * Truncates Implementation Summary first (most verbose section)
+ * Adds clear truncation indicator with story link
+ */
+export function truncatePRBody(body, maxLength = 64000) {
+    // Check if truncation needed
+    if (body.length <= maxLength) {
+        return body;
+    }
+    // Find Implementation Summary section
+    const implSummaryMatch = body.match(/(## Implementation Summary\n\n)([\s\S]*?)(\n\n##|\n\n---|\n\n📋|$)/);
+    if (implSummaryMatch) {
+        const [fullMatch, header, content, trailer] = implSummaryMatch;
+        const beforeImpl = body.substring(0, body.indexOf(fullMatch));
+        const afterImpl = body.substring(body.indexOf(fullMatch) + fullMatch.length);
+        // Calculate how much we need to remove
+        const overhead = beforeImpl.length + header.length + trailer.length + afterImpl.length;
+        const truncationIndicator = '\n\n⚠️ Implementation Summary truncated due to length. See full story for complete details.\n';
+        const availableForContent = maxLength - overhead - truncationIndicator.length;
+        if (availableForContent > 100) {
+            // Truncate Implementation Summary at paragraph boundary
+            let truncatedContent = content.substring(0, availableForContent);
+            const lastParagraph = truncatedContent.lastIndexOf('\n\n');
+            if (lastParagraph > 0) {
+                truncatedContent = truncatedContent.substring(0, lastParagraph);
+            }
+            return beforeImpl + header + truncatedContent + truncationIndicator + trailer + afterImpl;
+        }
+    }
+    // Fallback: simple truncation if no Implementation Summary found
+    const truncatedBody = body.substring(0, maxLength - 200);
+    const lastParagraph = truncatedBody.lastIndexOf('\n\n');
+    const finalBody = lastParagraph > 0 ? truncatedBody.substring(0, lastParagraph) : truncatedBody;
+    return finalBody + '\n\n⚠️ Description truncated due to length. See full story for complete details.\n';
+}
 /**
  * Run a sub-review with a specific prompt
  */
@@ -782,7 +1504,7 @@ Provide your ${reviewType} feedback. Be specific and actionable.`;
 /**
  * Create a pull request for the completed story
  */
-export async function createPullRequest(storyPath, sdlcRoot) {
+export async function createPullRequest(storyPath, sdlcRoot, options) {
     let story = parseStory(storyPath);
     const changesMade = [];
     const workingDir = path.dirname(sdlcRoot);
@@ -819,7 +1541,7 @@ export async function createPullRequest(storyPath, sdlcRoot) {
         catch {
             changesMade.push('GitHub CLI not available - PR creation skipped');
             // Still update to done for MVP
-            story = updateStoryStatus(story, 'done');
+            story = await updateStoryStatus(story, 'done');
             changesMade.push('Updated status to done');
             return {
                 success: true,
@@ -844,37 +1566,69 @@ export async function createPullRequest(storyPath, sdlcRoot) {
             // Push branch (already validated)
             execSync(`git push -u origin ${branchName}`, { cwd: workingDir, stdio: 'pipe' });
             changesMade.push(`Pushed branch: ${branchName}`);
-            // Create PR using gh CLI with safe arguments
-            // Security: Use escaped arguments to prevent shell injection
+            // Check if PR already exists for this branch
+            try {
+                const existingPROutput = execSync('gh pr view --json url', { cwd: workingDir, encoding: 'utf-8', stdio: 'pipe' });
+                const prData = JSON.parse(existingPROutput);
+                if (prData.url) {
+                    changesMade.push(`PR already exists: ${prData.url}`);
+                    // Update story with PR URL if missing
+                    if (!story.frontmatter.pr_url) {
+                        await updateStoryField(story, 'pr_url', prData.url);
+                        changesMade.push('Updated story with existing PR URL');
+                    }
+                    // Don't create duplicate - skip to status update
+                    story = await updateStoryStatus(story, 'done');
+                    changesMade.push('Updated status to done');
+                    return {
+                        success: true,
+                        story,
+                        changesMade,
+                    };
+                }
+            }
+            catch {
+                // No existing PR - proceed with creation
+            }
+            // Create PR using gh CLI with rich formatted body
+            // Security: Use escaped arguments and heredoc to prevent shell injection
             const prTitle = story.frontmatter.title;
-            const prBody = `## Summary
-
-${story.frontmatter.title}
-
-## Story
-
-${story.content.substring(0, 1000)}...
-
-## Checklist
-
-- [x] Implementation complete
-- [x] Code review passed
-- [x] Security review passed
-- [x] Product owner approved
-
----
-*Created by ai-sdlc*`;
-            const prOutput = execSync(`gh pr create --title ${escapeShellArg(prTitle)} --body ${escapeShellArg(prBody)}`, { cwd: workingDir, encoding: 'utf-8' });
+            // Generate story file URL
+            const storyFileUrl = getStoryFileURL(storyPath, branchName, workingDir);
+            // Format rich PR description
+            let prBody = formatPRDescription(story, storyFileUrl);
+            // Truncate if needed to respect GitHub's 65K limit
+            prBody = truncatePRBody(prBody);
+            // Determine if draft PR should be created
+            // Options parameter takes precedence, then config, default is false
+            const config = loadConfig(workingDir);
+            const createAsDraft = options?.draft ?? config.github?.createDraftPRs ?? false;
+            const draftFlag = createAsDraft ? ' --draft' : '';
+            // Use heredoc pattern for multi-line body to preserve formatting
+            const ghCommand = `gh pr create --title ${escapeShellArg(prTitle)}${draftFlag} --body "$(cat <<'EOF'
+${prBody}
+EOF
+)"`;
+            const prOutput = execSync(ghCommand, { cwd: workingDir, encoding: 'utf-8' });
             const prUrl = prOutput.trim();
-            updateStoryField(story, 'pr_url', prUrl);
-            changesMade.push(`Created PR: ${prUrl}`);
+            await updateStoryField(story, 'pr_url', prUrl);
+            const prTypeLabel = createAsDraft ? 'draft PR' : 'PR';
+            changesMade.push(`Created ${prTypeLabel}: ${prUrl}`);
         }
         catch (error) {
             const sanitizedError = sanitizeErrorMessage(error instanceof Error ? error.message : String(error), workingDir);
-            changesMade.push(`PR creation failed: ${sanitizedError}`);
+            // Provide actionable error messages for common issues
+            let errorMessage = `PR creation failed: ${sanitizedError}`;
+            if (sanitizedError.includes('authentication') || sanitizedError.includes('auth') || sanitizedError.includes('credentials')) {
+                errorMessage = `GitHub authentication failed. Please authenticate using one of:
+1. Set GITHUB_TOKEN env var: export GITHUB_TOKEN=ghp_xxx
+2. Run: gh auth login
+3. Check: gh auth status`;
+            }
+            changesMade.push(errorMessage);
         }
         // Update status to done
-        story = updateStoryStatus(story, 'done');
+        story = await updateStoryStatus(story, 'done');
         changesMade.push('Updated status to done');
         return {
             success: true,