@kentwynn/kgraph 0.2.16 → 0.2.17

package/README.md

@@ -121,12 +121,14 @@ After useful AI work, assistants save durable runtime-capture notes into `.kgrap
 Normal agent flow is intentionally small:
 
 ```bash
-kgraph "topic"
+kgraph pack "topic" --budget 8000 --json
 # work normally
 # if repo files changed, write an inbox note before the final refresh
 kgraph
 ```
 
+`kgraph "<topic>"` remains the human-readable briefing. Agents should prefer `kgraph pack "<topic>" --budget 8000 --json` because it returns the stable `ContextPack` contract with atoms, source ranges, git changes, omitted items, token estimates, and inclusion reasons.
+
 Use `kgraph doctor` after setup and before trusting a repo's saved intelligence. It checks initialization, maps, pending inbox notes, integration targets, and actionable quality problems. Use `kgraph doctor --quality` and `kgraph repair --dry-run` when stale or noisy atom references start making context harder to trust.
 
 Agents can also report session activity so KGraph can estimate token waste:
@@ -249,7 +251,7 @@ kgraph pack "auth token refresh" --budget 8000
 kgraph pack "auth token refresh" --budget 8000 --json
 ```
 
-Build a budget-aware context pack from files, symbols, relationships, git changes, session history, and knowledge atoms. JSON output is the stable machine-readable contract for agents.
+Build a budget-aware context pack from files, source ranges, symbols, relationships, git changes, session history, and knowledge atoms. JSON output is the stable machine-readable contract for agents; text output is an Atom Core briefing for humans.
 
 ```bash
 kgraph compact --dry-run

package/dist/cli/commands/pack.d.ts

@@ -1,2 +1,4 @@
 import type { Command } from 'commander';
+import type { ContextPack } from '../../types/knowledge.js';
 export declare function registerPackCommand(program: Command): void;
+export declare function renderPackText(pack: ContextPack): string;

package/dist/cli/commands/pack.js

@@ -31,19 +31,66 @@ export function registerPackCommand(program) {
             console.log(JSON.stringify(pack, null, 2));
             return;
         }
-        console.log(`# KGraph Context Pack`);
-        console.log('');
-        console.log(`Task: ${pack.task}`);
-        console.log(`Budget: ${pack.budget}`);
-        console.log(`Used: ${pack.usedTokens}`);
-        console.log('');
-        for (const item of pack.items) {
-            console.log(`- [${item.kind}] ${item.title} (~${item.tokenEstimate} tokens)`);
-            console.log(`  because ${item.reasons.slice(0, 3).join('; ')}`);
+        console.log(renderPackText(pack));
+    }));
+}
+export function renderPackText(pack) {
+    const lines = [
+        `KGraph Pack · ${pack.task}`,
+        `local-first · budget-aware · machine contract: --json`,
+        ``,
+        `● Budget`,
+        `  used        ${pack.usedTokens} / ${pack.budget}`,
+        `  included    ${pack.items.length}`,
+        `  omitted     ${pack.omitted.length}`,
+        ``,
+    ];
+    appendGroup(lines, 'Atoms', pack.items.filter((item) => item.kind === 'atom'));
+    appendGroup(lines, 'Git Changes', pack.items.filter((item) => item.kind === 'git-change'));
+    appendGroup(lines, 'Source Ranges', pack.items.filter((item) => item.kind === 'file-range'));
+    appendGroup(lines, 'Symbols', pack.items.filter((item) => item.kind === 'symbol'));
+    appendGroup(lines, 'Files', pack.items.filter((item) => item.kind === 'file'));
+    appendGroup(lines, 'Graph', pack.items.filter((item) => item.kind === 'relationship'));
+    lines.push(`● Omitted`);
+    const omitted = pack.omitted.slice(0, 8);
+    if (omitted.length === 0) {
+        lines.push('- None');
+    }
+    else {
+        for (const item of omitted) {
+            lines.push(`  ◌ ${item.kind} ${item.title} (~${item.tokenEstimate} tokens)`);
         }
-        if (pack.omitted.length > 0) {
-            console.log('');
-            console.log(`Omitted: ${pack.omitted.length} item(s) over budget`);
+        if (pack.omitted.length > omitted.length) {
+            lines.push(`  ◌ ${pack.omitted.length - omitted.length} more omitted items`);
         }
-    }));
+    }
+    lines.push('', '● Next', '  agents should consume this command with --json for the full ContextPack contract');
+    return lines.join('\n');
+}
+function appendGroup(lines, title, items) {
+    lines.push(`● ${title}`);
+    if (items.length === 0) {
+        lines.push('- None', '');
+        return;
+    }
+    for (const item of items.slice(0, 6)) {
+        lines.push(`  ● ${item.title} (~${item.tokenEstimate} tokens)`);
+        lines.push(`    because ${formatReasons(item.reasons)}`);
+        if (item.kind === 'file-range') {
+            const data = item.data;
+            if (data.path && data.startLine != null && data.endLine != null) {
+                lines.push(`    range ${data.path}:${data.startLine}-${data.endLine}`);
+            }
+        }
+    }
+    if (items.length > 6)
+        lines.push(`  ◌ ${items.length - 6} more ${title.toLowerCase()} omitted from display`);
+    lines.push('');
+}
+function formatReasons(reasons) {
+    if (reasons.length === 0)
+        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('; ');
 }

package/dist/context/context-pack.js

@@ -53,10 +53,15 @@ export function buildContextPack(response, budget, rootPath) {
         })),
     ];
     const orderedCandidates = candidates.sort(comparePackCandidates);
+    const strongPaths = strongPackPaths(candidates);
     const items = [];
     const omitted = [];
     let usedTokens = 0;
     for (const candidate of orderedCandidates) {
+        if (isLowSignalCandidate(candidate, strongPaths)) {
+            omitted.push(candidate);
+            continue;
+        }
         if (usedTokens + candidate.tokenEstimate <= budget) {
             items.push(candidate);
             usedTokens += candidate.tokenEstimate;
@@ -102,6 +107,60 @@ function packPriority(item) {
     score -= Math.floor(item.tokenEstimate / 2000);
     return score;
 }
+function strongPackPaths(candidates) {
+    const paths = new Set();
+    for (const candidate of candidates) {
+        if (candidate.kind === 'file-range' || candidate.kind === 'git-change') {
+            const pathValue = candidatePath(candidate);
+            if (pathValue)
+                paths.add(pathValue);
+        }
+        if (candidate.kind === 'file' && hasStrongReason(candidate)) {
+            const pathValue = candidatePath(candidate);
+            if (pathValue)
+                paths.add(pathValue);
+        }
+        if (candidate.kind === 'atom') {
+            const atom = candidate.data;
+            for (const file of atom?.relatedFiles ?? [])
+                paths.add(file);
+        }
+    }
+    return paths;
+}
+function isLowSignalCandidate(candidate, strongPaths) {
+    if (strongPaths.size === 0)
+        return false;
+    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';
+}
+function hasStrongReason(candidate) {
+    return candidate.reasons.some((reason) => reason.includes('matched atom') ||
+        reason.includes('current git change') ||
+        reason.includes('changed in recent commits') ||
+        reason.includes('unstaged change') ||
+        reason.includes('staged change'));
+}
+function candidateTouchesStrongPath(candidate, strongPaths) {
+    const pathValue = candidatePath(candidate);
+    if (pathValue && strongPaths.has(pathValue))
+        return true;
+    if (candidate.kind !== 'relationship')
+        return false;
+    const relationship = candidate.data;
+    return [...strongPaths].some((strongPath) => relationship.sourceId?.includes(strongPath) ||
+        relationship.targetId?.includes(strongPath));
+}
+function candidatePath(candidate) {
+    const data = candidate.data;
+    return data?.path ?? data?.filePath;
+}
 const GENERIC_RANGE_TOKENS = new Set([
     'app',
     'code',

package/dist/integrations/instruction-blocks.js

@@ -36,17 +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.';
+    const useResultBoundary = 'Use the returned KGraph ContextPack items as the first-pass source of truth. Prefer source ranges, atoms, git changes, and inclusion reasons from the pack before broad repository search. Do not rerun the same KGraph query just to tail or reformat output, do not continue broad repository search after the target file or range 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. ${useResultBoundary}`;
+            return `Every chat in this repository must start by running \`kgraph pack "<topic>" --budget 8000 --json\` before answering or exploring files. Infer the topic from the user's message; no exceptions, including simple or conversational requests. Use \`kgraph "<topic>"\` only when a human-readable briefing is explicitly needed. ${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.';
+            return 'Do not run KGraph automatically. Run `kgraph pack "<topic>" --budget 8000 --json` only when the user explicitly asks for KGraph context, invokes KGraph, or needs a machine-readable repo-memory pack.';
         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. ${useResultBoundary}`;
+            return `For repo-specific coding, debugging, architecture, refactor, review, or file-exploration requests, run \`kgraph pack "<topic>" --budget 8000 --json\` 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. Use \`kgraph "<topic>"\` only when a human-readable briefing is explicitly needed. ${useResultBoundary}`;
     }
 }
 export function renderCapturePolicy() {
@@ -56,7 +56,7 @@ export function renderCapturePolicy() {
 - Use \`.kgraph/inbox/<slug>.md\` only when a longer structured note is clearer than a single \`kgraph conclude\` command.
 - A \`.kgraph/inbox/*.md\` note is KGraph runtime capture, not project documentation. It is allowed by this workflow unless the user explicitly says not to capture to KGraph.
 - Do not skip capture for meaningful UI text, button, link, route, styling, or small file edits. Skip capture only when no reusable repository knowledge was created.
-- Do not run KGraph repeatedly. Run it once at the start with \`kgraph "<topic>"\`. If repo files changed, write the inbox note first, then run \`kgraph\` once at the end.
+- Do not run KGraph repeatedly. Run it once at the start with \`kgraph pack "<topic>" --budget 8000 --json\` for agent-readable context. If repo files changed, write the inbox note first, then run \`kgraph\` once at the end.
 - After the final \`kgraph\` run, mention whether durable cognition was stored or processed.
 
 When using an inbox note, use this structure:

package/dist/integrations/workflow-steps.js

@@ -8,7 +8,7 @@ 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.`;
-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 PACK_STEP = `Treat \`kgraph pack "<task>" --budget 8000 --json\` as the primary agent contract: use atoms, source ranges, git changes, omitted items, and inclusion reasons from the ContextPack before reading files. Use human \`kgraph "<topic>"\` output only when the user explicitly wants a briefing.`;
 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.`;

package/package.json

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