@kentwynn/kgraph 0.2.30 → 0.2.31

package/dist/cli/commands/knowledge.js

@@ -1,5 +1,5 @@
-import { atomToCognitionNote, readKnowledgeAtoms, updateKnowledgeAtom, updateKnowledgeAtoms, } from '../../knowledge/atom-store.js';
 import { rebuildDomainRecords } from '../../cognition/domain-records.js';
+import { atomToCognitionNote, readKnowledgeAtoms, updateKnowledgeAtom, updateKnowledgeAtoms, } from '../../knowledge/atom-store.js';
 import { assertWorkspace } from '../../storage/kgraph-paths.js';
 import { readMaps } from '../../storage/map-store.js';
 import { KGraphError, runCommand } from '../errors.js';
@@ -109,7 +109,10 @@ export function registerKnowledgeCommand(program) {
                 lifecycle: {
                     ...nextAtoms[newIndex].lifecycle,
                     supersedes: [
-                        ...new Set([...nextAtoms[newIndex].lifecycle.supersedes, oldId]),
+                        ...new Set([
+                            ...nextAtoms[newIndex].lifecycle.supersedes,
+                            oldId,
+                        ]),
                     ],
                 },
             };
@@ -144,13 +147,18 @@ function filterAtoms(atoms, options) {
     return atoms.filter((atom) => {
         if (options.type && atom.type !== options.type)
             return false;
-        if (options.status &&
-            atom.status !== normalizeStatus(options.status)) {
+        if (options.status && atom.status !== normalizeStatus(options.status)) {
             return false;
         }
-        if (options.topic &&
-            !atom.topic.toLowerCase().includes(options.topic.toLowerCase())) {
-            return false;
+        if (options.topic) {
+            const q = options.topic.toLowerCase();
+            const matches = atom.topic.toLowerCase().includes(q) ||
+                atom.claim.toLowerCase().includes(q) ||
+                (atom.summary?.toLowerCase().includes(q) ?? false) ||
+                atom.scopeRefs.files.some((f) => f.toLowerCase().includes(q)) ||
+                atom.scopeRefs.symbols.some((s) => s.toLowerCase().includes(q));
+            if (!matches)
+                return false;
         }
         return true;
     });

package/dist/cli/commands/pack.js

@@ -1,10 +1,10 @@
 import path from 'node:path';
+import { loadConfig } from '../../config/config.js';
 import { buildContextPack } from '../../context/context-pack.js';
 import { queryContext } from '../../context/context-query.js';
-import { loadConfig } from '../../config/config.js';
 import { assertSessionAgent, recordSessionEvent, } from '../../session/session-store.js';
-import { assertWorkspace } from '../../storage/kgraph-paths.js';
 import { listInboxNotes } from '../../storage/cognition-store.js';
+import { assertWorkspace } from '../../storage/kgraph-paths.js';
 import { mapsExist, readMaps } from '../../storage/map-store.js';
 import { KGraphError, runCommand } from '../errors.js';
 export function registerPackCommand(program) {
@@ -41,7 +41,7 @@ export function registerPackCommand(program) {
         ]);
         const response = await queryContext(workspace, config, maps, task);
         const pack = buildContextPack(response, budget, workspace.rootPath);
-        const pendingInboxFiles = (await listInboxNotes(workspace)).map((file) => path.relative(workspace.rootPath, file));
+        const pendingInboxFiles = (await listInboxNotes(workspace)).map((file) => path.relative(workspace.rootPath, file).split(path.sep).join('/'));
         if (pendingInboxFiles.length > 0) {
             pack.pendingInbox = {
                 count: pendingInboxFiles.length,
@@ -122,6 +122,12 @@ function appendGroup(lines, title, items) {
                 lines.push(`    range ${data.path}:${data.startLine}-${data.endLine}`);
             }
         }
+        if (item.kind === 'symbol') {
+            const data = item.data;
+            if (data.filePath && data.startLine != null && data.endLine != null) {
+                lines.push(`    ${data.filePath}:${data.startLine}-${data.endLine}`);
+            }
+        }
     }
     if (items.length > 6)
         lines.push(`  ◌ ${items.length - 6} more ${title.toLowerCase()} omitted from display`);
@@ -132,5 +138,7 @@ function formatReasons(reasons) {
         return 'included by pack ranking';
     const shown = reasons.slice(0, 3);
     const remaining = reasons.length - shown.length;
-    return remaining > 0 ? `${shown.join('; ')}; and ${remaining} more` : shown.join('; ');
+    return remaining > 0
+        ? `${shown.join('; ')}; and ${remaining} more`
+        : shown.join('; ');
 }

package/dist/context/context-pack.js

@@ -13,14 +13,7 @@ export function buildContextPack(response, budget, rootPath) {
             data: ranked.item,
         })),
         ...buildFileRangeCandidates(response, budget, rootPath),
-        ...response.relevantSymbols.map((ranked) => ({
-            kind: 'symbol',
-            id: ranked.item.id,
-            title: ranked.item.name,
-            tokenEstimate: 20,
-            reasons: ranked.reasons,
-            data: ranked.item,
-        })),
+        ...response.relevantSymbols.map((ranked) => buildSymbolCandidate(ranked, rootPath)),
         ...response.relevantCognition.map((ranked) => ({
             kind: 'atom',
             id: ranked.item.id,
@@ -131,14 +124,18 @@ function strongPackPaths(candidates) {
 function isLowSignalCandidate(candidate, strongPaths) {
     if (strongPaths.size === 0)
         return false;
-    if (candidate.kind === 'atom' || candidate.kind === 'git-change' || candidate.kind === 'file-range') {
+    if (candidate.kind === 'atom' ||
+        candidate.kind === 'git-change' ||
+        candidate.kind === 'file-range') {
         return false;
     }
     if (hasStrongReason(candidate))
         return false;
     if (candidateTouchesStrongPath(candidate, strongPaths))
         return false;
-    return candidate.kind === 'file' || candidate.kind === 'symbol' || candidate.kind === 'relationship';
+    return (candidate.kind === 'file' ||
+        candidate.kind === 'symbol' ||
+        candidate.kind === 'relationship');
 }
 function hasStrongReason(candidate) {
     return candidate.reasons.some((reason) => reason.includes('matched atom') ||
@@ -170,6 +167,39 @@ const GENERIC_RANGE_TOKENS = new Set([
     'repo',
     'work',
 ]);
+const MAX_SYMBOL_EXCERPT_LINES = 40;
+function buildSymbolCandidate(ranked, rootPath) {
+    const symbol = ranked.item;
+    let excerpt;
+    let tokenEstimate = 20;
+    if (rootPath &&
+        symbol.startLine != null &&
+        symbol.endLine != null &&
+        symbol.endLine - symbol.startLine + 1 <= MAX_SYMBOL_EXCERPT_LINES) {
+        const fullPath = path.join(rootPath, symbol.filePath);
+        if (existsSync(fullPath)) {
+            try {
+                const content = readFileSync(fullPath, 'utf8');
+                const allLines = content.split(/\r?\n/);
+                const from = symbol.startLine - 1; // 0-based
+                const to = symbol.endLine; // exclusive
+                excerpt = allLines.slice(from, to).join('\n');
+                tokenEstimate = estimateTokens(excerpt, symbol.filePath);
+            }
+            catch {
+                // best-effort; fall back to default estimate
+            }
+        }
+    }
+    return {
+        kind: 'symbol',
+        id: symbol.id,
+        title: symbol.name,
+        tokenEstimate,
+        reasons: ranked.reasons,
+        data: excerpt != null ? { ...symbol, excerpt } : symbol,
+    };
+}
 function buildFileRangeCandidates(response, budget, rootPath) {
     if (!rootPath)
         return [];

package/dist/knowledge/atom-store.js

@@ -1,5 +1,5 @@
 import { randomUUID } from 'node:crypto';
-import { mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { mkdir, readFile, rename, rm, unlink, writeFile, } from 'node:fs/promises';
 import path from 'node:path';
 import { setTimeout as delay } from 'node:timers/promises';
 import { KGraphError } from '../cli/errors.js';
@@ -120,8 +120,7 @@ export async function migrateLegacyCognitionToAtoms(workspace) {
             const current = await readAtomsFile(workspace);
             const currentIds = new Set(current.map((atom) => atom.id));
             const nextMigrated = migrated.filter((atom) => !currentIds.has(atom.id) &&
-                !current.some((existing) => existing.topic === atom.topic &&
-                    existing.claim === atom.claim));
+                !current.some((existing) => existing.topic === atom.topic && existing.claim === atom.claim));
             if (nextMigrated.length > 0) {
                 await writeKnowledgeAtomsUnlocked(workspace, [
                     ...current,
@@ -206,7 +205,10 @@ export async function refreshKnowledgeAtomStatuses(workspace, maps, dryRun = fal
 export async function validateKnowledgeStore(workspace, maps) {
     const issues = [];
     if (!(await pathExists(schemaPath(workspace)))) {
-        issues.push({ code: 'missing-schema', message: 'missing knowledge/schema.json' });
+        issues.push({
+            code: 'missing-schema',
+            message: 'missing knowledge/schema.json',
+        });
     }
     else {
         try {
@@ -220,7 +222,10 @@ export async function validateKnowledgeStore(workspace, maps) {
         }
         catch (error) {
             const message = error instanceof Error ? error.message : String(error);
-            issues.push({ code: 'missing-schema', message: `invalid knowledge schema: ${message}` });
+            issues.push({
+                code: 'missing-schema',
+                message: `invalid knowledge schema: ${message}`,
+            });
         }
     }
     let atoms = [];
@@ -252,11 +257,15 @@ export async function validateKnowledgeStore(workspace, maps) {
                         });
                     }
                     else if (ref.contentHash && ref.contentHash !== file.contentHash) {
-                        issues.push({
-                            code: 'stale-file-hash',
-                            atomId: atom.id,
-                            message: `${atom.id} references changed file ${ref.path}`,
-                        });
+                        // Only report if the atom hasn't already been moved to needs-review;
+                        // needs-review atoms are already caught by the quality gate.
+                        if (atom.status !== 'needs-review') {
+                            issues.push({
+                                code: 'stale-file-hash',
+                                atomId: atom.id,
+                                message: `${atom.id} references changed file ${ref.path}; run \`kgraph stale\` to update atom status`,
+                            });
+                        }
                     }
                 }
                 if (ref.type === 'symbol') {
@@ -344,7 +353,11 @@ function buildEvidenceRefs(input, maps) {
         refs.push({ type: 'git', commit: input.commit });
     }
     if (input.sessionId || input.agent) {
-        refs.push({ type: 'session', sessionId: input.sessionId, agent: input.agent });
+        refs.push({
+            type: 'session',
+            sessionId: input.sessionId,
+            agent: input.agent,
+        });
     }
     return refs;
 }
@@ -373,7 +386,8 @@ function evaluateAtomHealth(refs, maps) {
             }
         }
         if (ref.type === 'symbol') {
-            const exists = (ref.symbolId && symbolIds.has(ref.symbolId)) || symbolNames.has(ref.name);
+            const exists = (ref.symbolId && symbolIds.has(ref.symbolId)) ||
+                symbolNames.has(ref.name);
             if (!exists) {
                 stale = true;
                 reasons.push(`missing symbol:${ref.name}`);
@@ -393,7 +407,8 @@ function computeConfidence(initial, status, atom) {
         return 'low';
     if (status === 'needs-review' && initial === 'high')
         return 'medium';
-    if (atom?.provenance.sourceCommand === 'legacy-migration' && initial === 'high') {
+    if (atom?.provenance.sourceCommand === 'legacy-migration' &&
+        initial === 'high') {
         return 'medium';
     }
     return initial;
@@ -518,7 +533,37 @@ async function atomicWriteFile(targetPath, content) {
     await mkdir(path.dirname(targetPath), { recursive: true });
     const tempPath = path.join(path.dirname(targetPath), `.${path.basename(targetPath)}.${process.pid}.${randomUUID()}.tmp`);
     await writeFile(tempPath, content, 'utf8');
-    await rename(tempPath, targetPath);
+    // On Windows, rename over an existing file can transiently fail with EPERM
+    // when another handle was recently released. Retry with short delays.
+    let lastError;
+    for (let attempt = 0; attempt < 3; attempt++) {
+        try {
+            await rename(tempPath, targetPath);
+            return;
+        }
+        catch (error) {
+            const code = error.code;
+            if ((code === 'EPERM' || code === 'EACCES') && attempt < 2) {
+                lastError = error;
+                await delay(20 * (attempt + 1));
+                continue;
+            }
+            try {
+                await unlink(tempPath);
+            }
+            catch {
+                /* best-effort cleanup */
+            }
+            throw error;
+        }
+    }
+    try {
+        await unlink(tempPath);
+    }
+    catch {
+        /* best-effort cleanup */
+    }
+    throw lastError;
 }
 async function withKnowledgeWriteLock(workspace, operation) {
     await mkdir(workspace.knowledgePath, { recursive: true });

package/package.json

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