akm-cli 0.9.0-beta.6 → 0.9.0-rc.0

package/dist/commands/read/curate.js

@@ -8,16 +8,23 @@
  * high-signal set of stash + registry hits and enrich each with the data
  * needed to act (ref, run, parameters, follow-up command).
  *
- * The exported `akmCurate()` API is the single entry point. Internal
- * helpers stay private. Tests can drive the public API or call the smaller
- * pure helpers (`curateSearchResults`, `orderCuratedTypes`,
- * `deriveCurateFallbackQueries`) by importing them directly.
+ * The exported `akmCurate()` API is the single entry point. Internal helpers
+ * stay private. Tests can drive the public API or call the smaller pure
+ * helpers (`curateSearchResults`, `deriveCurateFallbackQueries`,
+ * `mergeCurateSearchResponses`) by importing them directly.
  */
+import fs from "node:fs";
+import { parseAssetRef } from "../../core/asset/asset-ref.js";
+import { parseFrontmatter } from "../../core/asset/frontmatter.js";
+import { getIndexPassConfig, loadConfig } from "../../core/config/config.js";
 import { rethrowIfTestIsolationError, UsageError } from "../../core/errors.js";
 import { appendEvent } from "../../core/events.js";
-import { closeDatabase, openExistingDatabase } from "../../indexer/db/db.js";
+import { computeBodyHash } from "../../indexer/db/db.js";
+import { enqueueGraphExtraction, hasGraphData } from "../../indexer/db/graph-db.js";
+import { findSourceForPath, resolveSourceEntries } from "../../indexer/search/search-source.js";
 import { insertUsageEvent } from "../../indexer/usage/usage-events.js";
 import { truncateDescription } from "../../output/shapes.js";
+import { TELEMETRY_BUSY_TIMEOUT_MS, withIndexDb } from "../../storage/repositories/index-db.js";
 import { akmSearch, parseSearchSource } from "./search.js";
 import { akmShowUnified } from "./show.js";
 const CURATE_FALLBACK_FILTER_WORDS = new Set([
@@ -34,26 +41,31 @@ const CURATE_FALLBACK_FILTER_WORDS = new Set([
     "to",
     "with",
 ]);
-const CURATED_TYPE_FALLBACK_ORDER = ["skill", "command", "script", "knowledge", "agent", "memory"];
-const CURATED_TYPE_FALLBACK_INDEX = new Map(CURATED_TYPE_FALLBACK_ORDER.map((type, index) => [type, index]));
+const CURATE_SHORT_FALLBACK_TOKENS = new Set(["ai", "ci", "cd", "go", "js", "ts"]);
 const MIN_CURATE_FALLBACK_TOKEN_LENGTH = 3;
 const MAX_CURATE_FALLBACK_KEYWORDS = 6;
 export const CURATE_SEARCH_LIMIT_MULTIPLIER = 4;
 export const MIN_CURATE_SEARCH_LIMIT = 12;
 const DEFAULT_CURATE_LIMIT = 4;
+const CURATE_CLOSE_SCORE_BAND = 0.12;
+const CURATE_TAIL_SCORE_FLOOR = 0.35;
+const CURATE_RELATIVE_SCORE_FLOOR = 0.7;
+const CURATE_FALLBACK_TOP_SCORE_THRESHOLD = 0.8;
+const CURATE_FALLBACK_STRONG_SCORE_FLOOR = 0.35;
+const MAX_CURATE_SUPPORT_REFS = 2;
+const CURATE_REFERENCE_QUERY_RE = /\b(?:reference|docs?|guide|how|explain|learn|readme|why)\b/;
 /**
  * Fire-and-forget: log a curate event to the usage_events table and events.jsonl.
  * Never blocks the caller; errors are silently ignored.
  */
-function logCurateEvent(query, result) {
+function logCurateEvent(query, result, eventSource = "user") {
     const itemRefs = result.items.map((item) => ("ref" in item ? item.ref : `registry:${item.id}`));
     appendEvent({
         eventType: "curate",
         metadata: { query, itemCount: result.items.length, itemRefs },
     });
     try {
-        const db = openExistingDatabase();
-        try {
+        withIndexDb((db) => {
             insertUsageEvent(db, {
                 event_type: "curate",
                 query,
@@ -61,22 +73,24 @@ function logCurateEvent(query, result) {
                     itemCount: result.items.length,
                     itemRefs,
                 }),
-                source: "user",
+                source: eventSource,
             });
-        }
-        finally {
-            closeDatabase(db);
-        }
+            for (const item of result.items) {
+                if (!("ref" in item) || typeof item.ref !== "string")
+                    continue;
+                insertUsageEvent(db, {
+                    event_type: "curate",
+                    query,
+                    entry_ref: item.ref,
+                    source: eventSource,
+                });
+            }
+        }, { busyTimeoutMs: TELEMETRY_BUSY_TIMEOUT_MS });
     }
     catch (err) {
         rethrowIfTestIsolationError(err);
-        /* ignore logging failures */
     }
 }
-/**
- * Public curate entry point. Performs the search itself when
- * `options.searchResponse` is not supplied.
- */
 export async function akmCurate(options) {
     const trimmedQuery = options.query.trim();
     if (!trimmedQuery) {
@@ -88,36 +102,33 @@ export async function akmCurate(options) {
         (await searchForCuration({
             query: options.query,
             type: options.type,
-            // Search deeper than the final curated count so we can pick one strong
-            // match per type and still have room for fallback retries.
             limit: Math.max(limit * CURATE_SEARCH_LIMIT_MULTIPLIER, MIN_CURATE_SEARCH_LIMIT),
             source,
         }));
     const result = await curateSearchResults(options.query, searchResponse, limit, options.type);
-    logCurateEvent(options.query, result);
+    logCurateEvent(options.query, result, options.eventSource);
     return result;
 }
 export async function curateSearchResults(query, result, limit, selectedType) {
     const stashHits = result.hits.filter((hit) => hit.type !== "registry");
     const registryHits = result.registryHits ?? [];
     let selectedStashHits;
+    let supportRefsByRef = new Map();
     if (selectedType && selectedType !== "any") {
         selectedStashHits = stashHits.slice(0, limit);
     }
     else {
-        const bestByType = new Map();
-        for (const hit of stashHits) {
-            if (!bestByType.has(hit.type))
-                bestByType.set(hit.type, hit);
-        }
-        const orderedTypes = orderCuratedTypes(query, Array.from(bestByType.keys()));
-        selectedStashHits = orderedTypes
-            .map((type) => bestByType.get(type))
-            .filter((hit) => Boolean(hit));
+        const selected = selectCuratedStashHits(query, stashHits, limit);
+        const preferred = preferBroadRootRepresentative(query, selected.selected, stashHits, selected.supportRefsByRef);
+        selectedStashHits = preferred.selected;
+        supportRefsByRef = preferred.supportRefsByRef;
     }
     const selectedRegistryHits = selectedStashHits.length >= limit ? [] : registryHits.slice(0, Math.min(2, limit - selectedStashHits.length));
+    const selectedRefs = new Set(selectedStashHits.map((hit) => hit.ref));
     const items = [
-        ...(await Promise.all(selectedStashHits.slice(0, limit).map((hit) => enrichCuratedStashHit(query, hit)))),
+        ...(await Promise.all(selectedStashHits
+            .slice(0, limit)
+            .map((hit) => enrichCuratedStashHit(query, hit, supportRefsByRef.get(hit.ref) ?? [], selectedRefs)))),
         ...selectedRegistryHits.map((hit) => buildCuratedRegistryItem(query, hit)),
     ].slice(0, limit);
     return {
@@ -128,37 +139,7 @@ export async function curateSearchResults(query, result, limit, selectedType) {
         ...(result.tip ? { tip: result.tip } : {}),
     };
 }
-export function orderCuratedTypes(query, types) {
-    const lower = query.toLowerCase();
-    const boosts = new Map();
-    const addBoost = (type, amount) => boosts.set(type, (boosts.get(type) ?? 0) + amount);
-    if (/(run|script|bash|shell|cli|execute|automation|deploy|build|test|lint)/.test(lower)) {
-        addBoost("script", 6);
-        addBoost("command", 4);
-    }
-    if (/(guide|docs?|readme|reference|how|explain|learn|why)/.test(lower)) {
-        addBoost("knowledge", 6);
-        addBoost("skill", 4);
-    }
-    if (/(agent|assistant|planner|review|analy[sz]e|architect|prompt)/.test(lower)) {
-        addBoost("agent", 6);
-        addBoost("skill", 3);
-    }
-    if (/(config|template|release|generate|command)/.test(lower)) {
-        addBoost("command", 5);
-    }
-    if (/(memory|context|recall|remember)/.test(lower)) {
-        addBoost("memory", 6);
-    }
-    return [...types].sort((a, b) => {
-        const boostDiff = (boosts.get(b) ?? 0) - (boosts.get(a) ?? 0);
-        if (boostDiff !== 0)
-            return boostDiff;
-        return ((CURATED_TYPE_FALLBACK_INDEX.get(a) ?? Number.MAX_SAFE_INTEGER) -
-            (CURATED_TYPE_FALLBACK_INDEX.get(b) ?? Number.MAX_SAFE_INTEGER));
-    });
-}
-async function enrichCuratedStashHit(query, hit) {
+async function enrichCuratedStashHit(query, hit, supportRefs, selectedRefs) {
     let shown;
     try {
         shown = await akmShowUnified({ ref: hit.ref });
@@ -166,8 +147,14 @@ async function enrichCuratedStashHit(query, hit) {
     catch {
         shown = undefined;
     }
+    // #624-P3: when lazy graph extraction is opted in, enqueue an ungraphed
+    // asset for a later pass to extract. Fire-and-forget, non-blocking, NO inline
+    // extraction and NO LLM call here. Default-off (flag unset) = byte-identical.
+    if (shown?.path)
+        maybeEnqueueLazyGraph(shown.path);
     const description = shown?.description ?? hit.description;
     const preview = buildCuratedPreview(shown, hit);
+    const mergedSupportRefs = mergeCurateSupportRefs(supportRefs, shown?.related?.hits, selectedRefs, hit.ref);
     return {
         source: "stash",
         type: shown?.type ?? hit.type,
@@ -178,11 +165,50 @@ async function enrichCuratedStashHit(query, hit) {
         ...(shown?.keys?.length ? { keys: shown.keys } : {}),
         ...(shown?.parameters?.length ? { parameters: shown.parameters } : {}),
         ...(shown?.run ? { run: shown.run } : {}),
+        ...(mergedSupportRefs.length > 0 ? { supportRefs: mergedSupportRefs } : {}),
         followUp: `akm show ${hit.ref}`,
         reason: buildCuratedReason(query, shown?.type ?? hit.type),
         ...(hit.score !== undefined ? { score: hit.score } : {}),
     };
 }
+/**
+ * #624-P3 — enqueue an ungraphed asset for lazy graph extraction when the
+ * `index.graph.lazyGraphExtraction` flag is on. Pure side-effect, fully
+ * best-effort: any failure (config, fs, db) is swallowed so curate never fails
+ * on it. NO LLM call and NO inline extraction — only a cheap queue insert.
+ * Default-off (flag unset) returns immediately = byte-identical behavior.
+ */
+function maybeEnqueueLazyGraph(assetPath) {
+    try {
+        const config = loadConfig();
+        if (getIndexPassConfig(config.index, "graph")?.lazyGraphExtraction !== true)
+            return;
+        const sources = resolveSourceEntries();
+        const source = findSourceForPath(assetPath, sources);
+        const stashRoot = source?.path;
+        if (!stashRoot)
+            return;
+        let raw;
+        try {
+            raw = fs.readFileSync(assetPath, "utf8");
+        }
+        catch {
+            return;
+        }
+        const body = parseFrontmatter(raw).content.trim();
+        if (!body)
+            return;
+        const bodyHash = computeBodyHash(body);
+        withIndexDb((db) => {
+            if (!hasGraphData(db, stashRoot, assetPath)) {
+                enqueueGraphExtraction(db, stashRoot, assetPath, bodyHash, 0);
+            }
+        }, { busyTimeoutMs: TELEMETRY_BUSY_TIMEOUT_MS });
+    }
+    catch (err) {
+        rethrowIfTestIsolationError(err);
+    }
+}
 function buildCuratedRegistryItem(query, hit) {
     return {
         source: "registry",
@@ -209,19 +235,19 @@ function buildCuratedPreview(shown, hit) {
 function buildCuratedReason(query, type) {
     switch (type) {
         case "script":
-            return `Best runnable script match for "${query}".`;
+            return `Strong runnable script match for "${query}".`;
         case "command":
-            return `Best reusable command/template match for "${query}".`;
+            return `Strong reusable command/template match for "${query}".`;
         case "knowledge":
-            return `Best reference document match for "${query}".`;
+            return `Strong reference document match for "${query}".`;
         case "skill":
-            return `Best instructions/workflow match for "${query}".`;
+            return `Strong instructions/workflow match for "${query}".`;
         case "agent":
-            return `Best specialized agent prompt match for "${query}".`;
+            return `Strong specialized agent prompt match for "${query}".`;
         case "memory":
-            return `Best saved context match for "${query}".`;
+            return `Strong saved context match for "${query}".`;
         default:
-            return `Best ${type} match for "${query}".`;
+            return `Strong ${type} match for "${query}".`;
     }
 }
 function buildCurateSummary(query, items) {
@@ -229,56 +255,108 @@ function buildCurateSummary(query, items) {
         return `No curated assets were selected for "${query}".`;
     }
     const labels = items.map((item) => `${item.type}:${item.name}`);
-    return `Selected ${items.length} high-signal result${items.length === 1 ? "" : "s"}: ${labels.join(", ")}.`;
+    return `Selected ${items.length} curated result${items.length === 1 ? "" : "s"}: ${labels.join(", ")}.`;
 }
-function hasSearchResults(result) {
-    return result.hits.length > 0 || (result.registryHits?.length ?? 0) > 0;
-}
-/**
- * Extract a small set of fallback keywords when a prompt-style curate query
- * returns no hits as a whole phrase.
- *
- * We keep up to MAX_CURATE_FALLBACK_KEYWORDS distinct keywords and drop short
- * or common filler words so follow-up searches stay inexpensive while focusing
- * on higher-signal terms.
- */
 export function deriveCurateFallbackQueries(query) {
-    return Array.from(new Set(query
+    const normalizedWhole = query
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, " ")
+        .trim();
+    const tokens = Array.from(new Set(query
         .toLowerCase()
         .split(/[^a-z0-9]+/)
         .map((token) => token.trim())
-        // Keep longer tokens so fallback stays focused on higher-signal terms
-        // and avoids broad one- and two-letter matches that overwhelm curation.
-        .filter((token) => token.length >= MIN_CURATE_FALLBACK_TOKEN_LENGTH && !CURATE_FALLBACK_FILTER_WORDS.has(token)))).slice(0, MAX_CURATE_FALLBACK_KEYWORDS);
+        .filter((token) => token.length > 0 &&
+        !CURATE_FALLBACK_FILTER_WORDS.has(token) &&
+        (token.length >= MIN_CURATE_FALLBACK_TOKEN_LENGTH || CURATE_SHORT_FALLBACK_TOKENS.has(token))))).slice(0, MAX_CURATE_FALLBACK_KEYWORDS);
+    if (tokens.length === 1 && tokens[0] === normalizedWhole)
+        return [];
+    return tokens;
 }
 export function mergeCurateSearchResponses(base, extras) {
-    const hitsByRef = new Map();
+    // The base (full-query) ranking is the relevance signal — keyword fallback
+    // searches exist only to ADD recall when that ranking is thin, never to
+    // re-rank it. So we PRESERVE base order and APPEND fallback-only hits below
+    // it. A single-token fallback match on an exact title/path normalizes to a
+    // high FTS score, but those scores are not comparable to the full-query
+    // (hybrid) scores; re-sorting the union by raw score (the prior behaviour)
+    // let that keyword junk leapfrog the contextually-relevant full-query hits.
+    // Dup refs (present in both base and a fallback) keep their base POSITION but
+    // take the MAX score, since matching both the full query and a key term is a
+    // stronger relevance signal for the downstream score floor.
+    const bestExtraStashScore = new Map();
+    for (const result of extras) {
+        for (const hit of result.hits.filter((entry) => entry.type !== "registry")) {
+            const prev = bestExtraStashScore.get(hit.ref);
+            if (prev === undefined || (hit.score ?? 0) > prev)
+                bestExtraStashScore.set(hit.ref, hit.score ?? 0);
+        }
+    }
+    const baseRefs = new Set();
+    const baseStash = [];
     for (const hit of base.hits.filter((entry) => entry.type !== "registry")) {
-        hitsByRef.set(hit.ref, hit);
+        baseRefs.add(hit.ref);
+        const extraScore = bestExtraStashScore.get(hit.ref);
+        baseStash.push(extraScore !== undefined && extraScore > (hit.score ?? 0) ? { ...hit, score: extraScore } : hit);
     }
+    const extraOnly = new Map();
     for (const result of extras) {
         for (const hit of result.hits.filter((entry) => entry.type !== "registry")) {
-            const existing = hitsByRef.get(hit.ref);
-            if (!existing || (hit.score ?? 0) > (existing.score ?? 0)) {
-                hitsByRef.set(hit.ref, hit);
-            }
+            if (baseRefs.has(hit.ref))
+                continue;
+            const existing = extraOnly.get(hit.ref);
+            if (!existing || (hit.score ?? 0) > (existing.score ?? 0))
+                extraOnly.set(hit.ref, hit);
+        }
+    }
+    // Fallback-only hits must rank BELOW every full-query hit through the rest of
+    // the pipeline. The downstream selector (`selectCuratedStashHits`) RE-SORTS by
+    // score and derives its relevance floor from the top score, so preserving
+    // order here is not enough — a single-token FTS match (normalized ~0.9) would
+    // otherwise become the leader and evict the contextual full-query memories.
+    // We therefore restamp fallback-only scores into a band strictly below the
+    // minimum base score (keeping their own relative order). When there are no
+    // base hits, fallback IS the result, so scores are kept as-is.
+    const sortedExtra = [...extraOnly.values()].sort((a, b) => (b.score ?? 0) - (a.score ?? 0));
+    const minBaseScore = baseStash.length
+        ? Math.min(...baseStash.map((hit) => hit.score ?? 0))
+        : Number.POSITIVE_INFINITY;
+    const cappedExtra = baseStash.length
+        ? sortedExtra.map((hit, i) => ({ ...hit, score: minBaseScore - 1e-6 * (i + 1) }))
+        : sortedExtra;
+    const mergedHits = [...baseStash, ...cappedExtra];
+    // Registry hits are supplemental fill — same rule: base first (max score on
+    // dups), then fallback-only registry hits appended by score.
+    const bestExtraRegScore = new Map();
+    for (const result of extras) {
+        for (const hit of result.registryHits ?? []) {
+            const prev = bestExtraRegScore.get(hit.id);
+            if (prev === undefined || (hit.score ?? 0) > prev)
+                bestExtraRegScore.set(hit.id, hit.score ?? 0);
         }
     }
-    const registryById = new Map();
+    const baseRegIds = new Set();
+    const baseReg = [];
     for (const hit of base.registryHits ?? []) {
-        registryById.set(hit.id, hit);
+        baseRegIds.add(hit.id);
+        const extraScore = bestExtraRegScore.get(hit.id);
+        baseReg.push(extraScore !== undefined && extraScore > (hit.score ?? 0) ? { ...hit, score: extraScore } : hit);
     }
+    const extraRegOnly = new Map();
     for (const result of extras) {
         for (const hit of result.registryHits ?? []) {
-            const existing = registryById.get(hit.id);
-            if (!existing || (hit.score ?? 0) > (existing.score ?? 0)) {
-                registryById.set(hit.id, hit);
-            }
+            if (baseRegIds.has(hit.id))
+                continue;
+            const existing = extraRegOnly.get(hit.id);
+            if (!existing || (hit.score ?? 0) > (existing.score ?? 0))
+                extraRegOnly.set(hit.id, hit);
         }
     }
     const warnings = Array.from(new Set([...(base.warnings ?? []), ...extras.flatMap((result) => result.warnings ?? [])]));
-    const mergedHits = [...hitsByRef.values()].sort((a, b) => (b.score ?? 0) - (a.score ?? 0));
-    const mergedRegistryHits = [...registryById.values()].sort((a, b) => (b.score ?? 0) - (a.score ?? 0));
+    const mergedRegistryHits = [
+        ...baseReg,
+        ...[...extraRegOnly.values()].sort((a, b) => (b.score ?? 0) - (a.score ?? 0)),
+    ];
     return {
         ...base,
         hits: mergedHits,
@@ -289,10 +367,10 @@ export function mergeCurateSearchResponses(base, extras) {
 }
 export async function searchForCuration(input) {
     const initial = await akmSearch({ ...input, skipLogging: true });
-    if (hasSearchResults(initial))
+    if (!shouldRunCurateFallback(initial, input.limit))
         return initial;
     const fallbackQueries = deriveCurateFallbackQueries(input.query);
-    if (fallbackQueries.length <= 1)
+    if (fallbackQueries.length === 0)
         return initial;
     const fallbackResults = await Promise.all(fallbackQueries.map((token) => akmSearch({
         query: token,
@@ -303,3 +381,241 @@ export async function searchForCuration(input) {
     })));
     return mergeCurateSearchResponses(initial, fallbackResults);
 }
+function parseCurateIntent(query) {
+    const lower = query.toLowerCase();
+    return {
+        executionHeavy: /(run|script|bash|shell|cli|execute|automation|deploy|build|test|lint)/.test(lower),
+        multiStep: /(plan|workflow|steps?|procedure|rollout|review|migration|release|checklist)/.test(lower),
+        delegation: /(agent|assistant|planner|reviewer|architect|prompt)/.test(lower),
+        recall: /(memory|context|recall|remember)/.test(lower),
+        reference: CURATE_REFERENCE_QUERY_RE.test(lower),
+    };
+}
+function computeCurateTypeNudge(type, intent) {
+    let nudge = 0;
+    if (intent.executionHeavy) {
+        if (type === "script")
+            nudge += 0.06;
+        else if (type === "command")
+            nudge += 0.04;
+        else if (type === "memory")
+            nudge -= 0.04;
+    }
+    if (intent.multiStep) {
+        if (type === "workflow")
+            nudge += 0.06;
+        else if (type === "skill")
+            nudge += 0.04;
+        else if (type === "knowledge")
+            nudge -= 0.02;
+    }
+    if (intent.delegation && type === "agent")
+        nudge += 0.06;
+    if (intent.recall && type === "memory")
+        nudge += 0.08;
+    if (intent.reference) {
+        if (type === "knowledge")
+            nudge += 0.05;
+        else if (type === "skill")
+            nudge += 0.02;
+    }
+    return nudge;
+}
+function getCurateFamily(ref) {
+    try {
+        const parsed = parseAssetRef(ref);
+        if (parsed.type === "skill") {
+            return { key: parsed.name, role: "root" };
+        }
+        if (parsed.type !== "knowledge")
+            return undefined;
+        const match = /^skills\/(.+?)\/references\/(.+)$/.exec(parsed.name);
+        if (!match)
+            return undefined;
+        return {
+            key: match[1],
+            role: "reference",
+            topicTokens: match[2]
+                .split(/[^a-z0-9]+/i)
+                .map((token) => token.trim().toLowerCase())
+                .filter(Boolean),
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+function annotateCurateHit(query, hit, index, intent) {
+    const rawScore = hit.score ?? 0;
+    const family = getCurateFamily(hit.ref);
+    let adjustedScore = rawScore + computeCurateTypeNudge(hit.type, intent);
+    if (family?.role === "root" && !isNarrowReferenceFamilyQuery(query, family))
+        adjustedScore += 0.07;
+    if (family?.role === "reference" && isNarrowReferenceFamilyQuery(query, family))
+        adjustedScore += 0.07;
+    return {
+        hit,
+        rawScore,
+        adjustedScore,
+        originalIndex: index,
+        family,
+    };
+}
+function compareCurateHits(a, b) {
+    const rawDiff = b.rawScore - a.rawScore;
+    if (Math.abs(rawDiff) > CURATE_CLOSE_SCORE_BAND)
+        return rawDiff;
+    const adjustedDiff = b.adjustedScore - a.adjustedScore;
+    if (adjustedDiff !== 0)
+        return adjustedDiff;
+    if (rawDiff !== 0)
+        return rawDiff;
+    return a.originalIndex - b.originalIndex;
+}
+function passesCurateScoreFloor(hit, leaderScore) {
+    if (leaderScore === undefined)
+        return true;
+    return hit.rawScore >= Math.max(CURATE_TAIL_SCORE_FLOOR, leaderScore * CURATE_RELATIVE_SCORE_FLOOR);
+}
+function isNarrowReferenceFamilyQuery(query, family) {
+    if (!family || family.role !== "reference")
+        return false;
+    const lower = query.toLowerCase();
+    if (CURATE_REFERENCE_QUERY_RE.test(lower))
+        return true;
+    return family.topicTokens.some((token) => token.length >= 3 && lower.includes(token));
+}
+function appendCurateSupportRef(supportRefsByRef, ownerRef, supportRef) {
+    const existing = supportRefsByRef.get(ownerRef) ?? [];
+    if (existing.some((entry) => entry.ref === supportRef.ref))
+        return;
+    supportRefsByRef.set(ownerRef, [...existing, supportRef]);
+}
+function selectCuratedStashHits(query, hits, limit) {
+    const intent = parseCurateIntent(query);
+    const collapsed = collapseCurateFamilies(query, hits);
+    const ranked = collapsed.hits
+        .map(({ hit, originalIndex }) => annotateCurateHit(query, hit, originalIndex, intent))
+        .sort(compareCurateHits);
+    const selected = [];
+    const supportRefsByRef = collapsed.supportRefsByRef;
+    let leaderScore;
+    for (const candidate of ranked) {
+        if (!passesCurateScoreFloor(candidate, leaderScore))
+            continue;
+        selected.push(candidate);
+        if (leaderScore === undefined)
+            leaderScore = candidate.rawScore;
+        if (selected.length >= limit)
+            break;
+    }
+    return { selected: selected.map((entry) => entry.hit), supportRefsByRef };
+}
+function collapseCurateFamilies(query, hits) {
+    const passthrough = [];
+    const supportRefsByRef = new Map();
+    const groups = new Map();
+    for (const [index, hit] of hits.entries()) {
+        const family = getCurateFamily(hit.ref);
+        if (!family) {
+            passthrough.push({ hit, originalIndex: index });
+            continue;
+        }
+        const group = groups.get(family.key) ?? { references: [] };
+        if (family.role === "root") {
+            if (!group.root)
+                group.root = { hit, originalIndex: index };
+        }
+        else {
+            group.references.push({ hit, originalIndex: index });
+        }
+        groups.set(family.key, group);
+    }
+    const collapsedFamilies = [];
+    for (const group of groups.values()) {
+        const bestReference = group.references[0];
+        const representative = group.root && !isNarrowReferenceFamilyQuery(query, getCurateFamily(bestReference?.hit.ref ?? group.root.hit.ref))
+            ? group.root
+            : (bestReference ?? group.root);
+        if (!representative)
+            continue;
+        collapsedFamilies.push(representative);
+        const supportCandidates = [group.root, ...group.references].filter((entry) => {
+            return entry !== undefined && entry.hit.ref !== representative.hit.ref;
+        });
+        for (const support of supportCandidates) {
+            appendCurateSupportRef(supportRefsByRef, representative.hit.ref, {
+                ref: support.hit.ref,
+                type: support.hit.type,
+                reason: "Related family asset to inspect next.",
+            });
+        }
+    }
+    return {
+        hits: [...passthrough, ...collapsedFamilies].sort((a, b) => a.originalIndex - b.originalIndex),
+        supportRefsByRef,
+    };
+}
+function preferBroadRootRepresentative(query, selected, allHits, supportRefsByRef) {
+    const first = selected[0];
+    if (!first)
+        return { selected, supportRefsByRef };
+    const match = /^knowledge:skills\/(.+?)\/references\/(.+)$/.exec(first.ref);
+    if (!match)
+        return { selected, supportRefsByRef };
+    const lower = query.toLowerCase();
+    const topicTokens = match[2].split(/[^a-z0-9]+/i).filter(Boolean);
+    const wantsReference = CURATE_REFERENCE_QUERY_RE.test(lower) ||
+        topicTokens.some((token) => token.length >= 3 && lower.includes(token.toLowerCase()));
+    if (wantsReference)
+        return { selected, supportRefsByRef };
+    const rootRef = `skill:${match[1]}`;
+    const rootHit = allHits.find((hit) => hit.ref === rootRef);
+    if (!rootHit)
+        return { selected, supportRefsByRef };
+    const next = [rootHit, ...selected.filter((hit) => hit.ref !== first.ref && hit.ref !== rootRef)];
+    const merged = new Map(supportRefsByRef);
+    const priorSupport = merged.get(first.ref) ?? [];
+    for (const entry of priorSupport)
+        appendCurateSupportRef(merged, rootRef, entry);
+    appendCurateSupportRef(merged, rootRef, {
+        ref: first.ref,
+        type: first.type,
+        reason: "Related family asset to inspect next.",
+    });
+    merged.delete(first.ref);
+    return { selected: next, supportRefsByRef: merged };
+}
+function mergeCurateSupportRefs(seeded, relatedHits, selectedRefs, ownerRef) {
+    const merged = [];
+    for (const entry of seeded) {
+        if (entry.ref === ownerRef || selectedRefs.has(entry.ref))
+            continue;
+        if (merged.some((existing) => existing.ref === entry.ref))
+            continue;
+        merged.push(entry);
+        if (merged.length >= MAX_CURATE_SUPPORT_REFS)
+            return merged;
+    }
+    if (!Array.isArray(relatedHits))
+        return merged;
+    for (const hit of relatedHits) {
+        if (!hit.ref || hit.ref === ownerRef || selectedRefs.has(hit.ref))
+            continue;
+        if (merged.some((existing) => existing.ref === hit.ref))
+            continue;
+        merged.push({ ref: hit.ref, type: hit.type, reason: "Related asset via shared entities." });
+        if (merged.length >= MAX_CURATE_SUPPORT_REFS)
+            break;
+    }
+    return merged;
+}
+function shouldRunCurateFallback(initial, desiredCount) {
+    const stashHits = initial.hits.filter((hit) => hit.type !== "registry");
+    if (stashHits.length === 0)
+        return true;
+    const topScore = stashHits[0]?.score ?? 0;
+    const strongFloor = Math.max(CURATE_FALLBACK_STRONG_SCORE_FLOOR, topScore * CURATE_RELATIVE_SCORE_FLOOR);
+    const strongCount = stashHits.filter((hit) => (hit.score ?? 0) >= strongFloor).length;
+    return !(topScore >= CURATE_FALLBACK_TOP_SCORE_THRESHOLD && strongCount >= Math.min(2, desiredCount));
+}