@kentwynn/kgraph 0.2.13 → 0.2.15

package/dist/cli/commands/doctor.js

@@ -179,6 +179,7 @@ export function printQualityReport(report) {
     console.log(`Duplicate compatibility note titles: ${report.duplicateTitleCount}`);
     console.log(`Generated files scanned: ${report.generatedFileScanCount}`);
     console.log(`Expensive files: ${report.expensiveFileCount}`);
+    console.log(`High-confidence atoms without evidence: ${report.highConfidenceMissingEvidenceCount}`);
     console.log(`Session repeated reads: ${report.sessionRepeatedReadCount}`);
     console.log(`Session estimated read tokens: ${report.sessionEstimatedReadTokens}`);
     console.log(`Session repeated-read tokens: ${report.sessionEstimatedRepeatedReadTokens}`);
@@ -214,6 +215,9 @@ function summarizeQualityFindings(report) {
     if (report.generatedFileScanCount > 0) {
         findings.push(`${report.generatedFileScanCount} generated/integration file(s) scanned; update excludes`);
     }
+    if (report.highConfidenceMissingEvidenceCount > 0) {
+        findings.push(`${report.highConfidenceMissingEvidenceCount} high-confidence atom(s) without evidence; add file/symbol refs or supersede`);
+    }
     return findings;
 }
 function summarizeCoverageNotes(report) {

package/dist/cli/commands/pack.js

@@ -26,7 +26,7 @@ export function registerPackCommand(program) {
             readMaps(workspace),
         ]);
         const response = await queryContext(workspace, config, maps, task);
-        const pack = buildContextPack(response, budget);
+        const pack = buildContextPack(response, budget, workspace.rootPath);
         if (options.json) {
             console.log(JSON.stringify(pack, null, 2));
             return;

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

@@ -23,6 +23,7 @@ export interface CognitionQualityReport {
     duplicateTitleCount: number;
     generatedFileScanCount: number;
     expensiveFileCount: number;
+    highConfidenceMissingEvidenceCount: number;
     sessionRepeatedReadCount: number;
     sessionEstimatedReadTokens: number;
     sessionEstimatedRepeatedReadTokens: number;

package/dist/cognition/cognition-quality.js

@@ -29,6 +29,7 @@ export async function analyzeCognitionQuality(workspace, maps) {
         duplicateTitleCount: countDuplicateAtomTopics(activeAtoms),
         generatedFileScanCount: countGeneratedScannedFiles(maps.fileMap),
         expensiveFileCount: countExpensiveFiles(maps.fileMap),
+        highConfidenceMissingEvidenceCount: countHighConfidenceMissingEvidence(activeAtoms),
         sessionRepeatedReadCount: session.repeatedReadCount,
         sessionEstimatedReadTokens: session.estimatedReadTokens,
         sessionEstimatedRepeatedReadTokens: session.estimatedRepeatedReadTokens,
@@ -36,6 +37,9 @@ export async function analyzeCognitionQuality(workspace, maps) {
         changes,
     };
 }
+function countHighConfidenceMissingEvidence(atoms) {
+    return atoms.filter((atom) => atom.confidence === 'high' && atom.evidenceRefs.length === 0).length;
+}
 export async function repairCognition(workspace, maps, dryRun = false) {
     const refreshed = await refreshKnowledgeAtomStatuses(workspace, { fileMap: maps.fileMap, symbolMap: maps.symbolMap }, dryRun);
     const atoms = refreshed.atoms;
@@ -135,6 +139,7 @@ export async function repairCognition(workspace, maps, dryRun = false) {
         duplicateTitleCount: countDuplicateTitles(nextNotes),
         generatedFileScanCount: countGeneratedScannedFiles(maps.fileMap),
         expensiveFileCount: countExpensiveFiles(maps.fileMap),
+        highConfidenceMissingEvidenceCount: countHighConfidenceMissingEvidence(atoms),
         sessionRepeatedReadCount: session.repeatedReadCount,
         sessionEstimatedReadTokens: session.estimatedReadTokens,
         sessionEstimatedRepeatedReadTokens: session.estimatedRepeatedReadTokens,

package/dist/cognition/conclusion.js

@@ -2,6 +2,7 @@ import { readMaps } from '../storage/map-store.js';
 import { slugify, writeCognitionNote, writeDomainRecord } from '../storage/cognition-store.js';
 import { KGraphError } from '../cli/errors.js';
 import { createKnowledgeAtom } from '../knowledge/atom-store.js';
+import { getWorkingTreeChanges } from '../scanner/git-utils.js';
 import { evaluateReferenceStatus } from './cognition-updater.js';
 import { readSessionState } from '../session/session-store.js';
 export async function concludeTopic(workspace, input) {
@@ -10,6 +11,10 @@ export async function concludeTopic(workspace, input) {
     const timestamp = now.replace(/[:.]/g, '-');
     const title = input.topic.trim();
     const summary = normalizeBody(input.body) ?? title;
+    const relatedFiles = input.relatedFiles && input.relatedFiles.length > 0
+        ? input.relatedFiles
+        : await inferChangedFiles(workspace, maps);
+    const relatedSymbols = input.relatedSymbols ?? [];
     const note = {
         title,
         kind: input.kind ?? 'summary',
@@ -19,18 +24,18 @@ export async function concludeTopic(workspace, input) {
         summary,
         sections: {
             Summary: summary,
-            ...(input.relatedFiles?.length ? { 'Related Files': input.relatedFiles.map((file) => `- ${file}`).join('\n') } : {}),
-            ...(input.relatedSymbols?.length ? { 'Key Symbols': input.relatedSymbols.map((symbol) => `- \`${symbol}\``).join('\n') } : {}),
+            ...(relatedFiles.length ? { 'Related Files': relatedFiles.map((file) => `- ${file}`).join('\n') } : {}),
+            ...(relatedSymbols.length ? { 'Key Symbols': relatedSymbols.map((symbol) => `- \`${symbol}\``).join('\n') } : {}),
         },
-        relatedFiles: input.relatedFiles ?? [],
-        relatedSymbols: input.relatedSymbols ?? [],
+        relatedFiles,
+        relatedSymbols,
         warnings: [],
         id: `${timestamp}-${slugify(title) || 'conclusion'}`,
         sourceInboxPath: '',
         processedPath: `.kgraph/cognition/${timestamp}-${slugify(title) || 'conclusion'}.md`,
         createdAt: now,
         source: input.source,
-        referencesStatus: evaluateReferenceStatus(input.relatedFiles ?? [], input.relatedSymbols ?? [], { files: maps.fileMap.files, symbols: maps.symbolMap.symbols }),
+        referencesStatus: evaluateReferenceStatus(relatedFiles, relatedSymbols, { files: maps.fileMap.files, symbols: maps.symbolMap.symbols }),
     };
     await writeCognitionNote(workspace, note);
     await writeDomainRecord(workspace, toDomainRecord(note, {
@@ -43,8 +48,8 @@ export async function concludeTopic(workspace, input) {
         claim: note.summary ?? note.title,
         summary: note.summary,
         confidence: note.confidence,
-        files: note.relatedFiles,
-        symbols: note.relatedSymbols,
+        files: relatedFiles,
+        symbols: relatedSymbols,
         domains: note.domain ? [note.domain] : [],
         sourceCommand: input.source === 'session-conclude'
             ? 'session-conclude'
@@ -58,6 +63,13 @@ export async function concludeTopic(workspace, input) {
     }, maps);
     return note;
 }
+async function inferChangedFiles(workspace, maps) {
+    const changed = await getWorkingTreeChanges(workspace.rootPath);
+    if (changed.length === 0)
+        return [];
+    const currentFiles = new Set(maps.fileMap.files.map((file) => file.path));
+    return changed.filter((file) => currentFiles.has(file));
+}
 export async function concludeActiveSession(workspace, agent, input) {
     return concludeTopic(workspace, await buildActiveSessionConclusion(workspace, agent, input));
 }

package/dist/context/context-pack.d.ts

@@ -1,3 +1,3 @@
 import type { ContextResponse } from '../types/cognition.js';
 import type { ContextPack } from '../types/knowledge.js';
-export declare function buildContextPack(response: ContextResponse, budget: number): ContextPack;
+export declare function buildContextPack(response: ContextResponse, budget: number, rootPath?: string): ContextPack;

package/dist/context/context-pack.js

@@ -1,5 +1,8 @@
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
 import { estimateTokens } from '../session/token-estimator.js';
-export function buildContextPack(response, budget) {
+import { tokenize } from './ranking.js';
+export function buildContextPack(response, budget, rootPath) {
     const candidates = [
         ...response.relevantFiles.map((ranked) => ({
             kind: 'file',
@@ -9,6 +12,7 @@ export function buildContextPack(response, budget) {
             reasons: ranked.reasons,
             data: ranked.item,
         })),
+        ...buildFileRangeCandidates(response, budget, rootPath),
         ...response.relevantSymbols.map((ranked) => ({
             kind: 'symbol',
             id: ranked.item.id,
@@ -48,10 +52,11 @@ export function buildContextPack(response, budget) {
             data: change,
         })),
     ];
+    const orderedCandidates = candidates.sort(comparePackCandidates);
     const items = [];
     const omitted = [];
     let usedTokens = 0;
-    for (const candidate of candidates) {
+    for (const candidate of orderedCandidates) {
         if (usedTokens + candidate.tokenEstimate <= budget) {
             items.push(candidate);
             usedTokens += candidate.tokenEstimate;
@@ -69,3 +74,132 @@ export function buildContextPack(response, budget) {
         warnings: response.warnings,
     };
 }
+function comparePackCandidates(left, right) {
+    return packPriority(right) - packPriority(left);
+}
+function packPriority(item) {
+    let score = 0;
+    if (item.kind === 'atom')
+        score += 1000;
+    if (item.kind === 'git-change')
+        score += 900;
+    if (item.kind === 'file-range')
+        score += 800;
+    if (item.kind === 'symbol')
+        score += 300;
+    if (item.kind === 'file')
+        score += 200;
+    if (item.kind === 'relationship')
+        score += 100;
+    if (item.reasons.some((reason) => reason.includes('matched atom')))
+        score += 30;
+    if (item.reasons.some((reason) => reason.includes('current git change')))
+        score += 25;
+    if (item.reasons.some((reason) => reason.includes('specific query token')))
+        score += 10;
+    if (item.reasons.some((reason) => reason.includes('generic path-only match penalty')))
+        score -= 20;
+    score -= Math.floor(item.tokenEstimate / 2000);
+    return score;
+}
+const GENERIC_RANGE_TOKENS = new Set([
+    'app',
+    'code',
+    'component',
+    'file',
+    'page',
+    'repo',
+    'work',
+]);
+function buildFileRangeCandidates(response, budget, rootPath) {
+    if (!rootPath)
+        return [];
+    const queryTokens = tokenize(response.query).filter((token) => token.length >= 3 && !GENERIC_RANGE_TOKENS.has(token));
+    if (queryTokens.length === 0)
+        return [];
+    const maxRangeTokens = Math.max(250, Math.min(1200, Math.floor(budget / 3)));
+    const candidates = [];
+    for (const rankedFile of response.relevantFiles.slice(0, 8)) {
+        const file = rankedFile.item;
+        const fileTokens = file.tokenEstimate ?? 0;
+        if (fileTokens <= Math.max(1000, Math.floor(budget / 2)))
+            continue;
+        const fullPath = path.join(rootPath, file.path);
+        if (!existsSync(fullPath))
+            continue;
+        let content = '';
+        try {
+            content = readFileSync(fullPath, 'utf8');
+        }
+        catch {
+            continue;
+        }
+        const ranges = selectQueryRanges(content, queryTokens, maxRangeTokens, file.path);
+        for (const range of ranges) {
+            const lines = content.split(/\r?\n/).slice(range.start - 1, range.end);
+            const excerpt = lines.join('\n');
+            candidates.push({
+                kind: 'file-range',
+                id: `${file.path}:${range.start}-${range.end}`,
+                title: `${file.path}:${range.start}-${range.end}`,
+                tokenEstimate: estimateTokens(excerpt, file.path),
+                reasons: [
+                    ...rankedFile.reasons,
+                    `range selected from oversized file`,
+                    `line text matched ${range.tokens.map((token) => `"${token}"`).join(', ')}`,
+                ],
+                data: {
+                    path: file.path,
+                    startLine: range.start,
+                    endLine: range.end,
+                    excerpt,
+                },
+            });
+        }
+    }
+    return candidates;
+}
+function selectQueryRanges(content, queryTokens, maxRangeTokens, filePath) {
+    const lines = content.split(/\r?\n/);
+    const hits = [];
+    for (const [index, line] of lines.entries()) {
+        const lower = line.toLowerCase();
+        const matched = queryTokens.filter((token) => lower.includes(token));
+        if (matched.length === 0)
+            continue;
+        hits.push({
+            start: Math.max(1, index + 1 - 8),
+            end: Math.min(lines.length, index + 1 + 8),
+            tokens: matched,
+        });
+    }
+    const ranges = mergeRanges(hits);
+    return ranges
+        .sort((left, right) => right.tokens.length - left.tokens.length)
+        .slice(0, 3)
+        .map((range) => trimRangeToBudget(range, lines, maxRangeTokens, filePath));
+}
+function mergeRanges(ranges) {
+    const merged = [];
+    for (const range of ranges.sort((left, right) => left.start - right.start)) {
+        const current = merged.at(-1);
+        if (!current || range.start > current.end + 3) {
+            merged.push({ ...range, tokens: [...new Set(range.tokens)] });
+            continue;
+        }
+        current.end = Math.max(current.end, range.end);
+        current.tokens = [...new Set([...current.tokens, ...range.tokens])];
+    }
+    return merged;
+}
+function trimRangeToBudget(range, lines, maxRangeTokens, filePath) {
+    let start = range.start;
+    let end = Math.min(range.end, start + 79);
+    while (end > start + 4) {
+        const excerpt = lines.slice(start - 1, end).join('\n');
+        if (estimateTokens(excerpt, filePath) <= maxRangeTokens)
+            break;
+        end -= 5;
+    }
+    return { ...range, start, end };
+}

package/dist/context/context-query.js

@@ -3,6 +3,7 @@ import { readDomainRecords } from '../storage/cognition-store.js';
 import { readSessionState } from '../session/session-store.js';
 import { atomToCognitionNote, refreshKnowledgeAtomStatuses, } from '../knowledge/atom-store.js';
 import { rankByFields } from './ranking.js';
+import { tokenize } from './ranking.js';
 export async function queryContext(workspace, config, maps, query) {
     const refreshedAtoms = await refreshKnowledgeAtomStatuses(workspace, {
         fileMap: maps.fileMap,
@@ -18,27 +19,43 @@ export async function queryContext(workspace, config, maps, query) {
         .map((event) => event.path)
         .filter((path) => Boolean(path)));
     const max = config.maxContextItems;
-    let relevantFiles = rankByFields(query, maps.fileMap.files, [
-        { name: 'path', value: (file) => file.path },
-        { name: 'language', value: (file) => file.language },
-    ])
-        .map((ranked) => ({
-        ...ranked,
-        score: ranked.score -
-            Math.floor((ranked.item.tokenEstimate ?? 0) / 2000) +
-            (sessionTouchedPaths.has(ranked.item.path) ? 3 : 0),
-        reasons: sessionTouchedPaths.has(ranked.item.path)
-            ? [...ranked.reasons, 'touched in current session']
-            : ranked.reasons,
-    }))
-        .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 },
-        { name: 'kind', value: (symbol) => symbol.kind },
-        { name: 'parent', value: (symbol) => symbol.parentName },
-    ]).slice(0, max);
+    // Collect git changes before file ranking so dirty files can influence ranking,
+    // not just appear later as a low-token pack item.
+    const knownFilePaths = new Set(maps.fileMap.files.map((f) => f.path));
+    const gitChanges = [];
+    if (await isGitRepo(workspace.rootPath)) {
+        const workingTreeChanges = await getWorkingTreeChangesDetailed(workspace.rootPath);
+        for (const change of workingTreeChanges) {
+            if (!knownFilePaths.has(change.path))
+                continue;
+            const status = change.staged && !change.unstaged
+                ? 'staged'
+                : change.unstaged && !change.staged
+                    ? 'unstaged'
+                    : 'staged'; // both staged and unstaged -> report as staged
+            gitChanges.push({
+                path: change.path,
+                status,
+                reason: change.staged && change.unstaged
+                    ? 'partially staged'
+                    : status === 'staged'
+                        ? 'staged change'
+                        : 'unstaged change',
+            });
+        }
+        const committedPaths = new Set(gitChanges.map((c) => c.path));
+        const recentCommitted = await getRecentlyCommittedFiles(workspace.rootPath);
+        for (const filePath of recentCommitted) {
+            if (!knownFilePaths.has(filePath) || committedPaths.has(filePath))
+                continue;
+            gitChanges.push({
+                path: filePath,
+                status: 'recent-commit',
+                reason: 'changed in recent commits',
+            });
+        }
+    }
+    const gitChangedPaths = new Set(gitChanges.map((change) => change.path));
     const relevantCognition = rankByFields(query, atoms.filter((atom) => atom.status !== 'archived'), [
         { name: 'topic', value: (atom) => atom.topic },
         { name: 'claim', value: (atom) => atom.claim },
@@ -58,11 +75,38 @@ export async function queryContext(workspace, config, maps, query) {
     }))
         .sort((a, b) => b.score - a.score)
         .slice(0, max);
+    const atomLinkedFiles = new Map();
+    for (const ranked of relevantCognition) {
+        for (const fp of ranked.item.relatedFiles) {
+            atomLinkedFiles.set(fp, [
+                ...(atomLinkedFiles.get(fp) ?? []),
+                `referenced by matched atom "${ranked.item.title}"`,
+            ]);
+        }
+    }
     const matchedDomains = rankByFields(query, domains, [
         { name: 'name', value: (domain) => domain.name },
         { name: 'tags', value: (domain) => domain.tags },
         { name: 'path', value: (domain) => domain.pathHints },
     ]).slice(0, max);
+    let relevantFiles = rankByFields(query, maps.fileMap.files, [
+        { name: 'path', value: (file) => file.path },
+        { name: 'language', value: (file) => file.language },
+    ])
+        .map((ranked) => applyFileRankAdjustments(ranked, {
+        query,
+        atomLinkedFiles,
+        gitChangedPaths,
+        sessionTouchedPaths,
+    }))
+        .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 },
+        { name: 'kind', value: (symbol) => symbol.kind },
+        { name: 'parent', value: (symbol) => symbol.parentName },
+    ]).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();
@@ -110,10 +154,10 @@ export async function queryContext(workspace, config, maps, query) {
             .filter((f) => cognitionLinkedMap.has(f.path))
             .map((f) => ({
             item: f,
-            score: 1,
+            score: 12,
             reasons: cognitionLinkedMap.get(f.path),
         })),
-    ];
+    ].sort((a, b) => b.score - a.score);
     const relatedIds = new Set([
         ...relevantFiles.map((file) => file.item.path),
         ...relevantSymbols.map((symbol) => symbol.item.id),
@@ -207,41 +251,6 @@ export async function queryContext(workspace, config, maps, query) {
             ...dependenciesForImportedSymbol(symbol, maps.dependencyMap.dependencies),
         ],
     }));
-    // Collect git changes: working-tree and recently committed files known to KGraph
-    const knownFilePaths = new Set(maps.fileMap.files.map((f) => f.path));
-    const gitChanges = [];
-    if (await isGitRepo(workspace.rootPath)) {
-        const workingTreeChanges = await getWorkingTreeChangesDetailed(workspace.rootPath);
-        for (const change of workingTreeChanges) {
-            if (!knownFilePaths.has(change.path))
-                continue;
-            const status = change.staged && !change.unstaged
-                ? 'staged'
-                : change.unstaged && !change.staged
-                    ? 'unstaged'
-                    : 'staged'; // both staged and unstaged → report as staged
-            gitChanges.push({
-                path: change.path,
-                status,
-                reason: change.staged && change.unstaged
-                    ? 'partially staged'
-                    : status === 'staged'
-                        ? 'staged change'
-                        : 'unstaged change',
-            });
-        }
-        const committedPaths = new Set(gitChanges.map((c) => c.path));
-        const recentCommitted = await getRecentlyCommittedFiles(workspace.rootPath);
-        for (const filePath of recentCommitted) {
-            if (!knownFilePaths.has(filePath) || committedPaths.has(filePath))
-                continue;
-            gitChanges.push({
-                path: filePath,
-                status: 'recent-commit',
-                reason: 'changed in recent commits',
-            });
-        }
-    }
     return {
         query,
         matchedDomains,
@@ -257,6 +266,36 @@ export async function queryContext(workspace, config, maps, query) {
         warnings: [],
     };
 }
+function applyFileRankAdjustments(ranked, context) {
+    const reasons = [...ranked.reasons];
+    let score = ranked.score - Math.floor((ranked.item.tokenEstimate ?? 0) / 2000);
+    if (context.sessionTouchedPaths.has(ranked.item.path)) {
+        score += 3;
+        reasons.push('touched in current session');
+    }
+    if (context.gitChangedPaths.has(ranked.item.path)) {
+        score += 10;
+        reasons.push('current git change');
+    }
+    const atomReasons = context.atomLinkedFiles.get(ranked.item.path) ?? [];
+    if (atomReasons.length > 0) {
+        score += 12;
+        reasons.push(...atomReasons);
+    }
+    const strongTokens = tokenize(context.query).filter((token) => token.length >= 4 &&
+        !['page', 'work', 'file', 'component', 'app'].includes(token));
+    const pathTokens = new Set(tokenize(ranked.item.path));
+    const strongMatches = strongTokens.filter((token) => pathTokens.has(token));
+    if (strongMatches.length > 0) {
+        score += strongMatches.length * 3;
+        reasons.push(`path matched specific query token(s): ${strongMatches.join(', ')}`);
+    }
+    else if (strongTokens.length > 0) {
+        score -= 6;
+        reasons.push('generic path-only match penalty');
+    }
+    return { ...ranked, score, reasons };
+}
 function explainRelationships(relationships, context) {
     const rankedReasons = new Map(context.rankedRelationships.map((ranked) => [
         relationshipKey(ranked.item),

package/dist/types/knowledge.d.ts

@@ -75,7 +75,7 @@ export interface KnowledgeValidationIssue {
     atomId?: string;
 }
 export interface ContextPackItem {
-    kind: 'file' | 'symbol' | 'atom' | 'relationship' | 'git-change';
+    kind: 'file' | 'file-range' | 'symbol' | 'atom' | 'relationship' | 'git-change';
     id: string;
     title: string;
     tokenEstimate: number;

package/package.json

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