@kentwynn/kgraph 0.2.12 → 0.2.14

package/README.md

@@ -308,13 +308,13 @@ KGraph integrations are local files. They do not start background agents, call A
 
 ```bash
 kgraph integrate add codex copilot cursor claude-code gemini windsurf cline
-kgraph integrate add copilot --mode always
+kgraph integrate add copilot --mode smart
 kgraph integrate set copilot --mode manual
 kgraph integrate list
 kgraph integrate remove cursor
 ```
 
-New integrations default to `smart` mode. Use `--mode always` to force KGraph on every chat, or `--mode manual` to run only when explicitly asked.
+New integrations default to `always` mode, so every chat in the repository starts with `kgraph "<topic>"`. Use `--mode smart` to run KGraph only for repo-specific work, or `--mode manual` to run only when explicitly asked.
 
 | Mode     | Behavior                                                                                                                                                                                                |
 | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

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

@@ -15,7 +15,7 @@ export function registerInitCommand(program) {
         .description('Initialize a .kgraph workspace')
         .option('--integration <name>', 'Configure an AI tool integration', collectOption, [])
         .option('--integrations <names>', 'Configure comma-separated AI tool integrations')
-        .option('--mode <mode>', 'Integration mode: always, smart, manual, or off', 'smart')
+        .option('--mode <mode>', 'Integration mode: always, smart, manual, or off', 'always')
         .action((options) => runCommand(async () => {
         const workspace = await ensureWorkspace(process.cwd());
         await ensureKnowledgeStore(workspace);
@@ -55,7 +55,7 @@ export function registerInitCommand(program) {
         })) {
             const selected = await promptForInitIntegrations(recommendedIntegrations);
             if (selected.length > 0) {
-                const changed = await addIntegrations(workspace, selected, 'smart');
+                const changed = await addIntegrations(workspace, selected, 'always');
                 console.log(`Configured integrations: ${changed.map((item) => `${item.name}:${item.mode}`).join(', ')}`);
                 config = await loadConfig(workspace);
                 recommendedIntegrations = recommendedIntegrationsForInit({

package/dist/cli/commands/integrate.js

@@ -25,7 +25,7 @@ export function registerIntegrateCommand(program) {
         .command('add')
         .description('Add AI tool integrations')
         .argument('<names...>')
-        .option('--mode <mode>', 'always, smart, manual, or off', 'smart')
+        .option('--mode <mode>', 'always, smart, manual, or off', 'always')
         .action((names, options) => runCommand(async () => {
         const workspace = await assertWorkspace(process.cwd());
         const normalized = normalizeIntegrationNames(names);

package/dist/cli/commands/uninstall.js

@@ -1,8 +1,13 @@
 import { rm } from 'node:fs/promises';
+import path from 'node:path';
 import { loadConfig } from '../../config/config.js';
 import { removeIntegrations } from '../../integrations/integration-store.js';
 import { pathExists, resolveWorkspace } from '../../storage/kgraph-paths.js';
 import { runCommand } from '../errors.js';
+const LEGACY_GENERATED_FILES = [
+    '.github/agents/kgraph.agent.md',
+    '.github/kgraph.agent.md',
+];
 export function registerUninstallCommand(program) {
     program
         .command('uninstall')
@@ -28,6 +33,7 @@ export function registerUninstallCommand(program) {
             !options.keepIntegrations &&
             configuredIntegrations.length > 0) {
             await removeIntegrations(workspace, configuredIntegrations);
+            await removeLegacyGeneratedFiles(workspace.rootPath);
         }
         if (initialized) {
             await rm(workspace.kgraphPath, { recursive: true, force: true });
@@ -37,6 +43,9 @@ export function registerUninstallCommand(program) {
         console.log('Run `kgraph init` to set up this repository again.');
     }));
 }
+async function removeLegacyGeneratedFiles(rootPath) {
+    await Promise.all(LEGACY_GENERATED_FILES.map((filePath) => rm(path.join(rootPath, filePath), { force: true })));
+}
 function printUninstallPreview(input) {
     console.log('KGraph Uninstall Preview');
     console.log('');

package/dist/cli/help.js

@@ -50,8 +50,8 @@ export function renderRootHelp(useColor = supportsColor()) {
         '',
         theme.bold('Integrations'),
         command('integrate list', 'Show configured AI tool integrations'),
-        command('integrate add gemini windsurf cline', 'Write KGraph instructions using smart mode by default'),
-        command('integrate add copilot --mode always', 'Every Copilot chat starts with kgraph "<topic>"'),
+        command('integrate add gemini windsurf cline', 'Write KGraph instructions using always mode by default'),
+        command('integrate add copilot --mode smart', 'Run KGraph for repo-specific Copilot work only'),
         command('integrate set copilot --mode manual', 'Only run KGraph when explicitly requested'),
         command('integrate remove cursor', 'Remove KGraph-managed instruction blocks'),
         command('--mode smart|always|manual|off', 'Control automatic KGraph involvement per integration'),

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

@@ -157,7 +157,7 @@ function normalizeIntegrations(value) {
     return integrations;
 }
 function normalizeIntegrationMode(value) {
-    return value === 'always' || value === 'manual' || value === 'off'
+    return value === 'smart' || value === 'manual' || value === 'off'
         ? value
-        : 'smart';
+        : 'always';
 }

package/dist/context/context-pack.js

@@ -48,10 +48,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 +70,29 @@ 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 += 40;
+    if (item.kind === 'git-change')
+        score += 35;
+    if (item.kind === 'symbol')
+        score += 25;
+    if (item.kind === 'file')
+        score += 15;
+    if (item.kind === 'relationship')
+        score += 5;
+    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;
+}

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/integrations/adapters/claude-code.js

@@ -1,4 +1,3 @@
-import { numberedWorkflow } from '../workflow-steps.js';
 export const claudeCodeAdapter = {
     name: 'claude-code',
     label: 'Claude Code',
@@ -6,13 +5,22 @@ export const claudeCodeAdapter = {
     instructions: `## KGraph Workflow
 
 {{KGRAPH_CONTEXT_POLICY}} Use /kgraph for the full automated workflow. Run \`kgraph pack "<task>" --budget 8000 --json\` for a machine-readable token-budgeted context pack, \`kgraph knowledge list\` or \`kgraph knowledge get <atom-id>\` to inspect durable atoms, \`kgraph stale\` and \`kgraph blame <atom-id>\` when lifecycle/provenance matters, \`kgraph conclude\` for durable typed engineering memory, and \`kgraph compact --dry-run\` when cognition looks duplicated or stale. Run \`kgraph doctor\` when setup or generated maps look wrong. Run \`kgraph scan\`, \`kgraph update\`, and \`kgraph context\` manually only when you need one specific step.
+
+{{KGRAPH_CAPTURE_POLICY}}
 `,
     commandFiles: [
         {
             path: '.claude/commands/kgraph.md',
-            content: `Use KGraph persistent repo intelligence for the current request.
+            content: `Use KGraph persistent repo intelligence through the single normal \`kgraph "<topic>"\` entry point.
 
-${numberedWorkflow('claude-code', { sessionQualifier: 'when native hooks are unavailable' })}
+1. Infer a concise topic from the user's request.
+2. Run exactly one command from the repository root: \`kgraph "<topic>"\`.
+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, store durable engineering memory with \`kgraph conclude "<topic>" --type <finding|decision|gotcha|summary|relationship> --confidence <high|medium|low>\` only when the work created reusable engineering knowledge.
 `,
         },
         {

package/dist/integrations/adapters/copilot.js

@@ -8,26 +8,6 @@ export const copilotAdapter = {
 ${numberedWorkflow('copilot')}
 `,
     commandFiles: [
-        {
-            path: '.github/agents/kgraph.agent.md',
-            content: `---
-name: kgraph
-description: Use KGraph persistent repo intelligence to answer questions about this codebase. Runs kgraph context, pack, knowledge, stale, blame, scan, update, conclude, compact, impact, history, and session commands to ground responses in durable local knowledge.
-tools:
-  - run_in_terminal
-  - read_file
-  - file_search
-  - grep_search
-  - semantic_search
----
-
-## KGraph Agent
-
-You are a KGraph-powered agent. Before exploring the repository freely, always:
-
-${numberedWorkflow('copilot')}
-`,
-        },
         {
             path: '.github/prompts/kgraph-doctor.prompt.md',
             content: `---

package/dist/integrations/instruction-blocks.js

@@ -36,16 +36,17 @@ export function applyContextPolicy(content, mode) {
         .replaceAll(KGRAPH_CAPTURE_POLICY_PLACEHOLDER, renderCapturePolicy());
 }
 export function renderContextPolicy(mode) {
+    const useResultBoundary = 'Use the returned KGraph candidate files as the first-pass source of truth. Do not rerun the same KGraph query just to tail or reformat output, do not continue broad repository search after the target file is identified, do not retry malformed shell commands with broader variants, and do not run broad `find`, recursive `grep`, or repeated full-file dumps after KGraph has narrowed the target.';
     switch (mode) {
         case 'always':
-            return 'Every chat in this repository must start by running `kgraph "<topic>"` before answering or exploring files. Infer the topic from the user\'s message; no exceptions, including simple or conversational requests.';
+            return `Every chat in this repository must start by running \`kgraph "<topic>"\` before answering or exploring files. Infer the topic from the user's message; no exceptions, including simple or conversational requests. ${useResultBoundary}`;
         case 'manual':
             return 'Do not run KGraph automatically. Run `kgraph "<topic>"` only when the user explicitly asks for KGraph context or invokes the KGraph command.';
         case 'off':
             return 'KGraph is disabled for this integration.';
         case 'smart':
         default:
-            return 'For repo-specific coding, debugging, architecture, refactor, review, or file-exploration requests, run `kgraph "<topic>"` before broad repository exploration. Infer the topic from the user\'s message. Skip KGraph for simple conversational requests that do not depend on repo knowledge.';
+            return `For repo-specific coding, debugging, architecture, refactor, review, or file-exploration requests, run \`kgraph "<topic>"\` before broad repository exploration. Infer the topic from the user's message. Skip KGraph for simple conversational requests that do not depend on repo knowledge. ${useResultBoundary}`;
     }
 }
 export function renderCapturePolicy() {

package/dist/integrations/integration-store.js

@@ -15,7 +15,7 @@ export async function listIntegrations(workspace) {
     })));
     return statuses.sort((left, right) => left.name.localeCompare(right.name));
 }
-export async function addIntegrations(workspace, names, mode = 'smart') {
+export async function addIntegrations(workspace, names, mode = 'always') {
     const config = await loadConfig(workspace);
     const byName = new Map(config.integrations.map((integration) => [integration.name, integration]));
     const changed = [];

package/dist/integrations/workflow-steps.js

@@ -10,6 +10,8 @@ const HISTORY_STEP = `Run \`kgraph history\` or \`kgraph history "<topic>"\` to
 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.`;
 const PACK_STEP = `Run \`kgraph pack "<task>" --budget 8000 --json\` when an agent needs a machine-readable, token-budgeted context pack instead of human Markdown context.`;
 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.`;
 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}.`;
@@ -22,19 +24,21 @@ export function numberedWorkflow(agentName, options = {}) {
     return `1. Infer the topic from the user's request.
 2. {{KGRAPH_CONTEXT_POLICY}}
 3. Use the returned files, symbols, relationships, and cognition before broad exploration.
-4. ${PACK_STEP}
-5. ${KNOWLEDGE_STEP}
-6. ${DOCTOR_STEP}
-7. ${STALE_STEP}
-8. ${sessionStep(agentName, options.sessionQualifier)}
-9. ${IMPACT_STEP}
+4. ${EXPLORATION_BOUNDARY_STEP}
+5. ${VERIFY_EDIT_STEP}
+6. ${PACK_STEP}
+7. ${KNOWLEDGE_STEP}
+8. ${DOCTOR_STEP}
+9. ${STALE_STEP}
+10. ${sessionStep(agentName, options.sessionQualifier)}
+11. ${IMPACT_STEP}
 
 {{KGRAPH_CAPTURE_POLICY}}
 
-10. ${REPAIR_STEP}
-11. ${COMPACT_STEP}
-12. Run \`kgraph visualize\` when the user wants to inspect the dependency graph — opens an interactive graph at http://localhost:4242 with PNG export.
-13. ${HISTORY_STEP}`;
+12. ${REPAIR_STEP}
+13. ${COMPACT_STEP}
+14. Run \`kgraph visualize\` when the user wants to inspect the dependency graph — opens an interactive graph at http://localhost:4242 with PNG export.
+15. ${HISTORY_STEP}`;
 }
 /**
  * Returns the bullet-list workflow for rules files.
@@ -42,6 +46,8 @@ export function numberedWorkflow(agentName, options = {}) {
  */
 export function bulletWorkflow(agentName, options = {}) {
     return `- {{KGRAPH_CONTEXT_POLICY}}
+- ${EXPLORATION_BOUNDARY_STEP}
+- ${VERIFY_EDIT_STEP}
 - ${PACK_STEP}
 - ${KNOWLEDGE_STEP}
 - ${DOCTOR_STEP}

package/package.json

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