@kage-core/kage-graph-mcp 3.1.0 → 3.3.0

package/dist/cli.js

@@ -10,11 +10,13 @@ const node_process_1 = require("node:process");
 const daemon_js_1 = require("./daemon.js");
 const kernel_js_1 = require("./kernel.js");
 const graph_registry_js_1 = require("./graph-registry.js");
+const check_js_1 = require("./check.js");
 const okf_js_1 = require("./okf.js");
 const CORE_USAGE = `Kage — code-grounded memory for coding agents
 
 Core commands:
   kage install [--project <dir>]             one-shot: init + index + auto-wire detected agents
+  kage check [--project <dir>]               verify CLAUDE.md/AGENTS.md/docs claims against the code — counted, not estimated
   kage scan --project <dir>                  60-second truth report on any repo (zero setup)
   kage init --project <dir>                  create repo memory (.agent_memory only)
   kage index --project <dir> [--full]        build/refresh code graph + indexes
@@ -32,6 +34,7 @@ const FULL_USAGE = `Kage — full command reference
 
 Usage:
   kage index --project <dir>
+  kage check [--project <dir>] [--json | --md] [--base <ref>] [--write-baseline] [--init-ci [--force]]
   kage scan --project <dir> [--json] [--scorecard [--out <file>]]
   kage demo [--project <dir>]
   kage install [--project <dir>] [--agents a,b] [--no-agents] [--json]
@@ -307,6 +310,41 @@ async function main() {
         console.log(`Indexes:\n${result.indexes.map((path) => `  - ${path}`).join("\n")}`);
         return;
     }
+    if (command === "check") {
+        const checkTarget = (0, node_path_1.resolve)(projectArg(args));
+        if (args.includes("--init-ci")) {
+            const workflowPath = (0, node_path_1.join)(checkTarget, ".github", "workflows", "kage-check.yml");
+            if ((0, node_fs_1.existsSync)(workflowPath) && !args.includes("--force")) {
+                console.log(`${workflowPath} already exists — rerun with --force to overwrite.`);
+                process.exit(2);
+            }
+            (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(workflowPath), { recursive: true });
+            (0, node_fs_1.writeFileSync)(workflowPath, (0, check_js_1.kageCheckWorkflowYaml)(), "utf8");
+            console.log(`Wrote ${workflowPath}`);
+            console.log("Every PR now gets a drift check: it comments and fails only when the diff breaks a documented claim.");
+            return;
+        }
+        let report;
+        try {
+            report = (0, check_js_1.driftCheck)(checkTarget, { base: takeArg(args, "--base") });
+        }
+        catch (error) {
+            console.error(`kage check failed: ${error instanceof Error ? error.message : String(error)}`);
+            process.exit(2);
+        }
+        if (args.includes("--write-baseline")) {
+            const written = (0, check_js_1.writeCheckBaseline)(checkTarget, report);
+            console.log(`Baseline written: ${written} (${report.confirmed.length} finding(s) accepted — future runs gate only on new drift)`);
+            return;
+        }
+        if (args.includes("--json"))
+            console.log(JSON.stringify(report, null, 2));
+        else if (args.includes("--md"))
+            console.log((0, check_js_1.checkReportMarkdown)(report));
+        else
+            console.log((0, check_js_1.formatCheckReport)(report));
+        process.exit(report.totals.confirmed > 0 ? 1 : 0);
+    }
     if (command === "scan") {
         const scanTarget = (0, node_path_1.resolve)(projectArg(args));
         if (scanTarget === (0, node_os_1.homedir)()) {
@@ -1577,13 +1615,18 @@ async function main() {
         const packetId = takeArg(args, "--packet");
         if (!packetId)
             usage();
-        const result = (0, kernel_js_1.reverifyMemory)(projectArg(args), packetId);
+        const result = (0, kernel_js_1.reverifyMemory)(projectArg(args), packetId, {
+            evidence: takeArg(args, "--evidence"),
+            verifiedBy: takeArg(args, "--verified-by"),
+        });
         if (args.includes("--json")) {
             console.log(JSON.stringify(result, null, 2));
         }
         else if (result.ok) {
             console.log(`Reverified ${result.packet_id}`);
             console.log(`  grounding refreshed for ${result.refreshed_paths.length} path(s)${result.was_stale ? " · stale flag cleared" : ""}`);
+            if (result.changed_paths.length)
+                console.log(`  evidence recorded for changed path(s): ${result.changed_paths.join(", ")}`);
             if (result.missing_paths.length)
                 console.log(`  dropped missing path(s): ${result.missing_paths.join(", ")}`);
         }

package/dist/index.js

@@ -8,6 +8,7 @@ const index_js_1 = require("@modelcontextprotocol/sdk/server/index.js");
 const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
 const types_js_1 = require("@modelcontextprotocol/sdk/types.js");
 const kernel_js_1 = require("./kernel.js");
+const check_js_1 = require("./check.js");
 const graph_registry_js_1 = require("./graph-registry.js");
 const BASE_URL = "https://raw.githubusercontent.com/kage-core/kage-graph/master";
 async function fetchText(url) {
@@ -91,6 +92,7 @@ const KAGE_WORKFLOW_TEXT = "Kage memory workflow (this tool performs no action;
 // mode (KAGE_TOOLS=full) or via the CLI. Keeping the default small enough that
 // the client always-loads it removes the per-call ToolSearch round-trip.
 exports.CORE_TOOLS = new Set([
+    "kage_check",
     "kage_context",
     "kage_learn",
     "kage_supersede",
@@ -536,6 +538,19 @@ function listTools() {
                 required: ["project_dir"],
             },
         },
+        {
+            name: "kage_check",
+            description: "Verify the claims in agent-context files (CLAUDE.md, AGENTS.md, .cursor/rules, README, docs) against the code: cited paths, npm scripts, make targets, CLI subcommands. Reports confirmed drift / verified true / unverifiable — every number is a reproducible check, never an estimate. Pass base to gate only drift introduced since that ref.",
+            annotations: { title: "Verify agent-context files against the code", readOnlyHint: true },
+            inputSchema: {
+                type: "object",
+                properties: {
+                    project_dir: { type: "string", description: "Absolute path to the repository root." },
+                    base: { type: "string", description: "Optional git ref: only report drift attributable to changes since this ref (diff-aware mode for PRs)." },
+                },
+                required: ["project_dir"],
+            },
+        },
         {
             name: "kage_memory_reconcile",
             description: "Return agent-owned memory reconciliation work when source files linked to existing memory changed. Agents must update, supersede, or mark stale memory before final handoff.",
@@ -1097,10 +1112,12 @@ async function callTool(name, args) {
             reconciliation.unresolved_count ? `\n## Memory Reconciliation\n${reconciliation.agent_instruction}` : "",
             `\n_${validationText}_`,
         ].filter(Boolean).join("");
-        // Visible receipt: surface what the harness saved today so agents relay it. Kept
-        // outside the size cap so it always survives.
+        // Receipt of counts only: served/withheld are observable events; token or
+        // dollar "savings" were estimates with no counterfactual and do not ship.
         const gains = (0, kernel_js_1.valueSummary)(projectDir).today;
-        const gainsLine = `\n\nGains: ~${(0, kernel_js_1.formatTokenCount)(gains.tokens_saved)} tokens saved this session · stale memories withheld: ${gains.stale_withheld}`;
+        const gainsLine = gains.stale_withheld > 0
+            ? `\n\n_${gains.stale_withheld} stale memor${gains.stale_withheld === 1 ? "y" : "ies"} withheld today (cited code changed; run \`kage doctor\` to review)._`
+            : "";
         // Backstop: per-field clamping + graph dedup keep this compact in practice, but never
         // let a pathological repo overflow the MCP response again. ~24k chars ≈ 6k tokens.
         const MAX_CONTEXT_CHARS = 24000;
@@ -1122,11 +1139,11 @@ async function callTool(name, args) {
             if (docsSection)
                 result.context_block = `${result.context_block}\n\n${docsSection}`;
         }
-        // Visible receipt: in text mode, surface what this recall saved so the agent
-        // can relay it. Value is otherwise invisible; an unseen win is a churned user.
+        // Counts only: stale-withheld is an observable event; estimated token
+        // savings are not a measurement and do not ship.
         const receipt = result.value_receipt;
-        const gainsLine = receipt && (receipt.tokens_saved > 0 || receipt.stale_withheld > 0)
-            ? `\n\nGains: ~${(0, kernel_js_1.formatTokenCount)(receipt.tokens_saved)} tokens saved by this recall${receipt.stale_withheld ? ` · stale memories withheld: ${receipt.stale_withheld}` : ""}`
+        const gainsLine = receipt && receipt.stale_withheld > 0
+            ? `\n\n_${receipt.stale_withheld} stale memor${receipt.stale_withheld === 1 ? "y" : "ies"} withheld by this recall (cited code changed)._`
             : "";
         return {
             content: [{ type: "text", text: args?.json || args?.explain ? JSON.stringify(result, null, 2) : `${result.context_block}${gainsLine}` }],
@@ -1385,6 +1402,14 @@ async function callTool(name, args) {
             isError: !result.ok,
         };
     }
+    if (name === "kage_check") {
+        const report = (0, check_js_1.driftCheck)(String(args?.project_dir ?? ""), {
+            base: typeof args?.base === "string" ? args.base : undefined,
+        });
+        return {
+            content: [{ type: "text", text: (0, check_js_1.formatCheckReport)(report) }],
+        };
+    }
     if (name === "kage_quality") {
         const result = (0, kernel_js_1.qualityReport)(String(args?.project_dir ?? ""));
         return {