pi-lens 2.2.9 → 3.0.0

package/commands/booboo.js

@@ -1,26 +1,89 @@
-import * as childProcess from "node:child_process";
 import * as nodeFs from "node:fs";
 import * as path from "node:path";
+import { EXCLUDED_DIRS, isTestFile } from "../clients/file-utils.js";
+import { validateProductionReadiness } from "../clients/production-readiness.js";
+import { buildProjectIndex, } from "../clients/project-index.js";
+import { detectProjectMetadata, formatProjectMetadata, getAvailableCommands, } from "../clients/project-metadata.js";
+import { RunnerTracker } from "../clients/runner-tracker.js";
+import { safeSpawn } from "../clients/safe-spawn.js";
 import { getSourceFiles } from "../clients/scan-utils.js";
+import { calculateSimilarity } from "../clients/state-matrix.js";
+import { TreeSitterClient } from "../clients/tree-sitter-client.js";
 const getExtensionDir = () => {
     if (typeof __dirname !== "undefined") {
         return __dirname;
     }
     return ".";
 };
+/**
+ * Centralized test file exclusion for booboo runners.
+ * Mirrors the dispatch system's skipTestFiles behavior.
+ */
+function shouldIncludeFile(filePath) {
+    return !isTestFile(filePath);
+}
+/** Standard test file glob exclusions for CLI tools */
+const _TEST_FILE_EXCLUDES = [
+    "!**/*.test.ts",
+    "!**/*.test.tsx",
+    "!**/*.test.js",
+    "!**/*.test.jsx",
+    "!**/*.spec.ts",
+    "!**/*.spec.tsx",
+    "!**/*.spec.js",
+    "!**/*.spec.jsx",
+    "!**/*.poc.test.ts",
+    "!**/*.poc.test.tsx",
+    "!**/test-utils.ts",
+    "!**/test-*.ts",
+    "!**/__tests__/**",
+    "!**/tests/**",
+    "!**/test/**",
+];
 export async function handleBooboo(args, ctx, clients, pi) {
     const targetPath = args.trim() || ctx.cwd || process.cwd();
-    ctx.ui.notify("🔍 Running full codebase review...", "info");
+    // Detect project metadata for richer reporting
+    const projectMeta = detectProjectMetadata(targetPath);
+    const metaDisplay = formatProjectMetadata(projectMeta);
+    ctx.ui.notify(`🔍 Running full codebase review...\n${metaDisplay}`, "info");
+    // Detect project type once for all runners
+    const isTsProject = nodeFs.existsSync(path.join(targetPath, "tsconfig.json"));
+    // Get available commands for the project
+    const availableCommands = getAvailableCommands(projectMeta);
+    // Load false positives from fix session to filter them out
+    const sessionFile = path.join(process.cwd(), ".pi-lens", "fix-session.json");
+    let falsePositives = [];
+    try {
+        const sessionData = JSON.parse(nodeFs.readFileSync(sessionFile, "utf-8") || "{}");
+        falsePositives = sessionData.falsePositives || [];
+    }
+    catch {
+        // No session file yet
+    }
+    // Helper to check if an issue is marked as false positive
+    const isFalsePositive = (category, file, line) => {
+        const fpKey = line !== undefined
+            ? `${category}:${file}:${line}`
+            : `${category}:${file}`;
+        return falsePositives.some((fp) => fp === fpKey || fp.startsWith(`${category}:${file}`));
+    };
     // Summary counts for terminal display
     const summaryItems = [];
     const fullReport = [];
     const timestamp = new Date().toISOString().replace(/[:.]/g, "-").slice(0, 19);
     const reviewDir = path.join(process.cwd(), ".pi-lens", "reviews");
-    // Part 1: Design smells via ast-grep
-    if (clients.astGrep.isAvailable()) {
+    // Initialize runner tracker (no per-runner progress to avoid UI overwriting)
+    const tracker = new RunnerTracker();
+    // Helper to format elapsed time
+    const formatElapsed = (ms) => ms < 1000 ? `${ms}ms` : `${(ms / 1000).toFixed(1)}s`;
+    // Runner 1: Design smells via ast-grep
+    await tracker.run("ast-grep (design smells)", async () => {
+        if (!clients.astGrep.isAvailable()) {
+            return { findings: 0, status: "skipped" };
+        }
         const configPath = path.join(getExtensionDir(), "..", "rules", "ast-grep-rules", ".sgconfig.yml");
         try {
-            const result = childProcess.spawnSync("npx", [
+            const result = safeSpawn("npx", [
                 "sg",
                 "scan",
                 "--config",
@@ -31,15 +94,28 @@ export async function handleBooboo(args, ctx, clients, pi) {
                 "--globs",
                 "!**/*.spec.ts",
                 "--globs",
+                "!**/*.poc.test.ts",
+                "--globs",
                 "!**/test-utils.ts",
                 "--globs",
+                "!**/test-*.ts",
+                "--globs",
+                "!**/__tests__/**",
+                "--globs",
+                "!**/tests/**",
+                "--globs",
                 "!**/.pi-lens/**",
+                "--globs",
+                "!**/.pi/**",
+                "--globs",
+                "!**/node_modules/**",
+                "--globs",
+                "!**/.git/**",
+                "--globs",
+                "!**/.ruff_cache/**",
                 targetPath,
             ], {
-                encoding: "utf-8",
                 timeout: 30000,
-                shell: true,
-                maxBuffer: 32 * 1024 * 1024, // 32MB
             });
             const output = result.stdout || result.stderr || "";
             if (output.trim() && result.status !== undefined) {
@@ -50,8 +126,7 @@ export async function handleBooboo(args, ctx, clients, pi) {
                         try {
                             return JSON.parse(trimmed);
                         }
-                        catch (err) {
-                            void err;
+                        catch {
                             return [];
                         }
                     }
@@ -59,8 +134,7 @@ export async function handleBooboo(args, ctx, clients, pi) {
                         try {
                             return [JSON.parse(l)];
                         }
-                        catch (err) {
-                            void err;
+                        catch {
                             return [];
                         }
                     });
@@ -74,45 +148,73 @@ export async function handleBooboo(args, ctx, clients, pi) {
                         item.range?.start?.line ||
                         0;
                     issues.push({
+                        file: item.file || item.path || targetPath,
                         line: lineNum + 1,
                         rule: ruleId,
                         message: message,
                     });
                 }
-                if (issues.length > 0) {
+                const filteredIssues = issues.filter((issue) => !isFalsePositive("ast_issues", issue.file, issue.line));
+                if (filteredIssues.length > 0) {
                     summaryItems.push({
                         category: "ast-grep",
-                        count: issues.length,
-                        severity: issues.length > 10 ? "🔴" : "🟡",
+                        count: filteredIssues.length,
+                        severity: filteredIssues.length > 10 ? "🔴" : "🟡",
                         fixable: true,
                     });
-                    let fullSection = `## ast-grep (Structural Issues)\n\n**${issues.length} issue(s) found**\n\n`;
+                    let fullSection = `## ast-grep (Structural Issues)\n\n**${filteredIssues.length} issue(s) found**\n\n`;
                     fullSection +=
                         "| Line | Rule | Message |\n|------|------|--------|\n";
-                    for (const issue of issues) {
+                    for (const issue of filteredIssues) {
                         fullSection += `| ${issue.line} | ${issue.rule} | ${issue.message} |\n`;
                     }
+                    fullSection += "\n### 💡 How to Fix\n\n";
+                    const seenRules = new Set();
+                    for (const issue of filteredIssues.slice(0, 5)) {
+                        if (seenRules.has(issue.rule))
+                            continue;
+                        seenRules.add(issue.rule);
+                        const ruleDesc = clients.astGrep.getRuleDescription?.(issue.rule);
+                        if (ruleDesc?.note || ruleDesc?.fix) {
+                            fullSection += `**${issue.rule}:**\n`;
+                            if (ruleDesc.note)
+                                fullSection += `${ruleDesc.note}\n\n`;
+                            if (ruleDesc.fix)
+                                fullSection += `Suggested fix:\n\`\`\`typescript\n${ruleDesc.fix}\n\`\`\`\n\n`;
+                        }
+                    }
                     fullReport.push(fullSection);
                 }
+                return { findings: filteredIssues.length, status: "done" };
             }
+            return { findings: 0, status: "done" };
         }
-        catch (err) {
-            const _err = err;
-            // Ignored
+        catch {
+            return { findings: 0, status: "error" };
+        }
+    });
+    // Runner 2: Similar functions
+    await tracker.run("ast-grep (similar functions)", async () => {
+        if (!clients.astGrep.isAvailable()) {
+            return { findings: 0, status: "skipped" };
         }
-    }
-    // Part 2: Similar functions
-    if (clients.astGrep.isAvailable()) {
         const similarGroups = await clients.astGrep.findSimilarFunctions(targetPath, "typescript");
-        if (similarGroups.length > 0) {
+        // Filter out test files using centralized exclusion
+        const filteredGroups = similarGroups
+            .map((group) => ({
+            ...group,
+            functions: group.functions.filter((fn) => shouldIncludeFile(fn.file)),
+        }))
+            .filter((group) => group.functions.length > 1); // Need at least 2 non-test functions
+        if (filteredGroups.length > 0) {
             summaryItems.push({
                 category: "Similar Functions",
-                count: similarGroups.length,
+                count: filteredGroups.length,
                 severity: "🟡",
                 fixable: true,
             });
-            let fullSection = `## Similar Functions\n\n**${similarGroups.length} group(s) of structurally similar functions**\n\n`;
-            for (const group of similarGroups) {
+            let fullSection = `## Similar Functions\n\n**${filteredGroups.length} group(s) of structurally similar functions**\n\n`;
+            for (const group of filteredGroups) {
                 fullSection += `### Pattern: ${group.functions.map((f) => f.name).join(", ")}\n\n`;
                 fullSection +=
                     "| Function | File | Line |\n|----------|------|------|\n";
@@ -123,18 +225,74 @@ export async function handleBooboo(args, ctx, clients, pi) {
             }
             fullReport.push(fullSection);
         }
-    }
-    // Part 3: Complexity metrics
-    const results = [];
-    const aiSlopIssues = [];
-    const isTsProject = nodeFs.existsSync(path.join(targetPath, "tsconfig.json"));
-    const files = getSourceFiles(targetPath, isTsProject);
-    for (const fullPath of files) {
-        if (clients.complexity.isSupportedFile(fullPath)) {
-            const metrics = clients.complexity.analyzeFile(fullPath);
-            if (metrics) {
-                results.push(metrics);
-                if (!/\.(test|spec)\.[jt]sx?$/.test(path.basename(fullPath))) {
+        return { findings: filteredGroups.length, status: "done" };
+    });
+    // Runner 3: Semantic similarity
+    await tracker.run("semantic similarity (Amain)", async () => {
+        try {
+            const { glob } = await import("glob");
+            const sourceFiles = await glob("**/*.ts", {
+                cwd: targetPath,
+                ignore: [
+                    "**/node_modules/**",
+                    "**/*.test.ts",
+                    "**/*.test.tsx",
+                    "**/*.spec.ts",
+                    "**/*.spec.tsx",
+                    "**/*.poc.test.ts",
+                    "**/*.poc.test.tsx",
+                    "**/test-utils.ts",
+                    "**/test-*.ts",
+                    "**/__tests__/**",
+                    "**/tests/**",
+                    "**/dist/**",
+                ],
+            });
+            if (sourceFiles.length === 0) {
+                return { findings: 0, status: "done" };
+            }
+            // Filter out test files using centralized exclusion
+            const absoluteFiles = sourceFiles
+                .map((f) => path.join(targetPath, f))
+                .filter(shouldIncludeFile);
+            const index = await buildProjectIndex(targetPath, absoluteFiles);
+            const topPairs = findTopSimilarPairs(index, 10);
+            if (topPairs.length > 0) {
+                summaryItems.push({
+                    category: "Semantic Duplicates",
+                    count: topPairs.length,
+                    severity: "🟡",
+                    fixable: true,
+                });
+                let fullSection = `## Semantic Duplicates (Amain Algorithm)\n\n`;
+                fullSection += `**${topPairs.length} pair(s) with >75% semantic similarity**\n\n`;
+                fullSection +=
+                    "Functions with different names/variables but similar logic structures.\n\n";
+                for (const pair of topPairs) {
+                    fullSection += `### ${pair.func1} ↔ ${pair.func2}\n\n`;
+                    fullSection += `- Similarity: **${(pair.similarity * 100).toFixed(1)}%**\n`;
+                    fullSection += `- Consider consolidating or extracting shared logic\n\n`;
+                }
+                fullReport.push(fullSection);
+            }
+            return { findings: topPairs.length, status: "done" };
+        }
+        catch (err) {
+            console.error("[booboo] Semantic similarity analysis failed:", err);
+            return { findings: 0, status: "error" };
+        }
+    });
+    // Runner 4: Complexity metrics
+    await tracker.run("complexity metrics", async () => {
+        const results = [];
+        const aiSlopIssues = [];
+        const files = getSourceFiles(targetPath, isTsProject).filter(shouldIncludeFile);
+        for (const fullPath of files) {
+            if (clients.complexity.isSupportedFile(fullPath)) {
+                const metrics = clients.complexity.analyzeFile(fullPath);
+                if (metrics) {
+                    results.push(metrics);
+                    // AI slop check - already filtered by shouldIncludeFile above
                     const warnings = clients.complexity.checkThresholds(metrics);
                     if (warnings.length > 0) {
                         aiSlopIssues.push(`  ${metrics.filePath}:`);
@@ -145,227 +303,439 @@ export async function handleBooboo(args, ctx, clients, pi) {
                 }
             }
         }
-    }
-    if (results.length > 0) {
-        const avgMI = results.reduce((a, b) => a + b.maintainabilityIndex, 0) / results.length;
-        const avgCognitive = results.reduce((a, b) => a + b.cognitiveComplexity, 0) / results.length;
-        const avgCyclomatic = results.reduce((a, b) => a + b.cyclomaticComplexity, 0) / results.length;
-        const maxNesting = Math.max(...results.map((r) => r.maxNestingDepth));
-        const maxCognitive = Math.max(...results.map((r) => r.cognitiveComplexity));
-        const minMI = Math.min(...results.map((r) => r.maintainabilityIndex));
-        const lowMI = results
-            .filter((r) => r.maintainabilityIndex < 60)
-            .sort((a, b) => a.maintainabilityIndex - b.maintainabilityIndex);
-        const highCognitive = results
-            .filter((r) => r.cognitiveComplexity > 20)
-            .sort((a, b) => b.cognitiveComplexity - a.cognitiveComplexity);
-        let _summary = `[Complexity] ${results.length} file(s) scanned\n`;
-        _summary += `  Maintainability: ${avgMI.toFixed(1)} avg | Cognitive: ${avgCognitive.toFixed(1)} avg | Max Nesting: ${maxNesting} levels\n`;
-        if (lowMI.length > 0) {
-            _summary += `\n  Low Maintainability (MI < 60):\n`;
-            for (const f of lowMI.slice(0, 5)) {
-                _summary += `    ✗ ${f.filePath}: MI ${f.maintainabilityIndex.toFixed(1)}\n`;
-            }
-            if (lowMI.length > 5)
-                _summary += `    ... and ${lowMI.length - 5} more\n`;
-        }
-        if (highCognitive.length > 0) {
-            _summary += `\n  High Cognitive Complexity (> 20):\n`;
-            for (const f of highCognitive.slice(0, 5)) {
-                _summary += `    ⚠ ${f.filePath}: ${f.cognitiveComplexity}\n`;
-            }
-            if (highCognitive.length > 5)
-                _summary += `    ... and ${highCognitive.length - 5} more\n`;
-        }
-        if (aiSlopIssues.length > 0) {
-            _summary += `\n[AI Slop Indicators]\n${aiSlopIssues.join("\n")}`;
-        }
-        // Add complexity summary items
-        if (lowMI.length > 0) {
-            summaryItems.push({
-                category: "Low MI",
-                count: lowMI.length,
-                severity: lowMI.some((f) => f.maintainabilityIndex < 20) ? "🔴" : "🟡",
-                fixable: false,
-            });
+        if (results.length > 0) {
+            const avgMI = results.reduce((a, b) => a + b.maintainabilityIndex, 0) /
+                results.length;
+            const avgCognitive = results.reduce((a, b) => a + b.cognitiveComplexity, 0) / results.length;
+            const avgCyclomatic = results.reduce((a, b) => a + b.cyclomaticComplexity, 0) /
+                results.length;
+            const maxNesting = Math.max(...results.map((r) => r.maxNestingDepth));
+            const maxCognitive = Math.max(...results.map((r) => r.cognitiveComplexity));
+            const minMI = Math.min(...results.map((r) => r.maintainabilityIndex));
+            // Only flag files with EXTREME issues (tuned to reduce false positives)
+            // MI < 20 is "critically unmaintainable" (was < 40, too aggressive)
+            const severeLowMI = results
+                .filter((r) => r.maintainabilityIndex < 20 && !isTestFile(r.filePath))
+                .sort((a, b) => a.maintainabilityIndex - b.maintainabilityIndex);
+            // Cognitive > 80 is extreme (was > 30, flagged too many files)
+            const veryHighCognitive = results
+                .filter((r) => r.cognitiveComplexity > 80 && !isTestFile(r.filePath))
+                .sort((a, b) => b.cognitiveComplexity - a.cognitiveComplexity);
+            // Deep nesting > 8 levels is extreme (was > 5, normal code hits this)
+            const deepNesting = results
+                .filter((r) => r.maxNestingDepth > 8 && !isTestFile(r.filePath))
+                .sort((a, b) => b.maxNestingDepth - a.maxNestingDepth);
+            let findings = 0;
+            if (severeLowMI.length > 0) {
+                findings += severeLowMI.length;
+                summaryItems.push({
+                    category: "Low Maintainability",
+                    count: severeLowMI.length,
+                    severity: "🔴",
+                    fixable: false,
+                });
+            }
+            if (veryHighCognitive.length > 0) {
+                findings += veryHighCognitive.length;
+                summaryItems.push({
+                    category: "Very High Complexity",
+                    count: veryHighCognitive.length,
+                    severity: "🔴",
+                    fixable: true,
+                });
+            }
+            if (deepNesting.length > 0) {
+                findings += deepNesting.length;
+                summaryItems.push({
+                    category: "Deep Nesting",
+                    count: deepNesting.length,
+                    severity: "🟡",
+                    fixable: true,
+                });
+            }
+            if (aiSlopIssues.length > 0) {
+                findings += Math.floor(aiSlopIssues.length / 2);
+                summaryItems.push({
+                    category: "AI Slop",
+                    count: Math.floor(aiSlopIssues.length / 2),
+                    severity: "🟡",
+                    fixable: true,
+                });
+            }
+            let fullSection = `## Complexity Metrics\n\n**${results.length} file(s) scanned**\n\n`;
+            fullSection += `### Summary\n\n| Metric | Value |\n|--------|-------|\n`;
+            fullSection += `| Avg Maintainability Index | ${avgMI.toFixed(1)} |\n`;
+            fullSection += `| Min Maintainability Index | ${minMI.toFixed(1)} |\n`;
+            fullSection += `| Avg Cognitive Complexity | ${avgCognitive.toFixed(1)} |\n`;
+            fullSection += `| Max Cognitive Complexity | ${maxCognitive} |\n`;
+            fullSection += `| Avg Cyclomatic Complexity | ${avgCyclomatic.toFixed(1)} |\n`;
+            fullSection += `| Max Nesting Depth | ${maxNesting} |\n`;
+            fullSection += `| Total Files | ${results.length} |\n\n`;
+            // Report severe issues (thresholds match findings count)
+            if (severeLowMI.length > 0) {
+                fullSection += `### Low Maintainability (MI < 40)\n\n| File | MI | Cognitive | Cyclomatic | Nesting |\n|------|-----|-----------|------------|--------|\n`;
+                for (const f of severeLowMI) {
+                    fullSection += `| ${f.filePath} | ${f.maintainabilityIndex.toFixed(1)} | ${f.cognitiveComplexity} | ${f.cyclomaticComplexity} | ${f.maxNestingDepth} |\n`;
+                }
+                fullSection += "\n";
+            }
+            if (veryHighCognitive.length > 0) {
+                fullSection += `### Very High Cognitive Complexity (> 30)\n\n| File | Cognitive | MI | Cyclomatic | Nesting |\n|------|-----------|-----|------------|--------|\n`;
+                for (const f of veryHighCognitive) {
+                    fullSection += `| ${f.filePath} | ${f.cognitiveComplexity} | ${f.maintainabilityIndex.toFixed(1)} | ${f.cyclomaticComplexity} | ${f.maxNestingDepth} |\n`;
+                }
+                fullSection += "\n";
+            }
+            if (deepNesting.length > 0) {
+                fullSection += `### Deep Nesting (> 5 levels)\n\n| File | Nesting | Cognitive | MI |\n|------|---------|-----------|-----|\n`;
+                for (const f of deepNesting) {
+                    fullSection += `| ${f.filePath} | ${f.maxNestingDepth} | ${f.cognitiveComplexity} | ${f.maintainabilityIndex.toFixed(1)} |\n`;
+                }
+                fullSection += "\n";
+            }
+            // Only show "All Files" table in verbose mode - it's informational noise
+            if (pi.getFlag("lens-verbose")) {
+                fullSection += `### All Files\n\n| File | MI | Cognitive | Cyclomatic | Nesting | Entropy |\n|------|-----|-----------|------------|---------|--------|\n`;
+                for (const f of results.sort((a, b) => a.maintainabilityIndex - b.maintainabilityIndex)) {
+                    fullSection += `| ${f.filePath} | ${f.maintainabilityIndex.toFixed(1)} | ${f.cognitiveComplexity} | ${f.cyclomaticComplexity} | ${f.maxNestingDepth} | ${f.codeEntropy.toFixed(2)} |\n`;
+                }
+                fullSection += "\n";
+            }
+            if (aiSlopIssues.length > 0) {
+                fullSection += `### AI Slop Indicators\n\n`;
+                for (const issue of aiSlopIssues) {
+                    fullSection += `${issue}\n`;
+                }
+                fullSection += "\n";
+            }
+            fullReport.push(fullSection);
+            return { findings, status: "done" };
         }
-        if (highCognitive.length > 0) {
-            summaryItems.push({
-                category: "High Complexity",
-                count: highCognitive.length,
+        return { findings: 0, status: "done" };
+    });
+    // Runner 4: Tree-sitter patterns (complementary to ast-grep)
+    // - Falls back to tree-sitter if ast-grep unavailable
+    // - Detects patterns ast-grep can't easily do (multi-statement, complex nesting)
+    // - Captures values for richer reporting
+    await tracker.run("tree-sitter patterns", async () => {
+        const client = new TreeSitterClient();
+        if (!client.isAvailable()) {
+            return { findings: 0, status: "skipped" };
+        }
+        const languageId = isTsProject ? "typescript" : "javascript";
+        let findings = 0;
+        const structuralIssues = [];
+        // Only run basic patterns if ast-grep is NOT available (avoid duplication)
+        const astGrepAvailable = clients.astGrep.isAvailable();
+        if (!astGrepAvailable) {
+            // Fallback: console.log detection (ast-grep normally handles this)
+            const consoleLogs = await client.structuralSearch("console.$METHOD($MSG)", languageId, targetPath, { maxResults: 30, fileFilter: shouldIncludeFile });
+            for (const match of consoleLogs) {
+                const method = match.captures.METHOD || "log";
+                if (["log", "debug", "info", "warn"].includes(method)) {
+                    structuralIssues.push({
+                        file: match.file,
+                        line: match.line,
+                        pattern: `console.${method}()`,
+                        severity: "🟡",
+                        fixable: true,
+                        note: astGrepAvailable
+                            ? undefined
+                            : "(fallback - ast-grep not available)",
+                    });
+                    findings++;
+                }
+            }
+        }
+        // Pattern 1: Nested promise chains (ast-grep struggles with multi-statement nesting)
+        // This detects: .then().catch().then() chains that could be async/await
+        const promiseChains = await client.structuralSearch("$PROMISE.then($$$HANDLER1).catch($$$HANDLER2).then($$$HANDLER3)", languageId, targetPath, { maxResults: 20, fileFilter: shouldIncludeFile });
+        for (const match of promiseChains) {
+            structuralIssues.push({
+                file: match.file,
+                line: match.line,
+                pattern: "deep promise chain (3+ levels)",
                 severity: "🟡",
                 fixable: true,
+                note: "Consider converting to async/await for readability",
             });
+            findings++;
         }
-        if (aiSlopIssues.length > 0) {
-            summaryItems.push({
-                category: "AI Slop",
-                count: (aiSlopIssues.length / 2) | 0,
+        // Pattern 2: Callback pyramids (error-first callbacks nested 3+ levels)
+        const callbackPyramids = await client.structuralSearch("$FUNC($$$ARGS, ($ERR, $$$PARAMS) => { $$$BODY })", languageId, targetPath, { maxResults: 20, fileFilter: shouldIncludeFile });
+        // Filter for actual callback nesting (error parameter pattern)
+        const nestedCallbacks = callbackPyramids.filter((m) => {
+            const body = m.captures.BODY || "";
+            // Check if body contains another callback
+            return body.includes("(") && body.includes("=>");
+        });
+        for (const match of nestedCallbacks.slice(0, 10)) {
+            structuralIssues.push({
+                file: match.file,
+                line: match.line,
+                pattern: "callback pyramid (error-first pattern)",
                 severity: "🟡",
                 fixable: true,
-            }); // Each issue is 2 lines
-        }
-        let fullSection = `## Complexity Metrics\n\n**${results.length} file(s) scanned**\n\n`;
-        fullSection += `### Summary\n\n| Metric | Value |\n|--------|-------|\n| Avg Maintainability Index | ${avgMI.toFixed(1)} |\n| Min Maintainability Index | ${minMI.toFixed(1)} |\n| Avg Cognitive Complexity | ${avgCognitive.toFixed(1)} |\n| Max Cognitive Complexity | ${maxCognitive} |\n| Avg Cyclomatic Complexity | ${avgCyclomatic.toFixed(1)} |\n| Max Nesting Depth | ${maxNesting} |\n| Total Files | ${results.length} |\n\n`;
-        if (lowMI.length > 0) {
-            fullSection += `### Low Maintainability (MI < 60)\n\n| File | MI | Cognitive | Cyclomatic | Nesting |\n|------|-----|-----------|------------|--------|\n`;
-            for (const f of lowMI) {
-                fullSection += `| ${f.filePath} | ${f.maintainabilityIndex.toFixed(1)} | ${f.cognitiveComplexity} | ${f.cyclomaticComplexity} | ${f.maxNestingDepth} |\n`;
-            }
-            fullSection += "\n";
+                note: "Consider promisify + async/await",
+            });
+            findings++;
         }
-        if (highCognitive.length > 0) {
-            fullSection += `### High Cognitive Complexity (> 20)\n\n| File | Cognitive | MI | Cyclomatic | Nesting |\n|------|-----------|-----|------------|--------|\n`;
-            for (const f of highCognitive) {
-                fullSection += `| ${f.filePath} | ${f.cognitiveComplexity} | ${f.maintainabilityIndex.toFixed(1)} | ${f.cyclomaticComplexity} | ${f.maxNestingDepth} |\n`;
+        // Pattern 3: Mixed async patterns (async function + .then() + callback)
+        // Detects inconsistent async styles in same function
+        const asyncFunctions = await client.structuralSearch("async function $NAME($$$PARAMS) { $BODY }", languageId, targetPath, { maxResults: 50, fileFilter: shouldIncludeFile });
+        for (const match of asyncFunctions) {
+            const body = match.captures.BODY || "";
+            // Check if async function uses both await and .then()
+            const hasAwait = body.includes("await");
+            const hasThen = body.match(/\.\s*then\s*\(/);
+            if (hasAwait && hasThen) {
+                structuralIssues.push({
+                    file: match.file,
+                    line: match.line,
+                    pattern: "mixed async/await + promise chains",
+                    severity: "🟡",
+                    fixable: true,
+                    note: "Use consistent async style (prefer await)",
+                });
+                findings++;
             }
-            fullSection += "\n";
         }
-        fullSection += `### All Files\n\n| File | MI | Cognitive | Cyclomatic | Nesting | Entropy |\n|------|-----|-----------|------------|---------|--------|\n`;
-        for (const f of results.sort((a, b) => a.maintainabilityIndex - b.maintainabilityIndex)) {
-            fullSection += `| ${f.filePath} | ${f.maintainabilityIndex.toFixed(1)} | ${f.cognitiveComplexity} | ${f.cyclomaticComplexity} | ${f.maxNestingDepth} | ${f.codeEntropy.toFixed(2)} |\n`;
+        // Pattern 4: Complex nested if/else (ast-grep can do this, but tree-sitter captures entire block)
+        const deepIfs = await client.structuralSearch("if ($COND1) { if ($COND2) { if ($COND3) { $$$BODY } } }", languageId, targetPath, { maxResults: 15, fileFilter: shouldIncludeFile });
+        for (const match of deepIfs) {
+            structuralIssues.push({
+                file: match.file,
+                line: match.line,
+                pattern: "deeply nested conditionals (3+ levels)",
+                severity: "🟡",
+                fixable: true,
+                note: "Consider early returns or guard clauses",
+            });
+            findings++;
         }
-        fullSection += "\n";
-        if (aiSlopIssues.length > 0) {
-            fullSection += `### AI Slop Indicators\n\n`;
-            for (const issue of aiSlopIssues) {
-                fullSection += `${issue}\n`;
+        // Add to summary if issues found
+        if (findings > 0) {
+            summaryItems.push({
+                category: astGrepAvailable
+                    ? "Advanced Structural"
+                    : "Structural Patterns (fallback)",
+                count: findings,
+                severity: "🟡",
+                fixable: true,
+            });
+            // Build detailed report
+            let fullSection = `## ${astGrepAvailable ? "Advanced Structural" : "Structural Patterns"} (Tree-sitter)\n\n`;
+            fullSection += `**${findings} issue(s) found**`;
+            if (!astGrepAvailable) {
+                fullSection += ` *(ast-grep not available - showing basic + advanced patterns)*`;
             }
-            fullSection += "\n";
+            fullSection += `\n\n`;
+            // Group by pattern type
+            const byPattern = {};
+            for (const issue of structuralIssues) {
+                if (!byPattern[issue.pattern])
+                    byPattern[issue.pattern] = [];
+                byPattern[issue.pattern].push(issue);
+            }
+            for (const [pattern, issues] of Object.entries(byPattern)) {
+                fullSection += `### ${pattern} (${issues.length})\n\n`;
+                fullSection += "| File | Line | Note |\n|------|------|------|\n";
+                for (const issue of issues.slice(0, 10)) {
+                    fullSection += `| ${issue.file} | ${issue.line} | ${issue.note || ""} |\n`;
+                }
+                if (issues.length > 10) {
+                    fullSection += `| ... | ... | ... |\n`;
+                }
+                fullSection += "\n";
+            }
+            fullReport.push(fullSection);
         }
-        fullReport.push(fullSection);
-    }
-    // Part 4: TODOs
-    const todoResult = clients.todo.scanDirectory(targetPath);
-    if (todoResult.items.length > 0) {
-        summaryItems.push({
-            category: "TODOs",
-            count: todoResult.items.length,
-            severity: "ℹ️",
-            fixable: false,
-        });
-        let fullSection = `## TODOs / Annotations\n\n`;
+        return { findings, status: "done" };
+    });
+    // Runner 5: TODOs
+    await tracker.run("TODO scanner", async () => {
+        const todoResult = clients.todo.scanDirectory(targetPath);
         if (todoResult.items.length > 0) {
-            fullSection += `**${todoResult.items.length} annotation(s) found**\n\n| Type | File | Line | Text |\n|------|------|------|------|\n`;
+            summaryItems.push({
+                category: "TODOs",
+                count: todoResult.items.length,
+                severity: "ℹ️",
+                fixable: false,
+            });
+            let fullSection = `## TODOs / Annotations\n\n`;
+            fullSection += `**${todoResult.items.length} annotation(s) found**\n\n`;
+            fullSection +=
+                "| Type | File | Line | Text |\n|------|------|------|------|\n";
             for (const item of todoResult.items) {
                 fullSection += `| ${item.type} | ${item.file} | ${item.line} | ${item.message} |\n`;
             }
+            fullSection += "\n";
+            fullReport.push(fullSection);
         }
-        else {
-            fullSection += `No annotations found.\n`;
+        return { findings: todoResult.items.length, status: "done" };
+    });
+    // Runner 6: Dead code
+    await tracker.run("dead code (Knip)", async () => {
+        if (!clients.knip.isAvailable()) {
+            return { findings: 0, status: "skipped" };
         }
-        fullSection += "\n";
-        fullReport.push(fullSection);
-    }
-    // Part 5: Dead code
-    if (clients.knip.isAvailable()) {
-        const knipResult = clients.knip.analyze(targetPath);
-        if (knipResult.issues.length > 0) {
+        // Exclude test files from Knip analysis
+        const knipResult = clients.knip.analyze(targetPath, [
+            "**/*.test.ts",
+            "**/*.test.tsx",
+            "**/*.test.js",
+            "**/*.spec.ts",
+            "**/*.spec.tsx",
+            "**/*.spec.js",
+            "**/*.poc.test.ts",
+            "**/*.poc.test.tsx",
+            "**/__tests__/**",
+            "**/tests/**",
+        ]);
+        // Filter out test file issues as additional safeguard
+        const filteredIssues = knipResult.issues.filter((issue) => !issue.file || shouldIncludeFile(issue.file));
+        if (filteredIssues.length > 0) {
             summaryItems.push({
                 category: "Dead Code",
-                count: knipResult.issues.length,
+                count: filteredIssues.length,
                 severity: "🟡",
                 fixable: true,
             });
             let fullSection = `## Dead Code (Knip)\n\n`;
-            if (knipResult.issues.length > 0) {
-                fullSection += `**${knipResult.issues.length} issue(s) found**\n\n| Type | Name | File |\n|------|------|------|\n`;
-                for (const issue of knipResult.issues) {
-                    fullSection += `| ${issue.type} | ${issue.name} | ${issue.file ?? ""} |\n`;
-                }
-            }
-            else {
-                fullSection += `No dead code issues found.\n`;
+            fullSection += `**${filteredIssues.length} issue(s) found**\n\n`;
+            fullSection += "| Type | Name | File |\n|------|------|------|\n";
+            for (const issue of filteredIssues) {
+                fullSection += `| ${issue.type} | ${issue.name} | ${issue.file ?? ""} |\n`;
             }
             fullSection += "\n";
             fullReport.push(fullSection);
         }
-    }
-    // Part 6: Duplicate code
-    if (clients.jscpd.isAvailable()) {
-        const jscpdResult = clients.jscpd.scan(targetPath);
-        if (jscpdResult.clones.length > 0) {
+        return { findings: filteredIssues.length, status: "done" };
+    });
+    // Runner 7: Duplicate code
+    await tracker.run("duplicate code (jscpd)", async () => {
+        if (!clients.jscpd.isAvailable()) {
+            return { findings: 0, status: "skipped" };
+        }
+        // In TS projects, exclude .js files (they're compiled artifacts)
+        const jscpdResult = clients.jscpd.scan(targetPath, 5, 50, isTsProject);
+        // Filter out test file duplicates using centralized exclusion
+        const filteredClones = jscpdResult.clones.filter((dup) => shouldIncludeFile(dup.fileA) && shouldIncludeFile(dup.fileB));
+        if (filteredClones.length > 0) {
             summaryItems.push({
                 category: "Duplicates",
-                count: jscpdResult.clones.length,
+                count: filteredClones.length,
                 severity: "🟡",
                 fixable: true,
             });
             let fullSection = `## Code Duplication (jscpd)\n\n`;
-            if (jscpdResult.clones.length > 0) {
-                fullSection += `**${jscpdResult.clones.length} duplicate block(s) found** (${jscpdResult.duplicatedLines}/${jscpdResult.totalLines} lines, ${jscpdResult.percentage.toFixed(1)}%)\n\n| File A | Line A | File B | Line B | Lines | Tokens |\n|--------|--------|--------|--------|-------|--------|\n`;
-                for (const dup of jscpdResult.clones) {
-                    fullSection += `| ${dup.fileA} | ${dup.startA} | ${dup.fileB} | ${dup.startB} | ${dup.lines} | ${dup.tokens} |\n`;
-                }
-            }
-            else {
-                fullSection += `No duplicate code found.\n`;
+            fullSection += `**${filteredClones.length} duplicate block(s) found** (${jscpdResult.duplicatedLines}/${jscpdResult.totalLines} lines, ${jscpdResult.percentage.toFixed(1)}%)\n\n`;
+            fullSection +=
+                "| File A | Line A | File B | Line B | Lines | Tokens |\n|--------|--------|--------|--------|-------|--------|\n";
+            for (const dup of filteredClones) {
+                fullSection += `| ${dup.fileA} | ${dup.startA} | ${dup.fileB} | ${dup.startB} | ${dup.lines} | ${dup.tokens} |\n`;
             }
             fullSection += "\n";
             fullReport.push(fullSection);
         }
-    }
-    // Part 7: Type coverage
-    if (clients.typeCoverage.isAvailable()) {
+        return { findings: filteredClones.length, status: "done" };
+    });
+    // Runner 8: Type coverage
+    await tracker.run("type coverage", async () => {
+        if (!clients.typeCoverage.isAvailable()) {
+            return { findings: 0, status: "skipped" };
+        }
         const tcResult = clients.typeCoverage.scan(targetPath);
         if (tcResult.percentage < 100) {
-            const untyped = tcResult.total - tcResult.typed;
+            // Filter out test file locations using centralized exclusion
+            const filteredLocations = tcResult.untypedLocations.filter((u) => shouldIncludeFile(u.file));
+            const filesWithLowCoverage = new Set(filteredLocations
+                .filter(() => tcResult.percentage < 90)
+                .map((u) => u.file)).size;
             summaryItems.push({
-                category: "Untyped",
-                count: untyped,
+                category: "Type Coverage",
+                count: filesWithLowCoverage || 1,
                 severity: tcResult.percentage < 90 ? "🟡" : "ℹ️",
                 fixable: false,
             });
             let fullSection = `## Type Coverage\n\n**${tcResult.percentage.toFixed(1)}% typed** (${tcResult.typed}/${tcResult.total} identifiers)\n\n`;
-            if (tcResult.untypedLocations.length > 0) {
-                fullSection += `### Untyped Identifiers\n\n| File | Line | Column | Name |\n|------|------|--------|------|\n`;
-                for (const u of tcResult.untypedLocations) {
-                    fullSection += `| ${u.file} | ${u.line} | ${u.column} | ${u.name} |\n`;
+            const byFile = {};
+            for (const u of filteredLocations) {
+                byFile[u.file] = (byFile[u.file] || 0) + 1;
+            }
+            const sortedFiles = Object.entries(byFile)
+                .filter(([file]) => shouldIncludeFile(file))
+                .sort((a, b) => b[1] - a[1])
+                .slice(0, 10);
+            if (sortedFiles.length > 0) {
+                fullSection += `### Top Files by Untyped Count\n\n| File | Untyped Count |\n|------|---------------|\n`;
+                for (const [file, count] of sortedFiles) {
+                    fullSection += `| ${file} | ${count} |\n`;
+                }
+                if (Object.keys(byFile).length > 10) {
+                    fullSection += `| ... | +${Object.keys(byFile).length - 10} more files |\n`;
                 }
             }
             fullSection += "\n";
             fullReport.push(fullSection);
+            return { findings: filesWithLowCoverage || 1, status: "done" };
+        }
+        return { findings: 0, status: "done" };
+    });
+    // Runner 9: Circular deps
+    await tracker.run("circular deps (Madge)", async () => {
+        if (pi.getFlag("no-madge") || !clients.depChecker.isAvailable()) {
+            return { findings: 0, status: "skipped" };
         }
-    }
-    // Part 8: Circular deps
-    if (!pi.getFlag("no-madge") && clients.depChecker.isAvailable()) {
         const { circular } = clients.depChecker.scanProject(targetPath);
-        if (circular.length > 0) {
+        // Filter out circular deps involving only test files using centralized exclusion
+        const filteredCircular = circular.filter((dep) => {
+            // Keep if ANY file in the chain is not a test file
+            return dep.path.some((file) => shouldIncludeFile(file));
+        });
+        if (filteredCircular.length > 0) {
             summaryItems.push({
                 category: "Circular Deps",
-                count: circular.length,
+                count: filteredCircular.length,
                 severity: "🔴",
                 fixable: false,
             });
-            let fullSection = `## Circular Dependencies (Madge)\n\n**${circular.length} circular chain(s) found**\n\n`;
-            for (const dep of circular) {
+            let fullSection = `## Circular Dependencies (Madge)\n\n`;
+            fullSection += `**${filteredCircular.length} circular chain(s) found**\n\n`;
+            for (const dep of filteredCircular) {
                 fullSection += `- ${dep.path.join(" → ")}\n`;
             }
             fullReport.push(`${fullSection}\n`);
         }
-    }
-    // Part 9: Arch rules
-    if (!clients.architect.hasConfig()) {
-        clients.architect.loadConfig(process.cwd());
-    }
-    if (clients.architect.hasConfig()) {
+        return { findings: filteredCircular.length, status: "done" };
+    });
+    // Runner 10: Arch rules
+    await tracker.run("architectural rules", async () => {
+        if (!clients.architect.hasConfig()) {
+            clients.architect.loadConfig(process.cwd());
+        }
+        if (!clients.architect.hasConfig()) {
+            return { findings: 0, status: "skipped" };
+        }
+        // Detect TypeScript project - skip .js files in TS projects (compiled artifacts)
+        const isTsProject = nodeFs.existsSync(path.join(targetPath, "tsconfig.json"));
         const archViolations = [];
         const archScanDir = (dir) => {
             for (const entry of nodeFs.readdirSync(dir, { withFileTypes: true })) {
                 const full = path.join(dir, entry.name);
                 if (entry.isDirectory()) {
-                    if ([
-                        "node_modules",
-                        ".git",
-                        "dist",
-                        "build",
-                        ".next",
-                        ".pi-lens",
-                    ].includes(entry.name))
+                    if (EXCLUDED_DIRS.includes(entry.name))
                         continue;
                     archScanDir(full);
                 }
                 else if (/\.(ts|tsx|js|jsx|py|go|rs)$/.test(entry.name)) {
+                    if (isTestFile(full))
+                        continue;
+                    // In TS projects, skip .js files (they're compiled artifacts)
+                    if (isTsProject &&
+                        /\.(js|jsx)$/.test(entry.name) &&
+                        nodeFs.existsSync(full.replace(/\.(js|jsx)$/, ".ts")))
+                        continue;
                     const relPath = path.relative(targetPath, full).replace(/\\/g, "/");
                     const content = nodeFs.readFileSync(full, "utf-8");
                     const lineCount = content.split("\n").length;
@@ -386,44 +756,254 @@ export async function handleBooboo(args, ctx, clients, pi) {
                 severity: "🔴",
                 fixable: false,
             });
-            let fullSection = `## Architectural Rules\n\n**${archViolations.length} violation(s) found**\n\n`;
+            let fullSection = `## Architectural Rules\n\n`;
+            fullSection += `**${archViolations.length} violation(s) found**\n\n`;
             for (const v of archViolations) {
                 fullSection += `- **${v.file}**: ${v.message}\n`;
             }
             fullReport.push(`${fullSection}\n`);
         }
-    }
+        return { findings: archViolations.length, status: "done" };
+    });
+    // Runner 11: Production Readiness (inspired by pi-validate)
+    await tracker.run("production readiness", async () => {
+        const readiness = validateProductionReadiness(targetPath);
+        // Add to summary if not perfect
+        if (readiness.overallScore < 100) {
+            const severity = readiness.grade === "A"
+                ? "🟢"
+                : readiness.grade === "B"
+                    ? "🟢"
+                    : readiness.grade === "C"
+                        ? "🟡"
+                        : "🟠";
+            // Count issues across all categories
+            const totalIssues_ = Object.values(readiness.categories).reduce((sum, cat) => sum + cat.issues.length, 0);
+            if (totalIssues_ > 0) {
+                summaryItems.push({
+                    category: "Production Readiness",
+                    count: totalIssues_,
+                    severity: severity,
+                    fixable: true,
+                });
+            }
+        }
+        // Add to full report
+        let section = `## Production Readiness\n\n`;
+        section += `**Score:** ${readiness.overallScore}/100 **Grade:** ${readiness.grade}\n\n`;
+        for (const [key, cat] of Object.entries(readiness.categories)) {
+            section += `### ${key.charAt(0).toUpperCase() + key.slice(1)} (${cat.score}/100)\n\n`;
+            if (cat.details.length > 0) {
+                for (const detail of cat.details) {
+                    section += `- ${detail}\n`;
+                }
+            }
+            if (cat.issues.length > 0) {
+                for (const issue of cat.issues) {
+                    section += `- ⚠️ ${issue}\n`;
+                }
+            }
+            if (cat.details.length === 0 && cat.issues.length === 0) {
+                section += `- ✅ No issues\n`;
+            }
+            section += "\n";
+        }
+        fullReport.push(section);
+        // Add metadata to report
+        const criticalIssues = [];
+        for (const [key, cat] of Object.entries(readiness.categories)) {
+            for (const issue of cat.issues) {
+                // Flag critical issues
+                if (key === "code" && issue.includes("debugger")) {
+                    criticalIssues.push(`[CRITICAL] ${issue}`);
+                }
+                else if (key === "tests" && cat.score < 50) {
+                    criticalIssues.push(`[CRITICAL] No tests found`);
+                }
+            }
+        }
+        return {
+            findings: Object.values(readiness.categories).reduce((sum, cat) => sum + cat.issues.length, 0),
+            status: "done",
+        };
+    });
+    // --- Create structured JSON report ---
     nodeFs.mkdirSync(reviewDir, { recursive: true });
     const projectName = path.basename(process.cwd());
-    const mdReport = `# Code Review: ${projectName}\n\n**Scanned:** ${new Date().toISOString()}\n\n**Path:** \`${targetPath}\`\n\n---\n\n${fullReport.join("\n")}`;
-    const reportPath = path.join(reviewDir, `booboo-${timestamp}.md`);
-    nodeFs.writeFileSync(reportPath, mdReport, "utf-8");
-    // Build summary table for terminal
+    const totalIssues = summaryItems.reduce((sum, s) => sum + s.count, 0);
+    const fixableCount = summaryItems
+        .filter((s) => s.fixable)
+        .reduce((sum, s) => sum + s.count, 0);
+    const refactorNeeded = summaryItems
+        .filter((s) => !s.fixable)
+        .reduce((sum, s) => sum + s.count, 0);
+    // Build runner summary
+    const runnerSummary = tracker.getRunners().map((r) => ({
+        name: r.name,
+        status: r.status,
+        findings: r.findings,
+        time: formatElapsed(r.elapsedMs),
+    }));
+    const jsonReport = {
+        meta: {
+            timestamp: new Date().toISOString(),
+            project: projectName,
+            path: targetPath,
+            totalIssues,
+            fixableCount,
+            refactorNeeded,
+            // New: runner execution details
+            runners: runnerSummary,
+            totalTime: formatElapsed(runnerSummary.reduce((sum, r) => {
+                const ms = r.time.endsWith("ms")
+                    ? parseInt(r.time, 10)
+                    : parseFloat(r.time) * 1000;
+                return sum + (Number.isNaN(ms) ? 0 : ms);
+            }, 0)),
+        },
+        // New: project metadata
+        project: {
+            type: projectMeta.type,
+            name: projectMeta.name,
+            version: projectMeta.version,
+            packageManager: projectMeta.packageManager,
+            languages: projectMeta.languages,
+            hasTests: projectMeta.hasTests,
+            testFramework: projectMeta.testFramework,
+            hasLinting: projectMeta.hasLinting,
+            linter: projectMeta.linter,
+            hasFormatting: projectMeta.hasFormatting,
+            formatter: projectMeta.formatter,
+            hasTypeScript: projectMeta.hasTypeScript,
+            configFiles: projectMeta.configFiles,
+            scripts: projectMeta.scripts,
+        },
+        // New: available commands for the project
+        commands: availableCommands,
+        byCategory: summaryItems.reduce((acc, item) => {
+            acc[item.category] = {
+                count: item.count,
+                severity: item.severity,
+                fixable: item.fixable,
+                falsePositivePrefix: `${item.category.toLowerCase().replace(/\s+/g, "-")}:`,
+            };
+            return acc;
+        }, {}),
+        howToMarkFalsePositive: {
+            command: "Ignore via AGENTS.md rules or suppress comments",
+            format: "Add to .claude/rules or use biome/oxlint ignore comments",
+            examples: [
+                "// biome-ignore lint/suspicious/noConsole: intentional debug",
+                "// oxlint-disable-next-line no-console",
+            ],
+        },
+        sessionFile: path.join(process.cwd(), ".pi-lens", "fix-session.json"),
+        details: fullReport.join("\n"),
+    };
+    const jsonPath = path.join(reviewDir, `booboo-${timestamp}.json`);
+    nodeFs.writeFileSync(jsonPath, JSON.stringify(jsonReport, null, 2), "utf-8");
+    // --- Create markdown report ---
+    // Build project info section
+    let projectSection = `## Project Info\n\n**Type:** ${projectMeta.type}`;
+    if (projectMeta.name)
+        projectSection += ` | **Name:** ${projectMeta.name}`;
+    if (projectMeta.version)
+        projectSection += ` | **Version:** ${projectMeta.version}`;
+    if (projectMeta.packageManager)
+        projectSection += `\n**Package Manager:** ${projectMeta.packageManager}`;
+    if (projectMeta.languages.length > 0)
+        projectSection += `\n**Languages:** ${projectMeta.languages.join(", ")}`;
+    // Tools
+    const tools = [];
+    if (projectMeta.testFramework)
+        tools.push(`🧪 ${projectMeta.testFramework}`);
+    else if (projectMeta.hasTests)
+        tools.push("🧪 tests");
+    if (projectMeta.linter)
+        tools.push(`🔍 ${projectMeta.linter}`);
+    if (projectMeta.formatter)
+        tools.push(`✨ ${projectMeta.formatter}`);
+    if (tools.length > 0)
+        projectSection += `\n**Tools:** ${tools.join(" | ")}`;
+    // Available commands
+    if (availableCommands.length > 0) {
+        projectSection += `\n\n### Available Commands\n\n| Action | Command |\n|--------|---------|`;
+        for (const cmd of availableCommands) {
+            projectSection += `\n| ${cmd.action} | \`${cmd.command}\` |`;
+        }
+    }
+    const mdReport = `# Code Review: ${projectName}
+
+**Scanned:** ${jsonReport.meta.timestamp}
+**Path:** \`${targetPath}\`
+**Summary:** ${jsonReport.meta.totalIssues} issues | ${jsonReport.meta.fixableCount} fixable | ${jsonReport.meta.refactorNeeded} need refactor
+**Total Time:** ${jsonReport.meta.totalTime}
+
+${projectSection}
+
+## Runner Summary
+
+| Runner | Status | Findings | Time |
+|--------|--------|----------|------|
+${runnerSummary.map((r) => `| ${r.name} | ${r.status} | ${r.findings} | ${r.time} |`).join("\n")}
+
+---
+
+${fullReport.join("\n")}`;
+    const mdPath = path.join(reviewDir, `booboo-${timestamp}.md`);
+    nodeFs.writeFileSync(mdPath, mdReport, "utf-8");
+    // --- Brief terminal summary ---
     if (summaryItems.length === 0) {
-        ctx.ui.notify("✓ Code review clean — saved to .pi-lens/reviews/", "info");
+        ctx.ui.notify("✓ Code review clean", "info");
     }
     else {
-        const totalIssues = summaryItems.reduce((sum, s) => sum + s.count, 0);
-        const fixableCount = summaryItems
-            .filter((s) => s.fixable)
-            .reduce((sum, s) => sum + s.count, 0);
-        const refactorNeeded = totalIssues - fixableCount;
-        let summary = `📊 Code Review: ${totalIssues} issues found\n`;
-        summary += `━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n`;
-        for (const item of summaryItems) {
-            summary += `${item.severity} ${item.category}: ${item.count}${item.fixable ? " (fixable)" : ""}\n`;
-        }
-        summary += `━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n`;
-        if (fixableCount > 0 && refactorNeeded > 0) {
-            summary += `🔧 ${fixableCount} fixable via /lens-booboo-fix | 🏗️ ${refactorNeeded} need /lens-booboo-refactor\n`;
-        }
-        else if (fixableCount > 0) {
-            summary += `🔧 All ${fixableCount} issues fixable via /lens-booboo-fix\n`;
-        }
-        else {
-            summary += `🏗️ All issues need /lens-booboo-refactor\n`;
-        }
-        summary += `📄 Full report: ${reportPath}`;
-        ctx.ui.notify(summary, "info");
+        const { totalIssues, fixableCount, refactorNeeded } = jsonReport.meta;
+        // Build runner lines for terminal output
+        const runnerLines = tracker
+            .getRunners()
+            .filter((r) => r.findings > 0)
+            .map((r) => `  ${r.status === "error" ? "✗" : "⚠"} ${r.name}: ${r.findings} finding${r.findings !== 1 ? "s" : ""} (${formatElapsed(r.elapsedMs)})`);
+        const summaryLines = [
+            `📊 Code Review: ${totalIssues} issues`,
+            ...runnerLines,
+            `  🔧 ${fixableCount} fixable | 🏗️ ${refactorNeeded} refactor`,
+            `  ⏱️  Total: ${jsonReport.meta.totalTime}`,
+            `📄 JSON: ${jsonPath}`,
+            `📄 MD: ${mdPath}`,
+        ];
+        ctx.ui.notify(summaryLines.join("\n"), "info");
+    }
+}
+/**
+ * Find top N most similar function pairs in the project index
+ * Uses canonical pair ordering to avoid duplicates (A,B) vs (B,A)
+ */
+function findTopSimilarPairs(index, maxPairs) {
+    const entries = Array.from(index.entries.values());
+    const seenPairs = new Set();
+    const pairs = [];
+    for (let i = 0; i < entries.length; i++) {
+        for (let j = i + 1; j < entries.length; j++) {
+            const entry1 = entries[i];
+            const entry2 = entries[j];
+            // Skip if same file (we want cross-file duplicates)
+            if (entry1.filePath === entry2.filePath)
+                continue;
+            const similarity = calculateSimilarity(entry1.matrix, entry2.matrix);
+            if (similarity >= 0.75) {
+                // Canonical pair key (sorted to avoid duplicates)
+                const pairKey = [entry1.id, entry2.id].sort().join("::");
+                if (seenPairs.has(pairKey))
+                    continue;
+                seenPairs.add(pairKey);
+                pairs.push({
+                    func1: entry1.id,
+                    func2: entry2.id,
+                    similarity,
+                });
+            }
+        }
     }
+    // Sort by similarity descending, take top N
+    return pairs.sort((a, b) => b.similarity - a.similarity).slice(0, maxPairs);
 }