@chigichan24/crune 0.1.4 → 0.1.5

package/dist-cli/analyze-sessions.js

@@ -10,10 +10,10 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import * as os from "node:os";
-import { buildSemanticKnowledgeGraph, } from "./knowledge-graph-builder.js";
-import { buildSynthesisPrompt, synthesizeWithClaude } from "./skill-synthesizer.js";
+import { buildSemanticKnowledgeGraph, readFacetsDir, aggregateFacetsForTopic, } from "./knowledge-graph-builder.js";
+import { buildSynthesisPrompt, synthesizeWithClaude, stripSynthesisPreamble } from "./skill-synthesizer.js";
 import { generateSessionSummary } from "./session-summarizer.js";
-import { discoverSessions, parseJsonlFile, buildTurns, extractMetadata, parseSubagents, loadLinkedPlan, } from "./session-parser.js";
+import { discoverSessions, parseJsonlFile, buildTurns, extractMetadata, parseSubagents, loadLinkedPlan, isNonInteractiveSession, } from "./session-parser.js";
 function parseArgs() {
     const args = process.argv.slice(2);
     let sessionsDir = path.join(os.homedir(), ".claude", "projects");
@@ -21,6 +21,8 @@ function parseArgs() {
     let skipSynthesis = false;
     let synthesisModel;
     let synthesisCount = 5;
+    let facetsDir = path.join(os.homedir(), ".claude", "usage-data", "facets");
+    let skipFacets = false;
     for (let i = 0; i < args.length; i++) {
         if (args[i] === "--sessions-dir" && args[i + 1]) {
             sessionsDir = path.resolve(args[++i]);
@@ -31,17 +33,32 @@ function parseArgs() {
         else if (args[i] === "--skip-synthesis") {
             skipSynthesis = true;
         }
+        else if (args[i] === "--skip-synthesize") {
+            skipSynthesis = true;
+        }
         else if (args[i] === "--synthesis-model" && args[i + 1]) {
             synthesisModel = args[++i];
         }
+        else if (args[i] === "--synthesize-model" && args[i + 1]) {
+            synthesisModel = args[++i];
+        }
         else if (args[i] === "--synthesis-count" && args[i + 1]) {
             synthesisCount = Math.max(1, parseInt(args[++i], 10) || 5);
         }
+        else if (args[i] === "--synthesize-count" && args[i + 1]) {
+            synthesisCount = Math.max(1, parseInt(args[++i], 10) || 5);
+        }
+        else if (args[i] === "--facets-dir" && args[i + 1]) {
+            facetsDir = path.resolve(args[++i]);
+        }
+        else if (args[i] === "--skip-facets") {
+            skipFacets = true;
+        }
     }
-    return { sessionsDir, outputDir, skipSynthesis, synthesisModel, synthesisCount };
+    return { sessionsDir, outputDir, skipSynthesis, synthesisModel, synthesisCount, facetsDir, skipFacets };
 }
 // ─── Task 1.5: index.json Generation ────────────────────────────────────────
-function generateIndex(sessions) {
+function generateIndex(sessions, facetsMap) {
     const projectMap = new Map();
     const sessionSummaries = sessions.map((s) => {
         const existing = projectMap.get(s.projectDisplayName) || {
@@ -69,7 +86,7 @@ function generateIndex(sessions) {
             durationMinutes: s.meta.durationMinutes,
             turnCount: s.meta.turnCount,
             toolBreakdown: s.meta.toolBreakdown,
-            firstUserPrompt: s.meta.firstUserPrompt,
+            firstUserPrompt: facetsMap?.get(s.meta.sessionId)?.briefSummary || s.meta.firstUserPrompt,
             summaryText: summaryInfo.summary,
             keywords: summaryInfo.keywords,
             scope: summaryInfo.scope,
@@ -250,7 +267,9 @@ async function generateOverview(sessions, synthesisConfig = { skip: false, count
             subagentCount: s.meta.subagentCount,
         },
     }));
-    const knowledgeGraph = buildSemanticKnowledgeGraph(sessionInputs);
+    const knowledgeGraph = buildSemanticKnowledgeGraph(sessionInputs, {
+        facetsDir: synthesisConfig.facetsDir,
+    });
     // Top files
     const topFiles = [...fileEditCounts.entries()]
         .sort((a, b) => b[1] - a[1])
@@ -337,16 +356,21 @@ async function generateOverview(sessions, synthesisConfig = { skip: false, count
             const topicSessionSet = new Set(topic.sessionIds);
             const relatedSequences = knowledgeGraph.enrichedToolSequences.filter((seq) => seq.sessionIds.some((sid) => topicSessionSet.has(sid)));
             console.error(`[crune]   [${i + 1}/${total}] ${topic.label}...`);
+            // Build facets insights for this topic if facets data is available
+            const facetsInsights = synthesisConfig.facetsDir
+                ? aggregateFacetsForTopic(topic.sessionIds, readFacetsDir(synthesisConfig.facetsDir))
+                : undefined;
             const prompt = buildSynthesisPrompt({
                 skillCandidate: candidate,
                 topicNode: topic,
                 enrichedSequences: relatedSequences,
+                facetsInsights: facetsInsights,
             });
             const result = await synthesizeWithClaude(prompt, synthOpts);
             if (result.success) {
                 const original = knowledgeGraph.skillCandidates.find((sc) => sc.topicId === candidate.topicId);
                 if (original) {
-                    original.synthesizedMarkdown = result.stdout;
+                    original.synthesizedMarkdown = stripSynthesisPreamble(result.stdout);
                 }
                 console.error(`[crune]   [${i + 1}/${total}] Done.`);
             }
@@ -386,9 +410,21 @@ function getWeekLabel(date) {
 // buildKnowledgeGraphEdges removed — replaced by buildSemanticKnowledgeGraph
 // ─── Main Pipeline ──────────────────────────────────────────────────────────
 async function main() {
-    const { sessionsDir, outputDir, skipSynthesis, synthesisModel, synthesisCount } = parseArgs();
+    const { sessionsDir, outputDir, skipSynthesis, synthesisModel, synthesisCount, facetsDir, skipFacets } = parseArgs();
     console.error(`[crune] Sessions dir: ${sessionsDir}`);
     console.error(`[crune] Output dir:   ${outputDir}`);
+    console.error(`[crune] Facets dir:   ${skipFacets ? "(skipped)" : facetsDir}`);
+    // Step 0: Refresh /insights data if facets are enabled
+    if (!skipFacets) {
+        console.error(`\n[crune] Refreshing /insights data...`);
+        const refreshResult = await synthesizeWithClaude("/insights", { timeoutMs: 300_000 });
+        if (refreshResult.success) {
+            console.error(`[crune] /insights data refreshed.`);
+        }
+        else {
+            console.error(`[crune] /insights refresh failed (continuing without): ${refreshResult.error ?? "unknown"}`);
+        }
+    }
     // Step 1: Discover sessions
     console.error(`\n[crune] Discovering sessions...`);
     const sessionFiles = discoverSessions(sessionsDir);
@@ -397,11 +433,17 @@ async function main() {
         console.error("[crune] No sessions found. Exiting.");
         process.exit(1);
     }
+    // Step 1.5: Filter out non-interactive sessions (claude -p synthesis, /insights)
+    const interactiveSessions = sessionFiles.filter((sf) => !isNonInteractiveSession(sf.filePath));
+    const skippedCount = sessionFiles.length - interactiveSessions.length;
+    if (skippedCount > 0) {
+        console.error(`[crune] Skipped ${skippedCount} non-interactive sessions (claude -p)`);
+    }
     // Step 2: Parse each session with metadata and subagents
     const parsedSessions = [];
-    for (let i = 0; i < sessionFiles.length; i++) {
-        const sf = sessionFiles[i];
-        console.error(`[crune] Processing session ${i + 1}/${sessionFiles.length}: ${sf.sessionId}`);
+    for (let i = 0; i < interactiveSessions.length; i++) {
+        const sf = interactiveSessions[i];
+        console.error(`[crune] Processing session ${i + 1}/${interactiveSessions.length}: ${sf.sessionId}`);
         try {
             // Parse main JSONL
             const lines = await parseJsonlFile(sf.filePath);
@@ -439,7 +481,8 @@ async function main() {
     fs.mkdirSync(outputDir, { recursive: true });
     fs.mkdirSync(path.join(outputDir, "detail"), { recursive: true });
     // index.json
-    const indexData = generateIndex(parsedSessions);
+    const indexFacetsMap = skipFacets ? undefined : readFacetsDir(facetsDir);
+    const indexData = generateIndex(parsedSessions, indexFacetsMap);
     const indexPath = path.join(outputDir, "index.json");
     fs.writeFileSync(indexPath, JSON.stringify(indexData, null, 2));
     const indexSize = fs.statSync(indexPath).size;
@@ -458,6 +501,7 @@ async function main() {
         skip: skipSynthesis,
         model: synthesisModel,
         count: synthesisCount,
+        facetsDir: skipFacets ? undefined : facetsDir,
     });
     const overviewPath = path.join(outputDir, "overview.json");
     fs.writeFileSync(overviewPath, JSON.stringify(overviewData, null, 2));

package/dist-cli/cli.js

@@ -7,7 +7,7 @@ import * as path from "node:path";
 import * as os from "node:os";
 import { discoverSessions, parseJsonlFile, buildTurns, extractMetadata, parseSubagents, } from "./session-parser.js";
 import { buildSemanticKnowledgeGraph, } from "./knowledge-graph-builder.js";
-import { buildSynthesisPrompt, synthesizeWithClaude, } from "./skill-synthesizer.js";
+import { buildSynthesisPrompt, synthesizeWithClaude, stripSynthesisPreamble, } from "./skill-synthesizer.js";
 export function parseCliArgs(argv) {
     const args = argv.slice(2);
     let sessionsDir = path.join(os.homedir(), ".claude", "projects");
@@ -168,7 +168,7 @@ async function main() {
                 model: config.model,
             });
             if (result.success) {
-                markdown = result.stdout;
+                markdown = stripSynthesisPreamble(result.stdout);
                 console.error(`    Synthesized`);
             }
             else {

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

@@ -1,6 +1,7 @@
 /**
  * Agglomerative clustering with average linkage and automatic elbow detection.
  */
+import { normalizeGoalCategory } from "./facets-reader.js";
 export function agglomerativeClusteringFromDistMatrix(sessionIds, precomputedDist) {
     const n = sessionIds.length;
     if (n === 0)
@@ -172,3 +173,110 @@ export function splitOversizedClusters(clusters, totalSessions, precomputedDist,
     }
     return result;
 }
+/**
+ * Merge narrow (≤ maxNarrowSize sessions) clusters that share normalized goal
+ * categories from facets data. This addresses the "too narrow scope" issue
+ * where the clustering algorithm creates single-session topics.
+ *
+ * Algorithm:
+ * 1. Identify narrow clusters (≤ maxNarrowSize members)
+ * 2. For each pair of narrow clusters, check if they share normalized goal categories
+ * 3. Merge if they share ≥1 category AND average inter-cluster distance < distanceThreshold
+ * 4. Stop merging if merged size exceeds maxMergedSize
+ */
+export function mergeNarrowClusters(clusters, sessionIds, facetsMap, precomputedDist, maxNarrowSize = 2, distanceThreshold = 0.7, maxMergedSize = 8) {
+    // Separate clusters into narrow and large
+    const largeClusters = [];
+    const narrowClusters = [];
+    for (const cluster of clusters) {
+        if (cluster.length > maxNarrowSize) {
+            largeClusters.push(cluster);
+        }
+        else {
+            narrowClusters.push([...cluster]);
+        }
+    }
+    // If no narrow clusters, return as-is
+    if (narrowClusters.length === 0) {
+        return clusters;
+    }
+    // For each narrow cluster, collect normalized goal categories
+    const clusterCategories = narrowClusters.map((cluster) => {
+        const cats = new Set();
+        for (const idx of cluster) {
+            const sid = sessionIds[idx];
+            const facets = facetsMap.get(sid);
+            if (facets && facets.goalCategories) {
+                for (const rawCat of Object.keys(facets.goalCategories)) {
+                    cats.add(normalizeGoalCategory(rawCat));
+                }
+            }
+        }
+        return cats;
+    });
+    // Helper: compute average inter-cluster distance
+    const avgInterClusterDist = (clusterA, clusterB) => {
+        let sum = 0;
+        let count = 0;
+        for (const i of clusterA) {
+            for (const j of clusterB) {
+                const lo = Math.min(i, j);
+                const hi = Math.max(i, j);
+                const d = precomputedDist.get(`${lo}:${hi}`) ?? 1.0;
+                sum += d;
+                count++;
+            }
+        }
+        return count > 0 ? sum / count : 1.0;
+    };
+    // Helper: check if two category sets share at least one category
+    const sharesCategory = (a, b) => {
+        for (const cat of a) {
+            if (b.has(cat))
+                return true;
+        }
+        return false;
+    };
+    // Track which narrow clusters have been consumed
+    const consumed = new Set();
+    // Greedily merge narrow clusters
+    for (let i = 0; i < narrowClusters.length; i++) {
+        if (consumed.has(i))
+            continue;
+        // Skip if this cluster has no facets categories
+        if (clusterCategories[i].size === 0)
+            continue;
+        for (let j = i + 1; j < narrowClusters.length; j++) {
+            if (consumed.has(j))
+                continue;
+            // Skip if target cluster has no facets categories
+            if (clusterCategories[j].size === 0)
+                continue;
+            // Check shared categories
+            if (!sharesCategory(clusterCategories[i], clusterCategories[j]))
+                continue;
+            // Check merged size
+            if (narrowClusters[i].length + narrowClusters[j].length > maxMergedSize)
+                continue;
+            // Check distance
+            const dist = avgInterClusterDist(narrowClusters[i], narrowClusters[j]);
+            if (dist >= distanceThreshold)
+                continue;
+            // Merge j into i
+            narrowClusters[i].push(...narrowClusters[j]);
+            // Merge categories
+            for (const cat of clusterCategories[j]) {
+                clusterCategories[i].add(cat);
+            }
+            consumed.add(j);
+        }
+    }
+    // Collect surviving narrow clusters
+    const mergedNarrow = [];
+    for (let i = 0; i < narrowClusters.length; i++) {
+        if (!consumed.has(i)) {
+            mergedNarrow.push(narrowClusters[i]);
+        }
+    }
+    return [...largeClusters, ...mergedNarrow];
+}

package/dist-cli/knowledge-graph/facets-reader.js

@@ -0,0 +1,188 @@
+/**
+ * Reads facets JSON files from /insights directory and provides
+ * utilities for normalization and aggregation.
+ */
+import { readFileSync, readdirSync, existsSync } from "node:fs";
+import { join } from "node:path";
+// ─── Goal category normalization ────────────────────────────────────────────
+export function normalizeGoalCategory(raw) {
+    if (raw.startsWith("feature") ||
+        raw.startsWith("ui_") ||
+        raw.startsWith("css_")) {
+        return "feature";
+    }
+    if (raw.startsWith("fix_") ||
+        raw.startsWith("bug_") ||
+        raw.startsWith("debug")) {
+        return "bugfix";
+    }
+    if (raw.startsWith("refactoring") ||
+        raw === "code_cleanup" ||
+        raw.startsWith("cleanup_")) {
+        return "refactoring";
+    }
+    if (raw.startsWith("documentation") || raw.startsWith("readme_")) {
+        return "documentation";
+    }
+    if (raw.startsWith("code_review")) {
+        return "review";
+    }
+    if (raw.startsWith("test_")) {
+        return "testing";
+    }
+    if (raw.startsWith("ci_")) {
+        return "ci";
+    }
+    if (raw.startsWith("git_") ||
+        raw === "create_pr" ||
+        raw.startsWith("pr_") ||
+        raw.startsWith("resolve_merge")) {
+        return "git_ops";
+    }
+    if (raw.startsWith("setup_") ||
+        raw.startsWith("configuration_") ||
+        raw.startsWith("dependency_") ||
+        raw.startsWith("npm_")) {
+        return "setup";
+    }
+    return "other";
+}
+// ─── Read facets directory ──────────────────────────────────────────────────
+export function readFacetsDir(facetsDir) {
+    const result = new Map();
+    if (!existsSync(facetsDir)) {
+        console.warn(`[facets-reader] Directory not found: ${facetsDir}`);
+        return result;
+    }
+    let files;
+    try {
+        files = readdirSync(facetsDir).filter((f) => f.endsWith(".json"));
+    }
+    catch (err) {
+        console.warn(`[facets-reader] Failed to read directory: ${facetsDir}`, err);
+        return result;
+    }
+    for (const file of files) {
+        try {
+            const raw = readFileSync(join(facetsDir, file), "utf-8");
+            const json = JSON.parse(raw);
+            const facets = {
+                sessionId: json.session_id,
+                underlyingGoal: json.underlying_goal,
+                goalCategories: json.goal_categories,
+                outcome: json.outcome,
+                claudeHelpfulness: json.claude_helpfulness,
+                sessionType: json.session_type,
+                frictionCounts: json.friction_counts,
+                frictionDetail: json.friction_detail,
+                primarySuccess: json.primary_success,
+                briefSummary: json.brief_summary,
+            };
+            if (facets.sessionId) {
+                result.set(facets.sessionId, facets);
+            }
+        }
+        catch (err) {
+            console.warn(`[facets-reader] Failed to parse ${file}`, err);
+        }
+    }
+    return result;
+}
+// ─── Helpfulness mapping ────────────────────────────────────────────────────
+export function helpfulnessToScore(helpfulness) {
+    switch (helpfulness) {
+        case "essential":
+            return 1.0;
+        case "very_helpful":
+            return 0.8;
+        case "moderately_helpful":
+            return 0.5;
+        case "slightly_helpful":
+            return 0.25;
+        case "unhelpful":
+            return 0.0;
+        default:
+            return 0.5;
+    }
+}
+// ─── Aggregate facets for a topic ───────────────────────────────────────────
+export function aggregateFacetsForTopic(sessionIds, facetsMap) {
+    const matchedFacets = [];
+    for (const sid of sessionIds) {
+        const f = facetsMap.get(sid);
+        if (f)
+            matchedFacets.push(f);
+    }
+    if (matchedFacets.length === 0)
+        return undefined;
+    // aggregatedGoals: unique underlying_goal strings, max 3
+    const goalsSet = new Set();
+    for (const f of matchedFacets) {
+        if (f.underlyingGoal)
+            goalsSet.add(f.underlyingGoal);
+    }
+    const aggregatedGoals = [...goalsSet].slice(0, 3);
+    // normalizedCategories: unique normalized goal categories across all sessions
+    const categorySet = new Set();
+    for (const f of matchedFacets) {
+        if (f.goalCategories) {
+            for (const key of Object.keys(f.goalCategories)) {
+                categorySet.add(normalizeGoalCategory(key));
+            }
+        }
+    }
+    const normalizedCategories = [...categorySet];
+    // successRate: fraction with fully_achieved or mostly_achieved
+    // Sessions without facets get 0.5
+    let successSum = 0;
+    for (const sid of sessionIds) {
+        const f = facetsMap.get(sid);
+        if (f) {
+            const achieved = f.outcome === "fully_achieved" || f.outcome === "mostly_achieved";
+            successSum += achieved ? 1 : 0;
+        }
+        else {
+            successSum += 0.5;
+        }
+    }
+    const successRate = sessionIds.length > 0 ? successSum / sessionIds.length : 0;
+    // helpfulnessScore: average helpfulnessToScore
+    // Sessions without facets get 0.5
+    let helpSum = 0;
+    for (const sid of sessionIds) {
+        const f = facetsMap.get(sid);
+        if (f) {
+            helpSum += helpfulnessToScore(f.claudeHelpfulness);
+        }
+        else {
+            helpSum += 0.5;
+        }
+    }
+    const helpfulnessScore = sessionIds.length > 0 ? helpSum / sessionIds.length : 0;
+    // commonFrictions: merge friction_counts, sort by count desc, top 5
+    const frictionMerged = new Map();
+    for (const f of matchedFacets) {
+        if (f.frictionCounts) {
+            for (const [key, count] of Object.entries(f.frictionCounts)) {
+                frictionMerged.set(key, (frictionMerged.get(key) || 0) + count);
+            }
+        }
+    }
+    const commonFrictions = [...frictionMerged.entries()]
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, 5)
+        .map(([key]) => key);
+    // frictionDetails: non-empty friction_detail strings, max 3
+    const frictionDetails = matchedFacets
+        .map((f) => f.frictionDetail)
+        .filter((d) => d && d.length > 0)
+        .slice(0, 3);
+    return {
+        aggregatedGoals,
+        normalizedCategories,
+        successRate,
+        helpfulnessScore,
+        commonFrictions,
+        frictionDetails,
+    };
+}

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

@@ -8,7 +8,8 @@ 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 { agglomerativeClusteringFromDistMatrix, splitOversizedClusters, mergeNarrowClusters, } from "./clustering.js";
+import { readFacetsDir } from "./facets-reader.js";
 import { buildTopicNodes } from "./topic-nodes.js";
 import { buildTopicEdges } from "./edges.js";
 import { louvainDetection, brandesBetweenness } from "./community.js";
@@ -20,17 +21,23 @@ 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 { agglomerativeClusteringFromDistMatrix, findElbowThreshold, clusterWithThresholdFromDistMatrix, splitOversizedClusters, mergeNarrowClusters, } 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";
+export { readFacetsDir, normalizeGoalCategory, helpfulnessToScore, aggregateFacetsForTopic } from "./facets-reader.js";
 // ─── Main Entry Point ───────────────────────────────────────────────────────
 export function buildSemanticKnowledgeGraph(sessions, options = {}) {
-    const { enableLouvain = true, enableBrandes = true } = options;
+    const { enableLouvain = true, enableBrandes = true, facetsDir } = options;
     console.log(`  [Knowledge Graph] Processing ${sessions.length} sessions...`);
+    // Read facets data if directory is provided
+    const facetsMap = facetsDir ? readFacetsDir(facetsDir) : new Map();
+    if (facetsDir) {
+        console.log(`  [Knowledge Graph] Facets: ${facetsMap.size} sessions with /insights data`);
+    }
     // Edge case: too few sessions
     if (sessions.length === 0) {
         return {
@@ -89,8 +96,8 @@ export function buildSemanticKnowledgeGraph(sessions, options = {}) {
     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 singleTopic = buildTopicNodes([sessionIds.map((_, i) => i)], activeSessions, emptyTfidf, toolIdf, facetsMap);
+        computeReusabilityScores(singleTopic, new Date(), facetsMap);
         const skillCandidates = generateSkillCandidates(singleTopic, enrichedSequences);
         return {
             nodes: singleTopic,
@@ -154,12 +161,20 @@ export function buildSemanticKnowledgeGraph(sessions, options = {}) {
         clusterMembers = agglomerativeClusteringFromDistMatrix(sessionIds, svdDist);
         // Split oversized clusters
         clusterMembers = splitOversizedClusters(clusterMembers, activeSessions.length, svdDist);
+        // Merge narrow clusters using facets goal categories
+        if (facetsMap.size > 0) {
+            const beforeCount = clusterMembers.length;
+            clusterMembers = mergeNarrowClusters(clusterMembers, sessionIds, facetsMap, svdDist);
+            if (clusterMembers.length < beforeCount) {
+                console.log(`  [Knowledge Graph] Merged narrow clusters: ${beforeCount} → ${clusterMembers.length} topics`);
+            }
+        }
     }
     console.log(`  [Knowledge Graph] Clustering: ${clusterMembers.length} topics from ${activeSessions.length} sessions`);
     // Step 5: Build topic nodes
-    const topics = buildTopicNodes(clusterMembers, activeSessions, tfidf, toolIdf);
+    const topics = buildTopicNodes(clusterMembers, activeSessions, tfidf, toolIdf, facetsMap);
     // Step 5b: Compute reusability scores
-    computeReusabilityScores(topics);
+    computeReusabilityScores(topics, new Date(), facetsMap);
     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);

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

@@ -2,7 +2,8 @@
  * 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()) {
+import { helpfulnessToScore } from "./facets-reader.js";
+export function computeReusabilityScores(topics, now = new Date(), facetsMap) {
     if (topics.length === 0)
         return;
     const maxSessionCount = Math.max(...topics.map((t) => t.sessionCount));
@@ -17,6 +18,7 @@ export function computeReusabilityScores(topics, now = new Date()) {
         return Math.max(0, diff / (1000 * 60 * 60 * 24));
     });
     const maxDays = Math.max(...daysSinceLastSeen.filter((d) => isFinite(d)), 1);
+    const useFacets = facetsMap != null && facetsMap.size > 0;
     for (let i = 0; i < topics.length; i++) {
         const topic = topics[i];
         const frequency = maxSessionCount > 0
@@ -35,17 +37,51 @@ export function computeReusabilityScores(topics, now = new Date()) {
         const recency = isFinite(days) && maxDays > 0
             ? 1 - days / maxDays
             : 0;
-        const overall = 0.35 * frequency +
-            0.25 * timeCost +
-            0.25 * crossProjectScore +
-            0.15 * recency;
+        let overall;
         const score = {
-            overall: Math.round(overall * 1000) / 1000,
+            overall: 0,
             frequency: Math.round(frequency * 1000) / 1000,
             timeCost: Math.round(timeCost * 1000) / 1000,
             crossProjectScore: Math.round(crossProjectScore * 1000) / 1000,
             recency: Math.round(recency * 1000) / 1000,
         };
+        if (useFacets) {
+            // Compute successRate and helpfulness from facets
+            let successSum = 0;
+            let helpfulnessSum = 0;
+            for (const sessionId of topic.sessionIds) {
+                const facets = facetsMap.get(sessionId);
+                if (facets) {
+                    const outcome = facets.outcome;
+                    successSum += (outcome === "fully_achieved" || outcome === "mostly_achieved") ? 1.0 : 0.0;
+                    helpfulnessSum += helpfulnessToScore(facets.claudeHelpfulness);
+                }
+                else {
+                    successSum += 0.5;
+                    helpfulnessSum += 0.5;
+                }
+            }
+            const sessionCount = topic.sessionIds.length || 1;
+            const successRate = successSum / sessionCount;
+            const helpfulness = helpfulnessSum / sessionCount;
+            overall =
+                0.30 * frequency +
+                    0.20 * timeCost +
+                    0.20 * crossProjectScore +
+                    0.10 * recency +
+                    0.10 * successRate +
+                    0.10 * helpfulness;
+            score.successRate = Math.round(successRate * 1000) / 1000;
+            score.helpfulness = Math.round(helpfulness * 1000) / 1000;
+        }
+        else {
+            overall =
+                0.35 * frequency +
+                    0.25 * timeCost +
+                    0.25 * crossProjectScore +
+                    0.15 * recency;
+        }
+        score.overall = Math.round(overall * 1000) / 1000;
         topic.reusabilityScore = score;
     }
 }