ai-sdlc 0.2.0-alpha.9 → 0.2.0-beta.1

package/dist/agents/review.js

@@ -1,12 +1,14 @@
-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 { 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 { 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 +95,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(),
@@ -252,7 +256,8 @@ Output your review as a JSON object with this structure:
       "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)
     }
   ]
 }
@@ -265,6 +270,70 @@ Severity guidelines:
 
 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?
+
+## 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 +341,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 +351,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?
@@ -316,6 +391,7 @@ 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,
@@ -383,8 +459,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 +502,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 +521,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 +537,41 @@ 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'];
+    }
+}
 /**
  * Generate executive summary from review issues (1-3 sentences)
  *
@@ -526,9 +669,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 +703,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 +728,67 @@ 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
+            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', {
+                    storyId: story.frontmatter.id,
+                    retryCount,
+                    maxRetries,
+                });
+                await updateStoryField(story, 'implementation_complete', false);
+                await updateStoryField(story, 'last_restart_reason', 'No source code changes detected. Implementation wrote documentation only.');
+                return {
+                    success: true,
+                    story: parseStory(storyPath),
+                    changesMade: ['Detected documentation-only 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.',
+                        }],
+                    feedback: 'Implementation recovery triggered - no source changes found.',
+                };
+            }
+            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', {
+                    storyId: story.frontmatter.id,
+                    retryCount,
+                    maxRetries,
+                });
+                return {
+                    success: true,
+                    story: parseStory(storyPath),
+                    changesMade: ['Detected documentation-only 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.',
+                        }],
+                    feedback: 'Implementation failed to produce code changes after multiple attempts.',
+                };
+            }
+        }
+        // Source changes exist - proceed with normal review flow
+        logger.info('review', 'Source code changes detected - proceeding with verification', {
+            storyId: story.frontmatter.id,
+            fileCount: sourceChanges.length,
+        });
         // Run build and tests BEFORE reviews (async with progress)
         changesMade.push('Running build and test verification...');
         const verification = await runVerificationAsync(workingDir, config, options?.onVerificationProgress);
@@ -646,60 +856,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 +941,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 +978,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 +1000,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 +1159,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 +1196,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 +1221,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,