@kentwynn/kgraph 0.2.30 → 0.2.32

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/cli/commands/workflow.js

@@ -3,8 +3,8 @@ import { concludeTopic } from '../../cognition/conclusion.js';
 import { loadConfig } from '../../config/config.js';
 import { queryContext } from '../../context/context-query.js';
 import { refreshKnowledgeAtomStatuses } from '../../knowledge/atom-store.js';
-import { getWorkingTreeChanges } from '../../scanner/git-utils.js';
 import { shouldExclude } from '../../scanner/file-classifier.js';
+import { getWorkingTreeChanges } from '../../scanner/git-utils.js';
 import { scanRepository } from '../../scanner/repo-scanner.js';
 import { assertSessionAgent, recordSessionEvent, } from '../../session/session-store.js';
 import { listInboxNotes } from '../../storage/cognition-store.js';
@@ -104,8 +104,7 @@ export async function runDefaultWorkflow(query, options = {}) {
                 atomsProcessed: update.processed.length,
                 pendingInbox: pendingInbox.length,
                 activeAtoms: activeAtoms.length,
-                needsReviewAtoms: atoms.filter((atom) => atom.status === 'needs-review')
-                    .length,
+                needsReviewAtoms: atoms.filter((atom) => atom.status === 'needs-review').length,
                 staleAtoms: atoms.filter((atom) => atom.status === 'stale').length,
                 highConfidenceMissingEvidence: activeAtoms.filter((atom) => atom.confidence === 'high' && atom.evidenceRefs.length === 0).length,
                 captureRequired: captureCheck.required,
@@ -250,17 +249,33 @@ function meaningfulTopicOverlap(a, b) {
     const weakTokens = new Set([
         'add',
         'after',
+        'and',
         'behavior',
         'change',
         'changed',
+        'check',
+        'code',
+        'current',
+        'file',
+        'fix',
+        'for',
+        'from',
+        'get',
+        'into',
         'new',
+        'not',
         'old',
         'review',
-        'check',
-        'current',
+        'run',
         'session',
+        'set',
         'smoke',
+        'test',
+        'that',
+        'the',
+        'this',
         'update',
+        'use',
         'with',
     ]);
     const aTokens = new Set(a
@@ -277,12 +292,14 @@ function tokenOverlap(a, b) {
     const aTokens = new Set(a
         .toLowerCase()
         .split(/[^a-z0-9]+/)
-        .filter(Boolean));
-    return b
+        .filter((token) => token.length >= 4));
+    if (aTokens.size === 0)
+        return false;
+    const matches = b
         .toLowerCase()
         .split(/[^a-z0-9]+/)
-        .filter(Boolean)
-        .some((token) => aTokens.has(token));
+        .filter((token) => token.length >= 4 && aTokens.has(token));
+    return matches.length >= 2;
 }
 function matchingInvalidatedAtoms(atoms, topic) {
     const tokens = new Set((topic ?? '')

package/dist/cli/index.js

@@ -130,6 +130,8 @@ function isCliEntrypoint() {
             realpathSync(process.argv[1]));
     }
     catch {
-        return import.meta.url === `file://${process.argv[1]}`;
+        const argv1 = process.argv[1].replace(/\\/g, '/');
+        return (import.meta.url === `file://${argv1}` ||
+            import.meta.url === `file:///${argv1}`);
     }
 }

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/copilot.js

@@ -16,7 +16,11 @@ ${numberedWorkflow('copilot')}
 description: Use KGraph persistent repo intelligence — runs kgraph before answering to provide file maps, symbols, relationships, and durable knowledge atoms.
 ---
 
-## KGraph Workflow
+# KGraph Agent
+
+You are the KGraph agent. You use the \`kgraph\` CLI via the terminal to provide persistent repo intelligence before answering questions or making edits.
+
+## Workflow
 
 ${numberedWorkflow('copilot')}
 `,

package/dist/integrations/agent-skills.js

@@ -45,7 +45,7 @@ name: kgraph-pack
 description: Build a budget-aware KGraph context pack
 ---
 
-Run \`kgraph pack "$ARGUMENTS" --budget 8000 --json --agent $AGENT\` to build a machine-readable context pack and record lightweight session context. Summarize token use, included files, symbols, relationships, git changes, session history, atoms, and omitted items with the inclusion reasons.
+Run \`kgraph pack "<topic>" --budget 8000 --json --agent $AGENT\` to build a machine-readable context pack and record lightweight session context. Summarize token use, included files, symbols, relationships, git changes, session history, atoms, and omitted items with the inclusion reasons. When a symbol item includes an \`excerpt\` field, you already have the source — do not read that file for the symbol.
 `,
     },
     {
@@ -75,7 +75,7 @@ name: kgraph-blame
 description: Show KGraph atom provenance and evidence
 ---
 
-Run \`kgraph blame "$ARGUMENTS"\` to show who or what created a knowledge atom, the source command/session/commit, evidence refs, and lifecycle links.
+Run \`kgraph blame <atom-id>\` to show who or what created a knowledge atom, the source command/session/commit, evidence refs, and lifecycle links.
 `,
     },
     {
@@ -127,7 +127,7 @@ name: kgraph-conclude
 description: Store a typed durable KGraph engineering conclusion
 ---
 
-Prefer \`kgraph "<topic>" --capture "$ARGUMENTS" --capture-file <path> --capture-symbol <name>\` when the session produced reusable engineering knowledge. Use low-level \`kgraph conclude "$ARGUMENTS"\` only when the user explicitly asks for the conclude command. Choose one type from finding, decision, gotcha, summary, relationship, and one confidence from high, medium, low. Add file or symbol evidence whenever possible; high-confidence conclusions require evidence. Store only durable conclusions, not raw chain-of-thought, temporary reasoning, speculative exploration, or low-value observations.
+Prefer \`kgraph "<topic>" --capture "<durable conclusion>" --capture-file <path> --capture-symbol <name>\` when the session produced reusable engineering knowledge. Use low-level \`kgraph conclude "<topic>" --note "<conclusion>"\` only when the user explicitly asks for the conclude command. Choose one type from finding, decision, gotcha, summary, relationship, and one confidence from high, medium, low. Add file or symbol evidence whenever possible; high-confidence conclusions require evidence. Store only durable conclusions, not raw chain-of-thought, temporary reasoning, speculative exploration, or low-value observations.
 `,
     },
     {
@@ -137,7 +137,7 @@ name: kgraph-impact
 description: Show KGraph change impact for a file, symbol, or topic
 ---
 
-Run \`kgraph impact "$ARGUMENTS"\` to show matched files/symbols, import users, callers, callees, related knowledge atoms, and risk hints.
+Run \`kgraph impact "<file-or-symbol>"\` to show matched files/symbols, import users, callers, callees, related knowledge atoms, and risk hints.
 `,
     },
     {
@@ -157,7 +157,7 @@ name: kgraph-history
 description: Show timeline of KGraph cognition sessions with git attribution
 ---
 
-Run \`kgraph history\` or \`kgraph history "$ARGUMENTS"\` to display processed cognition sessions. Summarize who contributed what and when. Use \`--last <n>\` to limit entries.
+Run \`kgraph history\` or \`kgraph history "<topic>"\` to display processed cognition sessions. Summarize who contributed what and when. Use \`--last <n>\` to limit entries.
 `,
     },
 ];

package/dist/integrations/instruction-blocks.js

@@ -9,7 +9,7 @@ export function upsertManagedBlock(content, integrationName, instructions) {
     if (pattern.test(content)) {
         return content.replace(pattern, block);
     }
-    return normalized ? `${block}\n\n${normalized}\n` : `${block}\n`;
+    return normalized ? `${normalized}\n\n${block}\n` : `${block}\n`;
 }
 export function removeManagedBlock(content, integrationName) {
     return (content
@@ -25,7 +25,7 @@ function renderManagedBlock(integrationName, instructions) {
     ].join('\n');
 }
 function managedBlockPattern(integrationName) {
-    return new RegExp(`${escapeRegExp(MARKER_PREFIX)} BEGIN KGRAPH ${escapeRegExp(integrationName)} ${escapeRegExp(MARKER_SUFFIX)}[\\s\\S]*?${escapeRegExp(MARKER_PREFIX)} END KGRAPH ${escapeRegExp(integrationName)} ${escapeRegExp(MARKER_SUFFIX)}\\n?`, 'm');
+    return new RegExp(`${escapeRegExp(MARKER_PREFIX)} BEGIN KGRAPH ${escapeRegExp(integrationName)} ${escapeRegExp(MARKER_SUFFIX)}[\\s\\S]*?${escapeRegExp(MARKER_PREFIX)} END KGRAPH ${escapeRegExp(integrationName)} ${escapeRegExp(MARKER_SUFFIX)}\\r?\\n?`, 'm');
 }
 function escapeRegExp(value) {
     return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');

package/dist/integrations/workflow-steps.d.ts

@@ -7,7 +7,7 @@ export interface WorkflowOptions {
     sessionQualifier?: string;
 }
 /**
- * Returns the 9-step numbered workflow for skill/agent/command files.
+ * Returns the numbered workflow for skill/agent/command files.
  * Used by: copilot (agent file), codex (skill file), claude-code (command file).
  */
 export declare function numberedWorkflow(agentName: string, options?: WorkflowOptions): string;

package/dist/integrations/workflow-steps.js

@@ -8,49 +8,41 @@ 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.`;
-}
+const STALE_STEP = `Run \`kgraph stale\` when changed or deleted code may have invalidated durable knowledge. Run \`kgraph blame <atom-id>\` when provenance or evidence for a memory matters.`;
+const EXPLORATION_BOUNDARY_STEP = `Keep exploration bounded by the task. For simple edits, use KGraph to identify the likely file, then read only that file or a narrow range and make the edit. Do not keep searching after the target file is found, do not retry malformed shell commands with broader variants, and do not run broad \`find\`, recursive \`grep\`, or repeated full-file dumps after KGraph already returned candidate files.`;
+const VERIFY_EDIT_STEP = `After editing, 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.`;
+const SCAN_STEP = `After bulk file creation, deletion, or rename (3+ files), run \`kgraph scan\` before the next \`kgraph pack\` so maps stay accurate.`;
 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.`;
 }
-const STALE_STEP = `Run \`kgraph stale\` when changed or deleted code may have invalidated durable knowledge. Run \`kgraph blame <atom-id>\` when provenance or evidence for a memory matters.`;
-const EXPLORATION_BOUNDARY_STEP = `Keep exploration bounded by the task. For simple edits, use KGraph to identify the likely file, then read only that file or a narrow range and make the edit. Do not keep searching after the target file is found, do not retry malformed shell commands with broader variants, and do not run broad \`find\`, recursive \`grep\`, or repeated full-file dumps after KGraph already returned candidate files. Use \`rg --files\` and quoted paths when a path must be located.`;
-const VERIFY_EDIT_STEP = `After editing, 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.`;
-const ROUTING_STEP = `Route explicit KGraph requests to the matching command before any default context lookup: history/prior work -> \`kgraph history "<topic>"\`; inbox/pending capture/process notes/update cognition -> \`kgraph "<topic>"\` or \`kgraph update\`; remembered knowledge/atoms/provenance -> \`kgraph knowledge list --topic "<topic>"\` or \`kgraph knowledge get <atom-id>\`; setup/health -> \`kgraph doctor\`.`;
 function sessionStep(agentName, qualifier) {
     const base = `Track meaningful session activity with \`kgraph session start --agent ${agentName}\`, \`kgraph session read <path> --agent ${agentName}\`, \`kgraph session write <path> --agent ${agentName}\`, and \`kgraph session end --agent ${agentName} --conclude --topic "<topic>"\` when durable session memory is useful`;
     return qualifier ? `${base} ${qualifier}.` : `${base}.`;
 }
 /**
- * Returns the 9-step numbered workflow for skill/agent/command files.
+ * Returns the numbered workflow for skill/agent/command files.
  * Used by: copilot (agent file), codex (skill file), claude-code (command file).
  */
 export function numberedWorkflow(agentName, options = {}) {
     return `1. Infer the topic from the user's request.
 2. {{KGRAPH_CONTEXT_POLICY}}
-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}
+3. When the pack includes a symbol with an \`excerpt\` field, you already have the source code — do not read that file again for that symbol. Items in the \`omitted\` array were evaluated and excluded — do not manually search for them unless the user explicitly asks.
+4. ${EXPLORATION_BOUNDARY_STEP}
+5. ${VERIFY_EDIT_STEP}
+6. ${smartRootStep(agentName)}
+7. ${KNOWLEDGE_STEP}
+8. ${DOCTOR_STEP}
+9. ${STALE_STEP}
+10. ${SCAN_STEP}
+11. ${sessionStep(agentName, options.sessionQualifier)}
+12. ${IMPACT_STEP}
 
 {{KGRAPH_CAPTURE_POLICY}}
 
-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}`;
+13. ${REPAIR_STEP}
+14. ${COMPACT_STEP}
+15. Run \`kgraph visualize\` when the user wants to inspect the dependency graph — opens an interactive graph locally with PNG export.
+16. ${HISTORY_STEP}`;
 }
 /**
  * Returns the bullet-list workflow for rules files.
@@ -58,20 +50,19 @@ export function numberedWorkflow(agentName, options = {}) {
  */
 export function bulletWorkflow(agentName, options = {}) {
     return `- {{KGRAPH_CONTEXT_POLICY}}
-- ${inboxStep(agentName)}
-- ${ROUTING_STEP}
+- When the pack includes a symbol with an \`excerpt\` field, you already have the source code — do not read that file again for that symbol. Items in the \`omitted\` array were evaluated and excluded — do not manually search for them unless the user explicitly asks.
 - ${EXPLORATION_BOUNDARY_STEP}
 - ${VERIFY_EDIT_STEP}
 - ${smartRootStep(agentName)}
-- ${packStep(agentName)}
 - ${KNOWLEDGE_STEP}
 - ${DOCTOR_STEP}
 - ${STALE_STEP}
+- ${SCAN_STEP}
 - ${sessionStep(agentName, options.sessionQualifier)}
 - ${IMPACT_STEP}
 {{KGRAPH_CAPTURE_POLICY}}
 - ${REPAIR_STEP}
 - ${COMPACT_STEP}
-- Run \`kgraph visualize\` to open the interactive dependency graph at http://localhost:4242 with PNG export.
+- Run \`kgraph visualize\` to open the interactive dependency graph locally with PNG export.
 - ${HISTORY_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';
@@ -33,7 +33,7 @@ export async function readAtomsFile(workspace) {
 }
 export function parseAtomsJsonl(raw) {
     const atoms = [];
-    for (const [index, line] of raw.split('\n').entries()) {
+    for (const [index, line] of raw.split(/\r?\n/).entries()) {
         if (!line.trim())
             continue;
         try {
@@ -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/dist/visualization/html-template.js

@@ -1,5 +1,5 @@
 export function renderHtml(graphData, rootPath) {
-    const repoName = escAttr(rootPath.split('/').pop() ?? 'Repository');
+    const repoName = escAttr(rootPath.split(/[\\/]/).pop() ?? 'Repository');
     const { meta } = graphData;
     // Prevent </script> tag injection from embedded JSON
     const safeData = JSON.stringify(graphData).replace(/<\/script>/gi, '<\\/script>');

package/package.json

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