@kentwynn/kgraph 0.2.18 → 0.2.20

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 { refreshKnowledgeAtomStatuses } 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,47 @@ 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 refreshedAtoms = await refreshKnowledgeAtomStatuses(workspace, {
+            fileMap: {
+                generatedAt: new Date().toISOString(),
+                files: scan.files,
+            },
+            symbolMap: {
+                generatedAt: new Date().toISOString(),
+                symbols: scan.symbols,
+            },
+        });
+        const atoms = refreshedAtoms.atoms;
+        const pendingInbox = await listInboxNotes(workspace);
+        const activeAtoms = atoms.filter((atom) => atom.status === 'active');
+        const captureCheck = await buildCaptureCheck(workspace.rootPath, {
+            topic,
+            previousFiles: previousMaps.fileMap.files,
+            files: scan.files,
+            atoms,
+        });
         console.log(renderWorkflowBanner({
             files: scan.files.length,
             symbols: scan.symbols.length,
@@ -42,11 +88,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 +121,137 @@ 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 previousByPath = new Map(input.previousFiles.map((file) => [file.path, file]));
+    const currentPaths = new Set(input.files.map((file) => file.path));
+    const mapChangedFiles = input.files
+        .filter((file) => {
+        const previous = previousByPath.get(file.path);
+        return !previous || previous.contentHash !== file.contentHash;
+    })
+        .map((file) => file.path);
+    const deletedFiles = input.previousFiles
+        .filter((file) => !currentPaths.has(file.path))
+        .map((file) => file.path);
+    const gitChangedFiles = (await getWorkingTreeChanges(rootPath)).filter((file) => knownFiles.has(file) || previousByPath.has(file));
+    const changedFiles = [
+        ...new Set([...mapChangedFiles, ...deletedFiles, ...gitChangedFiles]),
+    ];
+    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 invalidatedAtoms = matchingInvalidatedAtoms(input.atoms, input.topic).filter((atom) => !isInvalidatedAtomCovered(atom, recentActiveAtoms));
+    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)) ||
+            invalidatedAtoms.length > 0,
+        changedFiles,
+        coveredFiles: [...covered],
+        invalidatedAtoms,
+    };
+}
+function isInvalidatedAtomCovered(invalidated, recentActiveAtoms) {
+    const invalidatedFiles = new Set(invalidated.scopeRefs.files);
+    const invalidatedSymbols = new Set(invalidated.scopeRefs.symbols);
+    for (const ref of invalidated.evidenceRefs) {
+        if (ref.type === 'file')
+            invalidatedFiles.add(ref.path);
+        if (ref.type === 'symbol')
+            invalidatedSymbols.add(ref.name);
+    }
+    return recentActiveAtoms.some((atom) => {
+        const atomFiles = new Set(atom.scopeRefs.files);
+        const atomSymbols = new Set(atom.scopeRefs.symbols);
+        for (const ref of atom.evidenceRefs) {
+            if (ref.type === 'file')
+                atomFiles.add(ref.path);
+            if (ref.type === 'symbol')
+                atomSymbols.add(ref.name);
+        }
+        const fileOverlap = [...invalidatedFiles].some((file) => atomFiles.has(file));
+        const symbolOverlap = [...invalidatedSymbols].some((symbol) => atomSymbols.has(symbol));
+        if (fileOverlap || symbolOverlap)
+            return true;
+        return tokenOverlap(invalidated.topic, atom.topic);
+    });
+}
+function tokenOverlap(a, b) {
+    const aTokens = new Set(a
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .filter(Boolean));
+    return b
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .filter(Boolean)
+        .some((token) => aTokens.has(token));
+}
+function matchingInvalidatedAtoms(atoms, topic) {
+    const tokens = new Set((topic ?? '')
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .filter(Boolean));
+    return atoms.filter((atom) => {
+        if (atom.status !== 'needs-review' && atom.status !== 'stale')
+            return false;
+        if (tokens.size === 0)
+            return true;
+        const haystack = [
+            atom.topic,
+            atom.claim,
+            atom.summary,
+            ...atom.scopeRefs.files,
+            ...atom.scopeRefs.symbols,
+        ]
+            .filter(Boolean)
+            .join(' ')
+            .toLowerCase();
+        return [...tokens].some((token) => haystack.includes(token));
+    });
+}
+function renderFinalCaptureCheck(check, topic) {
+    console.log('KGraph Final Check');
+    if (check.changedFiles.length === 0) {
+        if (check.required) {
+            console.log('  status        capture-required');
+            console.log('  changed files 0');
+            console.log(`  invalid atoms ${check.invalidatedAtoms.length}`);
+            console.log('  conclusion    missing for needs-review or stale knowledge');
+            console.log(`  next          kgraph "${topic || '<topic>'}" --capture "<durable conclusion>" --capture-file <path>`);
+            return;
+        }
+        console.log('  status        clean');
+        console.log('  reason        no mapped repo files changed or invalidated matching atoms');
+        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}`);
+    if (check.invalidatedAtoms.length > 0) {
+        console.log(`  invalid atoms ${check.invalidatedAtoms.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,11 +1,12 @@
 import { agentSkillFiles } from '../agent-skills.js';
+import { numberedWorkflow } from '../workflow-steps.js';
 export const codexAdapter = {
     name: 'codex',
     label: 'Codex',
     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.
+${numberedWorkflow('codex')}
 `,
     commandFiles: agentSkillFiles('codex'),
     obsoleteCommandFiles: [],

package/dist/integrations/agent-skills.js

@@ -127,7 +127,7 @@ name: kgraph-conclude
 description: Store a typed durable KGraph engineering conclusion
 ---
 
-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.
+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.
 `,
     },
     {

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/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/dist/knowledge/atom-store.js

@@ -209,6 +209,8 @@ export async function validateKnowledgeStore(workspace, maps) {
         const symbolNames = new Set(maps.symbolMap.symbols.map((symbol) => symbol.name));
         const symbolIds = new Set(maps.symbolMap.symbols.map((symbol) => symbol.id));
         for (const atom of atoms) {
+            if (atom.status === 'archived')
+                continue;
             for (const ref of atom.evidenceRefs) {
                 if (ref.type === 'file') {
                     const file = fileByPath.get(ref.path);

package/package.json

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