@kentwynn/kgraph 0.2.4 → 0.2.5

package/dist/cli/commands/doctor.js

@@ -3,6 +3,7 @@ import path from 'node:path';
 import { analyzeCognitionQuality, } from '../../cognition/cognition-quality.js';
 import { loadConfig } from '../../config/config.js';
 import { listIntegrations } from '../../integrations/integration-store.js';
+import { getCurrentCommit, isGitRepo } from '../../scanner/git-utils.js';
 import { assertWorkspace, pathExists, resolveWorkspace, } from '../../storage/kgraph-paths.js';
 import { mapPaths, mapsExist, readMaps } from '../../storage/map-store.js';
 import { runCommand } from '../errors.js';
@@ -37,7 +38,9 @@ export function registerDoctorCommand(program) {
         checks.push({
             label: 'maps',
             ok: mapStatus,
-            detail: mapStatus ? 'structural maps are present' : 'run `kgraph scan` or just `kgraph`',
+            detail: mapStatus
+                ? 'structural maps are present'
+                : 'run `kgraph scan` or just `kgraph`',
         });
         const maps = mapStatus ? await readMaps(workspace) : undefined;
         if (maps) {
@@ -46,6 +49,19 @@ export function registerDoctorCommand(program) {
                 ok: true,
                 detail: `${maps.fileMap.files.length} files, ${maps.symbolMap.symbols.length} symbols, ${maps.dependencyMap.dependencies.length} dependencies`,
             });
+            // Detect whether the repo has advanced past the commit that was scanned
+            if (maps.fileMap.scannedAtCommit && (await isGitRepo(rootPath))) {
+                const headCommit = await getCurrentCommit(rootPath);
+                const stale = headCommit !== null &&
+                    headCommit !== maps.fileMap.scannedAtCommit;
+                checks.push({
+                    label: 'scan freshness',
+                    ok: !stale,
+                    detail: stale
+                        ? `scanned at ${maps.fileMap.scannedAtCommit.slice(0, 7)}, HEAD is ${headCommit.slice(0, 7)} — run \`kgraph scan\``
+                        : `maps current at ${maps.fileMap.scannedAtCommit.slice(0, 7)}`,
+                });
+            }
         }
         else {
             const paths = mapPaths(workspace);
@@ -125,6 +141,7 @@ function printChecks(checks) {
 export function printQualityReport(report) {
     console.log(`Notes: ${report.noteCount}`);
     console.log(`Mixed/stale/unresolved notes: ${report.mixedOrStaleCount}`);
+    console.log(`Orphaned notes (all refs dead): ${report.orphanedNoteCount}`);
     console.log(`Noisy file refs: ${report.noisyFileRefCount}`);
     console.log(`Noisy symbol refs: ${report.noisySymbolRefCount}`);
     console.log(`Unresolved local imports: ${report.unresolvedLocalImportCount}`);
@@ -152,6 +169,9 @@ export function printQualityReport(report) {
 }
 function summarizeQualityFindings(report) {
     const findings = [];
+    if (report.orphanedNoteCount > 0) {
+        findings.push(`${report.orphanedNoteCount} orphaned cognition note(s) (all refs dead); run \`kgraph repair\` to archive`);
+    }
     if (report.mixedOrStaleCount > 0) {
         findings.push(`${report.mixedOrStaleCount} stale/mixed/unresolved note(s)`);
     }

package/dist/cognition/cognition-quality.d.ts

@@ -1,5 +1,5 @@
-import type { KGraphWorkspace } from '../types/config.js';
 import type { ReferenceStatus } from '../types/cognition.js';
+import type { KGraphWorkspace } from '../types/config.js';
 import type { DependencyMap, FileMap, RelationshipMap, SymbolMap } from '../types/maps.js';
 export interface CognitionRepairChange {
     noteId: string;
@@ -21,6 +21,7 @@ export interface CognitionQualityReport {
     sessionRepeatedReadCount: number;
     sessionEstimatedReadTokens: number;
     sessionEstimatedRepeatedReadTokens: number;
+    orphanedNoteCount: number;
     changes: CognitionRepairChange[];
 }
 export declare function analyzeCognitionQuality(workspace: KGraphWorkspace, maps: {

package/dist/cognition/cognition-quality.js

@@ -1,5 +1,7 @@
-import { overwriteDomainRecord, readCognitionNotes, readDomainRecords, writeCognitionNote, } from '../storage/cognition-store.js';
+import { mkdir, rename } from 'node:fs/promises';
+import path from 'node:path';
 import { buildSessionReport } from '../session/session-store.js';
+import { overwriteDomainRecord, readCognitionNotes, readDomainRecords, writeCognitionNote, } from '../storage/cognition-store.js';
 export async function analyzeCognitionQuality(workspace, maps) {
     const notes = await readCognitionNotes(workspace);
     const session = await buildSessionReport(workspace);
@@ -7,6 +9,7 @@ export async function analyzeCognitionQuality(workspace, maps) {
         .map((note) => analyzeNote(note, maps))
         .filter((change) => change.removedFileRefs.length > 0 ||
         change.removedSymbolRefs.length > 0);
+    const orphanedNoteCount = notes.filter((note) => note.referencesStatus === 'stale').length;
     return {
         noteCount: notes.length,
         mixedOrStaleCount: notes.filter((note) => ['mixed', 'stale', 'unresolved'].includes(note.referencesStatus)).length,
@@ -20,6 +23,7 @@ export async function analyzeCognitionQuality(workspace, maps) {
         sessionRepeatedReadCount: session.repeatedReadCount,
         sessionEstimatedReadTokens: session.estimatedReadTokens,
         sessionEstimatedRepeatedReadTokens: session.estimatedRepeatedReadTokens,
+        orphanedNoteCount,
         changes,
     };
 }
@@ -40,9 +44,18 @@ export async function repairCognition(workspace, maps, dryRun = false) {
             }
         }
     }
-    if (!dryRun && changes.length > 0) {
-        await repairDomainRecords(workspace, nextNotes, maps);
+    // Archive fully-orphaned notes (all refs dead) so they no longer appear in context
+    const orphanedNotes = nextNotes.filter((note) => note.referencesStatus === 'stale');
+    if (!dryRun && (changes.length > 0 || orphanedNotes.length > 0)) {
+        // Exclude fully-orphaned notes from domain records — they are being archived
+        await repairDomainRecords(workspace, nextNotes.filter((n) => n.referencesStatus !== 'stale'), maps);
+    }
+    if (!dryRun) {
+        for (const note of orphanedNotes) {
+            await archiveOrphanedNote(workspace, note);
+        }
     }
+    const orphanedNoteCount = orphanedNotes.length;
     return {
         noteCount: notes.length,
         mixedOrStaleCount: nextNotes.filter((note) => ['mixed', 'stale', 'unresolved'].includes(note.referencesStatus)).length,
@@ -56,6 +69,7 @@ export async function repairCognition(workspace, maps, dryRun = false) {
         sessionRepeatedReadCount: session.repeatedReadCount,
         sessionEstimatedReadTokens: session.estimatedReadTokens,
         sessionEstimatedRepeatedReadTokens: session.estimatedRepeatedReadTokens,
+        orphanedNoteCount,
         changes,
     };
 }
@@ -98,7 +112,8 @@ function countGeneratedScannedFiles(fileMap) {
     ].some((prefix) => file.path === prefix || file.path.startsWith(prefix))).length;
 }
 function countExpensiveFiles(fileMap) {
-    return fileMap.files.filter((file) => (file.tokenEstimate ?? 0) >= 1000).length;
+    return fileMap.files.filter((file) => (file.tokenEstimate ?? 0) >= 1000)
+        .length;
 }
 function analyzeNote(note, maps) {
     const filePaths = new Set(maps.fileMap.files.map((file) => file.path));
@@ -161,11 +176,27 @@ function evaluateReferenceStatus(relatedFiles, relatedSymbols, maps) {
     return 'mixed';
 }
 function isNoisyFileRef(ref) {
-    return !ref.includes('/') && /^[A-Z][A-Za-z0-9_-]*\.[A-Za-z0-9_-]+$/.test(ref);
+    return (!ref.includes('/') && /^[A-Z][A-Za-z0-9_-]*\.[A-Za-z0-9_-]+$/.test(ref));
 }
 function isNoisySymbolRef(ref) {
-    return /^[a-z][A-Za-z0-9_$]*$/.test(ref);
+    // Only treat as noise if the ref is a short all-lowercase word (no camelCase, no _ or $).
+    // Preserve camelCase refs even when unresolved — the symbol may have been renamed.
+    if (/[A-Z_$]/.test(ref))
+        return false;
+    return ref.length <= 5;
 }
 function unique(items) {
     return [...new Set(items)];
 }
+async function archiveOrphanedNote(workspace, note) {
+    const archivedDir = path.join(workspace.cognitionPath, 'archived');
+    await mkdir(archivedDir, { recursive: true });
+    const source = path.join(workspace.cognitionPath, `${note.id}.md`);
+    const target = path.join(archivedDir, `${note.id}.md`);
+    try {
+        await rename(source, target);
+    }
+    catch {
+        // source file may already be missing — ignore
+    }
+}

package/dist/cognition/cognition-updater.js

@@ -11,7 +11,11 @@ export async function updateCognition(workspace, currentMaps, dryRun = false) {
             const raw = await readFile(inboxPath, 'utf8');
             const parsed = parseMarkdownNote(raw);
             const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
-            const id = `${timestamp}-${slugify(parsed.title) || path.basename(inboxPath, '.md')}`;
+            // Always include the inbox basename as a per-note unique suffix so two notes with
+            // the same title processed in the same millisecond never receive the same ID.
+            const base = path.basename(inboxPath, '.md');
+            const slug = slugify(parsed.title);
+            const id = slug ? `${timestamp}-${slug}-${base}` : `${timestamp}-${base}`;
             const archivedPath = path.join(workspace.processedInteractionsPath, `${timestamp}-${path.basename(inboxPath)}`);
             const note = {
                 ...parsed,
@@ -39,6 +43,11 @@ export async function updateCognition(workspace, currentMaps, dryRun = false) {
             warnings.push(`${path.basename(inboxPath)}: ${error instanceof Error ? error.message : String(error)}`);
         }
     }
+    // Refresh reference statuses on all existing notes so that notes which
+    // became stale since the last scan reflect the current map state.
+    if (!dryRun) {
+        await refreshCognitionReferenceStatuses(workspace, currentMaps);
+    }
     return { processed, warnings };
 }
 export async function refreshCognitionReferenceStatuses(workspace, currentMaps) {

package/dist/cognition/markdown-note-parser.js

@@ -14,7 +14,7 @@ export function parseMarkdownNote(markdown) {
         tags: Array.isArray(frontmatter.tags) ? frontmatter.tags.map(String) : [],
         summary: sections.Summary,
         sections,
-        relatedFiles: unique(extractMatches(combined, PATH_REF)),
+        relatedFiles: unique(extractMatches(stripCodeFences(combined), PATH_REF)),
         relatedSymbols: unique(extractSymbolRefs(sections)),
         warnings,
     };
@@ -70,3 +70,8 @@ function extractSymbolRefs(sections) {
 function unique(items) {
     return [...new Set(items)];
 }
+function stripCodeFences(text) {
+    // Remove triple-backtick code blocks so paths inside code examples are not
+    // mistaken for real file references, which would create phantom stale refs.
+    return text.replace(/```[\s\S]*?```/g, '');
+}

package/dist/context/context-query.js

@@ -5,10 +5,16 @@ export async function queryContext(workspace, config, maps, query) {
     const cognition = await readCognitionNotes(workspace);
     const domains = await readDomainRecords(workspace);
     const max = config.maxContextItems;
-    const relevantFiles = rankByFields(query, maps.fileMap.files, [
+    let relevantFiles = rankByFields(query, maps.fileMap.files, [
         { name: 'path', value: (file) => file.path },
         { name: 'language', value: (file) => file.language },
-    ]).slice(0, max);
+    ])
+        .map((ranked) => ({
+        ...ranked,
+        score: ranked.score - Math.floor((ranked.item.tokenEstimate ?? 0) / 2000),
+    }))
+        .sort((a, b) => b.score - a.score)
+        .slice(0, max);
     const relevantSymbols = rankByFields(query, maps.symbolMap.symbols, [
         { name: 'name', value: (symbol) => symbol.name },
         { name: 'path', value: (symbol) => symbol.filePath },
@@ -28,6 +34,57 @@ export async function queryContext(workspace, config, maps, query) {
         { name: 'tags', value: (domain) => domain.tags },
         { name: 'path', value: (domain) => domain.pathHints },
     ]).slice(0, max);
+    // Inject files linked by matched cognition notes/domains that didn't score on name alone
+    const rankedFilePaths = new Set(relevantFiles.map((f) => f.item.path));
+    const cognitionLinkedMap = new Map();
+    for (const ranked of relevantCognition) {
+        for (const fp of ranked.item.relatedFiles) {
+            if (!rankedFilePaths.has(fp)) {
+                const reasons = cognitionLinkedMap.get(fp) ?? [];
+                reasons.push(`linked by cognition note "${ranked.item.title}"`);
+                cognitionLinkedMap.set(fp, reasons);
+            }
+        }
+    }
+    for (const ranked of matchedDomains) {
+        for (const fp of ranked.item.files) {
+            if (!rankedFilePaths.has(fp)) {
+                const reasons = cognitionLinkedMap.get(fp) ?? [];
+                reasons.push(`in domain "${ranked.item.name}"`);
+                cognitionLinkedMap.set(fp, reasons);
+            }
+        }
+    }
+    // Apply domainHints from config: inject paths for hints whose name matches the query
+    const queryTokens = new Set(query
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .filter(Boolean));
+    for (const [hintName, hint] of Object.entries(config.domainHints)) {
+        const hintWords = hintName
+            .toLowerCase()
+            .split(/[^a-z0-9]+/)
+            .filter(Boolean);
+        if (!hintWords.some((w) => queryTokens.has(w)))
+            continue;
+        for (const fp of hint.paths ?? []) {
+            if (!rankedFilePaths.has(fp)) {
+                const reasons = cognitionLinkedMap.get(fp) ?? [];
+                reasons.push(`in configured domain hint "${hintName}"`);
+                cognitionLinkedMap.set(fp, reasons);
+            }
+        }
+    }
+    relevantFiles = [
+        ...relevantFiles,
+        ...maps.fileMap.files
+            .filter((f) => cognitionLinkedMap.has(f.path))
+            .map((f) => ({
+            item: f,
+            score: 1,
+            reasons: cognitionLinkedMap.get(f.path),
+        })),
+    ];
     const relatedIds = new Set([
         ...relevantFiles.map((file) => file.item.path),
         ...relevantSymbols.map((symbol) => symbol.item.id),
@@ -69,10 +126,12 @@ export async function queryContext(workspace, config, maps, query) {
     });
     const filePaths = new Set(maps.fileMap.files.map((f) => f.path));
     const symbolNames = new Set(maps.symbolMap.symbols.map((s) => s.name));
+    const matchedCognitionIds = new Set(relevantCognition.map((r) => r.item.id));
     const staleReferences = cognition
-        .filter((note) => note.referencesStatus === 'stale' ||
-        note.referencesStatus === 'unresolved' ||
-        note.referencesStatus === 'mixed')
+        .filter((note) => matchedCognitionIds.has(note.id) &&
+        (note.referencesStatus === 'stale' ||
+            note.referencesStatus === 'unresolved' ||
+            note.referencesStatus === 'mixed'))
         .flatMap((note) => [
         ...note.relatedFiles
             .filter((f) => !filePaths.has(f))
@@ -98,9 +157,18 @@ export async function queryContext(workspace, config, maps, query) {
     // Remove files already in the matched set
     for (const p of matchedFilePaths)
         importedFilePaths.delete(p);
+    // Skip generic utility/barrel files with many exports — surface only focused modules
+    const exportCountByFile = new Map();
+    for (const s of maps.symbolMap.symbols) {
+        if (s.exported) {
+            exportCountByFile.set(s.filePath, (exportCountByFile.get(s.filePath) ?? 0) + 1);
+        }
+    }
+    const MAX_NEARBY_FILE_EXPORTS = 15;
+    const relevantImportedFilePaths = new Set([...importedFilePaths].filter((fp) => (exportCountByFile.get(fp) ?? 0) <= MAX_NEARBY_FILE_EXPORTS));
     const nearbySymbols = maps.symbolMap.symbols
         .filter((s) => s.exported &&
-        importedFilePaths.has(s.filePath) &&
+        relevantImportedFilePaths.has(s.filePath) &&
         !matchedSymbolIds.has(s.id))
         .slice(0, max);
     const nearbySymbolExplanations = nearbySymbols.map((symbol) => ({

package/dist/session/session-store.js

@@ -1,8 +1,8 @@
 import { mkdir, readFile, rm, stat, writeFile } from 'node:fs/promises';
 import path from 'node:path';
+import { KGraphError } from '../cli/errors.js';
 import { getIntegrationAdapter } from '../integrations/integration-registry.js';
 import { pathExists } from '../storage/kgraph-paths.js';
-import { KGraphError } from '../cli/errors.js';
 import { estimateTokens } from './token-estimator.js';
 const EMPTY_STATE = {
     active: {},
@@ -32,6 +32,12 @@ export async function readSessionLedger(workspace) {
 export async function recordSessionEvent(workspace, input) {
     const now = new Date().toISOString();
     const state = await readSessionState(workspace);
+    // Auto-close any open session for this agent before starting a new one so
+    // the ledger entry is never silently lost on repeated start calls.
+    if (input.type === 'start' && state.active[input.agent]) {
+        await appendLedgerEntry(workspace, summarizeAgentSession(input.agent, state, now));
+        delete state.active[input.agent];
+    }
     const active = state.active[input.agent] ?? {
         agent: input.agent,
         sessionId: `${input.agent}-${now.replace(/[:.]/g, '-')}`,
@@ -146,7 +152,11 @@ function topRepeatedReads(events) {
     for (const event of events) {
         if (!event.path)
             continue;
-        const current = byPath.get(event.path) ?? { path: event.path, count: 0, estimatedTokens: 0 };
+        const current = byPath.get(event.path) ?? {
+            path: event.path,
+            count: 0,
+            estimatedTokens: 0,
+        };
         current.count += 1;
         current.estimatedTokens += event.tokenEstimate ?? 0;
         byPath.set(event.path, current);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kentwynn/kgraph",
-  "version": "0.2.4",
+  "version": "0.2.5",
   "description": "Persistent repo intelligence for AI coding assistants.",
   "type": "module",
   "bin": {