@girardmedia/bootspring 2.0.21 → 2.0.23

package/src/core/audit-workflow.ts

@@ -0,0 +1,1681 @@
+/**
+ * Bootspring Audit Workflow Engine
+ *
+ * Quality, security, and best practices audit for codebases.
+ * Generates prioritized recommendations and remediation tasks.
+ *
+ * @package bootspring
+ * @module core/audit-workflow
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+
+// Import analyzers from JS modules
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const securityModule = require('../../analyzers/security-scanner') as {
+  SecurityScanner: new (projectRoot: string) => {
+    scan: () => SecurityScanResult;
+  };
+  SEVERITY: Record<string, string>;
+};
+const { SecurityScanner, SEVERITY } = securityModule;
+
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const { QualityAnalyzer } = require('../../analyzers/quality-analyzer') as {
+  QualityAnalyzer: new (projectRoot: string) => {
+    analyze: () => QualityAnalysisResult;
+  };
+};
+
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const { DependencyAnalyzer } = require('../../analyzers/dependency-analyzer') as {
+  DependencyAnalyzer: new (projectRoot: string) => {
+    buildGraph: () => void;
+    findUnusedDependencies: () => UnusedDependency[];
+  };
+};
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export type AuditPhaseStatus = 'pending' | 'in_progress' | 'completed' | 'skipped' | 'failed';
+export type AuditSeverity = 'critical' | 'high' | 'medium' | 'low' | 'info';
+
+export interface AuditPhaseDefinition {
+  name: string;
+  description: string;
+  order: number;
+  required: boolean;
+  dependencies?: string[] | undefined;
+}
+
+export interface AuditPhaseState {
+  status: AuditPhaseStatus;
+  startedAt: string | null;
+  completedAt: string | null;
+  result: unknown | null;
+  error: string | null;
+}
+
+export interface SeverityLevel {
+  label: string;
+  color: string;
+  action: string;
+  priority: number;
+}
+
+export interface AuditFinding {
+  id?: string | undefined;
+  phase: string;
+  category: string;
+  severity: AuditSeverity;
+  title: string;
+  description: string;
+  file?: string | null | undefined;
+  line?: number | undefined;
+  function?: string | null | undefined;
+  remediation?: string | undefined;
+  timestamp?: string | undefined;
+}
+
+export interface AuditSummary {
+  reportPath: string;
+  totalFindings: number;
+  critical: number;
+  high: number;
+  medium: number;
+  low: number;
+  recommendations: number;
+  generatedAt: string;
+}
+
+export interface AuditWorkflowState {
+  version: string;
+  startedAt: string | null;
+  lastUpdated: string | null;
+  currentPhase: string | null;
+  phases: Record<string, AuditPhaseState>;
+  findings: AuditFinding[];
+  summary: AuditSummary | null;
+}
+
+export interface QualityMetricsResult {
+  score: number;
+  breakdown: Record<string, number>;
+  totalFiles: number;
+  totalIssues: number;
+  totalSmells: number;
+}
+
+export interface SecurityScanResultSummary {
+  passed: boolean;
+  total: number;
+  critical: number;
+  high: number;
+  medium: number;
+  low: number;
+  info?: number | undefined;
+}
+
+export interface SecurityFinding {
+  id: string;
+  type: string;
+  severity: AuditSeverity;
+  name: string;
+  message: string;
+  file: string;
+  line?: number;
+  remediation?: string;
+}
+
+interface SecurityScanResult {
+  findings: SecurityFinding[];
+  bySeverity: Record<string, SecurityFinding[]>;
+  byType: {
+    secret: SecurityFinding[];
+    [key: string]: SecurityFinding[];
+  };
+  summary: SecurityScanResultSummary;
+}
+
+interface QualityAnalysisResult {
+  scores: {
+    overall: number;
+    breakdown: {
+      complexity: number;
+      maintainability: number;
+      documentation: number;
+      codeSmells: number;
+    };
+  };
+  summary: {
+    totalFiles: number;
+    totalLines: number;
+    averageComplexity: number;
+    totalIssues: number;
+    totalSmells: number;
+  };
+  worstFiles: Array<{
+    path: string;
+    complexity: number;
+    issues: Array<{
+      type: string;
+      message: string;
+      function?: string;
+    }>;
+  }>;
+  smells: Array<{
+    id: string;
+    name: string;
+    severity: AuditSeverity;
+    count: number;
+    file: string;
+  }>;
+  smellsByCategory?: Record<string, Array<{
+    name: string;
+    file: string;
+    count: number;
+  }>>;
+}
+
+interface UnusedDependency {
+  name: string;
+  type: string;
+}
+
+export interface PerformanceResult {
+  recommendations: number;
+}
+
+export interface BestPracticesResult {
+  passed: number;
+  total: number;
+  checks: Record<string, CheckResult>;
+}
+
+export interface CheckResult {
+  passed: boolean;
+  issues: CheckIssue[];
+}
+
+export interface CheckIssue {
+  title: string;
+  description: string;
+  file?: string;
+  severity?: AuditSeverity;
+  remediation?: string;
+}
+
+export interface TechDebtResult {
+  todos: number;
+  unusedDeps: number;
+  testCoverage: number;
+  depAnalysisSkipped: boolean;
+}
+
+export interface Recommendation {
+  priority: string;
+  severity: AuditSeverity;
+  title: string;
+  description: string;
+  file?: string | undefined;
+  remediation?: string | undefined;
+}
+
+export interface RecommendationsResult {
+  reportPath: string;
+  recommendations: number;
+  passed: boolean;
+}
+
+export interface AuditPhaseProgress {
+  id: string;
+  name: string;
+  description: string;
+  order: number;
+  required: boolean;
+  status: AuditPhaseStatus;
+  dependenciesMet: boolean;
+}
+
+export interface AuditWorkflowProgress {
+  currentPhase: string | null;
+  startedAt: string | null;
+  lastUpdated: string | null;
+  phases: AuditPhaseProgress[];
+  overall: {
+    completed: number;
+    total: number;
+    percentage: number;
+  };
+  findings: {
+    total: number;
+    critical: number;
+    high: number;
+    medium: number;
+    low: number;
+    info: number;
+  };
+  isComplete: boolean;
+  summary: AuditSummary | null;
+}
+
+export interface AuditResumePoint {
+  phase: string;
+  phaseName: string | undefined;
+  phaseStatus: AuditPhaseStatus | undefined;
+  lastUpdated: string | null;
+  findingsCount: number;
+}
+
+export interface AuditWorkflowOptions {
+  severityFilter?: string | null | undefined;
+  autoFix?: boolean | undefined;
+  ciMode?: boolean | undefined;
+  [key: string]: unknown;
+}
+
+// ============================================================================
+// Constants
+// ============================================================================
+
+/**
+ * Workflow phase status
+ */
+export const PHASE_STATUS: Record<string, AuditPhaseStatus> = {
+  PENDING: 'pending',
+  IN_PROGRESS: 'in_progress',
+  COMPLETED: 'completed',
+  SKIPPED: 'skipped',
+  FAILED: 'failed'
+};
+
+/**
+ * Audit phases
+ */
+export const AUDIT_PHASES: Record<string, AuditPhaseDefinition> = {
+  quality: {
+    name: 'Quality Metrics',
+    description: 'Complexity, duplication, comments, naming',
+    order: 1,
+    required: true
+  },
+  security: {
+    name: 'Security Scan',
+    description: 'Secrets, vulnerabilities, OWASP, injection',
+    order: 2,
+    required: true
+  },
+  performance: {
+    name: 'Performance Analysis',
+    description: 'Bundle size, lazy loading, N+1 queries',
+    order: 3,
+    required: false,
+    dependencies: ['quality']
+  },
+  practices: {
+    name: 'Best Practices',
+    description: 'TypeScript strict, error handling, env vars',
+    order: 4,
+    required: true
+  },
+  techDebt: {
+    name: 'Tech Debt Inventory',
+    description: 'TODOs, deprecated APIs, dead code, missing tests',
+    order: 5,
+    required: true,
+    dependencies: ['quality']
+  },
+  recommendations: {
+    name: 'Recommendations',
+    description: 'Prioritize (P0-P3), estimate effort, generate tasks',
+    order: 6,
+    required: true,
+    dependencies: ['quality', 'security', 'practices', 'techDebt']
+  }
+};
+
+/**
+ * Finding severity levels with actions
+ */
+export const SEVERITY_LEVELS: Record<AuditSeverity, SeverityLevel> = {
+  critical: {
+    label: 'CRITICAL',
+    color: 'red',
+    action: 'Immediate fix required',
+    priority: 0
+  },
+  high: {
+    label: 'HIGH',
+    color: 'orange',
+    action: 'Fix within 1-2 days',
+    priority: 1
+  },
+  medium: {
+    label: 'MEDIUM',
+    color: 'yellow',
+    action: 'Plan fix within 1-2 weeks',
+    priority: 2
+  },
+  low: {
+    label: 'LOW',
+    color: 'blue',
+    action: 'Add to backlog',
+    priority: 3
+  },
+  info: {
+    label: 'INFO',
+    color: 'gray',
+    action: 'Consider when convenient',
+    priority: 4
+  }
+};
+
+/**
+ * Default workflow state
+ */
+export const DEFAULT_STATE: AuditWorkflowState = {
+  version: '1.0.0',
+  startedAt: null,
+  lastUpdated: null,
+  currentPhase: null,
+  phases: {},
+  findings: [],
+  summary: null
+};
+
+// ============================================================================
+// AuditWorkflowEngine Class
+// ============================================================================
+
+/**
+ * AuditWorkflowEngine - Manages audit workflow
+ */
+export class AuditWorkflowEngine {
+  readonly projectRoot: string;
+  readonly workflowDir: string;
+  readonly stateFile: string;
+  readonly reportsDir: string;
+  readonly findingsDir: string;
+  readonly options: AuditWorkflowOptions;
+  state: AuditWorkflowState | null;
+
+  constructor(projectRoot: string, options: AuditWorkflowOptions = {}) {
+    this.projectRoot = projectRoot;
+    this.workflowDir = path.join(projectRoot, '.bootspring', 'audit');
+    this.stateFile = path.join(this.workflowDir, 'workflow-state.json');
+    this.reportsDir = path.join(this.workflowDir, 'reports');
+    this.findingsDir = path.join(this.workflowDir, 'findings');
+    this.options = {
+      severityFilter: options.severityFilter ?? null,
+      autoFix: options.autoFix ?? false,
+      ciMode: options.ciMode ?? false,
+      ...options
+    };
+    this.state = null;
+  }
+
+  /**
+   * Setup directories
+   */
+  setupDirectories(): void {
+    const dirs = [this.workflowDir, this.reportsDir, this.findingsDir];
+
+    for (const dir of dirs) {
+      if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+      }
+    }
+  }
+
+  /**
+   * Load workflow state
+   */
+  loadState(): boolean {
+    if (fs.existsSync(this.stateFile)) {
+      try {
+        this.state = JSON.parse(fs.readFileSync(this.stateFile, 'utf-8')) as AuditWorkflowState;
+        return true;
+      } catch {
+        this.state = { ...DEFAULT_STATE, phases: {}, findings: [] };
+        return false;
+      }
+    }
+    this.state = { ...DEFAULT_STATE, phases: {}, findings: [] };
+    return false;
+  }
+
+  /**
+   * Save workflow state
+   */
+  saveState(): void {
+    if (!this.state) return;
+    this.setupDirectories();
+    this.state.lastUpdated = new Date().toISOString();
+    fs.writeFileSync(this.stateFile, JSON.stringify(this.state, null, 2));
+  }
+
+  /**
+   * Initialize workflow
+   */
+  initializeWorkflow(): AuditWorkflowState {
+    this.setupDirectories();
+    this.state = {
+      ...DEFAULT_STATE,
+      startedAt: new Date().toISOString(),
+      lastUpdated: new Date().toISOString(),
+      phases: {},
+      findings: []
+    };
+
+    // Initialize phase states
+    for (const phaseId of Object.keys(AUDIT_PHASES)) {
+      this.state.phases[phaseId] = {
+        status: 'pending',
+        startedAt: null,
+        completedAt: null,
+        result: null,
+        error: null
+      };
+    }
+
+    this.state.currentPhase = 'quality';
+    this.saveState();
+    return this.state;
+  }
+
+  /**
+   * Check if workflow exists
+   */
+  hasWorkflow(): boolean {
+    return fs.existsSync(this.stateFile);
+  }
+
+  /**
+   * Reset workflow
+   */
+  resetWorkflow(): boolean {
+    if (fs.existsSync(this.stateFile)) {
+      fs.unlinkSync(this.stateFile);
+    }
+    this.state = null;
+    return true;
+  }
+
+  /**
+   * Check if phase dependencies are met
+   */
+  arePhaseDependenciesMet(phaseId: string): boolean {
+    const phase = AUDIT_PHASES[phaseId];
+    if (!phase || !phase.dependencies || phase.dependencies.length === 0) {
+      return true;
+    }
+
+    for (const depPhaseId of phase.dependencies) {
+      const depPhase = this.state?.phases[depPhaseId];
+      if (!depPhase || (depPhase.status !== 'completed' && depPhase.status !== 'skipped')) {
+        return false;
+      }
+    }
+
+    return true;
+  }
+
+  /**
+   * Get next phase
+   */
+  getNextPhase(): string | null {
+    if (!this.state) return null;
+
+    const phaseOrder = Object.keys(AUDIT_PHASES).sort((a, b) => {
+      const phaseA = AUDIT_PHASES[a];
+      const phaseB = AUDIT_PHASES[b];
+      return (phaseA?.order ?? 0) - (phaseB?.order ?? 0);
+    });
+
+    for (const phaseId of phaseOrder) {
+      const phase = this.state.phases[phaseId];
+      if (phase?.status === 'pending' && this.arePhaseDependenciesMet(phaseId)) {
+        return phaseId;
+      }
+    }
+
+    return null;
+  }
+
+  /**
+   * Start a phase
+   */
+  startPhase(phaseId: string): void {
+    if (!this.state) {
+      throw new Error('Workflow not initialized');
+    }
+
+    const phase = this.state.phases[phaseId];
+    if (!phase) {
+      throw new Error(`Unknown phase: ${phaseId}`);
+    }
+
+    phase.status = 'in_progress';
+    phase.startedAt = new Date().toISOString();
+    this.state.currentPhase = phaseId;
+    this.saveState();
+  }
+
+  /**
+   * Complete a phase
+   */
+  completePhase(phaseId: string, result: unknown = null): void {
+    if (!this.state) {
+      throw new Error('Workflow not initialized');
+    }
+
+    const phase = this.state.phases[phaseId];
+    if (!phase) {
+      throw new Error(`Unknown phase: ${phaseId}`);
+    }
+
+    phase.status = 'completed';
+    phase.completedAt = new Date().toISOString();
+    phase.result = result;
+    this.saveState();
+  }
+
+  /**
+   * Fail a phase
+   */
+  failPhase(phaseId: string, error: string): void {
+    if (!this.state) {
+      throw new Error('Workflow not initialized');
+    }
+
+    const phase = this.state.phases[phaseId];
+    if (!phase) {
+      throw new Error(`Unknown phase: ${phaseId}`);
+    }
+
+    phase.status = 'failed';
+    phase.completedAt = new Date().toISOString();
+    phase.error = error;
+    this.saveState();
+  }
+
+  /**
+   * Skip a phase
+   */
+  skipPhase(phaseId: string): void {
+    if (!this.state) {
+      throw new Error('Workflow not initialized');
+    }
+
+    const phase = this.state.phases[phaseId];
+    if (!phase) {
+      throw new Error(`Unknown phase: ${phaseId}`);
+    }
+
+    phase.status = 'skipped';
+    phase.completedAt = new Date().toISOString();
+    this.saveState();
+  }
+
+  /**
+   * Add finding
+   */
+  addFinding(finding: Omit<AuditFinding, 'id' | 'timestamp'>): void {
+    if (!this.state) return;
+
+    this.state.findings.push({
+      ...finding,
+      id: `F${this.state.findings.length + 1}`,
+      timestamp: new Date().toISOString()
+    });
+    this.saveState();
+  }
+
+  /**
+   * Run quality metrics phase
+   */
+  async runQualityMetrics(): Promise<QualityMetricsResult> {
+    const analyzer = new QualityAnalyzer(this.projectRoot);
+    const result = analyzer.analyze();
+
+    // Add findings for quality issues
+    for (const file of result.worstFiles) {
+      for (const issue of file.issues) {
+        this.addFinding({
+          phase: 'quality',
+          category: 'quality',
+          severity: issue.type === 'high-complexity' ? 'medium' : 'low',
+          title: issue.type,
+          description: issue.message,
+          file: file.path,
+          function: issue.function ?? null,
+          remediation: this.getQualityRemediation(issue.type)
+        });
+      }
+    }
+
+    // Add findings for code smells
+    for (const smell of result.smells) {
+      this.addFinding({
+        phase: 'quality',
+        category: 'code-smell',
+        severity: smell.severity,
+        title: smell.name,
+        description: `Found ${smell.count} instance(s)`,
+        file: smell.file,
+        remediation: this.getSmellRemediation(smell.id)
+      });
+    }
+
+    // Save report
+    const report = this.generateQualityReport(result);
+    fs.writeFileSync(
+      path.join(this.reportsDir, 'quality.md'),
+      report
+    );
+
+    return {
+      score: result.scores.overall,
+      breakdown: result.scores.breakdown,
+      totalFiles: result.summary.totalFiles,
+      totalIssues: result.summary.totalIssues,
+      totalSmells: result.summary.totalSmells
+    };
+  }
+
+  /**
+   * Get remediation for quality issue
+   */
+  getQualityRemediation(issueType: string): string {
+    const remediations: Record<string, string> = {
+      'long-function': 'Break function into smaller, focused functions',
+      'high-complexity': 'Simplify logic by extracting helper functions or using early returns',
+      'too-many-params': 'Use an options object or break into multiple functions',
+      'long-file': 'Split into multiple modules with clear responsibilities',
+      'low-comments': 'Add JSDoc comments for public functions and complex logic'
+    };
+    return remediations[issueType] ?? 'Review and refactor as needed';
+  }
+
+  /**
+   * Get remediation for code smell
+   */
+  getSmellRemediation(smellId: string): string {
+    const remediations: Record<string, string> = {
+      'todo-comment': 'Convert to a tracked issue or complete the TODO',
+      'fixme-comment': 'Address the issue and remove the comment',
+      'console-log': 'Remove console.log or replace with proper logging',
+      'debugger': 'Remove debugger statement before committing',
+      'empty-catch': 'Handle the error appropriately or add a comment explaining why it is safe to ignore',
+      'any-type': 'Add proper TypeScript types',
+      'ts-ignore': 'Fix the underlying TypeScript error',
+      'eslint-disable': 'Fix the underlying ESLint error or add specific disable reason'
+    };
+    return remediations[smellId] ?? 'Review and address as appropriate';
+  }
+
+  /**
+   * Generate quality report
+   */
+  generateQualityReport(analysis: QualityAnalysisResult): string {
+    const lines: string[] = [
+      '# Quality Analysis Report',
+      '',
+      `Generated: ${new Date().toISOString()}`,
+      '',
+      '## Quality Score',
+      '',
+      `**Overall**: ${analysis.scores.overall}/100`,
+      '',
+      '| Category | Score |',
+      '|----------|-------|',
+      `| Complexity | ${analysis.scores.breakdown.complexity}/100 |`,
+      `| Maintainability | ${analysis.scores.breakdown.maintainability}/100 |`,
+      `| Documentation | ${analysis.scores.breakdown.documentation}/100 |`,
+      `| Code Smells | ${analysis.scores.breakdown.codeSmells}/100 |`,
+      '',
+      '## Summary',
+      '',
+      `- **Total Files**: ${analysis.summary.totalFiles}`,
+      `- **Total Lines**: ${analysis.summary.totalLines}`,
+      `- **Average Complexity**: ${analysis.summary.averageComplexity}`,
+      `- **Total Issues**: ${analysis.summary.totalIssues}`,
+      `- **Code Smells**: ${analysis.summary.totalSmells}`,
+      ''
+    ];
+
+    if (analysis.worstFiles.length > 0) {
+      lines.push('## Files Needing Attention');
+      lines.push('');
+      lines.push('| File | Issues | Complexity |');
+      lines.push('|------|--------|------------|');
+      for (const file of analysis.worstFiles.slice(0, 10)) {
+        lines.push(`| \`${file.path}\` | ${file.issues.length} | ${file.complexity} |`);
+      }
+      lines.push('');
+    }
+
+    if (analysis.smellsByCategory && Object.keys(analysis.smellsByCategory).length > 0) {
+      lines.push('## Code Smells by Category');
+      lines.push('');
+      for (const [category, smells] of Object.entries(analysis.smellsByCategory)) {
+        lines.push(`### ${category}`);
+        for (const smell of smells.slice(0, 5)) {
+          lines.push(`- **${smell.name}** in \`${smell.file}\`: ${smell.count} instances`);
+        }
+        lines.push('');
+      }
+    }
+
+    return lines.join('\n');
+  }
+
+  /**
+   * Run security scan phase
+   */
+  async runSecurityScan(): Promise<SecurityScanResultSummary> {
+    const scanner = new SecurityScanner(this.projectRoot);
+    const result = scanner.scan();
+
+    // Add findings
+    for (const finding of result.findings) {
+      this.addFinding({
+        phase: 'security',
+        category: finding.type,
+        severity: finding.severity,
+        title: finding.name,
+        description: finding.message,
+        file: finding.file,
+        line: finding.line,
+        remediation: finding.remediation ?? this.getSecurityRemediation(finding.id)
+      });
+    }
+
+    // Save findings by severity
+    const criticalFindings = result.bySeverity['critical'] ?? [];
+    const highFindings = result.bySeverity['high'] ?? [];
+
+    fs.writeFileSync(
+      path.join(this.findingsDir, 'critical.json'),
+      JSON.stringify(criticalFindings, null, 2)
+    );
+    fs.writeFileSync(
+      path.join(this.findingsDir, 'high.json'),
+      JSON.stringify(highFindings, null, 2)
+    );
+
+    // Save report
+    const report = this.generateSecurityReport(result);
+    fs.writeFileSync(
+      path.join(this.reportsDir, 'security.md'),
+      report
+    );
+
+    return {
+      passed: result.summary.passed,
+      total: result.summary.total,
+      critical: result.summary.critical,
+      high: result.summary.high,
+      medium: result.summary.medium,
+      low: result.summary.low
+    };
+  }
+
+  /**
+   * Get security remediation
+   */
+  getSecurityRemediation(findingId: string): string {
+    const remediations: Record<string, string> = {
+      'aws-key': 'Remove AWS key and rotate credentials immediately',
+      'api-key': 'Move API key to environment variables',
+      'private-key': 'Remove private key from repository and rotate',
+      'sql-injection': 'Use parameterized queries',
+      'command-injection': 'Sanitize input and use spawn with array arguments',
+      'xss': 'Sanitize output and use content security policy'
+    };
+    return remediations[findingId] ?? 'Review and remediate security issue';
+  }
+
+  /**
+   * Generate security report
+   */
+  generateSecurityReport(analysis: SecurityScanResult): string {
+    const lines: string[] = [
+      '# Security Audit Report',
+      '',
+      `Generated: ${new Date().toISOString()}`,
+      '',
+      '## Summary',
+      '',
+      `**Status**: ${analysis.summary.passed ? 'PASSED' : 'FAILED'}`,
+      '',
+      '| Severity | Count |',
+      '|----------|-------|',
+      `| Critical | ${analysis.summary.critical} |`,
+      `| High | ${analysis.summary.high} |`,
+      `| Medium | ${analysis.summary.medium} |`,
+      `| Low | ${analysis.summary.low} |`,
+      `| Info | ${analysis.summary.info ?? 0} |`,
+      ''
+    ];
+
+    const criticalFindings = analysis.bySeverity['critical'] ?? [];
+    if (analysis.summary.critical > 0) {
+      lines.push('## Critical Findings');
+      lines.push('');
+      lines.push('> These require immediate attention.');
+      lines.push('');
+      for (const finding of criticalFindings) {
+        lines.push(`### ${finding.name}`);
+        lines.push(`- **File**: \`${finding.file}:${finding.line ?? 0}\``);
+        lines.push(`- **Message**: ${finding.message}`);
+        lines.push(`- **Remediation**: ${finding.remediation ?? 'Review and fix'}`);
+        lines.push('');
+      }
+    }
+
+    const highFindings = analysis.bySeverity['high'] ?? [];
+    if (analysis.summary.high > 0) {
+      lines.push('## High Severity Findings');
+      lines.push('');
+      for (const finding of highFindings) {
+        lines.push(`- **${finding.name}** in \`${finding.file}\`: ${finding.message}`);
+      }
+      lines.push('');
+    }
+
+    if (analysis.byType.secret.length > 0) {
+      lines.push('## Potential Secrets');
+      lines.push('');
+      lines.push('> Remove these from version control and rotate credentials.');
+      lines.push('');
+      for (const finding of analysis.byType.secret) {
+        lines.push(`- **${finding.name}** in \`${finding.file}\``);
+      }
+      lines.push('');
+    }
+
+    return lines.join('\n');
+  }
+
+  /**
+   * Run performance analysis phase
+   */
+  async runPerformanceAnalysis(): Promise<PerformanceResult> {
+    const recommendations: Array<{ id: string; title: string; description: string }> = [];
+
+    // Check for bundle analysis config
+    const nextConfigPath = path.join(this.projectRoot, 'next.config.js');
+    if (fs.existsSync(nextConfigPath)) {
+      const content = fs.readFileSync(nextConfigPath, 'utf-8');
+      if (!content.includes('bundle-analyzer')) {
+        recommendations.push({
+          id: 'add-bundle-analyzer',
+          title: 'Add Bundle Analyzer',
+          description: 'Consider adding @next/bundle-analyzer to monitor bundle size'
+        });
+      }
+    }
+
+    // Check for dynamic imports
+    const hasDynamicImports = await this.checkForDynamicImports();
+    if (!hasDynamicImports) {
+      recommendations.push({
+        id: 'use-dynamic-imports',
+        title: 'Use Dynamic Imports',
+        description: 'Consider using dynamic imports for large components'
+      });
+    }
+
+    // Add findings
+    for (const rec of recommendations) {
+      this.addFinding({
+        phase: 'performance',
+        category: 'performance',
+        severity: 'low',
+        title: rec.title,
+        description: rec.description,
+        remediation: 'Implement the suggested optimization'
+      });
+    }
+
+    return {
+      recommendations: recommendations.length
+    };
+  }
+
+  /**
+   * Check for dynamic imports
+   */
+  async checkForDynamicImports(): Promise<boolean> {
+    const patterns = [
+      /import\s*\(\s*['"][^'"]+['"]\s*\)/g,
+      /dynamic\s*\(\s*\(\)\s*=>\s*import/g,
+      /lazy\s*\(\s*\(\)\s*=>\s*import/g
+    ];
+
+    const sourceDirs = ['src', 'app', 'pages', 'components'];
+
+    for (const dir of sourceDirs) {
+      const dirPath = path.join(this.projectRoot, dir);
+      if (fs.existsSync(dirPath)) {
+        const found = await this.searchForPatterns(dirPath, patterns);
+        if (found) return true;
+      }
+    }
+
+    return false;
+  }
+
+  /**
+   * Search for patterns in directory
+   */
+  async searchForPatterns(dir: string, patterns: RegExp[]): Promise<boolean> {
+    try {
+      const items = fs.readdirSync(dir, { withFileTypes: true });
+
+      for (const item of items) {
+        const fullPath = path.join(dir, item.name);
+
+        if (item.isDirectory() && !item.name.startsWith('.') && item.name !== 'node_modules') {
+          if (await this.searchForPatterns(fullPath, patterns)) {
+            return true;
+          }
+        } else if (item.isFile() && /\.(js|jsx|ts|tsx)$/.test(item.name)) {
+          const content = fs.readFileSync(fullPath, 'utf-8');
+          for (const pattern of patterns) {
+            if (pattern.test(content)) {
+              return true;
+            }
+          }
+        }
+      }
+    } catch {
+      // Skip
+    }
+
+    return false;
+  }
+
+  /**
+   * Run best practices phase
+   */
+  async runBestPractices(): Promise<BestPracticesResult> {
+    const checks: Record<string, CheckResult> = {
+      typescript: await this.checkTypeScriptConfig(),
+      errorHandling: await this.checkErrorHandling(),
+      envVars: await this.checkEnvVars(),
+      gitignore: await this.checkGitignore()
+    };
+
+    // Add findings for failed checks
+    for (const [_check, result] of Object.entries(checks)) {
+      if (!result.passed) {
+        for (const issue of result.issues) {
+          this.addFinding({
+            phase: 'practices',
+            category: 'best-practice',
+            severity: issue.severity ?? 'medium',
+            title: issue.title,
+            description: issue.description,
+            file: issue.file,
+            remediation: issue.remediation
+          });
+        }
+      }
+    }
+
+    const passedCount = Object.values(checks).filter(c => c.passed).length;
+
+    return {
+      passed: passedCount,
+      total: Object.keys(checks).length,
+      checks
+    };
+  }
+
+  /**
+   * Check TypeScript configuration
+   */
+  async checkTypeScriptConfig(): Promise<CheckResult> {
+    const result: CheckResult = { passed: true, issues: [] };
+    const tsconfigPath = path.join(this.projectRoot, 'tsconfig.json');
+
+    if (!fs.existsSync(tsconfigPath)) {
+      result.passed = false;
+      result.issues.push({
+        title: 'TypeScript Not Configured',
+        description: 'No tsconfig.json found',
+        severity: 'low',
+        remediation: 'Consider using TypeScript for better type safety'
+      });
+      return result;
+    }
+
+    try {
+      const tsconfig = JSON.parse(fs.readFileSync(tsconfigPath, 'utf-8')) as Record<string, unknown>;
+      const compilerOptions = (tsconfig.compilerOptions ?? {}) as Record<string, unknown>;
+
+      if (!compilerOptions.strict) {
+        result.passed = false;
+        result.issues.push({
+          title: 'TypeScript Strict Mode Disabled',
+          description: 'strict mode is not enabled in tsconfig.json',
+          file: 'tsconfig.json',
+          severity: 'low',
+          remediation: 'Enable "strict": true for better type safety'
+        });
+      }
+
+      if (compilerOptions.noImplicitAny === false) {
+        result.passed = false;
+        result.issues.push({
+          title: 'Implicit Any Allowed',
+          description: 'noImplicitAny is disabled',
+          file: 'tsconfig.json',
+          severity: 'low',
+          remediation: 'Enable noImplicitAny for stricter typing'
+        });
+      }
+    } catch {
+      // Invalid tsconfig
+    }
+
+    return result;
+  }
+
+  /**
+   * Check error handling patterns
+   */
+  async checkErrorHandling(): Promise<CheckResult> {
+    const result: CheckResult = { passed: true, issues: [] };
+
+    // Check for global error handler in Next.js
+    const errorPagePaths = [
+      'app/error.tsx', 'app/error.js',
+      'pages/_error.tsx', 'pages/_error.js',
+      'src/app/error.tsx', 'src/pages/_error.tsx'
+    ];
+
+    let hasErrorPage = false;
+    for (const errorPath of errorPagePaths) {
+      if (fs.existsSync(path.join(this.projectRoot, errorPath))) {
+        hasErrorPage = true;
+        break;
+      }
+    }
+
+    if (!hasErrorPage) {
+      result.passed = false;
+      result.issues.push({
+        title: 'No Global Error Handler',
+        description: 'No error page found for handling runtime errors',
+        severity: 'medium',
+        remediation: 'Create an error.tsx (App Router) or _error.tsx (Pages Router)'
+      });
+    }
+
+    return result;
+  }
+
+  /**
+   * Check environment variable handling
+   */
+  async checkEnvVars(): Promise<CheckResult> {
+    const result: CheckResult = { passed: true, issues: [] };
+
+    const envPath = path.join(this.projectRoot, '.env');
+    const envExamplePath = path.join(this.projectRoot, '.env.example');
+    const envLocalPath = path.join(this.projectRoot, '.env.local');
+
+    // Check for .env.example
+    if (!fs.existsSync(envExamplePath)) {
+      if (fs.existsSync(envPath) || fs.existsSync(envLocalPath)) {
+        result.passed = false;
+        result.issues.push({
+          title: 'Missing .env.example',
+          description: 'No .env.example file to document required environment variables',
+          severity: 'low',
+          remediation: 'Create .env.example with all required variables (without values)'
+        });
+      }
+    }
+
+    // Check .gitignore includes .env
+    const gitignorePath = path.join(this.projectRoot, '.gitignore');
+    if (fs.existsSync(gitignorePath)) {
+      const gitignore = fs.readFileSync(gitignorePath, 'utf-8');
+      if (!gitignore.includes('.env')) {
+        result.passed = false;
+        result.issues.push({
+          title: '.env Not in .gitignore',
+          description: '.env files should be excluded from version control',
+          file: '.gitignore',
+          severity: 'high',
+          remediation: 'Add .env* to .gitignore'
+        });
+      }
+    }
+
+    return result;
+  }
+
+  /**
+   * Check .gitignore configuration
+   */
+  async checkGitignore(): Promise<CheckResult> {
+    const result: CheckResult = { passed: true, issues: [] };
+    const gitignorePath = path.join(this.projectRoot, '.gitignore');
+
+    if (!fs.existsSync(gitignorePath)) {
+      result.passed = false;
+      result.issues.push({
+        title: 'Missing .gitignore',
+        description: 'No .gitignore file found',
+        severity: 'medium',
+        remediation: 'Create a .gitignore file with appropriate exclusions'
+      });
+      return result;
+    }
+
+    const gitignore = fs.readFileSync(gitignorePath, 'utf-8');
+    const requiredEntries = ['node_modules', '.env'];
+
+    for (const entry of requiredEntries) {
+      if (!gitignore.includes(entry)) {
+        result.passed = false;
+        result.issues.push({
+          title: `Missing ${entry} in .gitignore`,
+          description: `${entry} should be in .gitignore`,
+          file: '.gitignore',
+          severity: entry === '.env' ? 'high' : 'low',
+          remediation: `Add ${entry} to .gitignore`
+        });
+      }
+    }
+
+    return result;
+  }
+
+  /**
+   * Run tech debt inventory phase
+   */
+  async runTechDebtInventory(): Promise<TechDebtResult> {
+    const techDebt: {
+      todos: AuditFinding[];
+      deprecated: unknown[];
+      deadCode: unknown[];
+      missingTests: unknown[];
+    } = {
+      todos: [],
+      deprecated: [],
+      deadCode: [],
+      missingTests: []
+    };
+
+    // Scan for TODOs (already captured in quality phase)
+    const qualityFindings = this.state?.findings.filter(
+      f => f.phase === 'quality' && f.category === 'code-smell'
+    ) ?? [];
+
+    techDebt.todos = qualityFindings.filter(
+      f => f.title.toLowerCase().includes('todo') || f.title.toLowerCase().includes('fixme')
+    );
+
+    // Check for missing tests
+    const srcDirs = ['src', 'lib', 'app', 'components'];
+    let sourceFiles = 0;
+    let testFiles = 0;
+
+    for (const dir of srcDirs) {
+      const dirPath = path.join(this.projectRoot, dir);
+      if (fs.existsSync(dirPath)) {
+        const counts = await this.countSourceAndTestFiles(dirPath);
+        sourceFiles += counts.source;
+        testFiles += counts.test;
+      }
+    }
+
+    const testRatio = sourceFiles > 0 ? testFiles / sourceFiles : 0;
+    if (testRatio < 0.2) {
+      this.addFinding({
+        phase: 'techDebt',
+        category: 'tech-debt',
+        severity: 'medium',
+        title: 'Low Test Coverage',
+        description: `Only ${Math.round(testRatio * 100)}% test file ratio`,
+        remediation: 'Add unit and integration tests for critical paths'
+      });
+    }
+
+    // Check for unused dependencies (skip for large codebases)
+    const LARGE_CODEBASE_THRESHOLD = 500;
+    let unusedDeps: UnusedDependency[] = [];
+    let depAnalysisSkipped = false;
+
+    // Estimate file count from source files scanned
+    const estimatedFileCount = sourceFiles + testFiles;
+
+    if (estimatedFileCount < LARGE_CODEBASE_THRESHOLD) {
+      const depAnalyzer = new DependencyAnalyzer(this.projectRoot);
+      depAnalyzer.buildGraph();
+      unusedDeps = depAnalyzer.findUnusedDependencies();
+
+      for (const dep of unusedDeps.slice(0, 10)) {
+        this.addFinding({
+          phase: 'techDebt',
+          category: 'tech-debt',
+          severity: 'low',
+          title: 'Potentially Unused Dependency',
+          description: `${dep.name} may be unused`,
+          remediation: `Remove ${dep.name} if not needed, or verify it is used`
+        });
+      }
+    } else {
+      depAnalysisSkipped = true;
+    }
+
+    // Save tech debt report
+    const report = this.generateTechDebtReport(techDebt, testRatio, unusedDeps, depAnalysisSkipped);
+    fs.writeFileSync(
+      path.join(this.reportsDir, 'tech-debt.md'),
+      report
+    );
+
+    return {
+      todos: techDebt.todos.length,
+      unusedDeps: unusedDeps.length,
+      testCoverage: Math.round(testRatio * 100),
+      depAnalysisSkipped
+    };
+  }
+
+  /**
+   * Count source and test files
+   */
+  async countSourceAndTestFiles(dir: string): Promise<{ source: number; test: number }> {
+    let source = 0;
+    let test = 0;
+
+    try {
+      const items = fs.readdirSync(dir, { withFileTypes: true });
+
+      for (const item of items) {
+        const fullPath = path.join(dir, item.name);
+
+        if (item.isDirectory() && !item.name.startsWith('.') && item.name !== 'node_modules') {
+          const counts = await this.countSourceAndTestFiles(fullPath);
+          source += counts.source;
+          test += counts.test;
+        } else if (item.isFile() && /\.(js|jsx|ts|tsx)$/.test(item.name)) {
+          if (/\.(test|spec)\.(js|jsx|ts|tsx)$/.test(item.name)) {
+            test++;
+          } else {
+            source++;
+          }
+        }
+      }
+    } catch {
+      // Skip
+    }
+
+    return { source, test };
+  }
+
+  /**
+   * Generate tech debt report
+   */
+  generateTechDebtReport(
+    techDebt: { todos: AuditFinding[] },
+    testRatio: number,
+    unusedDeps: UnusedDependency[],
+    depAnalysisSkipped: boolean = false
+  ): string {
+    const lines: string[] = [
+      '# Technical Debt Report',
+      '',
+      `Generated: ${new Date().toISOString()}`,
+      '',
+      '## Summary',
+      '',
+      `- **TODO/FIXME Comments**: ${techDebt.todos.length}`,
+      `- **Test Coverage**: ${Math.round(testRatio * 100)}%`,
+      `- **Unused Dependencies**: ${depAnalysisSkipped ? 'Skipped (large codebase)' : unusedDeps.length}`,
+      ''
+    ];
+
+    if (techDebt.todos.length > 0) {
+      lines.push('## TODO/FIXME Items');
+      lines.push('');
+      for (const todo of techDebt.todos.slice(0, 20)) {
+        lines.push(`- \`${todo.file ?? 'unknown'}\`: ${todo.title}`);
+      }
+      lines.push('');
+    }
+
+    if (unusedDeps.length > 0) {
+      lines.push('## Potentially Unused Dependencies');
+      lines.push('');
+      for (const dep of unusedDeps) {
+        lines.push(`- \`${dep.name}\` (${dep.type})`);
+      }
+      lines.push('');
+    }
+
+    return lines.join('\n');
+  }
+
+  /**
+   * Run recommendations phase
+   */
+  async runRecommendations(): Promise<RecommendationsResult> {
+    if (!this.state) {
+      throw new Error('Workflow not initialized');
+    }
+
+    // Group findings by severity
+    const bySeverity: Record<AuditSeverity, AuditFinding[]> = {
+      critical: [],
+      high: [],
+      medium: [],
+      low: [],
+      info: []
+    };
+
+    for (const finding of this.state.findings) {
+      const severity = finding.severity ?? 'info';
+      const arr = bySeverity[severity];
+      if (arr) {
+        arr.push(finding);
+      }
+    }
+
+    // Generate prioritized recommendations
+    const recommendations: Recommendation[] = [];
+
+    // P0: Critical findings
+    for (const finding of bySeverity.critical) {
+      recommendations.push({
+        priority: 'P0',
+        severity: 'critical',
+        title: finding.title,
+        description: finding.description,
+        file: finding.file ?? undefined,
+        remediation: finding.remediation
+      });
+    }
+
+    // P1: High findings
+    for (const finding of bySeverity.high.slice(0, 10)) {
+      recommendations.push({
+        priority: 'P1',
+        severity: 'high',
+        title: finding.title,
+        description: finding.description,
+        file: finding.file ?? undefined,
+        remediation: finding.remediation
+      });
+    }
+
+    // P2: Medium findings
+    for (const finding of bySeverity.medium.slice(0, 10)) {
+      recommendations.push({
+        priority: 'P2',
+        severity: 'medium',
+        title: finding.title,
+        description: finding.description,
+        file: finding.file ?? undefined,
+        remediation: finding.remediation
+      });
+    }
+
+    // P3: Low findings (just summary)
+    recommendations.push({
+      priority: 'P3',
+      severity: 'low',
+      title: `${bySeverity.low.length} Low Priority Items`,
+      description: 'Address when convenient',
+      remediation: 'Review low priority findings in the audit report'
+    });
+
+    // Generate final report
+    const report = this.generateFinalReport(bySeverity, recommendations);
+    const reportPath = path.join(this.projectRoot, 'planning', 'AUDIT_REPORT.md');
+    const planningDir = path.join(this.projectRoot, 'planning');
+
+    if (!fs.existsSync(planningDir)) {
+      fs.mkdirSync(planningDir, { recursive: true });
+    }
+
+    fs.writeFileSync(reportPath, report);
+
+    // Also save in workflow directory
+    fs.writeFileSync(
+      path.join(this.reportsDir, 'AUDIT_REPORT.md'),
+      report
+    );
+
+    this.state.summary = {
+      reportPath,
+      totalFindings: this.state.findings.length,
+      critical: bySeverity.critical.length,
+      high: bySeverity.high.length,
+      medium: bySeverity.medium.length,
+      low: bySeverity.low.length,
+      recommendations: recommendations.length,
+      generatedAt: new Date().toISOString()
+    };
+
+    return {
+      reportPath,
+      recommendations: recommendations.length,
+      passed: bySeverity.critical.length === 0
+    };
+  }
+
+  /**
+   * Generate final audit report
+   */
+  generateFinalReport(
+    bySeverity: Record<AuditSeverity, AuditFinding[]>,
+    recommendations: Recommendation[]
+  ): string {
+    const totalFindings = Object.values(bySeverity).reduce((sum, arr) => sum + arr.length, 0);
+
+    const lines: string[] = [
+      '# Audit Report',
+      '',
+      '**Generated by**: Bootspring Audit',
+      `**Date**: ${new Date().toISOString().split('T')[0]}`,
+      `**Status**: ${bySeverity.critical.length === 0 ? 'PASSED' : 'NEEDS ATTENTION'}`,
+      '',
+      '## Executive Summary',
+      '',
+      `This audit found **${totalFindings}** findings across quality, security, and best practices checks.`,
+      '',
+      '### Findings by Severity',
+      '',
+      '| Severity | Count | Action Required |',
+      '|----------|-------|-----------------|',
+      `| Critical | ${bySeverity.critical.length} | Immediate |`,
+      `| High | ${bySeverity.high.length} | 1-2 days |`,
+      `| Medium | ${bySeverity.medium.length} | 1-2 weeks |`,
+      `| Low | ${bySeverity.low.length} | Backlog |`,
+      ''
+    ];
+
+    // Critical findings
+    if (bySeverity.critical.length > 0) {
+      lines.push('## Critical Findings');
+      lines.push('');
+      lines.push('> These require immediate attention.');
+      lines.push('');
+      for (const finding of bySeverity.critical) {
+        lines.push(`### ${finding.title}`);
+        lines.push(`- **Category**: ${finding.category}`);
+        lines.push(`- **File**: ${finding.file ? `\`${finding.file}\`` : 'N/A'}`);
+        lines.push(`- **Description**: ${finding.description}`);
+        lines.push(`- **Remediation**: ${finding.remediation ?? 'Review and fix'}`);
+        lines.push('');
+      }
+    }
+
+    // High findings
+    if (bySeverity.high.length > 0) {
+      lines.push('## High Priority Findings');
+      lines.push('');
+      for (const finding of bySeverity.high) {
+        lines.push(`- **${finding.title}** ${finding.file ? `(\`${finding.file}\`)` : ''}: ${finding.description}`);
+      }
+      lines.push('');
+    }
+
+    // Recommendations
+    lines.push('## Prioritized Recommendations');
+    lines.push('');
+    lines.push('| Priority | Title | Severity |');
+    lines.push('|----------|-------|----------|');
+    for (const rec of recommendations.slice(0, 15)) {
+      lines.push(`| ${rec.priority} | ${rec.title} | ${rec.severity} |`);
+    }
+    lines.push('');
+
+    // Quality metrics
+    const qualityPhase = this.state?.phases.quality;
+    const qualityResult = qualityPhase?.result as { score?: number; totalFiles?: number; totalIssues?: number } | undefined;
+    if (qualityResult) {
+      lines.push('## Quality Metrics');
+      lines.push('');
+      lines.push(`- **Quality Score**: ${qualityResult.score ?? 0}/100`);
+      lines.push(`- **Total Files**: ${qualityResult.totalFiles ?? 0}`);
+      lines.push(`- **Total Issues**: ${qualityResult.totalIssues ?? 0}`);
+      lines.push('');
+    }
+
+    // Security summary
+    const securityPhase = this.state?.phases.security;
+    const securityResult = securityPhase?.result as { passed?: boolean; critical?: number; high?: number } | undefined;
+    if (securityResult) {
+      lines.push('## Security Summary');
+      lines.push('');
+      lines.push(`- **Status**: ${securityResult.passed ? 'PASSED' : 'NEEDS ATTENTION'}`);
+      lines.push(`- **Critical Issues**: ${securityResult.critical ?? 0}`);
+      lines.push(`- **High Issues**: ${securityResult.high ?? 0}`);
+      lines.push('');
+    }
+
+    lines.push('---');
+    lines.push('');
+    lines.push('*Generated by [Bootspring](https://bootspring.com)*');
+
+    return lines.join('\n');
+  }
+
+  /**
+   * Get workflow progress
+   */
+  getProgress(): AuditWorkflowProgress | null {
+    if (!this.state) return null;
+
+    const phases: AuditPhaseProgress[] = Object.entries(AUDIT_PHASES).map(([phaseId, phase]) => {
+      const phaseState = this.state?.phases[phaseId];
+      const status: AuditPhaseStatus = phaseState?.status ?? 'pending';
+
+      return {
+        id: phaseId,
+        name: phase.name,
+        description: phase.description,
+        order: phase.order,
+        required: phase.required,
+        status,
+        dependenciesMet: this.arePhaseDependenciesMet(phaseId)
+      };
+    });
+
+    const completedCount = phases.filter(p => p.status === 'completed').length;
+    const activeCount = phases.filter(p => p.status !== 'skipped').length;
+
+    // Count findings by severity
+    const findingsBySeverity = {
+      critical: 0,
+      high: 0,
+      medium: 0,
+      low: 0,
+      info: 0
+    };
+
+    for (const finding of this.state.findings) {
+      const severity = finding.severity ?? 'info';
+      const current = findingsBySeverity[severity];
+      if (current !== undefined) {
+        findingsBySeverity[severity] = current + 1;
+      }
+    }
+
+    return {
+      currentPhase: this.state.currentPhase,
+      startedAt: this.state.startedAt,
+      lastUpdated: this.state.lastUpdated,
+      phases,
+      overall: {
+        completed: completedCount,
+        total: activeCount,
+        percentage: activeCount > 0 ? Math.round((completedCount / activeCount) * 100) : 0
+      },
+      findings: {
+        total: this.state.findings.length,
+        ...findingsBySeverity
+      },
+      isComplete: completedCount === activeCount,
+      summary: this.state.summary
+    };
+  }
+
+  /**
+   * Get resume point
+   */
+  getResumePoint(): AuditResumePoint | null {
+    if (!this.state || !this.state.currentPhase) {
+      return null;
+    }
+
+    const phase = AUDIT_PHASES[this.state.currentPhase];
+    const phaseState = this.state.phases[this.state.currentPhase];
+
+    return {
+      phase: this.state.currentPhase,
+      phaseName: phase?.name,
+      phaseStatus: phaseState?.status,
+      lastUpdated: this.state.lastUpdated,
+      findingsCount: this.state.findings.length
+    };
+  }
+
+  /**
+   * Get exit code for CI mode
+   */
+  getExitCode(): number {
+    if (!this.state) return 1;
+
+    const criticalCount = this.state.findings.filter(f => f.severity === 'critical').length;
+    const highCount = this.state.findings.filter(f => f.severity === 'high').length;
+
+    if (criticalCount > 0) return 2;
+    if (highCount > 0) return 1;
+    return 0;
+  }
+}
+
+// ============================================================================
+// Factory Function
+// ============================================================================
+
+export function createAuditWorkflowEngine(
+  projectRoot: string,
+  options: AuditWorkflowOptions = {}
+): AuditWorkflowEngine {
+  return new AuditWorkflowEngine(projectRoot, options);
+}