@kentwynn/kgraph 0.1.13 → 0.1.15

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

@@ -1,10 +1,10 @@
-import type { KGraphWorkspace } from "../types/config.js";
-import type { CognitionNote, ReferenceStatus } from "../types/cognition.js";
-import type { ScanResult } from "../types/maps.js";
+import type { CognitionNote, ReferenceStatus } from '../types/cognition.js';
+import type { KGraphWorkspace } from '../types/config.js';
+import type { ScanResult } from '../types/maps.js';
 export interface UpdateResult {
     processed: CognitionNote[];
     warnings: string[];
 }
-export declare function updateCognition(workspace: KGraphWorkspace, currentMaps: Pick<ScanResult, "files" | "symbols">, dryRun?: boolean): Promise<UpdateResult>;
-export declare function refreshCognitionReferenceStatuses(workspace: KGraphWorkspace, currentMaps: Pick<ScanResult, "files" | "symbols">): Promise<void>;
-export declare function evaluateReferenceStatus(relatedFiles: string[], relatedSymbols: string[], currentMaps: Pick<ScanResult, "files" | "symbols">): ReferenceStatus;
+export declare function updateCognition(workspace: KGraphWorkspace, currentMaps: Pick<ScanResult, 'files' | 'symbols'>, dryRun?: boolean): Promise<UpdateResult>;
+export declare function refreshCognitionReferenceStatuses(workspace: KGraphWorkspace, currentMaps: Pick<ScanResult, 'files' | 'symbols'>): Promise<void>;
+export declare function evaluateReferenceStatus(relatedFiles: string[], relatedSymbols: string[], currentMaps: Pick<ScanResult, 'files' | 'symbols'>): ReferenceStatus;

package/dist/cognition/cognition-updater.js

@@ -1,25 +1,31 @@
-import { readFile } from "node:fs/promises";
-import path from "node:path";
-import { parseMarkdownNote } from "./markdown-note-parser.js";
-import { archiveInboxNote, readCognitionNotes, listInboxNotes, slugify, writeCognitionNote, writeDomainRecord } from "../storage/cognition-store.js";
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { archiveInboxNote, listInboxNotes, readCognitionNotes, slugify, writeCognitionNote, writeDomainRecord, } from '../storage/cognition-store.js';
+import { parseMarkdownNote } from './markdown-note-parser.js';
 export async function updateCognition(workspace, currentMaps, dryRun = false) {
     const inboxNotes = await listInboxNotes(workspace);
     const processed = [];
     const warnings = [];
     for (const inboxPath of inboxNotes) {
         try {
-            const raw = await readFile(inboxPath, "utf8");
+            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")}`;
+            const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+            const id = `${timestamp}-${slugify(parsed.title) || path.basename(inboxPath, '.md')}`;
             const archivedPath = path.join(workspace.processedInteractionsPath, `${timestamp}-${path.basename(inboxPath)}`);
             const note = {
                 ...parsed,
                 id,
-                sourceInboxPath: path.relative(workspace.rootPath, inboxPath).split(path.sep).join("/"),
-                processedPath: path.relative(workspace.rootPath, archivedPath).split(path.sep).join("/"),
+                sourceInboxPath: path
+                    .relative(workspace.rootPath, inboxPath)
+                    .split(path.sep)
+                    .join('/'),
+                processedPath: path
+                    .relative(workspace.rootPath, archivedPath)
+                    .split(path.sep)
+                    .join('/'),
                 createdAt: new Date().toISOString(),
-                referencesStatus: evaluateReferenceStatus(parsed.relatedFiles, parsed.relatedSymbols, currentMaps)
+                referencesStatus: evaluateReferenceStatus(parsed.relatedFiles, parsed.relatedSymbols, currentMaps),
             };
             processed.push(note);
             warnings.push(...parsed.warnings.map((warning) => `${path.basename(inboxPath)}: ${warning}`));
@@ -38,9 +44,28 @@ export async function updateCognition(workspace, currentMaps, dryRun = false) {
 export async function refreshCognitionReferenceStatuses(workspace, currentMaps) {
     const notes = await readCognitionNotes(workspace);
     for (const note of notes) {
-        const nextStatus = evaluateReferenceStatus(note.relatedFiles, note.relatedSymbols, currentMaps);
-        if (nextStatus !== note.referencesStatus) {
-            await writeCognitionNote(workspace, { ...note, referencesStatus: nextStatus });
+        // Re-parse relatedSymbols from the archived raw markdown if available.
+        // This migrates old notes that were parsed with the old plain-text heuristic
+        // (which produced false positives like JWT, CSRF, TODO) to the current
+        // backtick-only logic.
+        let relatedSymbols = note.relatedSymbols;
+        if (note.processedPath) {
+            try {
+                const raw = await readFile(path.join(workspace.rootPath, note.processedPath), 'utf8');
+                relatedSymbols = parseMarkdownNote(raw).relatedSymbols;
+            }
+            catch {
+                // archived file missing — keep stored symbols
+            }
+        }
+        const nextStatus = evaluateReferenceStatus(note.relatedFiles, relatedSymbols, currentMaps);
+        if (nextStatus !== note.referencesStatus ||
+            relatedSymbols !== note.relatedSymbols) {
+            await writeCognitionNote(workspace, {
+                ...note,
+                relatedSymbols,
+                referencesStatus: nextStatus,
+            });
         }
     }
 }
@@ -49,21 +74,21 @@ export function evaluateReferenceStatus(relatedFiles, relatedSymbols, currentMap
     const symbolNames = new Set(currentMaps.symbols.map((symbol) => symbol.name));
     const references = [
         ...relatedFiles.map((file) => filePaths.has(file)),
-        ...relatedSymbols.map((symbol) => symbolNames.has(symbol))
+        ...relatedSymbols.map((symbol) => symbolNames.has(symbol)),
     ];
     if (references.length === 0) {
-        return "unresolved";
+        return 'unresolved';
     }
     if (references.every(Boolean)) {
-        return "current";
+        return 'current';
     }
     if (references.every((value) => !value)) {
-        return "stale";
+        return 'stale';
     }
-    return "mixed";
+    return 'mixed';
 }
 function toDomainRecord(note, currentMaps) {
-    const name = note.domain ?? "general";
+    const name = note.domain ?? 'general';
     const fileSet = new Set(currentMaps.files.map((file) => file.path));
     const symbolSet = new Set(currentMaps.symbols.map((symbol) => symbol.name));
     return {
@@ -72,6 +97,6 @@ function toDomainRecord(note, currentMaps) {
         tags: note.tags,
         files: note.relatedFiles.filter((file) => fileSet.has(file)),
         symbols: note.relatedSymbols.filter((symbol) => symbolSet.has(symbol)),
-        cognitionNotes: [note.id]
+        cognitionNotes: [note.id],
     };
 }

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

@@ -14,7 +14,7 @@ export function parseMarkdownNote(markdown) {
         summary: sections.Summary,
         sections,
         relatedFiles: unique(extractMatches(combined, PATH_REF)),
-        relatedSymbols: unique(extractSymbolRefs(combined)),
+        relatedSymbols: unique(extractSymbolRefs(sections)),
         warnings,
     };
 }
@@ -59,23 +59,12 @@ function parseSections(body) {
 function extractMatches(text, regex) {
     return [...text.matchAll(regex)].map((match) => match[1]);
 }
-function extractSymbolRefs(text) {
-    const stopwords = new Set([
-        'Summary',
-        'Related',
-        'Files',
-        'Functions',
-        'Decisions',
-        'Debugging',
-        'Conclusions',
-    ]);
-    // Backtick-quoted: accept any identifier in backticks
-    const backtickSymbols = [...text.matchAll(/`([A-Za-z_$][\w$]{2,})`/g)].map((m) => m[1]);
-    // Plain text: only camelCase, PascalCase, ALL_CAPS, or snake_case (must contain uppercase or underscore after first char)
-    const plainSymbols = [...text.matchAll(/\b([A-Za-z_$][\w$]{2,})\b/g)]
-        .map((m) => m[1])
-        .filter((item) => /[A-Z_]/.test(item.slice(1)));
-    return unique([...backtickSymbols, ...plainSymbols].filter((item) => !stopwords.has(item) && !item.includes('.')));
+function extractSymbolRefs(sections) {
+    // Prefer declared symbols in the Key Symbols section; fall back to backtick
+    // items across all sections. Never use plain-text heuristics — they produce
+    // false positives for domain vocabulary like JWT, CSRF, TODO, Next, etc.
+    const text = sections['Key Symbols'] ?? Object.values(sections).join('\n');
+    return [...text.matchAll(/`([A-Za-z_$][\w$]{2,})`/g)].map((m) => m[1]);
 }
 function unique(items) {
     return [...new Set(items)];

package/dist/integrations/adapters/claude-code.js

@@ -14,7 +14,7 @@ Before exploring the repository, run \`kgraph context "<topic>"\` to load existi
 1. Infer the topic from the user's request.
 2. Run \`kgraph context "<topic>"\`.
 3. Use the returned files, symbols, relationships, and cognition before broad exploration.
-4. **After completing the work**, always write a Markdown note to \`.kgraph/inbox/<slug>.md\` capturing what was built or changed, which files and symbols were touched, and any decisions made. Then immediately run \`kgraph update\`.
+4. **After completing the work**, write a Markdown note to \`.kgraph/inbox/<slug>.md\` **only if** you discovered something a future session would need to re-derive — a gotcha, constraint, non-obvious decision, or bug. Skip capture for read-only reviews or sessions where nothing new was found. When you do capture, immediately run \`kgraph update\`.
 5. If you created, moved, deleted, or renamed files or symbols during this session, run \`kgraph scan\` and report the summary. Skip it otherwise.
 6. Run \`kgraph visualize\` when the user wants to inspect the dependency graph — opens an interactive graph at http://localhost:4242 with PNG export.
 7. Run \`kgraph history\` to review the timeline of past cognition sessions with git author attribution.

package/dist/integrations/adapters/codex.js

@@ -21,7 +21,7 @@ Workflow:
 1. Infer the current topic from the user request.
 2. Run \`kgraph context "<topic>"\` before broad repo exploration.
 3. Use KGraph's returned files, symbols, relationships, and cognition as navigation hints.
-4. **After completing the work**, always write a Markdown note to \`.kgraph/inbox/<slug>.md\` capturing what was built or changed, which files and symbols were touched, and any decisions made. Then immediately run \`kgraph update\`.
+4. **After completing the work**, write a Markdown note to \`.kgraph/inbox/<slug>.md\` **only if** you discovered something a future session would need to re-derive — a gotcha, constraint, non-obvious decision, or bug. Skip capture for read-only reviews or sessions where nothing new was found. When you do capture, immediately run \`kgraph update\`.
 5. If you created, moved, deleted, or renamed files or symbols during this session, run \`kgraph scan\`. Skip it otherwise.
 6. Run \`kgraph visualize\` when the user wants to inspect the dependency graph — opens an interactive graph at http://localhost:4242 with PNG export.
 7. Run \`kgraph history\` to review the timeline of past cognition sessions with git author attribution.

package/dist/integrations/adapters/copilot.js

@@ -5,7 +5,7 @@ export const copilotAdapter = {
     instructions: `## KGraph Workflow
 
 1. **Before exploring the repository**, run \`kgraph context "<topic>"\` to load existing repo intelligence. Use the returned files, symbols, and cognition before any broad exploration.
-2. **After every meaningful implementation or discovery session**, write a Markdown note to \`.kgraph/inbox/<slug>.md\` capturing what was built, which files were touched, which symbols matter, and any decisions made. Then immediately run \`kgraph update\`.
+2. **After completing work**, write a Markdown note to \`.kgraph/inbox/<slug>.md\` **only if** you discovered something a future session would need to re-derive — a gotcha, architectural constraint, non-obvious decision, or bug. For routine or read-only sessions where nothing new was found, skip capture entirely. When you do capture, immediately run \`kgraph update\`.
 3. If you created, moved, deleted, or renamed files or symbols, run \`kgraph scan\`.
 
 The inbox note must use this structure:

package/dist/integrations/adapters/cursor.js

@@ -10,7 +10,7 @@ alwaysApply: true
 ## KGraph Workflow
 
 - **Before exploring the repository**, run \`kgraph context "<topic>"\` to load existing repo intelligence. Use the returned files, symbols, and cognition before any broad exploration.
-- **After every meaningful implementation or discovery session**, write a Markdown note to \`.kgraph/inbox/<slug>.md\` (title, Key Files, Key Symbols, Decisions sections) and immediately run \`kgraph update\`.
+- **After completing work**, write a Markdown note to \`.kgraph/inbox/<slug>.md\` (title, Key Files, Key Symbols, Decisions sections) **only if** you discovered something a future session would need to re-derive — a gotcha, constraint, non-obvious decision, or bug. Skip capture for read-only reviews or sessions where nothing new was found. When you do capture, immediately run \`kgraph update\`.
 - If you created, moved, deleted, or renamed files or symbols, run \`kgraph scan\`.
 - Run \`kgraph visualize\` to open the interactive dependency graph at http://localhost:4242 with PNG export.
 - Run \`kgraph history\` to review the timeline of past cognition sessions with git author attribution.

package/package.json

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