@4da/mcp-server 5.0.3 → 6.0.0

package/dist/tools/knowledge-gap-scope.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Knowledge-gap scope: which projects count as active, and which items the
+ * dependency linker bound to which packages. Mirrors the desktop app's
+ * `temporal::{active_repo_roots, dep_within_active_root, shares_active_root}`
+ * and `knowledge_decay::{get_active_project_paths, linked_to}`.
+ */
+import type BetterSqlite3 from "better-sqlite3";
+import type { FourDADatabase } from "../db.js";
+/** `stmt.all(...)`, or [] when the statement cannot run: a read here never throws out of the tool. */
+export declare function allRows<T>(stmt: BetterSqlite3.Statement, ...args: unknown[]): T[];
+/** Lowercase, forward slashes, no trailing slash (`knowledge_decay::normalize_project_path`). */
+export declare function normPath(p: string): string;
+/**
+ * Path-BOUNDARY match in either direction: `d:/4da` covers `d:/4da/src-tauri`
+ * (and a manifest recorded above its repo root still counts), but never
+ * `d:/4da-experiments` (`temporal::dep_within_active_root`).
+ */
+export declare function withinRoots(path: string, roots: readonly string[]): boolean;
+/** Do two project paths sit under one common active root (`temporal::shares_active_root`)? */
+export declare function sharesRoot(a: string, b: string, roots: readonly string[]): boolean;
+/** The app's two activity windows, loaded once per call. */
+export interface ActiveScope {
+    /** `temporal::active_repo_roots`: commits in the last 60 days. Scopes each project ROW. */
+    rowRoots: string[];
+    /** `knowledge_decay::get_active_project_paths`: activity in the last 30 days. Scopes each DEPENDENCY. */
+    dependencyRoots: string[];
+}
+export declare function loadActiveScope(db: FourDADatabase): ActiveScope;
+/**
+ * The project rows the app's dependency funnel keeps before knowledge decay
+ * ever sees them (`temporal::get_all_dependencies`): rows inside an active repo
+ * root. Without it a gap for a dependency the active repo shares with a
+ * dormant one is judged on the dormant copy too — vitest in `d:/4da` (4.1.11)
+ * beside navcal's untouched 3.2.4 would name navcal under a critical the app
+ * never shows. No recorded git activity means unscoped, and a scope that
+ * matches no row at all keeps every row rather than blanking the tool.
+ */
+export declare function scopeRows<T extends {
+    project_path: string;
+}>(rows: T[], scope: ActiveScope): T[];
+/**
+ * `knowledge_decay::detect_knowledge_gaps` active-project scoping: a
+ * dependency whose declaring projects all sit outside every recently active
+ * path is skipped. Measured 2026-09-11: axios and socket.io were reported
+ * critical from `kairos-mvp/backend`, a project untouched since 2025-10.
+ */
+export declare function dependencyIsActive(rows: ReadonlyArray<{
+    project_path: string;
+}>, scope: ActiveScope): boolean;
+/** Items the dependency linker bound to a package with STRUCTURED proof. */
+export interface LinkerIndex {
+    /** Ids of the items bound to this package (case- and `-`/`_`-folded). */
+    itemsFor(packageName: string): ReadonlySet<number>;
+}
+/**
+ * `source_item_dependencies` rows carrying structured proof: `advisory` (the
+ * advisory's own affected-package list) or `exact_registry`. A registry
+ * advisory cites a dependency only through this proof, never through a title
+ * word (#618; `knowledge_decay::linked_to`). Null when the table or its
+ * `match_type` column is absent: callers then fall back to the advisory's
+ * subject package, since heuristic rows cannot be told apart from proof.
+ */
+export declare function loadLinkerIndex(db: FourDADatabase): LinkerIndex | null;

package/dist/tools/knowledge-gap-scope.js

@@ -0,0 +1,118 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Knowledge-gap scope: which projects count as active, and which items the
+ * dependency linker bound to which packages. Mirrors the desktop app's
+ * `temporal::{active_repo_roots, dep_within_active_root, shares_active_root}`
+ * and `knowledge_decay::{get_active_project_paths, linked_to}`.
+ */
+/** `stmt.all(...)`, or [] when the statement cannot run: a read here never throws out of the tool. */
+export function allRows(stmt, ...args) {
+    try {
+        return stmt.all(...args);
+    }
+    catch {
+        return [];
+    }
+}
+/** Lowercase, forward slashes, no trailing slash (`knowledge_decay::normalize_project_path`). */
+export function normPath(p) {
+    return p.replace(/\\/g, "/").toLowerCase().replace(/\/+$/, "");
+}
+/**
+ * Repo roots with git activity in the last `days` days, normalized. The
+ * `git_signals.repo_path` column is stored raw ("D:\4DA"). Empty when the
+ * table is absent or silent, which every caller reads as "unscoped".
+ */
+function activeRoots(db, days, requireCommit) {
+    if (!db.hasColumn("git_signals", "repo_path") || !db.hasColumn("git_signals", "timestamp"))
+        return [];
+    const commit = requireCommit && db.hasColumn("git_signals", "commit_hash")
+        ? "AND commit_hash IS NOT NULL AND commit_hash != ''"
+        : "";
+    try {
+        const rows = db
+            .getRawDb()
+            .prepare(`SELECT DISTINCT repo_path FROM git_signals WHERE timestamp > datetime('now', ?) ${commit}`)
+            .all(`-${days} days`);
+        return [...new Set(rows.map((r) => normPath(r.repo_path ?? "")).filter((p) => p !== ""))];
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Path-BOUNDARY match in either direction: `d:/4da` covers `d:/4da/src-tauri`
+ * (and a manifest recorded above its repo root still counts), but never
+ * `d:/4da-experiments` (`temporal::dep_within_active_root`).
+ */
+export function withinRoots(path, roots) {
+    const p = normPath(path);
+    if (p === "")
+        return false;
+    return roots.some((root) => p === root || p.startsWith(`${root}/`) || root.startsWith(`${p}/`));
+}
+/** Do two project paths sit under one common active root (`temporal::shares_active_root`)? */
+export function sharesRoot(a, b, roots) {
+    return roots.some((root) => withinRoots(a, [root]) && withinRoots(b, [root]));
+}
+export function loadActiveScope(db) {
+    return { rowRoots: activeRoots(db, 60, true), dependencyRoots: activeRoots(db, 30, false) };
+}
+/**
+ * The project rows the app's dependency funnel keeps before knowledge decay
+ * ever sees them (`temporal::get_all_dependencies`): rows inside an active repo
+ * root. Without it a gap for a dependency the active repo shares with a
+ * dormant one is judged on the dormant copy too — vitest in `d:/4da` (4.1.11)
+ * beside navcal's untouched 3.2.4 would name navcal under a critical the app
+ * never shows. No recorded git activity means unscoped, and a scope that
+ * matches no row at all keeps every row rather than blanking the tool.
+ */
+export function scopeRows(rows, scope) {
+    if (scope.rowRoots.length === 0)
+        return rows;
+    const kept = rows.filter((r) => withinRoots(r.project_path, scope.rowRoots));
+    return kept.length > 0 ? kept : rows;
+}
+/**
+ * `knowledge_decay::detect_knowledge_gaps` active-project scoping: a
+ * dependency whose declaring projects all sit outside every recently active
+ * path is skipped. Measured 2026-09-11: axios and socket.io were reported
+ * critical from `kairos-mvp/backend`, a project untouched since 2025-10.
+ */
+export function dependencyIsActive(rows, scope) {
+    return scope.dependencyRoots.length === 0 || rows.some((r) => withinRoots(r.project_path, scope.dependencyRoots));
+}
+const foldName = (name) => name.toLowerCase().replace(/_/g, "-");
+const NO_ITEMS = new Set();
+/**
+ * `source_item_dependencies` rows carrying structured proof: `advisory` (the
+ * advisory's own affected-package list) or `exact_registry`. A registry
+ * advisory cites a dependency only through this proof, never through a title
+ * word (#618; `knowledge_decay::linked_to`). Null when the table or its
+ * `match_type` column is absent: callers then fall back to the advisory's
+ * subject package, since heuristic rows cannot be told apart from proof.
+ */
+export function loadLinkerIndex(db) {
+    const has = (column) => db.hasColumn("source_item_dependencies", column);
+    if (!has("source_item_id") || !has("package_name") || !has("match_type"))
+        return null;
+    const byPackage = new Map();
+    try {
+        const rows = db
+            .getRawDb()
+            .prepare("SELECT source_item_id, package_name FROM source_item_dependencies WHERE match_type IN ('advisory', 'exact_registry')")
+            .all();
+        for (const row of rows) {
+            if (!row.package_name)
+                continue;
+            const key = foldName(row.package_name);
+            const ids = byPackage.get(key) ?? new Set();
+            ids.add(row.source_item_id);
+            byPackage.set(key, ids);
+        }
+    }
+    catch {
+        return null;
+    }
+    return { itemsFor: (name) => byPackage.get(foldName(name)) ?? NO_ITEMS };
+}

package/dist/tools/knowledge-gaps.d.ts

@@ -1,10 +1,19 @@
 /**
  * knowledge_gaps tool
  *
- * Detect knowledge gaps - dependencies with relevant content you haven't engaged with.
+ * Detect knowledge gaps: direct dependencies with unread, consequential
+ * intelligence. The desktop app computes the same concept in
+ * `src-tauri/src/knowledge_decay.rs::detect_knowledge_gaps`, and every rule
+ * here names the function it mirrors, because two implementations disagreeing
+ * is the failure this tool keeps being audited for. Measured 2026-09-11 on the
+ * founder machine: five `critical` gaps, four false or inflated, every one
+ * contradicting the app.
  */
 import type { FourDADatabase } from "../db.js";
+import type { LiveIntelligence } from "../live/index.js";
 import type { SourceItemBriefRow } from "../types.js";
+export { advisorySubject, gradeGap, registryVersionFromTitle, type Exposure, type GapSeverity, type GradableItem, } from "./knowledge-gap-grading.js";
+export { versionInAnyRange, type AdvisoryRangeEvent } from "./knowledge-gap-ranges.js";
 export interface KnowledgeGapsParams {
     min_severity?: string;
     limit?: number;
@@ -31,14 +40,14 @@ export declare const knowledgeGapsTool: {
 };
 export interface KnowledgeGap {
     dependency: string;
-    version: string;
+    version: string | null;
     project_path: string;
     language: string;
     missed_items: SourceItemBriefRow[];
     gap_severity: string;
     missed_count: number;
 }
-export declare function executeKnowledgeGaps(db: FourDADatabase, params: KnowledgeGapsParams): {
+export declare function executeKnowledgeGaps(db: FourDADatabase, params: KnowledgeGapsParams, liveIntel?: Pick<LiveIntelligence, "getResolvedDeps" | "isInitialized"> | null): {
     gaps: never[];
     summary: string;
     total_dependencies?: undefined;

package/dist/tools/knowledge-gaps.js

@@ -2,29 +2,23 @@
 /**
  * knowledge_gaps tool
  *
- * Detect knowledge gaps - dependencies with relevant content you haven't engaged with.
+ * Detect knowledge gaps: direct dependencies with unread, consequential
+ * intelligence. The desktop app computes the same concept in
+ * `src-tauri/src/knowledge_decay.rs::detect_knowledge_gaps`, and every rule
+ * here names the function it mirrors, because two implementations disagreeing
+ * is the failure this tool keeps being audited for. Measured 2026-09-11 on the
+ * founder machine: five `critical` gaps, four false or inflated, every one
+ * contradicting the app.
  */
-// Word-boundary matching prevents "cve" matching inside "achieve", "receiver", etc.
-function hasWordBoundary(text, term) {
-    const regex = new RegExp(`\\b${escapeRegExp(term)}\\b`, 'i');
-    return regex.test(text);
-}
-// Package names can contain regex metacharacters (@scope/name, c++, next.js).
-function escapeRegExp(s) {
-    return s.replace(/[.*+?^${}()|[\]\\/]/g, "\\$&");
-}
-// True when `text` mentions the package name as a whole word. Word characters
-// for this purpose include - and _ (so dep "hono" does NOT match "hono-shim",
-// and never matches "in HONOr of"). @scope/name matches as the full literal.
-function mentionsPackage(text, pkg) {
-    const regex = new RegExp(`(^|[^A-Za-z0-9_-])${escapeRegExp(pkg)}($|[^A-Za-z0-9_-])`, "i");
-    return regex.test(text);
-}
-// Escape SQL LIKE wildcards so a package name containing % or _ (npm names may
-// contain _) is matched literally rather than as a pattern. Paired with ESCAPE '\'.
-function escapeLike(s) {
-    return s.replace(/[\\%_]/g, (c) => "\\" + c);
-}
+import { citesDependency, loadCandidates, normalizeGapTitle } from "./knowledge-gap-citations.js";
+import { AdvisoryStore, gapExposure, installExposure, reachingTier, rowVerdict, } from "./knowledge-gap-exposure.js";
+import { InstallResolver } from "./knowledge-gap-installs.js";
+import { gradeGap, isAdvisoryRow, parsePublishedAt, registryVersionFromTitle, } from "./knowledge-gap-grading.js";
+import { compareVersions } from "../live/version-compare.js";
+import { dependencyIsActive, loadActiveScope, loadLinkerIndex, scopeRows } from "./knowledge-gap-scope.js";
+// The grading and range rules live in their own modules; re-exported for existing importers.
+export { advisorySubject, gradeGap, registryVersionFromTitle, } from "./knowledge-gap-grading.js";
+export { versionInAnyRange } from "./knowledge-gap-ranges.js";
 export const knowledgeGapsTool = {
     name: "knowledge_gaps",
     description: `Detect knowledge gaps by cross-referencing your project dependencies with source items you haven't engaged with. Identifies things you should know about but might have missed.`,
@@ -45,18 +39,132 @@ export const knowledgeGapsTool = {
         },
     },
 };
-export function executeKnowledgeGaps(db, params) {
-    const rawDb = db.getRawDb();
-    // Feature-detect optional columns: a pure-standalone database has no scoring
-    // pipeline (no relevance_score) and may predate content_type — the tool must
-    // degrade to word-boundary + recency grounding there, never throw.
-    const hasRelevance = db.hasColumn("source_items", "relevance_score");
-    const hasContentType = db.hasColumn("source_items", "content_type");
-    const hasIsDirect = db.hasColumn("project_dependencies", "is_direct");
+const SEVERITY_ORDER = { critical: 4, high: 3, medium: 2, low: 1 };
+const MAX_MISSED_ITEMS = 5;
+/**
+ * published_at guard: OSV/CVE backfills ingest decades-old advisories whose
+ * created_at (discovery) is days old but whose published_at is ancient. A 2021
+ * advisory is not "missed intelligence" in 2026 — unless an install is
+ * positively inside it: a still-applying advisory is missed intelligence
+ * however old (live: the jsonwebtoken crate advisory, published February,
+ * still open against relay/'s 9.3.1 in September). NULL passes (many sources
+ * never set it).
+ */
+const PUBLISHED_WINDOW_MS = 90 * 24 * 60 * 60 * 1000;
+function passesPublishedCut(e, exposure, cutoff) {
+    const publishedAt = parsePublishedAt(e.item.published_at);
+    if (publishedAt === null || publishedAt >= cutoff)
+        return true;
+    return e.verdict === "reached" || (e.verdict === "unresolvable" && exposure === "exposed");
+}
+/**
+ * Does this evidence keep a security signal alive? A resolved row that reaches
+ * an install does; so, conservatively, does a row whose install cannot be read,
+ * and a row the mirror cannot resolve while the package is not positively
+ * patched (AD-040 rule 3: only exposed installs are findings, and an unknown
+ * installed version stays conservatively exposed).
+ */
+function stillReaches(e, exposure) {
+    return e.verdict === "reached" || e.verdict === "unknown" || (e.verdict === "unresolvable" && exposure !== "safe");
+}
+function advisoryVerdict(item, name, installs, store) {
+    const entries = store.forRow(item.source_id, name);
+    return entries === null ? "unresolvable" : rowVerdict(entries, installs);
+}
+const REGISTRY_SOURCES = new Set(["crates_io", "npm_registry", "pypi", "go_modules"]);
+/** A registry row's version is above every readable installed version (unknown versions keep it). */
+function newerThanEveryInstall(item, installs) {
+    const released = registryVersionFromTitle(item.title || "");
+    if (!released)
+        return true;
+    const known = installs.filter((i) => i.version && i.ecosystem);
+    if (known.length === 0)
+        return true;
+    return known.every((i) => compareVersions(released, i.version, i.ecosystem) > 0);
+}
+function brief(item) {
+    return {
+        id: item.id,
+        title: item.title && item.title.length > 120 ? `${item.title.substring(0, 120)}...` : item.title,
+        url: item.url,
+        source_type: item.source_type,
+        created_at: item.created_at,
+        relevance_score: item.relevance_score,
+    };
+}
+/** One dependency's gap, judged on every project that declares it, or null when nothing is missed. */
+function buildGap(name, rows, ctx) {
+    const cited = ctx.candidates.filter((item) => citesDependency(item, name, ctx.linker));
+    if (cited.length === 0)
+        return null;
+    const installs = ctx.installs.installsFor(rows);
+    const stored = ctx.advisories.forPackage(name);
+    const exposure = gapExposure(installs, stored);
+    // An advisory row is judged LIVE on its own advisories against the installs
+    // this gap names (`osv::exposure::advisory_row_reaches`, AD-045): a row every
+    // install is outside of is not a gap at all. A row the mirror cannot resolve
+    // stays in, conservatively. Reposts of one story count once, the newest
+    // (`keyword_misses_from`'s normalized-title dedup).
+    const evidence = [];
+    const seenTitles = new Set();
+    for (const item of cited) {
+        // A registry release you already run (or are past) was not missed: live
+        // 2026-10-01, "npm: react v19.3.0" was a gap for an installed react 19.3.0.
+        if (REGISTRY_SOURCES.has(item.source_type ?? "") && !newerThanEveryInstall(item, installs))
+            continue;
+        const verdict = isAdvisoryRow(item) ? advisoryVerdict(item, name, installs, ctx.advisories) : null;
+        if (verdict === "clear")
+            continue;
+        const e = { item, verdict };
+        if (!passesPublishedCut(e, exposure, ctx.publishedCutoff))
+            continue;
+        const titleKey = normalizeGapTitle(item.title || "");
+        if (seenTitles.has(titleKey))
+            continue;
+        seenTitles.add(titleKey);
+        evidence.push(e);
+    }
+    if (evidence.length === 0)
+        return null;
+    const vulnerable = evidence.some((e) => stillReaches(e, exposure));
+    const tier = vulnerable ? reachingTier(stored, installs) : null;
+    const versions = installs.map((i) => i.version).filter((v) => v !== null);
+    // Each item graded on its own: the gap's grade is the best of them, and the
+    // items shown lead with the ones that earn it.
+    const graded = evidence
+        .map((e, order) => ({
+        e,
+        order,
+        severity: gradeGap([{ ...e.item, cites: true }], name, stillReaches(e, exposure), versions, tier),
+    }))
+        .sort((a, b) => SEVERITY_ORDER[b.severity] - SEVERITY_ORDER[a.severity] || a.order - b.order);
+    const severity = graded[0].severity;
+    const shown = graded.slice(0, MAX_MISSED_ITEMS);
+    // AD-044: the row is true for every project it names. When the exposure is
+    // what makes this a gap, name the exposed projects with the lead one's own
+    // version (`affected_project_paths`); otherwise every declaring project.
+    const exposed = vulnerable ? installs.filter((i) => installExposure(i, stored) === "exposed") : [];
+    const named = exposed.length > 0 ? exposed : installs;
+    const lead = named[0];
+    return {
+        dependency: name,
+        version: lead.version,
+        project_path: named.length > 1 ? `${lead.projectPath} (+${named.length - 1} more)` : lead.projectPath,
+        language: lead.language,
+        missed_items: shown.map(({ e }) => brief(e.item)),
+        gap_severity: severity,
+        missed_count: shown.length,
+    };
+}
+export function executeKnowledgeGaps(db, params, liveIntel) {
     // Direct dependencies only — a transitive dep's news is not the user's
     // reading backlog. Dev deps stay in: a vitest or eslint advisory is real.
-    const deps = rawDb
-        .prepare(`SELECT package_name, version, project_path, language FROM project_dependencies ${hasIsDirect ? "WHERE is_direct = 1 " : ""}LIMIT 100`)
+    // Every direct dependency is scanned: a `LIMIT 100` here once left 43 of
+    // 143 unexamined.
+    const hasIsDirect = db.hasColumn("project_dependencies", "is_direct");
+    const deps = db
+        .getRawDb()
+        .prepare(`SELECT package_name, version, project_path, language FROM project_dependencies ${hasIsDirect ? "WHERE is_direct = 1" : ""}`)
         .all();
     if (deps.length === 0) {
         return {
@@ -64,100 +172,43 @@ export function executeKnowledgeGaps(db, params) {
             summary: "No project dependencies tracked. Add context directories to enable knowledge gap detection.",
         };
     }
-    const gaps = [];
-    const seenPackages = new Set();
-    for (const dep of deps) {
-        // Names shorter than 3 chars (e.g. "c", "go", "ws") match too many unrelated
-        // items via substring LIKE to be a trustworthy "mention" signal — skip them.
-        if (!dep.package_name || dep.package_name.length < 3)
+    const scope = loadActiveScope(db);
+    const ctx = {
+        candidates: loadCandidates(db),
+        linker: loadLinkerIndex(db),
+        advisories: new AdvisoryStore(db),
+        installs: new InstallResolver(db, liveIntel, scope.rowRoots),
+        publishedCutoff: Date.now() - PUBLISHED_WINDOW_MS,
+    };
+    // One gap per package however many projects declare it; each project's own
+    // install is judged inside the gap. Names shorter than 3 characters ("c",
+    // "go", "ws") match too much unrelated text to be evidence.
+    const byPackage = new Map();
+    for (const row of scopeRows(deps, scope)) {
+        if (!row.package_name || row.package_name.length < 3)
             continue;
-        // One gap per package: the same dep declared by several projects would
-        // otherwise repeat identical missed_items once per project_path.
-        const pkgKey = dep.package_name.toLowerCase();
-        if (seenPackages.has(pkgKey))
+        const key = row.package_name.toLowerCase();
+        const group = byPackage.get(key);
+        if (group)
+            group.push(row);
+        else
+            byPackage.set(key, [row]);
+    }
+    const gaps = [];
+    for (const rows of byPackage.values()) {
+        if (!dependencyIsActive(rows, scope))
             continue;
-        seenPackages.add(pkgKey);
-        // Find source items mentioning this dependency. Engagement is recorded by the
-        // app in interactions.item_id / .action_type (the canonical columns; the older
-        // source_item_id / action columns are unused), so the NOT-IN suppression must
-        // read those or it silently never fires.
-        //
-        // Grounding (each guard killed an observed false-positive class):
-        // - relevance_score >= 0.2: the scoring pipeline's above-noise band — drops
-        //   off-topic chatter that merely contains the string (chocolate-bar class).
-        // - 30-day window: a "gap" is something you MISSED, not archaeology — a
-        //   2014 StackOverflow post is not missed intelligence.
-        // - LIKE is only a cheap candidate pre-filter; the real test is the
-        //   word-boundary check below ("invite" must never evidence a vite gap).
-        // - feed_relevant is deliberately NOT filtered here: an item the feed gate
-        //   rejected can still be a legitimate unread dep mention — surfacing those
-        //   is this tool's niche. The relevance floor already excludes noise.
-        const pattern = `%${escapeLike(dep.package_name)}%`;
-        const candidates = rawDb
-            .prepare(`SELECT si.id, si.title, si.url, si.source_type, ${hasContentType ? "si.content_type" : "NULL AS content_type"}, si.created_at,
-               ${hasRelevance ? "si.relevance_score" : "NULL AS relevance_score"}, substr(COALESCE(si.content, ''), 1, 2000) AS content_head
-        FROM source_items si
-        WHERE (si.title LIKE ? ESCAPE '\\' OR si.content LIKE ? ESCAPE '\\')
-        ${hasRelevance ? "AND si.relevance_score IS NOT NULL AND si.relevance_score >= 0.2" : ""}
-        AND si.created_at >= datetime('now', '-30 days')
-        AND si.id NOT IN (SELECT item_id FROM interactions WHERE action_type IN ('click', 'save'))
-        ORDER BY si.created_at DESC LIMIT 25`)
-            .all(pattern, pattern);
-        // Word-boundary verification: the mention must be the package name as a
-        // whole word in the title or the content head, not a substring.
-        const mentionedItems = candidates
-            .filter((item) => mentionsPackage(item.title || "", dep.package_name) ||
-            mentionsPackage(item.content_head || "", dep.package_name))
-            .slice(0, 5);
-        if (mentionedItems.length > 0) {
-            const isAdvisory = (item) => item.source_type === "cve" ||
-                item.source_type === "osv" ||
-                item.content_type === "security_advisory";
-            const securityKeywords = (title) => hasWordBoundary(title, "cve") ||
-                hasWordBoundary(title, "security") ||
-                hasWordBoundary(title, "vulnerability");
-            // Graded honestly:
-            // - critical: an actual advisory whose TITLE names this dependency — the
-            //   advisory is about the dep, not merely co-mentioning it in a body.
-            // - high: a security-keyword item whose title names the dep.
-            // - medium: 3+ recent unread mentions; low: 1-2.
-            const advisoryAboutDep = mentionedItems.some((item) => isAdvisory(item) && mentionsPackage(item.title || "", dep.package_name));
-            const securityTitleMention = mentionedItems.some((item) => securityKeywords(item.title || "") &&
-                mentionsPackage(item.title || "", dep.package_name));
-            const severity = advisoryAboutDep
-                ? "critical"
-                : securityTitleMention
-                    ? "high"
-                    : mentionedItems.length >= 3
-                        ? "medium"
-                        : "low";
-            gaps.push({
-                dependency: dep.package_name,
-                version: dep.version,
-                project_path: dep.project_path,
-                language: dep.language,
-                missed_items: mentionedItems.map((item) => ({
-                    id: item.id,
-                    title: item.title && item.title.length > 120
-                        ? item.title.substring(0, 120) + "..."
-                        : item.title,
-                    url: item.url,
-                    source_type: item.source_type,
-                    created_at: item.created_at,
-                    relevance_score: item.relevance_score,
-                })),
-                gap_severity: severity,
-                missed_count: mentionedItems.length,
-            });
-        }
+        const gap = buildGap(rows[0].package_name, rows, ctx);
+        if (gap)
+            gaps.push(gap);
     }
-    // Filter by severity
-    const severityOrder = { critical: 4, high: 3, medium: 2, low: 1 };
-    const minLevel = severityOrder[params.min_severity || "medium"] || 2;
-    const filtered = gaps.filter((g) => (severityOrder[g.gap_severity] || 0) >= minLevel);
+    const minLevel = SEVERITY_ORDER[params.min_severity || "medium"] || 2;
+    const filtered = gaps.filter((g) => (SEVERITY_ORDER[g.gap_severity] || 0) >= minLevel);
     const maxGaps = Math.min(Math.max(1, params.limit || 15), 50);
     return {
-        gaps: filtered.sort((a, b) => (severityOrder[b.gap_severity] || 0) - (severityOrder[a.gap_severity] || 0)).slice(0, maxGaps),
+        gaps: filtered
+            .sort((a, b) => (SEVERITY_ORDER[b.gap_severity] || 0) - (SEVERITY_ORDER[a.gap_severity] || 0))
+            .slice(0, maxGaps),
         total_dependencies: deps.length,
         gaps_found: filtered.length,
         gaps_returned: Math.min(filtered.length, maxGaps),

package/dist/tools/package-presence.d.ts

@@ -0,0 +1,24 @@
+/**
+ * What this project's lockfiles hold for a package someone asked about by name.
+ *
+ * `vulnerability_scan` and `upgrade_planner` both take `package`. When either
+ * has nothing to show, "no findings" must not read as "not a dependency": in
+ * the 2026-10-03 agent eval the planner told an agent that `diff`, a
+ * transitive devDependency with two advisories, was "not a dependency of this
+ * project (or is a devDependency: pass include_dev)" while include_dev was set.
+ */
+import type { LiveIntelligence } from "../live/index.js";
+export interface PackagePresence {
+    /** The registry name as the lockfile spells it, or null when no lockfile holds it. */
+    name: string | null;
+    versions: string[];
+    scope: "direct" | "transitive" | null;
+    /** Every copy is a direct devDependency (left out of runtime-scope scans and plans). */
+    directDevOnly: boolean;
+}
+export declare function packagePresence(query: string, liveIntel: LiveIntelligence): PackagePresence;
+/**
+ * One sentence for a `package` query that produced no rows.
+ * `checked` says what an empty answer means for this tool ("no known advisories", "nothing to upgrade").
+ */
+export declare function emptyAnswerNote(query: string, liveIntel: LiveIntelligence, includeDev: boolean, checked: string): string;

package/dist/tools/package-presence.js

@@ -0,0 +1,35 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * What this project's lockfiles hold for a package someone asked about by name.
+ *
+ * `vulnerability_scan` and `upgrade_planner` both take `package`. When either
+ * has nothing to show, "no findings" must not read as "not a dependency": in
+ * the 2026-10-03 agent eval the planner told an agent that `diff`, a
+ * transitive devDependency with two advisories, was "not a dependency of this
+ * project (or is a devDependency: pass include_dev)" while include_dev was set.
+ */
+import { namesPackage } from "../live/version-compare.js";
+export function packagePresence(query, liveIntel) {
+    const copies = liveIntel.getAuditDeps().filter((d) => namesPackage(query, d.name, d.ecosystem));
+    if (copies.length === 0)
+        return { name: null, versions: [], scope: null, directDevOnly: false };
+    return {
+        name: copies[0].name,
+        versions: [...new Set(copies.map((d) => d.version ?? "unknown"))],
+        scope: copies.some((d) => d.isDirect) ? "direct" : "transitive",
+        directDevOnly: copies.every((d) => d.isDirect && d.isDev),
+    };
+}
+/**
+ * One sentence for a `package` query that produced no rows.
+ * `checked` says what an empty answer means for this tool ("no known advisories", "nothing to upgrade").
+ */
+export function emptyAnswerNote(query, liveIntel, includeDev, checked) {
+    const p = packagePresence(query, liveIntel);
+    if (!p.name)
+        return `"${query}" is not in this project's lockfiles`;
+    const held = `${p.name} ${p.versions.join(", ")} (${p.scope})`;
+    if (!includeDev && p.directDevOnly)
+        return `${held} is a direct devDependency, left out at this scope: pass include_dev: true`;
+    return `${held}: ${checked}`;
+}

package/dist/tools/record-feedback.d.ts

@@ -21,7 +21,6 @@ export declare const recordFeedbackTool: {
             source_type: {
                 type: string;
                 description: string;
-                enum: string[];
             };
             action: {
                 type: string;