@kentwynn/kgraph 0.2.29 → 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/integrations/adapters/claude-code.js

@@ -12,16 +12,9 @@ ${numberedWorkflow('claude-code', {
     commandFiles: [
         {
             path: '.claude/commands/kgraph.md',
-            content: `Use KGraph persistent repo intelligence through the single normal \`kgraph "<topic>" --agent claude-code\` entry point.
+            content: `## KGraph Workflow
 
-1. Infer a concise topic from the user's request.
-2. Run exactly one command from the repository root: \`kgraph "<topic>" --agent claude-code\`.
-3. Treat the returned files, symbols, relationships, atoms, and warnings as the first-pass source of truth.
-4. If the user asked for an edit, inspect only the returned candidate file or the smallest necessary range, then make the edit.
-5. Verify the change actually landed before claiming completion. Prefer a narrow read of the changed range or \`git diff -- <path>\`; if there is no diff or the expected text is missing, say the edit did not apply and fix it before summarizing.
-6. Do not run \`kgraph\` again, \`kgraph context\`, \`kgraph pack\`, \`kgraph knowledge\`, \`kgraph stale\`, \`kgraph blame\`, \`kgraph scan\`, \`kgraph update\`, \`kgraph compact\`, or \`kgraph repair\` unless the user explicitly asks for that lower-level command.
-7. Do not continue broad repository search after the target file is identified. If a path must be located, prefer \`rg --files\` and quote paths containing spaces or parentheses.
-8. At the end of repository-file changes, run \`kgraph "<topic>" --final --agent claude-code\`. If KGraph reports capture-required, run \`kgraph "<topic>" --capture "<durable conclusion>" --capture-file <path> --capture-symbol <name> --agent claude-code\`, or explicitly say "No durable knowledge created" only when there is genuinely no reusable knowledge.
+${numberedWorkflow('claude-code')}
 `,
         },
         {

package/dist/integrations/adapters/copilot.js

@@ -8,6 +8,19 @@ export const copilotAdapter = {
 
 ${numberedWorkflow('copilot')}
 `,
-    commandFiles: agentSkillFiles('copilot'),
+    commandFiles: [
+        ...agentSkillFiles('copilot'),
+        {
+            path: '.github/agents/kgraph.agent.md',
+            content: `---
+description: Use KGraph persistent repo intelligence — runs kgraph before answering to provide file maps, symbols, relationships, and durable knowledge atoms.
+---
+
+## KGraph Workflow
+
+${numberedWorkflow('copilot')}
+`,
+        },
+    ],
     obsoleteCommandFiles: [],
 };

package/dist/integrations/workflow-steps.js

@@ -8,8 +8,11 @@ const REPAIR_STEP = `Run \`kgraph repair --dry-run\` before cleanup when stale/n
 const COMPACT_STEP = `Run \`kgraph compact --dry-run\` when cognition looks duplicated, noisy, or stale. Run \`kgraph compact\` only when the user asks to merge/archive cognition.`;
 const HISTORY_STEP = `Run \`kgraph history\` or \`kgraph history "<topic>"\` to review past cognition sessions with git author attribution.`;
 const KNOWLEDGE_STEP = `Run \`kgraph knowledge list --topic "<topic>"\` or \`kgraph knowledge get <atom-id>\` when the user asks what KGraph remembers or atom provenance/lifecycle matters.`;
+function inboxStep(agentName) {
+    return `If the previous command output contains "pending inbox" or a \`pendingInbox\` field with count > 0, you MUST run \`kgraph "<topic>" --agent ${agentName}\` or \`kgraph update\` immediately before proceeding. Do not skip this step.`;
+}
 function packStep(agentName) {
-    return `For normal coding context, treat \`kgraph pack "<task>" --budget 8000 --json --agent ${agentName}\` as the machine-readable context contract: use atoms, source ranges, git changes, omitted items, and inclusion reasons from the ContextPack before reading files. If the pack reports pending inbox notes, run \`kgraph "<topic>" --agent ${agentName}\` or \`kgraph update\` before relying on history or newly captured atoms.`;
+    return `For normal coding context, treat \`kgraph pack "<task>" --budget 8000 --json --agent ${agentName}\` as the machine-readable context contract: use atoms, source ranges, git changes, omitted items, and inclusion reasons from the ContextPack before reading files.`;
 }
 function smartRootStep(agentName) {
     return `Use the root workflow when refresh or memory processing matters: run \`kgraph "<topic>" --agent ${agentName}\` to refresh maps, process inbox notes, and return a briefing; run \`kgraph "<topic>" --final --agent ${agentName}\` before the final answer when repository files changed; run \`kgraph "<topic>" --capture "<durable conclusion>" --capture-file <path> --capture-symbol <name> --agent ${agentName}\` when the final check requires durable knowledge.`;
@@ -29,24 +32,25 @@ function sessionStep(agentName, qualifier) {
 export function numberedWorkflow(agentName, options = {}) {
     return `1. Infer the topic from the user's request.
 2. {{KGRAPH_CONTEXT_POLICY}}
-3. ${ROUTING_STEP}
-4. Use the returned files, symbols, relationships, and cognition before broad exploration.
-5. ${EXPLORATION_BOUNDARY_STEP}
-6. ${VERIFY_EDIT_STEP}
-7. ${smartRootStep(agentName)}
-8. ${packStep(agentName)}
-9. ${KNOWLEDGE_STEP}
-10. ${DOCTOR_STEP}
-11. ${STALE_STEP}
-12. ${sessionStep(agentName, options.sessionQualifier)}
-13. ${IMPACT_STEP}
+3. ${inboxStep(agentName)}
+4. ${ROUTING_STEP}
+5. Use the returned files, symbols, relationships, and cognition before broad exploration.
+6. ${EXPLORATION_BOUNDARY_STEP}
+7. ${VERIFY_EDIT_STEP}
+8. ${smartRootStep(agentName)}
+9. ${packStep(agentName)}
+10. ${KNOWLEDGE_STEP}
+11. ${DOCTOR_STEP}
+12. ${STALE_STEP}
+13. ${sessionStep(agentName, options.sessionQualifier)}
+14. ${IMPACT_STEP}
 
 {{KGRAPH_CAPTURE_POLICY}}
 
-14. ${REPAIR_STEP}
-15. ${COMPACT_STEP}
-16. Run \`kgraph visualize\` when the user wants to inspect the dependency graph — opens an interactive graph at http://localhost:4242 with PNG export.
-17. ${HISTORY_STEP}`;
+15. ${REPAIR_STEP}
+16. ${COMPACT_STEP}
+17. Run \`kgraph visualize\` when the user wants to inspect the dependency graph — opens an interactive graph at http://localhost:4242 with PNG export.
+18. ${HISTORY_STEP}`;
 }
 /**
  * Returns the bullet-list workflow for rules files.
@@ -54,6 +58,7 @@ export function numberedWorkflow(agentName, options = {}) {
  */
 export function bulletWorkflow(agentName, options = {}) {
     return `- {{KGRAPH_CONTEXT_POLICY}}
+- ${inboxStep(agentName)}
 - ${ROUTING_STEP}
 - ${EXPLORATION_BOUNDARY_STEP}
 - ${VERIFY_EDIT_STEP}

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.29",
+  "version": "0.2.31",
   "description": "Persistent repo intelligence for AI coding assistants.",
   "type": "module",
   "bin": {