jfl 0.4.4 → 0.6.0

package/dist/lib/setup/doc-auditor.js

@@ -0,0 +1,629 @@
+/**
+ * @purpose Audit GTM workspace docs — bifurcated: framework vs customer docs
+ *
+ * Framework docs: came from templates/skills, compare to upstream, track version drift
+ * Customer docs: PRDs, knowledge, custom content — analyze for staleness, token cost, relevance
+ *
+ * Core insight: "this doc costs you $X per day and adds zero value" > "this doc is long, split it"
+ */
+import { existsSync, readFileSync, readdirSync, statSync } from "fs";
+import { join, relative, basename } from "path";
+// Markers that indicate a doc came from a framework/template
+const FRAMEWORK_MARKERS = [
+    "<!-- jfl-template",
+    "<!-- generated by jfl",
+    "# generated by jfl",
+    "<!-- skill:",
+    "<!-- managed by",
+    "DO NOT EDIT — managed by",
+    "Auto-generated from template",
+];
+// Directories that typically contain framework-managed content
+const FRAMEWORK_DIRS = [
+    ".claude/skills",
+    ".claude/commands",
+    ".cursor/rules",
+    "skills/",
+];
+// Directories that typically contain customer content
+const CUSTOMER_DIRS = [
+    "knowledge/",
+    "docs/",
+    "prds/",
+    "specs/",
+    "rfcs/",
+    "design/",
+    "decisions/",
+];
+// Well-known framework files
+const FRAMEWORK_FILES = new Set([
+    "CLAUDE.md",
+    "AGENTS.md",
+    ".cursorrules",
+    ".claude/settings.json",
+    "CONVENTIONS.md",
+    "CONTRIBUTING.md",
+]);
+const MAX_DOC_LINES = 300;
+const STALE_DAYS = 14;
+const TOKENS_PER_CHAR = 0.25; // rough estimate
+// ============================================================================
+// Main audit
+// ============================================================================
+export function auditDocs(projectRoot, insight) {
+    const result = {
+        docs: [],
+        totalDocs: 0,
+        totalLines: 0,
+        totalBytes: 0,
+        totalTokens: 0,
+        frameworkDocs: [],
+        customerDocs: [],
+        staleDocs: [],
+        bloatedDocs: [],
+        missingDocs: [],
+        unreferencedDocs: [],
+        recommendations: [],
+    };
+    const mdFiles = findMarkdownFiles(projectRoot);
+    const now = new Date();
+    // Build reference index from journals — which docs/paths get mentioned?
+    const journalReferences = buildJournalReferenceIndex(insight);
+    // Check for manifest (tracks what came from templates)
+    const manifest = loadManifest(projectRoot);
+    for (const filePath of mdFiles) {
+        const stat = statSync(filePath);
+        const content = readFileSync(filePath, "utf-8");
+        const lines = content.split("\n").length;
+        const relPath = relative(projectRoot, filePath);
+        const daysSinceModified = (now.getTime() - stat.mtime.getTime()) / (1000 * 60 * 60 * 24);
+        const tokenEstimate = Math.ceil(content.length * TOKENS_PER_CHAR);
+        // Classify origin
+        const origin = classifyOrigin(relPath, content, manifest);
+        // Calculate stale score
+        let staleScore = 0;
+        if (daysSinceModified > STALE_DAYS * 3)
+            staleScore = 1.0;
+        else if (daysSinceModified > STALE_DAYS * 2)
+            staleScore = 0.8;
+        else if (daysSinceModified > STALE_DAYS)
+            staleScore = 0.5;
+        else
+            staleScore = daysSinceModified / STALE_DAYS * 0.3;
+        // Calculate bloat score
+        let bloatScore = 0;
+        if (lines > MAX_DOC_LINES * 3)
+            bloatScore = 1.0;
+        else if (lines > MAX_DOC_LINES * 2)
+            bloatScore = 0.8;
+        else if (lines > MAX_DOC_LINES)
+            bloatScore = 0.5;
+        // Calculate relevance from journal references
+        const refCount = countReferences(relPath, journalReferences);
+        const relevanceScore = Math.min(1, refCount / 5); // 5+ references = fully relevant
+        // Extract sections (H1/H2)
+        const sections = extractSections(content);
+        // Count TODOs
+        const todoMatches = content.match(/\bTODO\b|\bFIXME\b|\bHACK\b|\bXXX\b/gi) || [];
+        const todoCount = todoMatches.length;
+        // Find dead links
+        const deadLinks = findDeadLinks(content, projectRoot);
+        // Build issues list
+        const issues = [];
+        if (staleScore > 0.5)
+            issues.push(`Not modified in ${Math.floor(daysSinceModified)} days`);
+        if (bloatScore > 0.5)
+            issues.push(`${lines} lines (${tokenEstimate} tokens)`);
+        if (relevanceScore < 0.1 && lines > 50)
+            issues.push("Never referenced in journals");
+        if (todoCount > 3)
+            issues.push(`${todoCount} unresolved TODOs`);
+        if (deadLinks.length > 0)
+            issues.push(`${deadLinks.length} dead link(s)`);
+        // Framework-specific: check for version drift
+        if (origin === "framework" && manifest) {
+            const entry = manifest.files?.[relPath];
+            if (entry?.templateVersion && entry?.currentHash) {
+                issues.push(`Template version: ${entry.templateVersion}`);
+            }
+        }
+        // Customer-specific: token cost awareness
+        if (origin === "customer" && relevanceScore < 0.2 && tokenEstimate > 1000) {
+            issues.push(`Costs ~${tokenEstimate} tokens/session with 0 journal references`);
+        }
+        const doc = {
+            path: filePath,
+            relativePath: relPath,
+            sizeBytes: stat.size,
+            lines,
+            lastModified: stat.mtime,
+            staleScore,
+            bloatScore,
+            relevanceScore,
+            origin,
+            tokenEstimate,
+            issues,
+            sections,
+            todoCount,
+            deadLinks,
+            referenceCount: refCount,
+        };
+        result.docs.push(doc);
+        result.totalDocs++;
+        result.totalLines += lines;
+        result.totalBytes += stat.size;
+        result.totalTokens += tokenEstimate;
+        if (origin === "framework")
+            result.frameworkDocs.push(doc);
+        else
+            result.customerDocs.push(doc);
+        if (staleScore > 0.5)
+            result.staleDocs.push(doc);
+        if (bloatScore > 0.5)
+            result.bloatedDocs.push(doc);
+        if (refCount === 0 && lines > 30)
+            result.unreferencedDocs.push(doc);
+    }
+    // Check for missing expected docs
+    checkMissingDocs(projectRoot, result);
+    // Generate bifurcated recommendations
+    result.recommendations = generateRecommendations(result, insight);
+    return result;
+}
+// ============================================================================
+// Origin classification
+// ============================================================================
+function classifyOrigin(relPath, content, manifest) {
+    // Check manifest first (most reliable)
+    if (manifest?.files?.[relPath])
+        return "framework";
+    // Check for framework markers in content
+    const contentLower = content.toLowerCase();
+    for (const marker of FRAMEWORK_MARKERS) {
+        if (contentLower.includes(marker.toLowerCase()))
+            return "framework";
+    }
+    // Check well-known framework files
+    if (FRAMEWORK_FILES.has(basename(relPath)) || FRAMEWORK_FILES.has(relPath)) {
+        return "framework";
+    }
+    // Check directory-based heuristics
+    for (const dir of FRAMEWORK_DIRS) {
+        if (relPath.startsWith(dir))
+            return "framework";
+    }
+    for (const dir of CUSTOMER_DIRS) {
+        if (relPath.startsWith(dir))
+            return "customer";
+    }
+    // Default: if it's in the root, probably framework; if nested, probably customer
+    if (!relPath.includes("/"))
+        return "framework";
+    return "customer";
+}
+function buildJournalReferenceIndex(insight) {
+    const pathMentions = new Map();
+    const termMentions = new Map();
+    // File hotspots from journal analysis
+    for (const hotspot of insight.fileHotspots) {
+        pathMentions.set(hotspot.path, hotspot.touches);
+    }
+    // Common patterns → terms
+    for (const pattern of insight.commonPatterns) {
+        const words = pattern.toLowerCase().split(/\s+/).filter(w => w.length > 4);
+        for (const w of words) {
+            termMentions.set(w, (termMentions.get(w) || 0) + 1);
+        }
+    }
+    return { pathMentions, termMentions };
+}
+function countReferences(relPath, index) {
+    let count = 0;
+    // Direct path mentions
+    for (const [path, touches] of index.pathMentions) {
+        if (relPath.includes(path) || path.includes(relPath.replace(/\.md$/, ""))) {
+            count += touches;
+        }
+    }
+    // Term overlap (weaker signal)
+    const pathTerms = relPath.toLowerCase().replace(/[/_.-]/g, " ").split(/\s+/).filter(t => t.length > 4);
+    for (const term of pathTerms) {
+        count += (index.termMentions.get(term) || 0) * 0.2;
+    }
+    return Math.round(count);
+}
+// ============================================================================
+// Recommendations — bifurcated by origin
+// ============================================================================
+function generateRecommendations(audit, insight) {
+    const recs = [];
+    // ---- Framework doc recommendations ----
+    for (const doc of audit.frameworkDocs) {
+        // Bloated framework docs → specific split guidance
+        if (doc.bloatScore > 0.5 && doc.sections.length > 3) {
+            const sectionList = doc.sections.slice(0, 6).join(", ");
+            recs.push({
+                type: "split",
+                target: doc.relativePath,
+                rationale: `${doc.lines} lines with ${doc.sections.length} sections (${sectionList}). Split by purpose: setup instructions, coding standards, and reference material should be separate files.`,
+                priority: doc.bloatScore > 0.8 ? 1 : 2,
+                estimatedSavings: `~${doc.tokenEstimate} tokens/session → ${Math.floor(doc.tokenEstimate * 0.4)} after split (agents only load relevant sections)`,
+                origin: "framework",
+                action: `Split into ${Math.min(doc.sections.length, 4)} focused files by section topic`,
+            });
+        }
+        else if (doc.bloatScore > 0.5) {
+            recs.push({
+                type: "trim",
+                target: doc.relativePath,
+                rationale: `${doc.lines} lines but only ${doc.sections.length || 1} section(s). Likely has verbose explanations that could be condensed.`,
+                priority: 2,
+                estimatedSavings: `~${Math.floor(doc.tokenEstimate * 0.3)} tokens removable`,
+                origin: "framework",
+                action: "Remove verbose explanations, convert prose to bullet points, eliminate redundant examples",
+            });
+        }
+        // Framework docs with many TODOs → template needs updating
+        if (doc.todoCount > 3) {
+            recs.push({
+                type: "update",
+                target: doc.relativePath,
+                rationale: `Framework doc has ${doc.todoCount} unresolved TODOs — template is shipping incomplete scaffolding`,
+                priority: 1,
+                origin: "framework",
+                action: "Resolve TODOs or remove placeholder sections that aren't actionable",
+            });
+        }
+        // Dead links in framework docs → broken template
+        if (doc.deadLinks.length > 0) {
+            recs.push({
+                type: "update",
+                target: doc.relativePath,
+                rationale: `${doc.deadLinks.length} dead link(s): ${doc.deadLinks.slice(0, 3).join(", ")}`,
+                priority: 1,
+                origin: "framework",
+                action: "Fix or remove broken references — these mislead agents",
+            });
+        }
+    }
+    // ---- Customer doc recommendations ----
+    for (const doc of audit.customerDocs) {
+        // Customer doc never referenced + large → biggest win
+        if (doc.referenceCount === 0 && doc.tokenEstimate > 500) {
+            const daysSinceModified = Math.floor((new Date().getTime() - doc.lastModified.getTime()) / (1000 * 60 * 60 * 24));
+            if (daysSinceModified > STALE_DAYS) {
+                recs.push({
+                    type: "archive",
+                    target: doc.relativePath,
+                    rationale: `Costs ~${doc.tokenEstimate} tokens/session but has 0 journal references in ${insight.totalSessions} sessions. Last modified ${daysSinceModified} days ago. Archiving saves tokens without losing anything agents use.`,
+                    priority: 1,
+                    estimatedSavings: `${doc.tokenEstimate} tokens/session (~$${(doc.tokenEstimate * 0.000003 * 30).toFixed(2)}/month at typical rates)`,
+                    origin: "customer",
+                    action: `Move to archive/ or .jfl/archived-docs/ — recoverable but out of context window`,
+                });
+            }
+            else {
+                recs.push({
+                    type: "archive",
+                    target: doc.relativePath,
+                    rationale: `${doc.tokenEstimate} tokens/session, 0 journal references across ${insight.totalSessions} sessions. Recently modified but agents aren't using it.`,
+                    priority: 2,
+                    estimatedSavings: `${doc.tokenEstimate} tokens/session`,
+                    origin: "customer",
+                    action: "Verify this doc is actually loaded into agent context. If not needed, archive it.",
+                });
+            }
+        }
+        // Customer doc with high reference count but stale → needs refresh
+        if (doc.referenceCount > 3 && doc.staleScore > 0.5) {
+            recs.push({
+                type: "refresh",
+                target: doc.relativePath,
+                rationale: `Referenced ${doc.referenceCount} times in journals but not updated in ${Math.floor((new Date().getTime() - doc.lastModified.getTime()) / (1000 * 60 * 60 * 24))} days. Agents rely on this — make sure it's accurate.`,
+                priority: 1,
+                origin: "customer",
+                action: "Review against current system state. Update or confirm accuracy.",
+            });
+        }
+        // Customer doc that's bloated → specific guidance based on sections
+        if (doc.bloatScore > 0.5) {
+            if (doc.sections.length >= 4) {
+                // Has clear section structure → can split meaningfully
+                const topicGroups = groupSections(doc.sections);
+                recs.push({
+                    type: "split",
+                    target: doc.relativePath,
+                    rationale: `${doc.lines} lines across ${doc.sections.length} sections. Topics: ${topicGroups.join("; ")}. Splitting lets agents load only relevant context.`,
+                    priority: 2,
+                    estimatedSavings: `${doc.tokenEstimate} tokens → ~${Math.floor(doc.tokenEstimate / doc.sections.length)} per split file`,
+                    origin: "customer",
+                    action: `Split into ${Math.min(topicGroups.length, 4)} files by topic area`,
+                });
+            }
+            else {
+                // No clear sections → trim
+                recs.push({
+                    type: "trim",
+                    target: doc.relativePath,
+                    rationale: `${doc.lines} lines but lacks clear section structure. Likely has redundant content or could be condensed.`,
+                    priority: 3,
+                    estimatedSavings: `~${Math.floor(doc.tokenEstimate * 0.3)} tokens removable`,
+                    origin: "customer",
+                    action: "Add section headers, remove redundant explanations, extract examples to separate files",
+                });
+            }
+        }
+        // Old TODOs in customer docs → stale promises
+        if (doc.todoCount > 0 && doc.staleScore > 0.3) {
+            recs.push({
+                type: "update",
+                target: doc.relativePath,
+                rationale: `${doc.todoCount} TODOs in a doc not updated in ${Math.floor((new Date().getTime() - doc.lastModified.getTime()) / (1000 * 60 * 60 * 24))} days — these are likely stale or completed`,
+                priority: 3,
+                origin: "customer",
+                action: "Resolve, remove, or convert stale TODOs to done items",
+            });
+        }
+    }
+    // ---- Cross-origin: duplication detection ----
+    const duplicateGroups = findPotentialDuplicates(audit.docs);
+    for (const group of duplicateGroups) {
+        recs.push({
+            type: "dedupe",
+            target: group.map(d => d.relativePath).join(" + "),
+            rationale: `These docs share similar topics (${group[0].sections.filter(s => group[1]?.sections.includes(s)).join(", ") || "similar content"}). Merge or deduplicate to reduce token cost.`,
+            priority: 2,
+            estimatedSavings: `~${group.reduce((sum, d) => sum + d.tokenEstimate, 0)} combined tokens → could halve with merge`,
+            origin: "unknown",
+            action: "Review for overlap. Keep one authoritative version.",
+        });
+    }
+    // ---- Missing docs for active areas ----
+    checkMissingDocsForActivity(audit, insight, recs);
+    // ---- Token budget summary ----
+    const unreferencedTokens = audit.unreferencedDocs.reduce((sum, d) => sum + d.tokenEstimate, 0);
+    if (unreferencedTokens > 5000) {
+        recs.unshift({
+            type: "archive",
+            target: `${audit.unreferencedDocs.length} unreferenced docs`,
+            rationale: `${audit.unreferencedDocs.length} docs (${unreferencedTokens} tokens) are never referenced in journals. Archiving all would save ~${unreferencedTokens} tokens/session.`,
+            priority: 1,
+            estimatedSavings: `${unreferencedTokens} tokens/session (~$${(unreferencedTokens * 0.000003 * 30 * 20).toFixed(2)}/month at 20 sessions/day)`,
+            origin: "unknown",
+            action: "Review list and archive docs that aren't needed in agent context",
+        });
+    }
+    return recs.sort((a, b) => a.priority - b.priority);
+}
+// ============================================================================
+// Duplication detection
+// ============================================================================
+function findPotentialDuplicates(docs) {
+    const groups = [];
+    const seen = new Set();
+    for (let i = 0; i < docs.length; i++) {
+        if (seen.has(docs[i].relativePath))
+            continue;
+        if (docs[i].sections.length < 2)
+            continue;
+        const group = [docs[i]];
+        for (let j = i + 1; j < docs.length; j++) {
+            if (seen.has(docs[j].relativePath))
+                continue;
+            if (docs[j].sections.length < 2)
+                continue;
+            // Check section overlap
+            const overlap = docs[i].sections.filter(s => docs[j].sections.some(s2 => sectionsSimilar(s, s2)));
+            const overlapRatio = overlap.length / Math.min(docs[i].sections.length, docs[j].sections.length);
+            if (overlapRatio > 0.5) {
+                group.push(docs[j]);
+                seen.add(docs[j].relativePath);
+            }
+        }
+        if (group.length > 1) {
+            seen.add(docs[i].relativePath);
+            groups.push(group);
+        }
+    }
+    return groups.slice(0, 5); // cap at 5 groups
+}
+function sectionsSimilar(a, b) {
+    const normalize = (s) => s.toLowerCase().replace(/[^a-z0-9]/g, " ").trim();
+    const na = normalize(a);
+    const nb = normalize(b);
+    if (na === nb)
+        return true;
+    // Check word overlap
+    const wa = new Set(na.split(/\s+/));
+    const wb = new Set(nb.split(/\s+/));
+    const intersection = [...wa].filter(w => wb.has(w) && w.length > 3);
+    return intersection.length >= 2;
+}
+// ============================================================================
+// Helpers
+// ============================================================================
+function extractSections(content) {
+    const sections = [];
+    for (const line of content.split("\n")) {
+        const match = line.match(/^#{1,2}\s+(.+)/);
+        if (match)
+            sections.push(match[1].trim());
+    }
+    return sections;
+}
+function groupSections(sections) {
+    // Group sections by topic keywords
+    const topics = new Map();
+    for (const s of sections) {
+        const words = s.toLowerCase().split(/\s+/);
+        const key = words.find(w => w.length > 4) || words[0] || "misc";
+        if (!topics.has(key))
+            topics.set(key, []);
+        topics.get(key).push(s);
+    }
+    return [...topics.entries()].map(([topic, secs]) => `${topic} (${secs.length} sections)`).slice(0, 5);
+}
+function findDeadLinks(content, projectRoot) {
+    const dead = [];
+    const linkMatches = content.match(/\[([^\]]+)\]\(([^)]+)\)/g) || [];
+    for (const link of linkMatches) {
+        const match = link.match(/\]\(([^)]+)\)/);
+        if (!match || match[1].startsWith("http") || match[1].startsWith("#"))
+            continue;
+        const target = join(projectRoot, match[1]);
+        if (!existsSync(target))
+            dead.push(match[1]);
+    }
+    return dead;
+}
+function loadManifest(projectRoot) {
+    const paths = [
+        join(projectRoot, ".jfl", "manifest.json"),
+        join(projectRoot, ".jfl", "template-manifest.json"),
+    ];
+    for (const p of paths) {
+        if (existsSync(p)) {
+            try {
+                return JSON.parse(readFileSync(p, "utf-8"));
+            }
+            catch {
+                continue;
+            }
+        }
+    }
+    return null;
+}
+function checkMissingDocs(projectRoot, result) {
+    const expected = [
+        { name: "VISION.md", purpose: "North star and product direction" },
+        { name: "ROADMAP.md", purpose: "Current priorities and milestones" },
+        { name: "ARCHITECTURE.md", purpose: "System design and service map" },
+        { name: "CHANGELOG.md", purpose: "What shipped and when" },
+    ];
+    const knowledgeDir = join(projectRoot, "knowledge");
+    for (const exp of expected) {
+        const paths = [
+            join(projectRoot, exp.name),
+            join(knowledgeDir, exp.name),
+        ];
+        if (!paths.some(p => existsSync(p))) {
+            result.missingDocs.push(`${exp.name} — ${exp.purpose}`);
+        }
+    }
+}
+function checkMissingDocsForActivity(audit, insight, recs) {
+    for (const hotspot of insight.fileHotspots.slice(0, 5)) {
+        const dir = hotspot.path.split("/").slice(0, 2).join("/");
+        const hasDocs = audit.docs.some(d => d.relativePath.startsWith(dir));
+        if (!hasDocs && hotspot.touches > 10) {
+            recs.push({
+                type: "create",
+                target: `${dir}/README.md`,
+                rationale: `${hotspot.path} has ${hotspot.touches} touches across sessions but no documentation. Agents working here have no context.`,
+                priority: 2,
+                origin: "customer",
+                action: "Create a README explaining the purpose, key files, and conventions for this directory",
+            });
+        }
+    }
+}
+// ============================================================================
+// Stratus-powered deep analysis
+// ============================================================================
+export function buildDocAuditPrompt(audit, insight) {
+    return `You are an expert at maintaining lean, effective workspace documentation for AI-assisted development.
+
+## Context
+Total docs: ${audit.totalDocs} (${audit.totalLines} lines, ${audit.totalTokens} tokens, ${(audit.totalBytes / 1024).toFixed(0)}KB)
+Framework docs: ${audit.frameworkDocs.length} (${audit.frameworkDocs.reduce((s, d) => s + d.tokenEstimate, 0)} tokens)
+Customer docs: ${audit.customerDocs.length} (${audit.customerDocs.reduce((s, d) => s + d.tokenEstimate, 0)} tokens)
+Unreferenced docs: ${audit.unreferencedDocs.length} (${audit.unreferencedDocs.reduce((s, d) => s + d.tokenEstimate, 0)} tokens wasted)
+
+## Framework Docs (from templates/skills — JFL manages these)
+${audit.frameworkDocs.filter(d => d.issues.length > 0).slice(0, 10).map(d => `- ${d.relativePath}: ${d.lines} lines, ${d.tokenEstimate} tokens, refs=${d.referenceCount}, sections=[${d.sections.slice(0, 4).join(", ")}] ${d.issues.length > 0 ? "⚠ " + d.issues.join("; ") : ""}`).join("\n") || "All clean"}
+
+## Customer Docs (PRDs, knowledge, roadmaps — user manages these)
+${audit.customerDocs.filter(d => d.issues.length > 0).slice(0, 15).map(d => `- ${d.relativePath}: ${d.lines} lines, ${d.tokenEstimate} tokens, refs=${d.referenceCount}, age=${Math.floor((new Date().getTime() - d.lastModified.getTime()) / 86400000)}d, sections=[${d.sections.slice(0, 4).join(", ")}] ${d.issues.length > 0 ? "⚠ " + d.issues.join("; ") : ""}`).join("\n") || "All clean"}
+
+## Unreferenced (never mentioned in ${insight.totalSessions} journal sessions)
+${audit.unreferencedDocs.slice(0, 10).map(d => `- ${d.relativePath}: ${d.tokenEstimate} tokens, origin=${d.origin}, age=${Math.floor((new Date().getTime() - d.lastModified.getTime()) / 86400000)}d`).join("\n") || "None"}
+
+## What agents actually work on (journal patterns)
+${insight.commonPatterns.slice(0, 8).join("\n") || "No patterns"}
+
+## Sessions: ${insight.totalSessions}, Entries: ${insight.totalEntries}
+
+## Instructions
+
+Give specific, actionable recommendations. For each:
+1. **type**: "trim" | "update" | "create" | "archive" | "split" | "merge" | "refresh" | "dedupe"
+2. **target**: file path
+3. **rationale**: why, citing token costs and reference counts
+4. **priority**: 1-3
+5. **action**: exactly what to do (not generic "split into sections" — say which sections and why)
+6. **origin**: "framework" or "customer"
+7. **estimatedSavings**: token count saved
+
+Key principle: "this doc costs N tokens/session and has 0 journal references" > "this doc is long"
+
+Respond ONLY with valid JSON array. No markdown wrapping.`;
+}
+export async function getSmartDocRecommendations(projectRoot, insight) {
+    const audit = auditDocs(projectRoot, insight);
+    const prompt = buildDocAuditPrompt(audit, insight);
+    const apiKey = process.env.STRATUS_API_KEY;
+    const apiUrl = process.env.STRATUS_API_URL || "https://api.stratus.run/v1/chat/completions";
+    if (!apiKey)
+        return audit.recommendations;
+    try {
+        const response = await fetch(apiUrl, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                "Authorization": `Bearer ${apiKey}`,
+            },
+            body: JSON.stringify({
+                model: "stratus-x1ac-base-claude-haiku-4-5",
+                messages: [{ role: "user", content: prompt }],
+                max_tokens: 3000,
+                temperature: 0.3,
+            }),
+        });
+        if (!response.ok)
+            return audit.recommendations;
+        const data = await response.json();
+        const content = data.choices?.[0]?.message?.content || "";
+        const jsonStr = content.replace(/^```json?\n?/, "").replace(/\n?```$/, "").trim();
+        const smartRecs = JSON.parse(jsonStr);
+        // Merge: smart recs first, then any heuristic recs not covered
+        return [...smartRecs, ...audit.recommendations.filter(r => !smartRecs.some(s => s.target === r.target && s.type === r.type))];
+    }
+    catch {
+        return audit.recommendations;
+    }
+}
+// ============================================================================
+// File discovery
+// ============================================================================
+function findMarkdownFiles(dir, depth = 0) {
+    if (depth > 3)
+        return [];
+    const files = [];
+    const skip = new Set(["node_modules", ".git", ".jfl", "dist", "build", ".next", "__pycache__", "archive", "archived-docs"]);
+    try {
+        for (const entry of readdirSync(dir, { withFileTypes: true })) {
+            if (skip.has(entry.name))
+                continue;
+            const fullPath = join(dir, entry.name);
+            if (entry.isFile() && entry.name.endsWith(".md")) {
+                files.push(fullPath);
+            }
+            else if (entry.isDirectory()) {
+                files.push(...findMarkdownFiles(fullPath, depth + 1));
+            }
+        }
+    }
+    catch { /* permission errors */ }
+    return files;
+}
+//# sourceMappingURL=doc-auditor.js.map