@chigichan24/crune 0.1.0

package/dist-cli/knowledge-graph/edges.js

@@ -0,0 +1,193 @@
+/**
+ * Topic edge construction and classification.
+ */
+import { cosineSimilarity } from "./similarity.js";
+export function buildTopicEdges(topics, sessions, tfidf, svd) {
+    const edges = [];
+    const sessionIndex = new Map();
+    for (const s of sessions)
+        sessionIndex.set(s.sessionId, s);
+    // Precompute topic centroids in latent SVD space (if available)
+    // Falls back to TF-IDF centroids if SVD not provided
+    const centroids = new Map();
+    for (const topic of topics) {
+        if (svd) {
+            // Average SVD session vectors for this topic
+            const centroid = new Float64Array(svd.k);
+            let count = 0;
+            for (const sid of topic.sessionIds) {
+                const vec = svd.sessionVectors.get(sid);
+                if (vec) {
+                    for (let k = 0; k < svd.k; k++)
+                        centroid[k] += vec[k];
+                    count++;
+                }
+            }
+            if (count > 0)
+                for (let k = 0; k < svd.k; k++)
+                    centroid[k] /= count;
+            // L2 normalize
+            let norm = 0;
+            for (let k = 0; k < svd.k; k++)
+                norm += centroid[k] * centroid[k];
+            norm = Math.sqrt(norm);
+            if (norm > 0)
+                for (let k = 0; k < svd.k; k++)
+                    centroid[k] /= norm;
+            centroids.set(topic.id, centroid);
+        }
+        else {
+            // Fallback: TF-IDF centroids
+            const centroid = new Float64Array(tfidf.vocabulary.length);
+            for (const sid of topic.sessionIds) {
+                const vec = tfidf.vectors.get(sid);
+                if (vec) {
+                    for (let k = 0; k < centroid.length; k++)
+                        centroid[k] += vec[k];
+                }
+            }
+            for (let k = 0; k < centroid.length; k++)
+                centroid[k] /= topic.sessionIds.length;
+            let norm = 0;
+            for (let k = 0; k < centroid.length; k++)
+                norm += centroid[k] * centroid[k];
+            norm = Math.sqrt(norm);
+            if (norm > 0)
+                for (let k = 0; k < centroid.length; k++)
+                    centroid[k] /= norm;
+            centroids.set(topic.id, centroid);
+        }
+    }
+    for (let i = 0; i < topics.length; i++) {
+        for (let j = i + 1; j < topics.length; j++) {
+            const ti = topics[i];
+            const tj = topics[j];
+            // Signal 1: Latent semantic similarity (SVD or TF-IDF centroid cosine)
+            const ci = centroids.get(ti.id);
+            const cj = centroids.get(tj.id);
+            const semanticSim = cosineSimilarity(ci, cj);
+            // Signal 2: File overlap (Jaccard of all edited files)
+            const filesI = new Set();
+            const filesJ = new Set();
+            for (const sid of ti.sessionIds) {
+                const s = sessionIndex.get(sid);
+                if (s)
+                    s.meta.filesEdited.forEach((f) => filesI.add(f));
+            }
+            for (const sid of tj.sessionIds) {
+                const s = sessionIndex.get(sid);
+                if (s)
+                    s.meta.filesEdited.forEach((f) => filesJ.add(f));
+            }
+            const intersection = [...filesI].filter((f) => filesJ.has(f));
+            const union = new Set([...filesI, ...filesJ]);
+            const fileOverlap = union.size > 0 ? intersection.length / union.size : 0;
+            // Signal 3: Session overlap (temporal adjacency / same branch)
+            let sessionOverlap = 0;
+            for (const sidI of ti.sessionIds) {
+                const si = sessionIndex.get(sidI);
+                if (!si)
+                    continue;
+                for (const sidJ of tj.sessionIds) {
+                    const sj = sessionIndex.get(sidJ);
+                    if (!sj)
+                        continue;
+                    if (si.projectDisplayName === sj.projectDisplayName &&
+                        si.meta.gitBranch &&
+                        si.meta.gitBranch === sj.meta.gitBranch) {
+                        sessionOverlap = Math.max(sessionOverlap, 0.6);
+                    }
+                    // Temporal adjacency: sessions within 1 hour of each other
+                    const timeDiff = Math.abs(new Date(si.meta.createdAt).getTime() -
+                        new Date(sj.meta.createdAt).getTime());
+                    if (timeDiff < 3600000) {
+                        sessionOverlap = Math.max(sessionOverlap, 0.4);
+                    }
+                }
+            }
+            // Weighted sum
+            const strength = semanticSim * 0.4 + fileOverlap * 0.3 + sessionOverlap * 0.3;
+            if (strength < 0.2)
+                continue;
+            // Determine dominant signal and generate label
+            const signals = { semanticSimilarity: semanticSim, fileOverlap, sessionOverlap };
+            const { type, label } = classifyEdge(ti, tj, signals, intersection, tfidf, centroids);
+            edges.push({
+                source: ti.id,
+                target: tj.id,
+                type,
+                strength: Math.round(strength * 100) / 100,
+                label,
+                signals,
+            });
+        }
+    }
+    return edges;
+}
+export function classifyEdge(ti, tj, signals, sharedFiles, tfidf, centroids) {
+    const isCrossProject = ti.projects.some((p) => tj.projects.includes(p)) === false &&
+        ti.project !== tj.project;
+    if (isCrossProject) {
+        // Find shared keywords between centroids
+        const sharedKw = findSharedKeywords(ti.id, tj.id, tfidf, centroids, 3);
+        return {
+            type: "cross-project-bridge",
+            label: `cross-project: ${sharedKw.join(", ") || "related concepts"}`,
+        };
+    }
+    // Find dominant signal
+    const { semanticSimilarity, fileOverlap, sessionOverlap } = signals;
+    const maxSignal = Math.max(semanticSimilarity * 0.4, fileOverlap * 0.3, sessionOverlap * 0.3);
+    if (maxSignal === fileOverlap * 0.3 && sharedFiles.length > 0) {
+        const commonPrefix = findCommonPathPrefix(sharedFiles);
+        return {
+            type: "shared-module",
+            label: `shared: ${commonPrefix || sharedFiles[0]?.split("/").slice(-2).join("/") || "files"}`,
+        };
+    }
+    if (maxSignal === sessionOverlap * 0.3) {
+        return {
+            type: "workflow-continuation",
+            label: "workflow continuation",
+        };
+    }
+    // Default: semantic similarity
+    const sharedKw = findSharedKeywords(ti.id, tj.id, tfidf, centroids, 3);
+    return {
+        type: "semantic-similarity",
+        label: `related: ${sharedKw.join(", ") || "similar topics"}`,
+    };
+}
+export function findSharedKeywords(topicIdA, topicIdB, tfidf, centroids, topK) {
+    const ca = centroids.get(topicIdA);
+    const cb = centroids.get(topicIdB);
+    if (!ca || !cb)
+        return [];
+    // Find terms with high weight in both centroids
+    const shared = [];
+    for (let i = 0; i < tfidf.vocabulary.length; i++) {
+        if (ca[i] > 0.01 && cb[i] > 0.01) {
+            shared.push({ term: tfidf.vocabulary[i], score: ca[i] * cb[i] });
+        }
+    }
+    shared.sort((a, b) => b.score - a.score);
+    return shared.slice(0, topK).map((s) => s.term);
+}
+export function findCommonPathPrefix(paths) {
+    if (paths.length === 0)
+        return "";
+    const segments = paths.map((p) => p.split("/"));
+    const minLen = Math.min(...segments.map((s) => s.length));
+    let prefixLen = 0;
+    for (let i = 0; i < minLen; i++) {
+        if (segments.every((s) => s[i] === segments[0][i])) {
+            prefixLen = i + 1;
+        }
+        else {
+            break;
+        }
+    }
+    if (prefixLen <= 1)
+        return ""; // too generic
+    return segments[0].slice(0, prefixLen).join("/");
+}

package/dist-cli/knowledge-graph/feature-extraction.js

@@ -0,0 +1,124 @@
+/**
+ * Tool-IDF and structural feature extraction.
+ */
+import { STRUCTURAL_DIM } from "./constants.js";
+export function buildToolIdf(sessions) {
+    const n = sessions.length;
+    // Collect all tool names across sessions
+    const allTools = new Set();
+    const sessionToolCounts = new Map();
+    for (const s of sessions) {
+        const toolCounts = new Map();
+        // Main session tools
+        for (const [tool, count] of Object.entries(s.meta.toolBreakdown)) {
+            toolCounts.set(tool, (toolCounts.get(tool) || 0) + count);
+            allTools.add(tool);
+        }
+        // Subagent tools
+        for (const sub of Object.values(s.subagents)) {
+            for (const turn of sub.turns) {
+                for (const tc of turn.toolCalls) {
+                    toolCounts.set(tc.toolName, (toolCounts.get(tc.toolName) || 0) + 1);
+                    allTools.add(tc.toolName);
+                }
+            }
+        }
+        sessionToolCounts.set(s.sessionId, toolCounts);
+    }
+    // Build vocabulary and IDF
+    const toolVocabulary = [...allTools].sort();
+    const toolVocabIndex = new Map();
+    toolVocabulary.forEach((t, i) => toolVocabIndex.set(t, i));
+    // Document frequency: how many sessions use each tool
+    const df = new Map();
+    for (const [, counts] of sessionToolCounts) {
+        for (const tool of counts.keys()) {
+            df.set(tool, (df.get(tool) || 0) + 1);
+        }
+    }
+    // IDF weights
+    const toolIdfWeights = new Map();
+    for (const tool of toolVocabulary) {
+        toolIdfWeights.set(tool, Math.log(n / (df.get(tool) || 1)));
+    }
+    // Build per-session tool vectors: log(1 + count) * tool_idf, then L2 normalize
+    const vectors = new Map();
+    for (const s of sessions) {
+        const counts = sessionToolCounts.get(s.sessionId);
+        const vec = new Float64Array(toolVocabulary.length);
+        for (const [tool, count] of counts) {
+            const idx = toolVocabIndex.get(tool);
+            if (idx !== undefined) {
+                vec[idx] = Math.log(1 + count) * (toolIdfWeights.get(tool) || 1);
+            }
+        }
+        // L2 normalize
+        let norm = 0;
+        for (let i = 0; i < vec.length; i++)
+            norm += vec[i] * vec[i];
+        norm = Math.sqrt(norm);
+        if (norm > 0) {
+            for (let i = 0; i < vec.length; i++)
+                vec[i] /= norm;
+        }
+        vectors.set(s.sessionId, vec);
+    }
+    return { toolVocabulary, toolVocabIndex, toolIdfWeights, vectors };
+}
+export function buildStructuralVectors(sessions) {
+    const vectors = new Map();
+    for (const s of sessions) {
+        const vec = new Float64Array(STRUCTURAL_DIM);
+        const totalTurns = s.turns.length;
+        if (totalTurns === 0) {
+            vectors.set(s.sessionId, vec);
+            continue;
+        }
+        // Count roles and tool usage
+        let userCount = 0;
+        let assistantCount = 0;
+        let toolCallCount = 0;
+        let subagentTurns = 0;
+        let totalToolsInTurns = 0;
+        for (const turn of s.turns) {
+            if (turn.userPrompt)
+                userCount++;
+            if (turn.assistantTexts.length > 0)
+                assistantCount++;
+            const turnToolCount = turn.toolCalls.length;
+            if (turnToolCount > 0)
+                toolCallCount++;
+            totalToolsInTurns += turnToolCount;
+            // Check if any tool call is an Agent call
+            if (turn.toolCalls.some((tc) => tc.toolName === "Agent")) {
+                subagentTurns++;
+            }
+        }
+        // Also count subagent involvement from subagents object
+        const subagentCount = Object.keys(s.subagents).length;
+        const totalEntries = userCount + assistantCount + toolCallCount || 1;
+        vec[0] = userCount / totalEntries; // userRatio
+        vec[1] = assistantCount / totalEntries; // assistantRatio
+        vec[2] = toolCallCount / totalEntries; // toolCallRatio
+        vec[3] = subagentCount > 0
+            ? Math.min(1, (subagentTurns + subagentCount) / totalTurns)
+            : 0; // subagentRatio
+        vec[4] = Math.log(1 + totalToolsInTurns / totalTurns); // avgToolsPerTurn (log dampened)
+        // Edit heaviness vs Read heaviness
+        const tb = s.meta.toolBreakdown;
+        const totalTools = Object.values(tb).reduce((a, b) => a + b, 0) || 1;
+        vec[5] = ((tb["Edit"] || 0) + (tb["Write"] || 0)) / totalTools; // editHeaviness
+        vec[6] = ((tb["Read"] || 0) + (tb["Grep"] || 0) + (tb["Glob"] || 0)) / totalTools; // readHeaviness
+        // L2 normalize
+        let norm = 0;
+        for (let i = 0; i < vec.length; i++)
+            norm += vec[i] * vec[i];
+        norm = Math.sqrt(norm);
+        if (norm > 0) {
+            for (let i = 0; i < vec.length; i++)
+                vec[i] /= norm;
+        }
+        vectors.set(s.sessionId, vec);
+    }
+    return vectors;
+}

package/dist-cli/knowledge-graph/index.js

@@ -0,0 +1,235 @@
+/**
+ * Semantic knowledge graph construction from Claude Code session data.
+ * Pipeline: TF-IDF + Tool-IDF + Structure → SVD (Latent Semantic) → Clustering → Louvain → Brandes
+ */
+import { STRUCTURAL_DIM } from "./constants.js";
+import { tokenize } from "./tokenizer.js";
+import { buildTfidf } from "./tfidf.js";
+import { buildToolIdf, buildStructuralVectors } from "./feature-extraction.js";
+import { buildCombinedMatrix, truncatedSvd, interpretLatentDimensions } from "./svd.js";
+import { cosineDistance } from "./similarity.js";
+import { agglomerativeClusteringFromDistMatrix, splitOversizedClusters, } from "./clustering.js";
+import { buildTopicNodes } from "./topic-nodes.js";
+import { buildTopicEdges } from "./edges.js";
+import { louvainDetection, brandesBetweenness } from "./community.js";
+import { computeReusabilityScores } from "./reusability.js";
+import { extractEnrichedSequences } from "./tool-pattern.js";
+import { generateSkillCandidates } from "./skill-generator.js";
+export { tokenize, splitCamelCase, extractPathTokens, isNoiseToken } from "./tokenizer.js";
+export { buildTfidf } from "./tfidf.js";
+export { buildToolIdf, buildStructuralVectors } from "./feature-extraction.js";
+export { buildCombinedMatrix, truncatedSvd, interpretLatentDimensions } from "./svd.js";
+export { cosineSimilarity, cosineDistance } from "./similarity.js";
+export { agglomerativeClusteringFromDistMatrix, findElbowThreshold, clusterWithThresholdFromDistMatrix, splitOversizedClusters, } from "./clustering.js";
+export { extractDominantAction, selectRepresentativePrompts, generateSuggestedPrompt, computeToolSignature, classifyDominantRole, buildTopicNodes, } from "./topic-nodes.js";
+export { buildTopicEdges, classifyEdge, findSharedKeywords, findCommonPathPrefix, } from "./edges.js";
+export { louvainDetection, brandesBetweenness } from "./community.js";
+export { computeReusabilityScores } from "./reusability.js";
+export { abstractToolCall, extractEnrichedSequences } from "./tool-pattern.js";
+export { generateSkillMarkdown, generateHookJson, generateSkillCandidates } from "./skill-generator.js";
+// ─── Main Entry Point ───────────────────────────────────────────────────────
+export function buildSemanticKnowledgeGraph(sessions, options = {}) {
+    const { enableLouvain = true, enableBrandes = true } = options;
+    console.log(`  [Knowledge Graph] Processing ${sessions.length} sessions...`);
+    // Edge case: too few sessions
+    if (sessions.length === 0) {
+        return {
+            nodes: [],
+            edges: [],
+            communities: [],
+            metrics: {
+                totalTopics: 0,
+                totalEdges: 0,
+                graphDensity: 0,
+                modularity: 0,
+                isolatedTopicCount: 0,
+                bridgeTopicIds: [],
+            },
+            enrichedToolSequences: [],
+            skillCandidates: [],
+        };
+    }
+    // Step 1: Extract session text documents (for TF-IDF)
+    const documents = new Map();
+    for (const session of sessions) {
+        const textParts = [];
+        for (const turn of session.turns) {
+            if (turn.userPrompt)
+                textParts.push(turn.userPrompt);
+            for (const text of turn.assistantTexts) {
+                textParts.push(text);
+            }
+        }
+        // Also include file paths as tokens
+        for (const f of session.meta.filesEdited) {
+            textParts.push(f);
+        }
+        // Include branch name
+        if (session.meta.gitBranch) {
+            textParts.push(session.meta.gitBranch);
+        }
+        const fullText = textParts.join(" ");
+        const tokens = tokenize(fullText);
+        if (tokens.length > 0) {
+            documents.set(session.sessionId, tokens);
+        }
+    }
+    console.log(`  [Knowledge Graph] Tokenized ${documents.size} sessions (${sessions.length - documents.size} excluded: empty)`);
+    // Filter sessions to only those with documents
+    const activeSessions = sessions.filter((s) => documents.has(s.sessionId));
+    const sessionIds = activeSessions.map((s) => s.sessionId);
+    // Step 1b: Build Tool-IDF and Structural vectors (always needed, even for single topic)
+    const toolIdf = buildToolIdf(activeSessions);
+    console.log(`  [Knowledge Graph] Tool-IDF: ${toolIdf.toolVocabulary.length} tool types`);
+    const structVectors = buildStructuralVectors(activeSessions);
+    console.log(`  [Knowledge Graph] Structural features: ${STRUCTURAL_DIM} dimensions`);
+    // Extract enriched tool sequences from all sessions
+    const enrichedSequences = extractEnrichedSequences(activeSessions);
+    console.log(`  [Knowledge Graph] Enriched sequences: ${enrichedSequences.length} patterns detected`);
+    if (activeSessions.length < 2) {
+        // Single session: create one topic
+        const emptyTfidf = { vocabulary: [], vocabIndex: new Map(), vectors: new Map() };
+        const singleTopic = buildTopicNodes([sessionIds.map((_, i) => i)], activeSessions, emptyTfidf, toolIdf);
+        computeReusabilityScores(singleTopic);
+        const skillCandidates = generateSkillCandidates(singleTopic, enrichedSequences);
+        return {
+            nodes: singleTopic,
+            edges: [],
+            communities: [
+                {
+                    id: 0,
+                    topicIds: singleTopic.map((t) => t.id),
+                    label: singleTopic[0]?.label || "All",
+                    dominantProject: singleTopic[0]?.project || "",
+                },
+            ],
+            metrics: {
+                totalTopics: singleTopic.length,
+                totalEdges: 0,
+                graphDensity: 0,
+                modularity: 0,
+                isolatedTopicCount: singleTopic.length,
+                bridgeTopicIds: [],
+            },
+            enrichedToolSequences: enrichedSequences,
+            skillCandidates,
+        };
+    }
+    // Step 2: TF-IDF (text features)
+    const tfidf = buildTfidf(documents);
+    console.log(`  [Knowledge Graph] TF-IDF: ${tfidf.vocabulary.length} terms in vocabulary`);
+    // Step 3: Build combined matrix and apply Truncated SVD
+    const textDim = tfidf.vocabulary.length;
+    const toolDim = toolIdf.toolVocabulary.length;
+    const { matrix, totalDim } = buildCombinedMatrix(sessionIds, tfidf.vectors, toolIdf.vectors, structVectors, textDim, toolDim, STRUCTURAL_DIM);
+    // Choose k: enough dimensions to capture nuanced clusters.
+    // Use m/4 clamped to [20, 80] — higher than sqrt(m) to preserve more signal.
+    const targetK = Math.min(80, Math.max(20, Math.round(activeSessions.length / 4)));
+    const svd = truncatedSvd(sessionIds, matrix, totalDim, targetK);
+    console.log(`  [Knowledge Graph] SVD: ${totalDim}d → ${svd.k}d latent space (top-3 σ: ${[...svd.sigma.slice(0, 3)].map(s => s.toFixed(2)).join(', ')})`);
+    // Interpret latent dimensions (for logging and potential use in labeling)
+    const latentDims = interpretLatentDimensions(svd, tfidf.vocabulary, toolIdf.toolVocabulary, textDim, toolDim, 5);
+    // Log top 3 latent dimensions
+    for (const dim of latentDims.slice(0, 3)) {
+        const terms = dim.topTerms.slice(0, 3).map(t => t.term).join(', ');
+        const tools = dim.topTools.slice(0, 2).map(t => t.tool).join(', ');
+        console.log(`    dim-${dim.index}: var=${(dim.varianceRatio * 100).toFixed(1)}% terms=[${terms}] tools=[${tools}]`);
+    }
+    // Step 4: Clustering on dense SVD vectors (cosine distance is now reliable)
+    let clusterMembers;
+    if (activeSessions.length < 5) {
+        clusterMembers = sessionIds.map((_, i) => [i]);
+    }
+    else {
+        // Build distance matrix from SVD session vectors
+        const distKey = (i, j) => i < j ? `${i}:${j}` : `${j}:${i}`;
+        const svdDist = new Map();
+        for (let i = 0; i < sessionIds.length; i++) {
+            const vi = svd.sessionVectors.get(sessionIds[i]);
+            for (let j = i + 1; j < sessionIds.length; j++) {
+                const vj = svd.sessionVectors.get(sessionIds[j]);
+                svdDist.set(distKey(i, j), cosineDistance(vi, vj));
+            }
+        }
+        clusterMembers = agglomerativeClusteringFromDistMatrix(sessionIds, svdDist);
+        // Split oversized clusters
+        clusterMembers = splitOversizedClusters(clusterMembers, activeSessions.length, svdDist);
+    }
+    console.log(`  [Knowledge Graph] Clustering: ${clusterMembers.length} topics from ${activeSessions.length} sessions`);
+    // Step 5: Build topic nodes
+    const topics = buildTopicNodes(clusterMembers, activeSessions, tfidf, toolIdf);
+    // Step 5b: Compute reusability scores
+    computeReusabilityScores(topics);
+    console.log(`  [Knowledge Graph] Reusability scores computed for ${topics.length} topics`);
+    // Step 6: Build topic edges (using SVD vectors for semantic similarity)
+    const edges = buildTopicEdges(topics, activeSessions, tfidf, svd);
+    console.log(`  [Knowledge Graph] Edges: ${edges.length} topic connections`);
+    // Step 7: Louvain community detection (optional)
+    let communities;
+    let modularity;
+    if (enableLouvain) {
+        const louvainResult = louvainDetection(topics, edges);
+        communities = louvainResult.communities;
+        modularity = louvainResult.modularity;
+        console.log(`  [Knowledge Graph] Communities: ${communities.length} (modularity: ${modularity.toFixed(3)})`);
+    }
+    else {
+        // Fallback: each cluster is its own community
+        communities = topics.map((t, i) => ({
+            id: i,
+            topicIds: [t.id],
+            label: t.label,
+            dominantProject: t.project,
+        }));
+        // Assign communityId to topics
+        for (let i = 0; i < topics.length; i++) {
+            topics[i].communityId = i;
+        }
+        modularity = 0;
+        console.log(`  [Knowledge Graph] Communities: ${communities.length} (Louvain disabled, using cluster-based)`);
+    }
+    // Step 8: Graph metrics (Brandes + degree centrality, optional)
+    if (enableBrandes) {
+        brandesBetweenness(topics, edges);
+    }
+    else {
+        // Compute degree centrality only
+        const nTopics = topics.length;
+        const degreeMap = new Map();
+        for (const e of edges) {
+            degreeMap.set(e.source, (degreeMap.get(e.source) || 0) + 1);
+            degreeMap.set(e.target, (degreeMap.get(e.target) || 0) + 1);
+        }
+        for (const t of topics) {
+            t.degreeCentrality = nTopics > 1
+                ? (degreeMap.get(t.id) || 0) / (nTopics - 1)
+                : 0;
+        }
+        console.log(`  [Knowledge Graph] Brandes disabled, degree centrality only`);
+    }
+    const isolatedCount = topics.filter((t) => t.degreeCentrality === 0).length;
+    const nTopics = topics.length;
+    const maxEdges = (nTopics * (nTopics - 1)) / 2;
+    const density = maxEdges > 0 ? edges.length / maxEdges : 0;
+    // Bridge topics: top 10% by betweenness centrality
+    const sortedByBetweenness = [...topics]
+        .filter((t) => t.betweennessCentrality > 0)
+        .sort((a, b) => b.betweennessCentrality - a.betweennessCentrality);
+    const bridgeCount = Math.max(1, Math.ceil(sortedByBetweenness.length * 0.1));
+    const bridgeTopicIds = sortedByBetweenness
+        .slice(0, bridgeCount)
+        .map((t) => t.id);
+    const metrics = {
+        totalTopics: nTopics,
+        totalEdges: edges.length,
+        graphDensity: Math.round(density * 10000) / 10000,
+        modularity: Math.round(modularity * 10000) / 10000,
+        isolatedTopicCount: isolatedCount,
+        bridgeTopicIds,
+    };
+    // Step 9: Generate skill candidates
+    const skillCandidates = generateSkillCandidates(topics, enrichedSequences);
+    console.log(`  [Knowledge Graph] Skill candidates: ${skillCandidates.length} generated`);
+    console.log(`  [Knowledge Graph] Done. ${nTopics} topics, ${edges.length} edges, ${communities.length} communities, ${isolatedCount} isolated`);
+    return { nodes: topics, edges, communities, metrics, enrichedToolSequences: enrichedSequences, skillCandidates };
+}

package/dist-cli/knowledge-graph/reusability.js

@@ -0,0 +1,51 @@
+/**
+ * Reusability score computation for topic nodes.
+ * Quantifies how valuable a topic pattern is for automation as skill/hook.
+ */
+export function computeReusabilityScores(topics, now = new Date()) {
+    if (topics.length === 0)
+        return;
+    const maxSessionCount = Math.max(...topics.map((t) => t.sessionCount));
+    const maxProjects = Math.max(...topics.map((t) => t.projects.length));
+    const avgDurations = topics.map((t) => t.sessionCount > 0 ? t.totalDurationMinutes / t.sessionCount : 0);
+    const maxAvgDuration = Math.max(...avgDurations, 1);
+    const nowMs = now.getTime();
+    const daysSinceLastSeen = topics.map((t) => {
+        if (!t.lastSeen)
+            return Infinity;
+        const diff = nowMs - new Date(t.lastSeen).getTime();
+        return Math.max(0, diff / (1000 * 60 * 60 * 24));
+    });
+    const maxDays = Math.max(...daysSinceLastSeen.filter((d) => isFinite(d)), 1);
+    for (let i = 0; i < topics.length; i++) {
+        const topic = topics[i];
+        const frequency = maxSessionCount > 0
+            ? topic.sessionCount / maxSessionCount
+            : 0;
+        const avgDuration = topic.sessionCount > 0
+            ? topic.totalDurationMinutes / topic.sessionCount
+            : 0;
+        const timeCost = maxAvgDuration > 0
+            ? avgDuration / maxAvgDuration
+            : 0;
+        const crossProjectScore = maxProjects > 1
+            ? (topic.projects.length - 1) / (maxProjects - 1)
+            : 0;
+        const days = daysSinceLastSeen[i];
+        const recency = isFinite(days) && maxDays > 0
+            ? 1 - days / maxDays
+            : 0;
+        const overall = 0.35 * frequency +
+            0.25 * timeCost +
+            0.25 * crossProjectScore +
+            0.15 * recency;
+        const score = {
+            overall: Math.round(overall * 1000) / 1000,
+            frequency: Math.round(frequency * 1000) / 1000,
+            timeCost: Math.round(timeCost * 1000) / 1000,
+            crossProjectScore: Math.round(crossProjectScore * 1000) / 1000,
+            recency: Math.round(recency * 1000) / 1000,
+        };
+        topic.reusabilityScore = score;
+    }
+}

package/dist-cli/knowledge-graph/similarity.js

@@ -0,0 +1,13 @@
+/**
+ * Cosine similarity and distance for L2-normalized vectors.
+ */
+export function cosineSimilarity(a, b) {
+    let dot = 0;
+    for (let i = 0; i < a.length; i++) {
+        dot += a[i] * b[i];
+    }
+    return dot; // Already L2-normalized
+}
+export function cosineDistance(a, b) {
+    return 1 - cosineSimilarity(a, b);
+}