@kentwynn/kgraph 0.2.17 → 0.2.19

package/README.md

@@ -121,13 +121,14 @@ After useful AI work, assistants save durable runtime-capture notes into `.kgrap
 Normal agent flow is intentionally small:
 
 ```bash
-kgraph pack "topic" --budget 8000 --json
+kgraph "topic"
 # work normally
-# if repo files changed, write an inbox note before the final refresh
-kgraph
+kgraph "topic" --final
+# if final check requires capture:
+kgraph "topic" --capture "durable conclusion" --capture-file path/to/file.ts --capture-symbol SymbolName
 ```
 
-`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.
+`kgraph "<topic>"` is the smart root workflow: it refreshes maps, processes capture notes, reports memory health, and returns focused context. Agents can still use `kgraph pack "<topic>" --budget 8000 --json` when they need the stable machine-readable `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.
 
@@ -163,6 +164,18 @@ kgraph "some topic"
 
 The normal command. Scans the repo, updates durable memory, and returns focused context for the topic.
 
+```bash
+kgraph "some topic" --final
+```
+
+End-of-work check. Refreshes intelligence and fails with `capture-required` when mapped repo files changed but no recent durable atom references those files.
+
+```bash
+kgraph "some topic" --capture "durable conclusion" --capture-file src/auth.ts --capture-symbol refreshSession
+```
+
+Stores durable cognition through the root workflow. Use `--capture-confidence high` only with file or symbol evidence.
+
 ```bash
 kgraph
 ```

package/dist/cli/commands/conclude.js

@@ -33,6 +33,9 @@ export function registerConcludeCommand(program) {
         console.log(`Stored ${note.kind} cognition: ${note.title}`);
         console.log(`Confidence: ${note.confidence}`);
         console.log(`Status: ${note.referencesStatus}`);
+        for (const warning of note.warnings) {
+            console.error(`Warning: ${warning}`);
+        }
     }));
 }
 export function normalizeKind(value) {

package/dist/cli/commands/session.js

@@ -89,6 +89,9 @@ export function registerSessionCommand(program) {
         if (pendingConclusion) {
             const note = await concludeTopic(workspace, pendingConclusion);
             console.log(`Stored session cognition: ${note.title}`);
+            for (const warning of note.warnings) {
+                console.error(`Warning: ${warning}`);
+            }
         }
     }));
     session

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

@@ -1 +1,11 @@
-export declare function runDefaultWorkflow(query?: string): Promise<void>;
+export interface DefaultWorkflowOptions {
+    final?: boolean;
+    capture?: string;
+    type?: string;
+    confidence?: string;
+    domain?: string;
+    tags?: string[];
+    files?: string[];
+    symbols?: string[];
+}
+export declare function runDefaultWorkflow(query?: string, options?: DefaultWorkflowOptions): Promise<void>;

package/dist/cli/commands/workflow.js

@@ -1,13 +1,18 @@
 import { refreshCognitionReferenceStatuses, updateCognition, } from '../../cognition/cognition-updater.js';
+import { concludeTopic } from '../../cognition/conclusion.js';
 import { loadConfig } from '../../config/config.js';
 import { queryContext } from '../../context/context-query.js';
+import { readKnowledgeAtoms } from '../../knowledge/atom-store.js';
+import { getWorkingTreeChanges } from '../../scanner/git-utils.js';
 import { scanRepository } from '../../scanner/repo-scanner.js';
+import { listInboxNotes } from '../../storage/cognition-store.js';
 import { assertWorkspace, pathExists, resolveWorkspace, } from '../../storage/kgraph-paths.js';
 import { readMaps, writeMaps } from '../../storage/map-store.js';
-import { runCommand } from '../errors.js';
+import { KGraphError, runCommand } from '../errors.js';
 import { renderRootHelp, renderWorkflowBanner } from '../help.js';
+import { normalizeConfidence, normalizeKind } from './conclude.js';
 import { renderContextMarkdown } from './context.js';
-export async function runDefaultWorkflow(query) {
+export async function runDefaultWorkflow(query, options = {}) {
     await runCommand(async () => {
         const topic = query?.trim();
         const candidateWorkspace = resolveWorkspace(process.cwd());
@@ -32,6 +37,35 @@ export async function runDefaultWorkflow(query) {
             symbols: scan.symbols,
         });
         const update = await updateCognition(workspace, { files: scan.files, symbols: scan.symbols }, false);
+        if (options.capture) {
+            if (!topic) {
+                throw new KGraphError('A topic is required when using --capture.');
+            }
+            const note = await concludeTopic(workspace, {
+                topic,
+                body: options.capture,
+                kind: normalizeKind(options.type),
+                confidence: normalizeConfidence(options.confidence),
+                domain: options.domain,
+                tags: options.tags ?? [],
+                relatedFiles: options.files ?? [],
+                relatedSymbols: options.symbols ?? [],
+                source: 'conclude',
+            });
+            console.log(`Stored ${note.kind} cognition: ${note.title}`);
+            console.log(`Confidence: ${note.confidence}`);
+            console.log(`Status: ${note.referencesStatus}`);
+            for (const warning of note.warnings) {
+                console.error(`Warning: ${warning}`);
+            }
+        }
+        const atoms = await readKnowledgeAtoms(workspace);
+        const pendingInbox = await listInboxNotes(workspace);
+        const activeAtoms = atoms.filter((atom) => atom.status === 'active');
+        const captureCheck = await buildCaptureCheck(workspace.rootPath, {
+            files: scan.files,
+            atoms,
+        });
         console.log(renderWorkflowBanner({
             files: scan.files.length,
             symbols: scan.symbols.length,
@@ -42,11 +76,30 @@ export async function runDefaultWorkflow(query) {
                 mode: integration.mode,
                 enabled: integration.enabled,
             })),
+            memory: {
+                atomsProcessed: update.processed.length,
+                pendingInbox: pendingInbox.length,
+                activeAtoms: activeAtoms.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,
+                changedFiles: captureCheck.changedFiles.length,
+            },
         }));
         console.log('');
         for (const warning of [...scan.warnings, ...update.warnings]) {
             console.warn(`Warning: ${warning}`);
         }
+        if (options.final) {
+            console.log('');
+            renderFinalCaptureCheck(captureCheck, topic);
+            if (captureCheck.required) {
+                process.exitCode = 1;
+            }
+            return;
+        }
         if (!topic) {
             return;
         }
@@ -56,3 +109,53 @@ export async function runDefaultWorkflow(query) {
         console.log(renderContextMarkdown(response));
     });
 }
+async function buildCaptureCheck(rootPath, input) {
+    const knownFiles = new Set(input.files.map((file) => file.path));
+    const changedFiles = (await getWorkingTreeChanges(rootPath)).filter((file) => knownFiles.has(file));
+    if (changedFiles.length === 0) {
+        return { required: false, changedFiles, coveredFiles: [] };
+    }
+    const recentCutoff = Date.now() - 24 * 60 * 60 * 1000;
+    const recentActiveAtoms = input.atoms.filter((atom) => {
+        if (atom.status !== 'active')
+            return false;
+        const createdAt = Date.parse(atom.provenance.createdAt);
+        return Number.isFinite(createdAt) && createdAt >= recentCutoff;
+    });
+    const covered = new Set();
+    for (const atom of recentActiveAtoms) {
+        for (const ref of atom.evidenceRefs) {
+            if (ref.type === 'file' && changedFiles.includes(ref.path)) {
+                covered.add(ref.path);
+            }
+        }
+        for (const file of atom.scopeRefs.files) {
+            if (changedFiles.includes(file)) {
+                covered.add(file);
+            }
+        }
+    }
+    return {
+        required: changedFiles.some((file) => !covered.has(file)),
+        changedFiles,
+        coveredFiles: [...covered],
+    };
+}
+function renderFinalCaptureCheck(check, topic) {
+    console.log('KGraph Final Check');
+    if (check.changedFiles.length === 0) {
+        console.log('  status        clean');
+        console.log('  reason        no mapped repo files changed');
+        return;
+    }
+    if (!check.required) {
+        console.log('  status        captured');
+        console.log(`  changed files ${check.changedFiles.length}`);
+        console.log(`  covered files ${check.coveredFiles.length}`);
+        return;
+    }
+    console.log('  status        capture-required');
+    console.log(`  changed files ${check.changedFiles.length}`);
+    console.log('  conclusion    missing for one or more changed files');
+    console.log(`  next          kgraph "${topic || '<topic>'}" --capture "<durable conclusion>" --capture-file <path>`);
+}

package/dist/cli/help.d.ts

@@ -5,11 +5,22 @@ interface WorkflowBannerStats {
     cognitionNotes: number;
     skippedFiles?: number;
     integrations?: WorkflowBannerIntegration[];
+    memory?: WorkflowBannerMemory;
 }
 interface WorkflowBannerIntegration {
     name: string;
     mode: string;
     enabled: boolean;
 }
+interface WorkflowBannerMemory {
+    atomsProcessed: number;
+    pendingInbox: number;
+    activeAtoms: number;
+    needsReviewAtoms: number;
+    staleAtoms: number;
+    highConfidenceMissingEvidence: number;
+    changedFiles?: number;
+    captureRequired?: boolean;
+}
 export declare function renderWorkflowBanner(stats: WorkflowBannerStats, useColor?: boolean): string;
 export {};

package/dist/cli/help.js

@@ -25,6 +25,8 @@ export function renderRootHelp(useColor = supportsColor()) {
         sectionTitle(theme, `${accent} Daily workflow`),
         command('kgraph', 'Refresh scan maps and process pending capture notes'),
         command('kgraph "auth token refresh"', 'Refresh everything and return compact context for a topic'),
+        command('kgraph "auth token refresh" --final', 'End-of-work check: enforce capture when changed files need memory'),
+        command('kgraph "auth token refresh" --capture "..."', 'Store durable knowledge through the smart root workflow'),
         '',
         sectionTitle(theme, `${accent} Workflows`),
         command('scan', 'Optional: refresh only file, symbol, import, and relationship maps'),
@@ -60,10 +62,16 @@ export function renderRootHelp(useColor = supportsColor()) {
         sectionTitle(theme, `${accent} Options`),
         command('-V, --version', 'Show version'),
         command('-h, --help', 'Show this help'),
+        command('--final', 'Run final capture enforcement in the root workflow'),
+        command('--capture <text>', 'Store a durable conclusion in the root workflow'),
+        command('--capture-file <path>', 'Attach file evidence to root capture'),
+        command('--capture-symbol <name>', 'Attach symbol evidence to root capture'),
         '',
         sectionTitle(theme, `${accent} Examples`),
         '  kgraph init --integrations codex,copilot,cursor,claude-code,gemini,windsurf,cline',
         '  kgraph "blog admin token usage"',
+        '  kgraph "blog admin token usage" --final',
+        '  kgraph "blog admin token usage" --capture "Author filter now uses display names" --capture-file www/app/blog/page.tsx',
         '  kgraph pack "about page update" --budget 4000',
         '  kgraph doctor',
         '',
@@ -97,6 +105,21 @@ export function renderWorkflowBanner(stats, useColor = supportsColor()) {
         command('symbols', String(stats.symbols)),
         command('capture notes processed', String(stats.cognitionNotes)),
         command('integration modes', integrationLine),
+        ...(stats.memory
+            ? [
+                '',
+                sectionTitle(theme, `${accent} Memory`),
+                command('atoms processed', String(stats.memory.atomsProcessed)),
+                command('pending inbox', String(stats.memory.pendingInbox)),
+                command('active atoms', String(stats.memory.activeAtoms)),
+                command('needs review', String(stats.memory.needsReviewAtoms)),
+                command('stale', String(stats.memory.staleAtoms)),
+                command('high-confidence missing evidence', String(stats.memory.highConfidenceMissingEvidence)),
+                command('capture status', stats.memory.captureRequired
+                    ? `required (${stats.memory.changedFiles ?? 0} changed file(s))`
+                    : `ok (${stats.memory.changedFiles ?? 0} changed file(s))`),
+            ]
+            : []),
         '',
         sectionTitle(theme, `${accent} Next`),
         command('kgraph "auth token refresh"', 'Return compact context for a topic'),

package/dist/cli/index.js

@@ -31,10 +31,27 @@ export function createProgram() {
         .name('kgraph')
         .description('Persistent repo intelligence for AI coding assistants')
         .argument('[topic...]', 'Run the default refresh workflow and optionally return context for a topic')
+        .option('--final', 'Run end-of-work capture enforcement after refresh')
+        .option('--capture <text>', 'Store a durable conclusion through the root workflow')
+        .option('--capture-type <type>', 'Capture type: finding, decision, gotcha, summary, or relationship', 'summary')
+        .option('--capture-confidence <level>', 'Capture confidence: high, medium, or low', 'medium')
+        .option('--capture-domain <name>', 'Capture domain name')
+        .option('--capture-tag <tag>', 'Capture tag; repeatable', collect, [])
+        .option('--capture-file <path>', 'Capture related repo file; repeatable', collect, [])
+        .option('--capture-symbol <name>', 'Capture related symbol; repeatable', collect, [])
         .version(version)
         .helpOption(false)
-        .action(async (topicParts = []) => {
-        await runDefaultWorkflow(topicParts.join(' '));
+        .action(async (topicParts = [], options) => {
+        await runDefaultWorkflow(topicParts.join(' '), {
+            final: options.final,
+            capture: options.capture,
+            type: options.captureType,
+            confidence: options.captureConfidence,
+            domain: options.captureDomain,
+            tags: options.captureTag,
+            files: options.captureFile,
+            symbols: options.captureSymbol,
+        });
     });
     program.option('-h, --help', 'Show this help');
     program.hook('preAction', (thisCommand) => {
@@ -63,6 +80,10 @@ export function createProgram() {
     registerUninstallCommand(program);
     return program;
 }
+function collect(value, previous) {
+    previous.push(value);
+    return previous;
+}
 if (isCliEntrypoint()) {
     const program = createProgram();
     const helpTarget = findExplicitHelpTarget(program, process.argv.slice(2));

package/dist/cognition/conclusion.js

@@ -15,6 +15,10 @@ export async function concludeTopic(workspace, input) {
         ? input.relatedFiles
         : await inferChangedFiles(workspace, maps);
     const relatedSymbols = input.relatedSymbols ?? [];
+    const hasEvidence = relatedFiles.length > 0 || relatedSymbols.length > 0;
+    if ((input.confidence ?? 'medium') === 'high' && !hasEvidence) {
+        throw new KGraphError('High-confidence cognition requires evidence. Add --file <path> or --symbol <name>, or use --confidence medium/low.');
+    }
     const note = {
         title,
         kind: input.kind ?? 'summary',
@@ -29,7 +33,11 @@ export async function concludeTopic(workspace, input) {
         },
         relatedFiles,
         relatedSymbols,
-        warnings: [],
+        warnings: (input.confidence ?? 'medium') === 'medium' && !hasEvidence
+            ? [
+                'Medium-confidence cognition has no file or symbol evidence; add --file or --symbol when possible.',
+            ]
+            : [],
         id: `${timestamp}-${slugify(title) || 'conclusion'}`,
         sourceInboxPath: '',
         processedPath: `.kgraph/cognition/${timestamp}-${slugify(title) || 'conclusion'}.md`,

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

@@ -1,12 +1,13 @@
+import { numberedWorkflow } from '../workflow-steps.js';
 export const claudeCodeAdapter = {
     name: 'claude-code',
     label: 'Claude Code',
     targetPath: 'CLAUDE.md',
     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}}
+${numberedWorkflow('claude-code', {
+        sessionQualifier: 'native hooks also report session activity when configured',
+    })}
 `,
     commandFiles: [
         {
@@ -20,7 +21,7 @@ export const claudeCodeAdapter = {
 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.
+8. At the end of repository-file changes, run \`kgraph "<topic>" --final\`. If KGraph reports capture-required, run \`kgraph "<topic>" --capture "<durable conclusion>" --capture-file <path> --capture-symbol <name>\`, or explicitly say "No durable knowledge created" only when there is genuinely no reusable knowledge.
 `,
         },
         {
@@ -85,7 +86,7 @@ export const claudeCodeAdapter = {
         },
         {
             path: '.claude/commands/kgraph-conclude.md',
-            content: `Use \`kgraph conclude "$ARGUMENTS"\` when the session produced reusable engineering knowledge. Choose one type from finding, decision, gotcha, summary, relationship, and one confidence from high, medium, low. Store only durable conclusions, not raw chain-of-thought, temporary reasoning, speculative exploration, or low-value observations.
+            content: `Prefer \`kgraph "<topic>" --capture "$ARGUMENTS" --capture-file <path> --capture-symbol <name>\` when the session produced reusable engineering knowledge. Use \`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.
 `,
         },
         {

package/dist/integrations/adapters/codex.js

@@ -1,3 +1,4 @@
+import { agentSkillFiles } from '../agent-skills.js';
 import { numberedWorkflow } from '../workflow-steps.js';
 export const codexAdapter = {
     name: 'codex',
@@ -5,26 +6,8 @@ export const codexAdapter = {
     targetPath: 'AGENTS.md',
     instructions: `## KGraph Workflow
 
-{{KGRAPH_CONTEXT_POLICY}} The /kgraph skill handles 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.
-`,
-    commandFiles: [
-        {
-            path: '.agents/skills/kgraph/SKILL.md',
-            content: `---
-name: kgraph
-description: Use KGraph persistent repo intelligence according to the configured integration mode. Use when asked about repo structure, debugging context, architecture decisions, or to avoid rediscovering what is already known.
----
-
-# KGraph Skill
-
-Workflow:
-
 ${numberedWorkflow('codex')}
 `,
-        },
-    ],
-    obsoleteCommandFiles: [
-        '.agents/skills/kgraph-scan/SKILL.md',
-        '.agents/skills/kgraph-update/SKILL.md',
-    ],
+    commandFiles: agentSkillFiles('codex'),
+    obsoleteCommandFiles: [],
 };

package/dist/integrations/adapters/copilot.js

@@ -1,3 +1,4 @@
+import { agentSkillFiles } from '../agent-skills.js';
 import { numberedWorkflow } from '../workflow-steps.js';
 export const copilotAdapter = {
     name: 'copilot',
@@ -7,172 +8,6 @@ export const copilotAdapter = {
 
 ${numberedWorkflow('copilot')}
 `,
-    commandFiles: [
-        {
-            path: '.github/prompts/kgraph-doctor.prompt.md',
-            content: `---
-description: Check KGraph workspace health and next actions
-agent: agent
----
-
-Run \`kgraph doctor\` to check whether the workspace is initialized, maps exist, inbox notes are pending, and configured integrations point to real files. Use \`kgraph doctor --quality\` when the user asks about stale or noisy cognition references. Summarize any failed checks and the next command to run.
-`,
-        },
-        {
-            path: '.github/prompts/kgraph-repair.prompt.md',
-            content: `---
-description: Preview or clean stale/noisy KGraph cognition references
-agent: agent
-argument-hint: "--dry-run or apply"
----
-
-Run \`kgraph repair --dry-run\` first and summarize the proposed atom-reference cleanup. Run \`kgraph repair\` only when the user asks to apply the cleanup.
-`,
-        },
-        {
-            path: '.github/prompts/kgraph-compact.prompt.md',
-            content: `---
-description: Merge duplicate KGraph cognition and archive stale low-value entries
-agent: agent
-argument-hint: "--dry-run or apply"
----
-
-Run \`kgraph compact --dry-run\` first and summarize duplicate cognition groups and stale low-confidence notes. Run \`kgraph compact\` only when the user asks to apply compaction.
-`,
-        },
-        {
-            path: '.github/prompts/kgraph-pack.prompt.md',
-            content: `---
-description: Build a budget-aware KGraph context pack
-agent: agent
-argument-hint: "Task description"
----
-
-Run \`kgraph pack "$ARGUMENTS" --budget 8000 --json\` to build a machine-readable context pack. Summarize token use, included files, symbols, relationships, git changes, session history, atoms, and omitted items with the inclusion reasons.
-`,
-        },
-        {
-            path: '.github/prompts/kgraph-knowledge.prompt.md',
-            content: `---
-description: Inspect or manage KGraph canonical knowledge atoms
-agent: agent
-argument-hint: "list, get <atom-id>, archive <atom-id>, or supersede <old-id> <new-id>"
----
-
-Use \`kgraph knowledge list\` and \`kgraph knowledge get <atom-id>\` to inspect durable atoms, evidence, provenance, and lifecycle. Run \`kgraph knowledge archive <atom-id>\` or \`kgraph knowledge supersede <old-id> <new-id>\` only when the user explicitly asks to mutate atom lifecycle.
-`,
-        },
-        {
-            path: '.github/prompts/kgraph-stale.prompt.md',
-            content: `---
-description: Show KGraph knowledge invalidated by changed or missing refs
-agent: agent
----
-
-Run \`kgraph stale\` to refresh atom status against the current scan and summarize stale or needs-review atoms with invalidation reasons.
-`,
-        },
-        {
-            path: '.github/prompts/kgraph-blame.prompt.md',
-            content: `---
-description: Show KGraph atom provenance and evidence
-agent: agent
-argument-hint: "Atom id"
----
-
-Run \`kgraph blame "$ARGUMENTS"\` to show who or what created a knowledge atom, the source command/session/commit, evidence refs, and lifecycle links.
-`,
-        },
-        {
-            path: '.github/prompts/kgraph-scan.prompt.md',
-            content: `---
-description: Refresh KGraph file, symbol, import, and relationship maps
-agent: agent
----
-
-Run \`kgraph scan\` to refresh the repository maps, then summarize what changed.
-`,
-        },
-        {
-            path: '.github/prompts/kgraph-update.prompt.md',
-            content: `---
-description: Process KGraph inbox notes into durable cognition
-agent: agent
----
-
-Run \`kgraph update\` to process any pending Markdown notes in \`.kgraph/inbox/\` into durable cognition.
-`,
-        },
-        {
-            path: '.github/prompts/kgraph-visualize.prompt.md',
-            content: `---
-description: Open interactive KGraph dependency graph in browser
-agent: agent
----
-
-Run \`kgraph visualize\` to start the interactive dependency graph at http://localhost:4242, then summarize what nodes and connections are visible.
-`,
-        },
-        {
-            path: '.github/prompts/kgraph-capture.prompt.md',
-            content: `---
-description: Save what was just built or changed into KGraph cognition
-agent: agent
-argument-hint: "Brief description of what was done"
----
-
-Capture this session into KGraph cognition.
-
-{{KGRAPH_CAPTURE_POLICY}}
-`,
-        },
-        {
-            path: '.github/prompts/kgraph-conclude.prompt.md',
-            content: `---
-description: Store a typed durable KGraph engineering conclusion
-agent: agent
-argument-hint: "Topic plus optional type, confidence, files, and symbols"
----
-
-Use \`kgraph conclude "$ARGUMENTS"\` when the session produced reusable engineering knowledge. Choose one type from finding, decision, gotcha, summary, relationship, and one confidence from high, medium, low. Store only durable conclusions, not raw chain-of-thought, temporary reasoning, speculative exploration, or low-value observations.
-`,
-        },
-        {
-            path: '.github/prompts/kgraph-impact.prompt.md',
-            content: `---
-description: Show KGraph change impact for a file, symbol, or topic
-agent: agent
-argument-hint: "File, symbol, or topic"
----
-
-Run \`kgraph impact "$ARGUMENTS"\` to show matched files/symbols, import users, callers, callees, related knowledge atoms, and risk hints.
-`,
-        },
-        {
-            path: '.github/prompts/kgraph-session.prompt.md',
-            content: `---
-description: Track KGraph session read/write activity and token estimates
-agent: agent
-argument-hint: "start, read <path>, write <path>, end, or status"
----
-
-Use \`kgraph session\` to inspect current session activity. Record meaningful events with \`kgraph session start --agent copilot\`, \`kgraph session read <path> --agent copilot\`, \`kgraph session write <path> --agent copilot\`, and \`kgraph session end --agent copilot --conclude --topic "<topic>"\` when durable session memory is useful.
-`,
-        },
-        {
-            path: '.github/prompts/kgraph-history.prompt.md',
-            content: `---
-description: Show timeline of KGraph cognition sessions with git attribution
-agent: agent
-argument-hint: "Optional topic"
----
-
-Run \`kgraph history\` or \`kgraph history "$ARGUMENTS"\` to display processed cognition sessions. Summarize who contributed what and when. Use \`--last <n>\` to limit entries.
-`,
-        },
-    ],
-    obsoleteCommandFiles: [
-        '.github/prompts/kgraph.prompt.md',
-        '.github/kgraph.agent.md',
-    ],
+    commandFiles: agentSkillFiles('copilot'),
+    obsoleteCommandFiles: [],
 };

package/dist/integrations/agent-skills.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Shared agent skill definitions used by any integration that writes
+ * `.agents/skills/` SKILL.md files (copilot, codex, etc.).
+ *
+ * Per-command skills are agent-name-agnostic.
+ * The main kgraph workflow skill is parameterised by agent name.
+ */
+import type { IntegrationCommandFile } from './integration-registry.js';
+/** Per-command skills shared across all agent-skill integrations. */
+export declare const SHARED_AGENT_SKILLS: IntegrationCommandFile[];
+/**
+ * Build the full agent skill list for an adapter: the main workflow skill
+ * (parameterised by agent name) plus all shared per-command skills.
+ */
+export declare function agentSkillFiles(agentName: string): IntegrationCommandFile[];

package/dist/integrations/agent-skills.js

@@ -0,0 +1,186 @@
+/**
+ * Shared agent skill definitions used by any integration that writes
+ * `.agents/skills/` SKILL.md files (copilot, codex, etc.).
+ *
+ * Per-command skills are agent-name-agnostic.
+ * The main kgraph workflow skill is parameterised by agent name.
+ */
+import { numberedWorkflow } from './workflow-steps.js';
+/** Per-command skills shared across all agent-skill integrations. */
+export const SHARED_AGENT_SKILLS = [
+    {
+        path: '.agents/skills/kgraph-doctor/SKILL.md',
+        content: `---
+name: kgraph-doctor
+description: Check KGraph workspace health and next actions
+---
+
+Run \`kgraph doctor\` to check whether the workspace is initialized, maps exist, inbox notes are pending, and configured integrations point to real files. Use \`kgraph doctor --quality\` when the user asks about stale or noisy cognition references. Summarize any failed checks and the next command to run.
+`,
+    },
+    {
+        path: '.agents/skills/kgraph-repair/SKILL.md',
+        content: `---
+name: kgraph-repair
+description: Preview or clean stale/noisy KGraph cognition references
+---
+
+Run \`kgraph repair --dry-run\` first and summarize the proposed atom-reference cleanup. Run \`kgraph repair\` only when the user asks to apply the cleanup.
+`,
+    },
+    {
+        path: '.agents/skills/kgraph-compact/SKILL.md',
+        content: `---
+name: kgraph-compact
+description: Merge duplicate KGraph cognition and archive stale low-value entries
+---
+
+Run \`kgraph compact --dry-run\` first and summarize duplicate cognition groups and stale low-confidence notes. Run \`kgraph compact\` only when the user asks to apply compaction.
+`,
+    },
+    {
+        path: '.agents/skills/kgraph-pack/SKILL.md',
+        content: `---
+name: kgraph-pack
+description: Build a budget-aware KGraph context pack
+---
+
+Run \`kgraph pack "$ARGUMENTS" --budget 8000 --json\` to build a machine-readable context pack. Summarize token use, included files, symbols, relationships, git changes, session history, atoms, and omitted items with the inclusion reasons.
+`,
+    },
+    {
+        path: '.agents/skills/kgraph-knowledge/SKILL.md',
+        content: `---
+name: kgraph-knowledge
+description: Inspect or manage KGraph canonical knowledge atoms
+---
+
+Use \`kgraph knowledge list\` and \`kgraph knowledge get <atom-id>\` to inspect durable atoms, evidence, provenance, and lifecycle. Run \`kgraph knowledge archive <atom-id>\` or \`kgraph knowledge supersede <old-id> <new-id>\` only when the user explicitly asks to mutate atom lifecycle.
+`,
+    },
+    {
+        path: '.agents/skills/kgraph-stale/SKILL.md',
+        content: `---
+name: kgraph-stale
+description: Show KGraph knowledge invalidated by changed or missing refs
+---
+
+Run \`kgraph stale\` to refresh atom status against the current scan and summarize stale or needs-review atoms with invalidation reasons.
+`,
+    },
+    {
+        path: '.agents/skills/kgraph-blame/SKILL.md',
+        content: `---
+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.
+`,
+    },
+    {
+        path: '.agents/skills/kgraph-scan/SKILL.md',
+        content: `---
+name: kgraph-scan
+description: Refresh KGraph file, symbol, import, and relationship maps
+---
+
+Run \`kgraph scan\` to refresh the repository maps, then summarize what changed.
+`,
+    },
+    {
+        path: '.agents/skills/kgraph-update/SKILL.md',
+        content: `---
+name: kgraph-update
+description: Process KGraph inbox notes into durable cognition
+---
+
+Run \`kgraph update\` to process any pending Markdown notes in \`.kgraph/inbox/\` into durable cognition.
+`,
+    },
+    {
+        path: '.agents/skills/kgraph-visualize/SKILL.md',
+        content: `---
+name: kgraph-visualize
+description: Open interactive KGraph dependency graph in browser
+---
+
+Run \`kgraph visualize\` to start the interactive dependency graph at http://localhost:4242, then summarize what nodes and connections are visible.
+`,
+    },
+    {
+        path: '.agents/skills/kgraph-capture/SKILL.md',
+        content: `---
+name: kgraph-capture
+description: Save what was just built or changed into KGraph cognition
+---
+
+Capture this session into KGraph cognition.
+
+{{KGRAPH_CAPTURE_POLICY}}
+`,
+    },
+    {
+        path: '.agents/skills/kgraph-conclude/SKILL.md',
+        content: `---
+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.
+`,
+    },
+    {
+        path: '.agents/skills/kgraph-impact/SKILL.md',
+        content: `---
+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.
+`,
+    },
+    {
+        path: '.agents/skills/kgraph-session/SKILL.md',
+        content: `---
+name: kgraph-session
+description: Track KGraph session read/write activity and token estimates
+---
+
+Use \`kgraph session\` to inspect current session activity. Record meaningful events with \`kgraph session start --agent $AGENT\`, \`kgraph session read <path> --agent $AGENT\`, \`kgraph session write <path> --agent $AGENT\`, and \`kgraph session end --agent $AGENT --conclude --topic "<topic>"\` when durable session memory is useful.
+`,
+    },
+    {
+        path: '.agents/skills/kgraph-history/SKILL.md',
+        content: `---
+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.
+`,
+    },
+];
+/**
+ * Build the full agent skill list for an adapter: the main workflow skill
+ * (parameterised by agent name) plus all shared per-command skills.
+ */
+export function agentSkillFiles(agentName) {
+    return [
+        {
+            path: '.agents/skills/kgraph/SKILL.md',
+            content: `---
+name: kgraph
+description: Use KGraph persistent repo intelligence according to the configured integration mode. Use when asked about repo structure, debugging context, architecture decisions, or to avoid rediscovering what is already known.
+---
+
+# KGraph Skill
+
+Workflow:
+
+${numberedWorkflow(agentName)}
+`,
+        },
+        ...SHARED_AGENT_SKILLS,
+    ];
+}

package/dist/integrations/instruction-blocks.js

@@ -51,12 +51,15 @@ export function renderContextPolicy(mode) {
 }
 export function renderCapturePolicy() {
     return `Capture policy:
-- At the end of any session that changed repository files, store durable engineering memory with \`kgraph conclude "<topic>" --type <finding|decision|gotcha|summary|relationship> --confidence <high|medium|low>\` or \`kgraph session end --agent <agent> --conclude --topic "<topic>"\`.
+- At the end of any session that changed repository files, run \`kgraph "<topic>" --final\` before the final response so KGraph can enforce whether capture is required.
+- If final check reports capture-required, run \`kgraph "<topic>" --capture "<durable conclusion>" --capture-file <path> --capture-symbol <name>\` to store durable engineering memory, or explicitly say "No durable knowledge created" only when there is genuinely no reusable knowledge.
+- Low-level alternatives remain available: \`kgraph conclude "<topic>" --type <finding|decision|gotcha|summary|relationship> --confidence <high|medium|low>\` or \`kgraph session end --agent <agent> --conclude --topic "<topic>"\`.
+- Add evidence when storing cognition. High-confidence conclusions must include at least one \`--file <path>\` or \`--symbol <name>\`; medium-confidence conclusions should include evidence when possible.
 - Preserve only expensive-to-rediscover findings, decisions, gotchas, summaries, and relationships. Do not store raw chain-of-thought, temporary reasoning, speculative exploration, or low-value observations.
 - 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 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.
+- Do not run KGraph repeatedly. Run it once at the start with \`kgraph "<topic>"\` or \`kgraph pack "<topic>" --budget 8000 --json\` for agent-readable context. If repo files changed, run \`kgraph "<topic>" --final\` once before the final answer.
 - After the final \`kgraph\` run, mention whether durable cognition was stored or processed.
 
 When using an inbox note, use this structure:

package/dist/integrations/integration-store.js

@@ -1,4 +1,4 @@
-import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { mkdir, readdir, readFile, rm, rmdir, writeFile, } from 'node:fs/promises';
 import path from 'node:path';
 import { loadConfig, saveConfig } from '../config/config.js';
 import { pathExists } from '../storage/kgraph-paths.js';
@@ -19,6 +19,7 @@ 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 = [];
+    const writtenCommandFiles = new Set();
     for (const name of names) {
         const adapter = getIntegrationAdapter(name);
         const next = {
@@ -34,10 +35,14 @@ export async function addIntegrations(workspace, names, mode = 'always') {
         }
         else {
             await writeIntegrationInstructions(workspace.rootPath, adapter.targetPath, adapter.name, applyContextPolicy(adapter.instructions, mode));
-            await writeIntegrationCommandFiles(workspace.rootPath, (adapter.commandFiles ?? []).map((file) => ({
+            const deduped = (adapter.commandFiles ?? []).filter((file) => !writtenCommandFiles.has(file.path));
+            await writeIntegrationCommandFiles(workspace.rootPath, deduped.map((file) => ({
                 ...file,
                 content: applyContextPolicy(file.content, mode),
             })));
+            for (const file of adapter.commandFiles ?? []) {
+                writtenCommandFiles.add(file.path);
+            }
         }
         await removeIntegrationCommandFiles(workspace.rootPath, adapter.obsoleteCommandFiles ?? []);
         changed.push(next);
@@ -53,10 +58,21 @@ export async function removeIntegrations(workspace, names) {
     const config = await loadConfig(workspace);
     const removeNames = new Set(names);
     const removed = [];
+    // Collect command-file paths still owned by remaining enabled integrations
+    const retainedPaths = new Set();
+    for (const integration of config.integrations) {
+        if (removeNames.has(integration.name) || !integration.enabled) {
+            continue;
+        }
+        const adapter = getIntegrationAdapter(integration.name);
+        for (const file of adapter.commandFiles ?? []) {
+            retainedPaths.add(file.path);
+        }
+    }
     for (const name of removeNames) {
         const adapter = getIntegrationAdapter(name);
         await removeIntegrationInstructions(workspace.rootPath, adapter.targetPath, adapter.name);
-        await removeIntegrationCommandFiles(workspace.rootPath, adapter.commandFiles ?? []);
+        await removeIntegrationCommandFiles(workspace.rootPath, (adapter.commandFiles ?? []).filter((file) => !retainedPaths.has(file.path)));
         await removeIntegrationCommandFiles(workspace.rootPath, adapter.obsoleteCommandFiles ?? []);
         removed.push(adapter.name);
     }
@@ -96,6 +112,21 @@ async function writeIntegrationCommandFiles(rootPath, files) {
 async function removeIntegrationCommandFiles(rootPath, files) {
     for (const file of files) {
         const filePath = typeof file === 'string' ? file : file.path;
-        await rm(path.join(rootPath, filePath), { force: true, recursive: true });
+        const fullPath = path.join(rootPath, filePath);
+        await rm(fullPath, { force: true, recursive: true });
+        // Remove empty parent directories up to (but not including) rootPath
+        let dir = path.dirname(fullPath);
+        while (dir !== rootPath && dir.startsWith(rootPath)) {
+            try {
+                const entries = await readdir(dir);
+                if (entries.length > 0)
+                    break;
+                await rmdir(dir);
+                dir = path.dirname(dir);
+            }
+            catch {
+                break;
+            }
+        }
     }
 }

package/dist/integrations/workflow-steps.js

@@ -9,6 +9,7 @@ const COMPACT_STEP = `Run \`kgraph compact --dry-run\` when cognition looks dupl
 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 = `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 SMART_ROOT_STEP = `Prefer the root workflow for normal agent work: run \`kgraph "<topic>"\` to refresh maps, process cognition, report memory health, and return context; run \`kgraph "<topic>" --final\` before the final answer when repository files changed; run \`kgraph "<topic>" --capture "<durable conclusion>" --capture-file <path> --capture-symbol <name>\` 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.`;
@@ -26,19 +27,20 @@ export function numberedWorkflow(agentName, options = {}) {
 3. Use the returned files, symbols, relationships, and cognition before broad exploration.
 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}
+6. ${SMART_ROOT_STEP}
+7. ${PACK_STEP}
+8. ${KNOWLEDGE_STEP}
+9. ${DOCTOR_STEP}
+10. ${STALE_STEP}
+11. ${sessionStep(agentName, options.sessionQualifier)}
+12. ${IMPACT_STEP}
 
 {{KGRAPH_CAPTURE_POLICY}}
 
-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}`;
+13. ${REPAIR_STEP}
+14. ${COMPACT_STEP}
+15. Run \`kgraph visualize\` when the user wants to inspect the dependency graph — opens an interactive graph at http://localhost:4242 with PNG export.
+16. ${HISTORY_STEP}`;
 }
 /**
  * Returns the bullet-list workflow for rules files.
@@ -48,6 +50,7 @@ export function bulletWorkflow(agentName, options = {}) {
     return `- {{KGRAPH_CONTEXT_POLICY}}
 - ${EXPLORATION_BOUNDARY_STEP}
 - ${VERIFY_EDIT_STEP}
+- ${SMART_ROOT_STEP}
 - ${PACK_STEP}
 - ${KNOWLEDGE_STEP}
 - ${DOCTOR_STEP}

package/package.json

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