@jokerized/getresearchdone 0.4.1

package/dist/lib/knowledge.js

@@ -0,0 +1,658 @@
+'use strict';
+Object.defineProperty(exports, "__esModule", { value: true });
+const fs = require('fs');
+const path = require('path');
+const { safeReadFile, output } = require('./utils');
+const KNOWHOW_HEADER = '# KNOWHOW\n\n';
+// Module-level cache: maps knowhowPath → parsed entries, invalidated on write.
+const _knowhowCache = new Map();
+function _cachedParseKnowhow(knowhowPath) {
+    try {
+        const stat = fs.statSync(knowhowPath);
+        const cached = _knowhowCache.get(knowhowPath);
+        if (cached && cached.mtime === stat.mtimeMs)
+            return cached.entries;
+        const content = fs.readFileSync(knowhowPath, 'utf8') ?? '';
+        const entries = parseKnowhowEntries(content);
+        _knowhowCache.set(knowhowPath, { entries, mtime: stat.mtimeMs });
+        return entries;
+    }
+    catch {
+        return [];
+    }
+}
+/** Serialize a KnowhowEntry to a markdown level-3 heading block. */
+function formatKnowhowEntry(entry) {
+    return (`### ${entry.pattern_name}\n\n` +
+        `- **source:** ${entry.source}\n` +
+        `- **applicability:** ${entry.applicability}\n` +
+        `- **code_snippet:** ${entry.code_snippet}\n` +
+        `- **phase_number:** ${entry.phase_number}\n` +
+        `- **created_at:** ${entry.created_at}\n`);
+}
+/**
+ * Parse KNOWHOW.md content into an array of KnowhowEntry objects.
+ *
+ * Splits on `### ` level-3 headings. For each block, extracts pattern_name from
+ * the heading text and parses structured `- **field:** value` lines.
+ * Returns empty array for empty/missing content.
+ *
+ * Roundtrip guarantee: parseKnowhowEntries(formatKnowhowEntry(entry)) produces
+ * an equivalent entry (lossless).
+ */
+function parseKnowhowEntries(content) {
+    if (!content || !content.trim()) {
+        return [];
+    }
+    const entries = [];
+    const blocks = content.split(/(?=^### )/m);
+    for (const block of blocks) {
+        const trimmed = block.trim();
+        if (!trimmed.startsWith('### ')) {
+            continue;
+        }
+        const lines = trimmed.split('\n');
+        const headingLine = lines[0];
+        const pattern_name = headingLine.replace(/^### /, '').trim();
+        if (!pattern_name) {
+            continue;
+        }
+        const fieldPattern = /^- \*\*(\w+):\*\* (.*)$/;
+        const fields = {};
+        for (const line of lines.slice(1)) {
+            const match = line.match(fieldPattern);
+            if (match) {
+                fields[match[1]] = match[2].trim();
+            }
+        }
+        const REQUIRED_FIELDS = ['source', 'applicability', 'code_snippet', 'phase_number', 'created_at'];
+        if (REQUIRED_FIELDS.every((k) => k in fields)) {
+            const phase_number = parseInt(fields['phase_number'], 10);
+            if (Number.isNaN(phase_number)) {
+                continue;
+            }
+            entries.push({
+                pattern_name,
+                source: fields['source'],
+                applicability: fields['applicability'],
+                code_snippet: fields['code_snippet'],
+                phase_number,
+                created_at: fields['created_at'],
+            });
+        }
+    }
+    return entries;
+}
+/**
+ * Read existing KNOWHOW.md at knowhowPath, merge new entries (deduplicating by
+ * pattern_name, keeping higher phase_number), and write back.
+ *
+ * - If the file does not exist, starts with an empty entry list.
+ * - Deduplication: when a new entry shares a pattern_name with an existing one,
+ *   the entry with the higher phase_number is kept.
+ * - File always starts with `# KNOWHOW\n\n` header.
+ * - Parent directories are created if needed.
+ */
+function appendKnowhowEntries(knowhowPath, entries) {
+    if (entries.length === 0)
+        return;
+    const existing = _cachedParseKnowhow(knowhowPath);
+    const byName = new Map();
+    for (const e of existing) {
+        byName.set(e.pattern_name, e);
+    }
+    const total = entries.length;
+    for (let i = 0; i < total; i++) {
+        const e = entries[i];
+        if (total > 50) {
+            process.stderr.write(`[knowledge] merging entry ${i + 1}/${total}: ${e.pattern_name}\n`);
+        }
+        const current = byName.get(e.pattern_name);
+        if (!current || e.phase_number >= current.phase_number) {
+            byName.set(e.pattern_name, e);
+        }
+    }
+    const merged = Array.from(byName.values());
+    merged.sort((a, b) => b.phase_number - a.phase_number);
+    const body = merged.map(formatKnowhowEntry).join('\n');
+    const fileContent = KNOWHOW_HEADER + body;
+    const dir = path.dirname(knowhowPath);
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(knowhowPath, fileContent, 'utf8');
+    _knowhowCache.delete(knowhowPath);
+}
+/**
+ * Return top-N entries from the input array sorted by recency.
+ *
+ * - Primary sort: phase_number descending (most recent first).
+ * - If moduleHints provided: entries whose source or applicability mentions any
+ *   hint string are sorted first within each phase_number bucket.
+ * - Tertiary sort: when currentPhase is provided, entries closer to the current
+ *   phase rank higher within the same phase_number bucket (proximity scoring).
+ * - Returns at most n entries.
+ * - If entries.length <= n, returns all entries sorted.
+ */
+function selectTopEntries(entries, n, moduleHints, currentPhase) {
+    if (entries.length === 0 || n <= 0) {
+        return [];
+    }
+    const lowerHints = moduleHints?.map((h) => h.toLowerCase()) ?? [];
+    const hintMatches = new Set();
+    if (lowerHints.length > 0) {
+        for (const entry of entries) {
+            const combined = `${entry.source} ${entry.applicability}`.toLowerCase();
+            if (lowerHints.some((hint) => combined.includes(hint))) {
+                hintMatches.add(entry);
+            }
+        }
+    }
+    const scoreEntry = (e) => e.phase_number * 1000 +
+        (hintMatches.has(e) ? 100 : 0) -
+        (currentPhase !== undefined ? Math.abs(currentPhase - e.phase_number) : 0);
+    const sorted = [...entries].sort((a, b) => scoreEntry(b) - scoreEntry(a));
+    return sorted.slice(0, n);
+}
+function _loadKnowledgeStats(statsPath) {
+    try {
+        const raw = fs.readFileSync(statsPath, 'utf8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return {};
+    }
+}
+function _saveKnowledgeStats(statsPath, stats) {
+    try {
+        fs.mkdirSync(path.dirname(statsPath), { recursive: true });
+        fs.writeFileSync(statsPath, JSON.stringify(stats, null, 2), 'utf8');
+    }
+    catch {
+        /* stats are best-effort; never crash injection on write failure */
+    }
+}
+/**
+ * Build a structured knowledge injection block from KNOWHOW.md for prompt injection.
+ *
+ * Reads KNOWHOW.md from path.join(cwd, 'KNOWHOW.md'), selects top 5 entries
+ * using selectTopEntries, and wraps them in <knowhow_context> XML tags.
+ * Increments hit_count and last_used in .planning/knowledge-stats.json after each injection.
+ *
+ * @param cwd - Project root directory
+ * @param _phaseNum - Current phase number (reserved for future phase-proximity scoring)
+ * @param moduleHints - Optional module name hints to boost relevant entries
+ * @returns Formatted injection block string, or '' if no entries
+ */
+function buildKnowledgeInjectionBlock(cwd, _phaseNum, moduleHints) {
+    const knowhowPath = path.join(cwd, 'KNOWHOW.md');
+    const entries = _cachedParseKnowhow(knowhowPath);
+    if (entries.length === 0) {
+        return '';
+    }
+    const parsedPhase = parseInt(_phaseNum, 10);
+    const currentPhase = Number.isNaN(parsedPhase) ? undefined : parsedPhase;
+    const top = selectTopEntries(entries, 5, moduleHints, currentPhase);
+    if (top.length === 0) {
+        return '';
+    }
+    // Track which entries were injected
+    const statsPath = path.join(cwd, '.planning', 'knowledge-stats.json');
+    const stats = _loadKnowledgeStats(statsPath);
+    const now = new Date().toISOString();
+    for (const entry of top) {
+        const existing = stats[entry.pattern_name];
+        stats[entry.pattern_name] = {
+            hit_count: (existing?.hit_count ?? 0) + 1,
+            last_used: now,
+        };
+    }
+    _saveKnowledgeStats(statsPath, stats);
+    const formatted = top.map(formatKnowhowEntry).join('\n');
+    return `<knowhow_context>\n${formatted}\n</knowhow_context>`;
+}
+/**
+ * Extract module hints from PLAN.md frontmatter files_modified fields.
+ *
+ * Reads all *-PLAN.md files in phaseDir, extracts files_modified from YAML
+ * frontmatter, and returns unique basenames (without extensions).
+ *
+ * @param phaseDir - Path to phase directory containing PLAN.md files
+ * @returns Array of unique module basenames
+ */
+function extractModuleHints(phaseDir) {
+    if (!fs.existsSync(phaseDir)) {
+        return [];
+    }
+    let files;
+    try {
+        files = fs.readdirSync(phaseDir).filter((f) => f.endsWith('-PLAN.md') || f === 'PLAN.md');
+    }
+    catch {
+        return [];
+    }
+    if (files.length === 0) {
+        return [];
+    }
+    const hints = new Set();
+    for (const file of files) {
+        const filePath = path.join(phaseDir, file);
+        const content = safeReadFile(filePath);
+        if (!content)
+            continue;
+        const fmMatch = content.match(/^---\n([\s\S]*?)\n---/);
+        if (!fmMatch)
+            continue;
+        const fmContent = fmMatch[1];
+        const filesMatch = fmContent.match(/files_modified:\s*\[([^\]]*)\]/);
+        if (!filesMatch)
+            continue;
+        const filesList = filesMatch[1].split(',').map((f) => f.trim()).filter(Boolean);
+        for (const f of filesList) {
+            const basename = path.basename(f).split('.')[0];
+            if (basename) {
+                hints.add(basename);
+            }
+        }
+    }
+    return Array.from(hints);
+}
+/**
+ * CLI command: Audit all KNOWHOW.md files for stale references and contradictions.
+ *
+ * Scans all KNOWHOW.md files under .planning/milestones/ and the root research dir.
+ * For each entry:
+ *   - Extracts file paths referenced in the source field and checks they exist.
+ *   - Detects entries with the same pattern_name but different applicability advice.
+ *
+ * @param cwd - Project working directory
+ * @param raw - Output raw text instead of JSON
+ */
+function cmdKnowhowAudit(cwd, raw) {
+    const milestonesBase = path.join(cwd, '.planning', 'milestones');
+    const flags = [];
+    // Collect all KNOWHOW.md paths
+    const knowhowPaths = [];
+    try {
+        const msDirs = fs.readdirSync(milestonesBase).filter((d) => {
+            try {
+                return fs.statSync(path.join(milestonesBase, d)).isDirectory();
+            }
+            catch {
+                return false;
+            }
+        });
+        for (const ms of msDirs) {
+            const msKnowhow = path.join(milestonesBase, ms, 'KNOWHOW.md');
+            if (fs.existsSync(msKnowhow))
+                knowhowPaths.push(msKnowhow);
+            const resKnowhow = path.join(milestonesBase, ms, 'research', 'KNOWHOW.md');
+            if (fs.existsSync(resKnowhow))
+                knowhowPaths.push(resKnowhow);
+            // Codex r25 P2: per-phase KNOWHOW.md files are where the knowledge
+            // miner writes new entries; audit/dedup must scan them or they
+            // miss the common case entirely.
+            const phasesBase = path.join(milestonesBase, ms, 'phases');
+            try {
+                for (const ph of fs.readdirSync(phasesBase)) {
+                    const phKnowhow = path.join(phasesBase, ph, 'KNOWHOW.md');
+                    if (fs.existsSync(phKnowhow))
+                        knowhowPaths.push(phKnowhow);
+                }
+            }
+            catch { /* skip */ }
+        }
+    }
+    catch {
+        // milestones dir doesn't exist
+    }
+    // Also check root planning research dir + project-root KNOWHOW.md
+    const rootResearchKnowhow = path.join(cwd, '.planning', 'research', 'KNOWHOW.md');
+    if (fs.existsSync(rootResearchKnowhow))
+        knowhowPaths.push(rootResearchKnowhow);
+    const rootKnowhow = path.join(cwd, '.planning', 'KNOWHOW.md');
+    if (fs.existsSync(rootKnowhow))
+        knowhowPaths.push(rootKnowhow);
+    const projectRootKnowhow = path.join(cwd, 'KNOWHOW.md');
+    if (fs.existsSync(projectRootKnowhow))
+        knowhowPaths.push(projectRootKnowhow);
+    let totalEntries = 0;
+    // Track all entries across files for contradiction detection (by pattern_name)
+    const allByName = new Map();
+    for (const kPath of knowhowPaths) {
+        const content = safeReadFile(kPath);
+        if (!content)
+            continue;
+        const entries = parseKnowhowEntries(content);
+        totalEntries += entries.length;
+        for (const entry of entries) {
+            // Check if source field references a real file path
+            const sourceRef = entry.source.split(':')[0].trim(); // strip line numbers
+            if (sourceRef && sourceRef.includes('/') && !sourceRef.startsWith('http')) {
+                const absRef = path.isAbsolute(sourceRef)
+                    ? sourceRef
+                    : path.join(cwd, sourceRef);
+                if (!fs.existsSync(absRef)) {
+                    flags.push({
+                        pattern_name: entry.pattern_name,
+                        source_file: path.relative(cwd, kPath),
+                        issue: 'broken_ref',
+                        detail: `Referenced source "${sourceRef}" does not exist`,
+                    });
+                }
+            }
+            // Accumulate for contradiction detection
+            const existing = allByName.get(entry.pattern_name) ?? [];
+            existing.push({ entry, file: path.relative(cwd, kPath) });
+            allByName.set(entry.pattern_name, existing);
+        }
+    }
+    // Detect contradictions: same pattern_name, significantly different applicability
+    let contradictionCount = 0;
+    for (const [name, items] of allByName) {
+        if (items.length < 2)
+            continue;
+        const applicabilities = items.map((i) => i.entry.applicability.toLowerCase());
+        const first = applicabilities[0];
+        // Heuristic: if one says "always/use" and another says "never/avoid", flag it
+        const hasPositive = applicabilities.some((a) => /\b(always|use|prefer|do)\b/.test(a));
+        const hasNegative = applicabilities.some((a) => /\b(never|avoid|don't|do not)\b/.test(a));
+        if (hasPositive && hasNegative) {
+            contradictionCount++;
+            flags.push({
+                pattern_name: name,
+                source_file: items.map((i) => i.file).join(', '),
+                issue: 'contradicts',
+                detail: `"${first.slice(0, 80)}" vs "${applicabilities.slice(1).join(' / ').slice(0, 80)}"`,
+            });
+        }
+    }
+    const staleCount = flags.filter((f) => f.issue === 'broken_ref').length;
+    const result = {
+        total_entries: totalEntries,
+        stale_count: staleCount,
+        contradiction_count: contradictionCount,
+        flags,
+        knowhow_files_scanned: knowhowPaths.length,
+    };
+    const summary = `${knowhowPaths.length} files, ${totalEntries} entries: ${staleCount} stale refs, ${contradictionCount} contradictions`;
+    output(result, raw, summary);
+}
+/** Compute trigram set from text for Jaccard similarity. */
+function _trigrams(text) {
+    const normalized = text.toLowerCase().replace(/[^a-z0-9 ]/g, ' ').replace(/\s+/g, ' ').trim();
+    const set = new Set();
+    for (let i = 0; i + 2 < normalized.length; i++) {
+        set.add(normalized.slice(i, i + 3));
+    }
+    return set;
+}
+/** Compute Jaccard similarity between two trigram sets. */
+function _jaccard(a, b) {
+    if (a.size === 0 && b.size === 0)
+        return 1;
+    let intersection = 0;
+    for (const t of a) {
+        if (b.has(t))
+            intersection++;
+    }
+    const union = a.size + b.size - intersection;
+    return union === 0 ? 0 : intersection / union;
+}
+/**
+ * CLI command: Find near-duplicate entries across all KNOWHOW.md files.
+ *
+ * Scans all KNOWHOW.md files under .planning/milestones/ and the root research dir.
+ * Computes pairwise trigram-Jaccard similarity on entry title + first 3 body lines.
+ * Writes a report to .planning/KNOWHOW-DEDUP.md listing pairs with similarity > threshold (default 0.75).
+ *
+ * @param cwd - Project working directory
+ * @param raw - Output raw text instead of JSON
+ * @param threshold - Similarity threshold (default 0.75)
+ */
+function cmdKnowhowDedup(cwd, raw, threshold = 0.75) {
+    const milestonesBase = path.join(cwd, '.planning', 'milestones');
+    // Collect all KNOWHOW.md paths
+    const knowhowPaths = [];
+    try {
+        const msDirs = fs.readdirSync(milestonesBase).filter((d) => {
+            try {
+                return fs.statSync(path.join(milestonesBase, d)).isDirectory();
+            }
+            catch {
+                return false;
+            }
+        });
+        for (const ms of msDirs) {
+            const msKnowhow = path.join(milestonesBase, ms, 'KNOWHOW.md');
+            if (fs.existsSync(msKnowhow))
+                knowhowPaths.push(msKnowhow);
+            const resKnowhow = path.join(milestonesBase, ms, 'research', 'KNOWHOW.md');
+            if (fs.existsSync(resKnowhow))
+                knowhowPaths.push(resKnowhow);
+            // Codex r25 P2: include per-phase KNOWHOW.md — that's where the
+            // knowledge miner writes the entries that most often dup.
+            const phasesBase = path.join(milestonesBase, ms, 'phases');
+            try {
+                for (const ph of fs.readdirSync(phasesBase)) {
+                    const phKnowhow = path.join(phasesBase, ph, 'KNOWHOW.md');
+                    if (fs.existsSync(phKnowhow))
+                        knowhowPaths.push(phKnowhow);
+                }
+            }
+            catch { /* skip */ }
+        }
+    }
+    catch {
+        // milestones dir doesn't exist
+    }
+    const rootResearchKnowhow = path.join(cwd, '.planning', 'research', 'KNOWHOW.md');
+    if (fs.existsSync(rootResearchKnowhow))
+        knowhowPaths.push(rootResearchKnowhow);
+    const rootKnowhow = path.join(cwd, '.planning', 'KNOWHOW.md');
+    if (fs.existsSync(rootKnowhow))
+        knowhowPaths.push(rootKnowhow);
+    const projectRootKnowhow = path.join(cwd, 'KNOWHOW.md');
+    if (fs.existsSync(projectRootKnowhow))
+        knowhowPaths.push(projectRootKnowhow);
+    // Load all entries with source file info
+    const allEntries = [];
+    for (const kPath of knowhowPaths) {
+        const content = safeReadFile(kPath);
+        if (!content)
+            continue;
+        const entries = parseKnowhowEntries(content);
+        for (const entry of entries) {
+            // Fingerprint: title + first 3 lines of applicability
+            const bodyLines = entry.applicability.split('\n').slice(0, 3).join(' ');
+            const fingerprint = `${entry.pattern_name} ${bodyLines}`;
+            allEntries.push({
+                entry,
+                file: path.relative(cwd, kPath),
+                fingerprint,
+                trigrams: _trigrams(fingerprint),
+            });
+        }
+    }
+    // Pairwise similarity (O(n^2), acceptable for typical KNOWHOW sizes <500 entries)
+    const pairs = [];
+    const totalEntryCount = allEntries.length;
+    for (let i = 0; i < totalEntryCount; i++) {
+        if (totalEntryCount > 20 && i % Math.max(1, Math.floor(totalEntryCount / 20)) === 0) {
+            process.stderr.write(`[knowledge:dedup] scanning entry ${i + 1}/${totalEntryCount}\n`);
+        }
+        for (let j = i + 1; j < totalEntryCount; j++) {
+            const sim = _jaccard(allEntries[i].trigrams, allEntries[j].trigrams);
+            if (sim >= threshold) {
+                pairs.push({
+                    entry_a: allEntries[i].entry.pattern_name,
+                    entry_b: allEntries[j].entry.pattern_name,
+                    source_a: allEntries[i].file,
+                    source_b: allEntries[j].file,
+                    similarity: Math.round(sim * 100) / 100,
+                    suggested_merge: `Keep: "${allEntries[i].entry.pattern_name}" (phase ${allEntries[i].entry.phase_number} ≥ ${allEntries[j].entry.phase_number} ? A : B)`,
+                });
+            }
+        }
+    }
+    // Sort by similarity descending
+    pairs.sort((a, b) => b.similarity - a.similarity);
+    // Write report
+    let reportPath = null;
+    const reportDir = path.join(cwd, '.planning');
+    const reportFile = path.join(reportDir, 'KNOWHOW-DEDUP.md');
+    try {
+        const lines = [
+            `# KNOWHOW Deduplication Report`,
+            ``,
+            `Generated: ${new Date().toISOString().split('T')[0]}`,
+            `Files scanned: ${knowhowPaths.length}`,
+            `Entries total: ${allEntries.length}`,
+            `Threshold: ${threshold}`,
+            `Pairs above threshold: ${pairs.length}`,
+            ``,
+        ];
+        if (pairs.length === 0) {
+            lines.push('No near-duplicate entries found.');
+        }
+        else {
+            lines.push('## Merge Candidates\n');
+            for (const p of pairs) {
+                lines.push(`### Similarity ${p.similarity}`);
+                lines.push(`- **A**: \`${p.entry_a}\` (${p.source_a})`);
+                lines.push(`- **B**: \`${p.entry_b}\` (${p.source_b})`);
+                lines.push(`- **Suggested**: ${p.suggested_merge}`);
+                lines.push('');
+            }
+        }
+        fs.mkdirSync(reportDir, { recursive: true });
+        fs.writeFileSync(reportFile, lines.join('\n'), 'utf-8');
+        reportPath = path.relative(cwd, reportFile);
+    }
+    catch {
+        // Non-fatal
+    }
+    const result = {
+        files_scanned: knowhowPaths.length,
+        entries_total: allEntries.length,
+        pairs_above_threshold: pairs.length,
+        pairs,
+        report_path: reportPath,
+    };
+    output(result, raw, `${allEntries.length} entries, ${pairs.length} duplicate pairs (threshold=${threshold}) → ${reportPath ?? 'report not written'}`);
+}
+// ─── TF-IDF Relevance Ranking ────────────────────────────────────────────────
+const STOPWORDS = new Set([
+    'a', 'an', 'the', 'and', 'or', 'but', 'in', 'on', 'at', 'to', 'for', 'of', 'with',
+    'is', 'are', 'was', 'were', 'be', 'been', 'being', 'have', 'has', 'had', 'do', 'does',
+    'did', 'will', 'would', 'could', 'should', 'may', 'might', 'it', 'its', 'this',
+    'that', 'these', 'those', 'from', 'by', 'as', 'if', 'when', 'where', 'which', 'who',
+]);
+/** Tokenize text into lowercase words, removing stopwords and punctuation. */
+function _tokenize(text) {
+    return text
+        .toLowerCase()
+        .replace(/[^a-z0-9 ]/g, ' ')
+        .split(/\s+/)
+        .filter((t) => t.length > 2 && !STOPWORDS.has(t));
+}
+/**
+ * Rank knowhow entries by TF-IDF relevance to a phase goal string.
+ *
+ * Tokenizes the goal and each entry's problem/solution text, computes IDF across
+ * all entries, then scores each entry by the sum of TF-IDF for query tokens.
+ * Returns at most topN entries sorted by descending relevance score.
+ *
+ * @param goal - Phase goal string to rank against
+ * @param entries - Array of KnowhowEntry to rank
+ * @param topN - Number of entries to return (default 5)
+ */
+function rankKnowhowByPhaseGoal(goal, entries, topN = 5) {
+    if (entries.length === 0 || !goal.trim())
+        return [];
+    const queryTokens = new Set(_tokenize(goal));
+    if (queryTokens.size === 0)
+        return entries.slice(0, topN);
+    // Build per-entry token lists from pattern_name + applicability (proxy for Problem+Solution)
+    const entryTexts = entries.map((e) => _tokenize(`${e.pattern_name} ${e.applicability} ${e.source}`));
+    // Compute IDF for each query token
+    const idf = new Map();
+    for (const token of queryTokens) {
+        const docsWithToken = entryTexts.filter((tokens) => tokens.includes(token)).length;
+        idf.set(token, Math.log((entries.length + 1) / (docsWithToken + 1)) + 1);
+    }
+    // Score each entry
+    const scored = entries.map((entry, i) => {
+        const tokens = entryTexts[i];
+        const tf = new Map();
+        for (const t of tokens) {
+            tf.set(t, (tf.get(t) ?? 0) + 1);
+        }
+        let score = 0;
+        for (const token of queryTokens) {
+            const termFreq = (tf.get(token) ?? 0) / Math.max(tokens.length, 1);
+            score += termFreq * (idf.get(token) ?? 1);
+        }
+        return { entry, score };
+    });
+    scored.sort((a, b) => b.score - a.score);
+    return scored.slice(0, topN).map((s) => s.entry);
+}
+/**
+ * CLI command: Rank KNOWHOW entries by relevance to a query string using TF-IDF.
+ *
+ * @param cwd - Project working directory
+ * @param query - Query string to rank against
+ * @param topN - Number of top entries to return (default 5)
+ * @param raw - Output raw text instead of JSON
+ */
+function cmdKnowhowRank(cwd, query, topN, raw) {
+    // Codex r21 P2: KNOWHOW lives in milestone/research dirs and per-phase
+    // dirs, not the project root. Match the multi-location scan from
+    // r18 (lib/context/agents.ts knowhow_block + lib/commands/knowledge-search.ts).
+    const fs = require('fs');
+    const candidates = [
+        path.join(cwd, '.planning', 'KNOWHOW.md'),
+        path.join(cwd, 'KNOWHOW.md'),
+    ];
+    const milestonesBase = path.join(cwd, '.planning', 'milestones');
+    try {
+        for (const ms of fs.readdirSync(milestonesBase)) {
+            candidates.push(path.join(milestonesBase, ms, 'KNOWHOW.md'));
+            candidates.push(path.join(milestonesBase, ms, 'research', 'KNOWHOW.md'));
+            const phasesBase = path.join(milestonesBase, ms, 'phases');
+            try {
+                for (const ph of fs.readdirSync(phasesBase)) {
+                    candidates.push(path.join(phasesBase, ph, 'KNOWHOW.md'));
+                }
+            }
+            catch { /* skip */ }
+        }
+    }
+    catch { /* skip */ }
+    const entries = [];
+    for (const p of candidates)
+        entries.push(..._cachedParseKnowhow(p));
+    if (entries.length === 0) {
+        output({ query, top_n: topN, entries: [], message: 'KNOWHOW.md not found or empty' }, raw, 'KNOWHOW.md not found');
+        return;
+    }
+    const ranked = rankKnowhowByPhaseGoal(query, entries, topN);
+    const summaries = ranked.map((e) => ({
+        pattern_name: e.pattern_name,
+        phase_number: e.phase_number,
+        applicability: e.applicability.slice(0, 100),
+    }));
+    output({ query, top_n: topN, total: entries.length, entries: summaries }, raw, ranked.map((e, i) => `${i + 1}. ${e.pattern_name} (phase ${e.phase_number})`).join('\n') || 'No entries');
+}
+module.exports = {
+    formatKnowhowEntry,
+    parseKnowhowEntries,
+    appendKnowhowEntries,
+    selectTopEntries,
+    buildKnowledgeInjectionBlock,
+    extractModuleHints,
+    rankKnowhowByPhaseGoal,
+    cmdKnowhowAudit,
+    cmdKnowhowDedup,
+    cmdKnowhowRank,
+};
+//# sourceMappingURL=knowledge.js.map