@coreyuan/vector-mind 1.0.39 → 1.0.42

package/dist/index.js

@@ -16,7 +16,7 @@ import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextpro
 import { BUILTIN_CONVENTIONS } from "./builtin-conventions.js";
 import { BUILTIN_ARCHITECTURE_AND_CODE_ORGANIZATION_INSTRUCTIONS, BUILTIN_DESTRUCTIVE_OPERATION_GUARD_INSTRUCTIONS, BUILTIN_FRONTEND_OUTPUT_PURITY_INSTRUCTIONS, BUILTIN_GIT_COMMIT_SUMMARY_INSTRUCTIONS, BUILTIN_LOW_OVERHEAD_WORKFLOW_INSTRUCTIONS, BUILTIN_PAYLOAD_GUARD_INSTRUCTIONS, BUILTIN_PLAN_LITE_INSTRUCTIONS, BUILTIN_THREAD_HANDOFF_SWITCH_INSTRUCTIONS, BUILTIN_WRITE_POLICY_INSTRUCTIONS, } from "./builtin-instructions.js";
 const SERVER_NAME = "vector-mind";
-const SERVER_VERSION = "1.0.39";
+const SERVER_VERSION = "1.0.42";
 const rootFromEnv = process.env.VECTORMIND_ROOT?.trim() ?? "";
 const prettyJsonOutput = ["1", "true", "on", "yes"].includes((process.env.VECTORMIND_PRETTY_JSON ?? "").trim().toLowerCase());
 const debugLogEnabled = ["1", "true", "on", "yes"].includes((process.env.VECTORMIND_DEBUG_LOG ?? "").trim().toLowerCase());
@@ -164,9 +164,13 @@ let getConventionByKeyStmt;
 let insertConventionStmt;
 let updateConventionByIdStmt;
 let listConventionsStmt;
+let upsertDecisionStmt;
+let getDecisionByKeyStmt;
+let listCurrentDecisionsStmt;
 let upsertProjectSummaryStmt;
 let getProjectSummaryStmt;
 let listRecentNotesStmt;
+let getLatestChangeIntentForFileStmt;
 let deleteFileChunkItemsStmt;
 let getEmbeddingMetaStmt;
 let upsertEmbeddingStmt;
@@ -556,6 +560,89 @@ function shouldIgnoreDbFilePath(filePath) {
         return false;
     return pathHasIgnoredSegments(filePath);
 }
+function isProbablyGitRepository() {
+    try {
+        return fs.existsSync(path.join(projectRoot, ".git"));
+    }
+    catch {
+        return false;
+    }
+}
+function normalizeGitStatusPath(raw) {
+    const first = raw.split("\0")[0] ?? "";
+    return first.trim().replace(/\\/g, "/").replace(/^"(.*)"$/, "$1");
+}
+function collectGitPendingChanges(limit) {
+    if (limit <= 0 || !isProbablyGitRepository())
+        return [];
+    const git = spawnSync("git", ["status", "--porcelain=v1", "-z", "--untracked-files=normal"], {
+        cwd: projectRoot,
+        encoding: "utf8",
+        timeout: 5000,
+        windowsHide: true,
+        maxBuffer: 2_000_000,
+    });
+    if (git.error || git.status !== 0 || !git.stdout)
+        return [];
+    const parts = git.stdout.split("\0").filter(Boolean);
+    const rows = [];
+    for (let i = 0; i < parts.length && rows.length < limit; i++) {
+        const rec = parts[i] ?? "";
+        const status = rec.slice(0, 2);
+        let rawPath = rec.slice(3);
+        if (status.startsWith("R") || status.startsWith("C")) {
+            // Porcelain -z rename/copy records include the destination in the next NUL field.
+            rawPath = parts[i + 1] ?? rawPath;
+            i += 1;
+        }
+        const filePath = normalizeGitStatusPath(rawPath);
+        if (!filePath || filePath === ".vectormind" || filePath.startsWith(".vectormind/"))
+            continue;
+        rows.push({
+            file_path: filePath,
+            last_event: status.includes("D") ? "unlink" : status === "??" ? "add" : "change",
+            updated_at: new Date().toISOString(),
+            source: "git",
+            git_status: status.trim() || "modified",
+            file_state_hash: getFileStateHash(filePath) ?? undefined,
+        });
+    }
+    return rows;
+}
+function mergePendingWithGit(pending, opts) {
+    const byPath = new Map();
+    for (const p of pending) {
+        if (shouldIgnoreDbFilePath(p.file_path))
+            continue;
+        byPath.set(p.file_path, { ...p, source: p.source ?? "watcher" });
+    }
+    const gitRows = collectGitPendingChanges(Math.max(500, opts.offset + opts.limit * 4));
+    for (const g of gitRows) {
+        const latestSyncedHash = getLatestSyncedFileHash(g.file_path);
+        if (latestSyncedHash && g.file_state_hash && latestSyncedHash === g.file_state_hash)
+            continue;
+        const existing = byPath.get(g.file_path);
+        if (!existing) {
+            byPath.set(g.file_path, g);
+            continue;
+        }
+        byPath.set(g.file_path, {
+            ...existing,
+            source: existing.source === "watcher" ? "watcher" : g.source,
+            git_status: g.git_status,
+            file_state_hash: g.file_state_hash,
+        });
+    }
+    const all = Array.from(byPath.values()).sort((a, b) => {
+        const at = Date.parse(a.updated_at) || 0;
+        const bt = Date.parse(b.updated_at) || 0;
+        if (bt !== at)
+            return bt - at;
+        return a.file_path.localeCompare(b.file_path);
+    });
+    const page = all.slice(opts.offset, opts.offset + opts.limit);
+    return { total: all.length, page, truncated: all.length > opts.offset + opts.limit };
+}
 function pruneIgnoredPendingChanges() {
     if (!db)
         return;
@@ -1249,6 +1336,22 @@ const UpsertConventionArgsSchema = ProjectRootArgSchema.merge(z.object({
     content: z.string().min(1),
     tags: z.array(z.string().min(1)).optional(),
 }));
+const UpsertDecisionArgsSchema = ProjectRootArgSchema.merge(z.object({
+    key: z.string().min(1),
+    title: z.string().optional().default(""),
+    content: z.string().min(1),
+    tags: z.array(z.string().min(1)).optional(),
+    supersedes_req_ids: z.array(z.number().int().positive()).optional(),
+    supersedes_memory_ids: z.array(z.number().int().positive()).optional(),
+    related_files: z.array(z.string().min(1)).optional(),
+}));
+const SupersedeMemoryArgsSchema = ProjectRootArgSchema.merge(z.object({
+    superseded_req_ids: z.array(z.number().int().positive()).optional(),
+    superseded_memory_ids: z.array(z.number().int().positive()).optional(),
+    replacement_req_id: z.number().int().positive().optional(),
+    replacement_memory_id: z.number().int().positive().optional(),
+    reason: z.string().min(1),
+}));
 const DEFAULT_PENDING_LIMIT = 10;
 const MAX_PENDING_LIMIT = 2000;
 const PendingPagingSchema = z.object({
@@ -1267,11 +1370,14 @@ const DEFAULT_RECENT_REQUIREMENTS = 2;
 const DEFAULT_RECENT_CHANGES_PER_REQ = 3;
 const DEFAULT_RECENT_NOTES = 3;
 const DEFAULT_CONVENTIONS_LIMIT = 0;
+const DEFAULT_DECISIONS_LIMIT = 5;
+const MAX_DECISIONS_LIMIT = 50;
 const BrainDumpLimitsSchema = z.object({
     requirements_limit: z.number().int().min(1).max(20).optional().default(DEFAULT_RECENT_REQUIREMENTS),
     changes_limit: z.number().int().min(1).max(100).optional().default(DEFAULT_RECENT_CHANGES_PER_REQ),
     notes_limit: z.number().int().min(0).max(50).optional().default(DEFAULT_RECENT_NOTES),
     conventions_limit: z.number().int().min(0).max(200).optional().default(DEFAULT_CONVENTIONS_LIMIT),
+    decisions_limit: z.number().int().min(0).max(MAX_DECISIONS_LIMIT).optional().default(DEFAULT_DECISIONS_LIMIT),
 });
 const GetPendingChangesArgsSchema = ProjectRootArgSchema.merge(z.object({
     offset: z.number().int().min(0).optional().default(0),
@@ -1329,7 +1435,7 @@ const InstallRtkArgsSchema = ProjectRootArgSchema.merge(z.object({
     dry_run: z.boolean().optional().default(true),
     method: z.enum(["auto", "cargo", "brew", "shell_script"]).optional().default("auto"),
     init: z
-        .enum(["none", "global_no_patch", "global_auto_patch", "global_hook_only", "local"])
+        .enum(["none", "global_no_patch", "global_auto_patch", "global_hook_only", "local", "codex_global", "codex_local"])
         .optional()
         .default("none"),
     uninstall_wrong_cargo_rtk: z.boolean().optional().default(false),
@@ -1346,6 +1452,28 @@ function escapeLike(pattern) {
 function sha256Hex(input) {
     return crypto.createHash("sha256").update(input).digest("hex");
 }
+function getFileStateHash(dbOrAbsPath) {
+    try {
+        const abs = path.isAbsolute(dbOrAbsPath) ? dbOrAbsPath : path.join(projectRoot, dbOrAbsPath);
+        const st = fs.statSync(abs);
+        if (!st.isFile())
+            return sha256Hex(`non-file:${st.mtimeMs}:${st.size}`);
+        if (st.size <= 5_000_000) {
+            return crypto.createHash("sha256").update(fs.readFileSync(abs)).digest("hex");
+        }
+        return sha256Hex(`large:${st.size}:${Math.floor(st.mtimeMs)}`);
+    }
+    catch {
+        return sha256Hex("missing");
+    }
+}
+function getLatestSyncedFileHash(dbFilePath) {
+    const row = getLatestChangeIntentForFileStmt?.get(dbFilePath);
+    if (!row)
+        return null;
+    const meta = parseMetadataJson(row.metadata_json);
+    return typeof meta.file_state_hash === "string" ? meta.file_state_hash : null;
+}
 function safeJson(value) {
     if (value === undefined)
         return null;
@@ -1409,7 +1537,9 @@ function compactChangeLabel(change) {
     return `change#${change.id} ${change.file_path}: ${oneLine(change.intent_preview, 120)}`;
 }
 function compactPendingLabel(p) {
-    return `${p.last_event} ${p.file_path}`;
+    const source = "source" in p && p.source === "git" ? " git" : "";
+    const status = "git_status" in p && p.git_status ? ` ${p.git_status}` : "";
+    return `${p.last_event}${source}${status} ${p.file_path}`;
 }
 function compactSemanticSearchText(data) {
     const lines = [
@@ -1480,6 +1610,11 @@ function compactBootstrapText(data) {
     lines.push(`ok ctx ${data.root_source} watcher=${data.watcher_enabled ? (data.watcher_ready ? "ready" : "starting") : "off"} root=${data.project_root}`);
     if (data.project_summary)
         lines.push(`summary ${compactMemoryLabel(data.project_summary, 140)}`);
+    if (data.decisions.length) {
+        lines.push("current decisions:");
+        for (const d of data.decisions.slice(0, 5))
+            lines.push(`- ${compactMemoryLabel(d, 160)}`);
+    }
     if (data.pending_total) {
         lines.push(`pending ${data.pending_changes.length}/${data.pending_total}${data.pending_truncated ? " truncated" : ""}: ${data.pending_changes
             .slice(0, 8)
@@ -1523,42 +1658,105 @@ function compactBootstrapText(data) {
 function compactBrainDumpText(data) {
     return compactBootstrapText(data);
 }
-function detectRtk() {
-    const command = process.platform === "win32" ? "rtk.exe" : "rtk";
-    const result = spawnSync(command, ["--version"], {
+function shellQuoteArg(arg) {
+    if (/^[A-Za-z0-9_./:@%+=,-]+$/.test(arg))
+        return arg;
+    if (process.platform === "win32")
+        return `"${arg.replace(/"/g, '\\"')}"`;
+    return `'${arg.replace(/'/g, "'\\''")}'`;
+}
+function getPackageRtkShimPath() {
+    try {
+        const currentDir = path.dirname(fileURLToPath(import.meta.url));
+        const candidate = path.join(currentDir, "rtk-shim.js");
+        if (fs.existsSync(candidate))
+            return candidate;
+    }
+    catch {
+        // import.meta.url may be unavailable only in unexpected runtimes.
+    }
+    return null;
+}
+function runRtkProbe(spec) {
+    const argsPrefix = spec.execArgsPrefix ?? [];
+    const result = spawnSync(spec.execCommand, [...argsPrefix, "--version"], {
         encoding: "utf8",
-        timeout: 2000,
+        timeout: 120_000,
         windowsHide: true,
+        shell: spec.execShell ?? false,
     });
     if (result.status === 0) {
-        const gain = spawnSync(command, ["gain"], {
-            encoding: "utf8",
-            timeout: 5000,
-            windowsHide: true,
-        });
-        const whereCommand = process.platform === "win32" ? "where.exe" : "which";
-        const whereResult = spawnSync(whereCommand, [process.platform === "win32" ? "rtk.exe" : "rtk"], {
+        const gain = spawnSync(spec.execCommand, [...argsPrefix, "gain"], {
             encoding: "utf8",
-            timeout: 2000,
+            timeout: 120_000,
             windowsHide: true,
+            shell: spec.execShell ?? false,
         });
+        let resolvedPath = spec.path;
+        if (spec.source === "path") {
+            const whereCommand = process.platform === "win32" ? "where.exe" : "which";
+            const whereResult = spawnSync(whereCommand, ["rtk"], {
+                encoding: "utf8",
+                timeout: 2000,
+                windowsHide: true,
+            });
+            resolvedPath = whereResult.status === 0 ? oneLine(whereResult.stdout, 240) : resolvedPath;
+        }
         const gainText = `${gain.stdout}${gain.stderr}`.trim();
         return {
             available: gain.status === 0,
-            command,
+            command: spec.displayCommand,
             version: `${result.stdout}${result.stderr}`.trim(),
             gain_ok: gain.status === 0,
             gain_preview: oneLine(gainText, 240),
-            path: whereResult.status === 0 ? oneLine(whereResult.stdout, 240) : undefined,
+            path: resolvedPath,
+            source: spec.source,
+            exec_command: spec.execCommand,
+            exec_args_prefix: argsPrefix,
+            exec_shell: spec.execShell ?? false,
             note: gain.status === 0
-                ? "Prefer prefixing shell commands with rtk for compact outputs, e.g. rtk git status / rtk npm run build / rtk rg pattern ."
-                : "An rtk binary exists, but `rtk gain` failed. This may be the wrong rtk project. Use install_rtk with uninstall_wrong_cargo_rtk=true only after confirming it is safe.",
+                ? spec.source === "package_shim"
+                    ? `Prefer prefixing shell commands with ${spec.displayCommand} for compact outputs. This is VectorMind's bundled RTK shim; first run auto-installs/caches rtk-ai/rtk if needed.`
+                    : "Prefer prefixing shell commands with rtk for compact outputs, e.g. rtk git status / rtk npm run build / rtk rg pattern ."
+                : spec.source === "package_shim"
+                    ? "VectorMind's bundled RTK shim exists, but `gain` failed. Check network/cache or set VECTORMIND_RTK_REAL to an existing rtk-ai/rtk binary."
+                    : "An rtk binary exists, but `rtk gain` failed. This may be the wrong rtk project. Use install_rtk with uninstall_wrong_cargo_rtk=true only after confirming it is safe.",
         };
     }
+    return null;
+}
+function detectRtk() {
+    const pathProbe = runRtkProbe({
+        source: "path",
+        displayCommand: "rtk",
+        execCommand: "rtk",
+        execShell: process.platform === "win32",
+    });
+    if (pathProbe?.available)
+        return pathProbe;
+    const shimPath = getPackageRtkShimPath();
+    if (shimPath) {
+        const displayCommand = `node ${shellQuoteArg(shimPath)}`;
+        const shimProbe = runRtkProbe({
+            source: "package_shim",
+            displayCommand,
+            execCommand: process.execPath,
+            execArgsPrefix: [shimPath],
+            path: shimPath,
+        });
+        if (shimProbe)
+            return shimProbe;
+    }
+    if (pathProbe)
+        return pathProbe;
     return {
         available: false,
-        command,
-        note: "rtk was not found on PATH. VectorMind compact MCP output still works; install rtk to compact shell command output too.",
+        command: shimPath ? `node ${shellQuoteArg(shimPath)}` : "rtk",
+        path: shimPath ?? undefined,
+        source: shimPath ? "package_shim" : undefined,
+        note: shimPath
+            ? "rtk was not found on PATH, and VectorMind's bundled RTK shim could not verify rtk gain. VectorMind compact MCP output still works; check network/cache or set VECTORMIND_RTK_REAL."
+            : "rtk was not found on PATH and the package RTK shim is unavailable. VectorMind compact MCP output still works; install rtk to compact shell command output too.",
     };
 }
 function commandExists(command) {
@@ -1581,6 +1779,40 @@ function runInstallStep(command, args, timeoutMs) {
         output: oneLine(output, 1200),
     };
 }
+function runDetectedRtkStep(detected, args, timeoutMs) {
+    const execCommand = detected.exec_command ?? "rtk";
+    const argsPrefix = detected.exec_args_prefix ?? [];
+    const result = spawnSync(execCommand, [...argsPrefix, ...args], {
+        encoding: "utf8",
+        timeout: timeoutMs,
+        windowsHide: true,
+        shell: detected.exec_shell ?? (execCommand === "rtk" && process.platform === "win32"),
+    });
+    const output = `${result.stdout ?? ""}${result.stderr ?? ""}`.trim();
+    return {
+        command: [detected.command, ...args].join(" "),
+        status: result.status,
+        ok: result.status === 0,
+        output: oneLine(output, 1200),
+    };
+}
+function appendRtkInitStep(steps, detected, init, timeoutMs) {
+    if (init === "none")
+        return;
+    if (init === "global_no_patch")
+        steps.push(runDetectedRtkStep(detected, ["init", "-g", "--no-patch"], timeoutMs));
+    if (init === "global_auto_patch")
+        steps.push(runDetectedRtkStep(detected, ["init", "-g", "--auto-patch"], timeoutMs));
+    if (init === "global_hook_only") {
+        steps.push(runDetectedRtkStep(detected, ["init", "-g", "--hook-only", "--no-patch"], timeoutMs));
+    }
+    if (init === "local")
+        steps.push(runDetectedRtkStep(detected, ["init"], timeoutMs));
+    if (init === "codex_global")
+        steps.push(runDetectedRtkStep(detected, ["init", "-g", "--codex"], timeoutMs));
+    if (init === "codex_local")
+        steps.push(runDetectedRtkStep(detected, ["init", "--codex"], timeoutMs));
+}
 function chooseRtkInstallMethod(method) {
     if (method !== "auto")
         return method;
@@ -1623,6 +1855,10 @@ function buildRtkInstallPlan(args) {
         commands.push("rtk init -g --hook-only --no-patch");
     if (args.init === "local")
         commands.push("rtk init");
+    if (args.init === "codex_global")
+        commands.push("rtk init -g --codex");
+    if (args.init === "codex_local")
+        commands.push("rtk init --codex");
     if (args.init !== "none") {
         notes.push("rtk init may modify Claude/RTK configuration. Use init=none for binary-only installation.");
     }
@@ -1635,6 +1871,9 @@ function installRtk(args) {
     const notes = [...plan.notes];
     if (detectedBefore.available) {
         notes.push("rtk is already installed and verified with `rtk gain`; installation skipped.");
+        if (!args.dry_run && args.init !== "none") {
+            appendRtkInitStep(steps, detectedBefore, args.init, args.timeout_ms);
+        }
         return {
             ok: true,
             dry_run: args.dry_run,
@@ -1682,15 +1921,7 @@ function installRtk(args) {
     }
     const detectedAfterInstall = detectRtk();
     if (detectedAfterInstall.available && args.init !== "none") {
-        if (args.init === "global_no_patch")
-            steps.push(runInstallStep("rtk", ["init", "-g", "--no-patch"], args.timeout_ms));
-        if (args.init === "global_auto_patch")
-            steps.push(runInstallStep("rtk", ["init", "-g", "--auto-patch"], args.timeout_ms));
-        if (args.init === "global_hook_only") {
-            steps.push(runInstallStep("rtk", ["init", "-g", "--hook-only", "--no-patch"], args.timeout_ms));
-        }
-        if (args.init === "local")
-            steps.push(runInstallStep("rtk", ["init"], args.timeout_ms));
+        appendRtkInitStep(steps, detectedAfterInstall, args.init, args.timeout_ms);
     }
     const detectedAfter = detectRtk();
     return {
@@ -1898,6 +2129,88 @@ function dotProduct(a, b) {
         s += a[i] * b[i];
     return s;
 }
+function parseMetadataJson(metadata) {
+    if (!metadata)
+        return {};
+    try {
+        const parsed = JSON.parse(metadata);
+        return parsed && typeof parsed === "object" && !Array.isArray(parsed)
+            ? parsed
+            : {};
+    }
+    catch {
+        return {};
+    }
+}
+function metadataStatus(row) {
+    const meta = parseMetadataJson(row.metadata_json);
+    return typeof meta.status === "string" ? meta.status : "";
+}
+function isSupersededMemory(row) {
+    const meta = parseMetadataJson(row.metadata_json);
+    return meta.superseded === true || meta.status === "superseded";
+}
+function semanticRecencyWeight(updatedAt) {
+    if (!updatedAt)
+        return 0;
+    const t = Date.parse(updatedAt.endsWith("Z") ? updatedAt : `${updatedAt}Z`);
+    if (!Number.isFinite(t))
+        return 0;
+    const ageDays = Math.max(0, (Date.now() - t) / 86_400_000);
+    if (ageDays <= 1)
+        return 0.8;
+    if (ageDays <= 7)
+        return 0.45;
+    if (ageDays <= 30)
+        return 0.2;
+    return 0;
+}
+function semanticKindWeight(kind) {
+    switch (kind) {
+        case "decision":
+            return 3.5;
+        case "convention":
+            return 2.6;
+        case "project_summary":
+            return 2.2;
+        case "note":
+            return 1.1;
+        case "requirement":
+            return 0.4;
+        case "change_intent":
+            return 0.2;
+        default:
+            return 0;
+    }
+}
+function adjustSemanticScore(row, rawScore) {
+    if (isSupersededMemory(row))
+        return rawScore - 1000;
+    let score = rawScore + semanticKindWeight(row.kind) + semanticRecencyWeight(row.updated_at);
+    const status = metadataStatus(row);
+    if (status === "active" || status === "current")
+        score += 1.2;
+    if (row.kind === "change_intent" && row.file_path && shouldIgnoreDbFilePath(row.file_path)) {
+        // Human-synced intent for generated/build/runtime files is often the only durable
+        // "why" for that change. Do not let built-in path ignores hide the decision trail.
+        score += 0.4;
+    }
+    return score;
+}
+function filterAndRankSemanticRows(rows, scoreOf, opts) {
+    return rows
+        .map((r) => ({ row: r, score: adjustSemanticScore(r, scoreOf(r)) }))
+        .filter(({ row }) => {
+        if (isSupersededMemory(row))
+            return false;
+        if (shouldIgnoreDbFilePath(row.file_path) && row.kind !== "change_intent")
+            return false;
+        return true;
+    })
+        .sort((a, b) => b.score - a.score)
+        .slice(0, opts.topK)
+        .map(({ row, score }) => toSemanticMatch(row, score, opts.includeContent, opts.previewChars, opts.contentMaxChars));
+}
 function makePreviewText(content, max) {
     if (max <= 0)
         return "";
@@ -1972,6 +2285,15 @@ function getConventionPreviews(conventionsLimit, previewChars, contentMaxChars)
     const stored = listConventionsStmt.all(remaining).map((c) => toMemoryItemPreview(c, false, previewChars, contentMaxChars));
     return [...builtin, ...stored];
 }
+function getDecisionPreviews(decisionsLimit, previewChars, contentMaxChars) {
+    if (decisionsLimit <= 0)
+        return [];
+    const rows = listCurrentDecisionsStmt.all(Math.min(MAX_DECISIONS_LIMIT * 4, Math.max(decisionsLimit, decisionsLimit * 4)));
+    return rows
+        .filter((d) => !isSupersededMemory(d))
+        .slice(0, decisionsLimit)
+        .map((d) => toMemoryItemPreview(d, false, previewChars, contentMaxChars));
+}
 function toRequirementPreview(req, includeContent, previewChars, contentMaxChars) {
     const context = req.context_data ?? null;
     const contextPreview = context ? makePreviewText(context, previewChars) : null;
@@ -2016,6 +2338,46 @@ function completeAllActiveRequirementMemoryItems() {
         console.error("[vectormind] failed to complete all active requirement memory items:", err);
     }
 }
+function patchMemoryItemMetadata(id, patch) {
+    const row = getMemoryItemByIdStmt.get(id);
+    if (!row)
+        return;
+    const meta = { ...parseMetadataJson(row.metadata_json), ...patch };
+    db.prepare(`UPDATE memory_items SET metadata_json = ?, updated_at = CURRENT_TIMESTAMP WHERE id = ?`).run(safeJson(meta), id);
+}
+function supersedeMemoryItemIds(ids, replacement) {
+    const updated = [];
+    for (const id of Array.from(new Set(ids)).filter((n) => Number.isFinite(n) && n > 0)) {
+        const row = getMemoryItemByIdStmt.get(id);
+        if (!row)
+            continue;
+        patchMemoryItemMetadata(id, {
+            ...parseMetadataJson(row.metadata_json),
+            status: "superseded",
+            superseded: true,
+            superseded_at: new Date().toISOString(),
+            superseded_reason: replacement.reason,
+            superseded_by_req_id: replacement.req_id ?? null,
+            superseded_by_memory_id: replacement.memory_id ?? null,
+            superseded_by_decision_id: replacement.decision_id ?? null,
+        });
+        updated.push(id);
+    }
+    return updated;
+}
+function supersedeRequirementIds(reqIds, replacement) {
+    const updatedReqs = [];
+    for (const reqId of Array.from(new Set(reqIds)).filter((n) => Number.isFinite(n) && n > 0)) {
+        const info = db.prepare(`UPDATE requirements SET status = 'superseded' WHERE id = ?`).run(reqId);
+        if (info.changes > 0)
+            updatedReqs.push(reqId);
+        const rows = db
+            .prepare(`SELECT id FROM memory_items WHERE req_id = ? OR (kind = 'requirement' AND req_id = ?)`)
+            .all(reqId, reqId);
+        supersedeMemoryItemIds(rows.map((r) => r.id), replacement);
+    }
+    return updatedReqs;
+}
 async function semanticSearchInternal(opts) {
     if (!embeddingsEnabled) {
         throw new Error("Embeddings are disabled");
@@ -2067,7 +2429,31 @@ async function semanticSearchInternal(opts) {
         return toSemanticMatch(item, t.score, opts.includeContent, opts.previewChars, opts.contentMaxChars);
     })
         .filter(Boolean);
-    const filtered = matches.filter((m) => !shouldIgnoreDbFilePath(m.item.file_path)).slice(0, opts.topK);
+    const filtered = matches
+        .filter((m) => {
+        if (isSupersededMemory({ metadata_json: m.item.metadata_json }))
+            return false;
+        if (shouldIgnoreDbFilePath(m.item.file_path) && m.item.kind !== "change_intent")
+            return false;
+        return true;
+    })
+        .map((m) => ({
+        ...m,
+        score: adjustSemanticScore({
+            id: m.item.id,
+            kind: m.item.kind,
+            title: m.item.title,
+            content: m.item.content ?? m.item.preview,
+            file_path: m.item.file_path,
+            start_line: m.item.start_line,
+            end_line: m.item.end_line,
+            req_id: m.item.req_id,
+            metadata_json: m.item.metadata_json,
+            updated_at: m.item.updated_at,
+        }, m.score),
+    }))
+        .sort((a, b) => b.score - a.score)
+        .slice(0, opts.topK);
     return { query: q, top_k: opts.topK, mode: "embeddings", matches: filtered };
 }
 function buildFtsMatchQuery(raw) {
@@ -2136,10 +2522,7 @@ function ftsSearchInternal(opts) {
     `);
         return stmt.all(matchQuery, rawLimit);
     })();
-    const matches = rows
-        .map((r) => toSemanticMatch(r, -Number(r.rank), opts.includeContent, opts.previewChars, opts.contentMaxChars))
-        .filter((m) => !shouldIgnoreDbFilePath(m.item.file_path))
-        .slice(0, opts.topK);
+    const matches = filterAndRankSemanticRows(rows, (r) => -Number(r.rank), opts);
     return { query: q, top_k: opts.topK, mode: "fts", matches };
 }
 function likeSearchInternal(opts) {
@@ -2205,10 +2588,7 @@ function likeSearchInternal(opts) {
     `);
         return stmt.all(like, like, like, like, like, rawLimit);
     })();
-    const matches = rows
-        .map((r) => toSemanticMatch(r, Number(r.score), opts.includeContent, opts.previewChars, opts.contentMaxChars))
-        .filter((m) => !shouldIgnoreDbFilePath(m.item.file_path))
-        .slice(0, opts.topK);
+    const matches = filterAndRankSemanticRows(rows, (r) => Number(r.score), opts);
     return { query: q, top_k: opts.topK, mode: "like", matches };
 }
 async function semanticSearchHybridInternal(opts) {
@@ -2933,65 +3313,59 @@ function listProjectFilesInternal(opts) {
 function buildServerInstructions() {
     return [
         "VectorMind MCP is available in this session. Use it to avoid guessing project context.",
-        "This package ships built-in baseline policy. If a client supports MCP instructions, these rules auto-apply as soon as the MCP is installed and connected; no user-side config file is required.",
-        "The write-operation rules below are strict workflow constraints. Do not claim that the environment has real git branch locks, checkout APIs, or file-lock tools unless such tools are actually available in the current client/runtime. If such tools are absent, you must still enforce the same exclusivity semantics through explicit coordination and serialized same-file edits.",
+        "Development guideline scope: VectorMind instructions define development conventions, project-memory conventions, code-organization conventions, and delivery-quality expectations only. They are unrelated to AI access permissions, runtime permissions, command permissions, filesystem/network permissions, approval mechanisms, or sandbox behavior.",
         "Project root resolution order: tool argument project_root (recommended for clients without roots/list), then VECTORMIND_ROOT (avoid hardcoding in global config), then MCP roots/list (best-effort; falls back quickly if unsupported), then process.cwd() (so start your MCP client in the project directory for per-project isolation).",
         "If root_source is fallback, file watching/indexing is disabled (pass project_root to enable per-project tracking).",
         "",
-        "Built-in write-operation policy:",
+        "Built-in write-operation quality policy:",
         BUILTIN_WRITE_POLICY_INSTRUCTIONS,
         "",
-        "Built-in task-list / Plan-Lite policy:",
+        "Built-in task-list / Plan-Lite quality policy:",
         BUILTIN_PLAN_LITE_INSTRUCTIONS,
         "",
-        "Built-in destructive-operation guard policy:",
+        "Built-in destructive-operation quality guard:",
         BUILTIN_DESTRUCTIVE_OPERATION_GUARD_INSTRUCTIONS,
         "",
-        "Built-in architecture and code-organization policy:",
+        "Built-in architecture and code-organization quality policy:",
         BUILTIN_ARCHITECTURE_AND_CODE_ORGANIZATION_INSTRUCTIONS,
         "",
-        "Built-in frontend output-purity policy:",
+        "Built-in frontend output-purity quality policy:",
         BUILTIN_FRONTEND_OUTPUT_PURITY_INSTRUCTIONS,
         "",
-        "Built-in git commit summary policy:",
+        "Built-in git commit summary quality policy:",
         BUILTIN_GIT_COMMIT_SUMMARY_INSTRUCTIONS,
         "",
-        "Built-in low-overhead execution and heavy-thread policy:",
+        "Built-in low-overhead execution and heavy-thread quality policy:",
         BUILTIN_LOW_OVERHEAD_WORKFLOW_INSTRUCTIONS,
         "",
-        "Built-in payload / oversized-thread guard policy:",
+        "Built-in payload / oversized-thread quality guard:",
         BUILTIN_PAYLOAD_GUARD_INSTRUCTIONS,
         "",
-        "Built-in thread handoff / switch-gate policy:",
+        "Built-in thread handoff / switch-gate quality policy:",
         BUILTIN_THREAD_HANDOFF_SWITCH_INSTRUCTIONS,
         "",
-        "Required workflow:",
+        "VectorMind workflow:",
         "- Tool outputs are compact by default. Pass format=json only when you need full structured data.",
         "- On every new conversation/session for analysis/design/development work: call bootstrap_context({ query: <current goal> }) first (or at least get_brain_dump()) to restore compact context and retrieve relevant matches from the local memory store (vector if enabled; otherwise FTS/LIKE).",
         "  - Output is compact by default. Use include_content=true only when you truly need full text (it increases tokens).",
-        "  - Tune output size with: requirements_limit/changes_limit/notes_limit, preview_chars, pending_limit/pending_offset.",
+        "  - Tune output size with: requirements_limit/changes_limit/notes_limit/decisions_limit, preview_chars, pending_limit/pending_offset.",
         "  - Prefer read_memory_item(id, offset, limit) to fetch full text on demand instead of returning large content in other tool outputs.",
         "- For pure execution-first tasks with explicit targets (for example compile/build/run/launch/package/publish/test rerun), you may skip retrieval and go straight to the minimum necessary shell or host tools unless code/context lookup is actually needed to unblock execution.",
-        "- If rtk is installed and verified (detect_rtk with gain_ok=true), prefix shell commands with rtk where possible (rtk git status, rtk npm run build, rtk rg ...) so command output is compact before it reaches the model.",
+        "- If rtk is installed or VectorMind's bundled RTK shim is verified (detect_rtk with gain_ok=true), prefix shell commands with the command returned by detect_rtk. Usually this is rtk (rtk git status, rtk npm run build, rtk rg ...); in npx/MCP-only installs it may be a package shim command such as node <...>/rtk-shim.js.",
         "- If rtk is missing and the user asks to install it, use install_rtk first with dry_run=true to show the exact commands; execute with dry_run=false only after the user clearly approves installation/init choices.",
         "- To read local Codex skill/prompt/rule files (for example SKILL.md under CODEX_HOME or AGENTS_HOME), prefer read_codex_text_file({ path }) instead of assuming a filesystem MCP resource server exists.",
         "- For project file/directory browsing, prefer list_project_files({ path, recursive?, max_depth? }) over shelling out to Get-ChildItem/ls. It respects ignore rules and keeps output bounded.",
         "- For small/medium raw file reads, prefer read_file_text({ path, offset?, max_chars? }) over Get-Content -Raw. Use read_file_lines(...) when you need deterministic line ranges or the file may be large.",
         "- For raw repo text search with exact file+line+col matches, prefer grep({ query: <pattern> }). It uses ripgrep against real project files when available, applies built-in noise filters, and only falls back to indexed search if ripgrep is unavailable.",
         "- To read a bounded segment of a file, prefer read_file_lines({ path: <file>, from_line/to_line or total_count }) over unbounded file reads.",
-        "- If the current thread is heavy, recently compacted, has become slow, or has already hit a 413 / Payload Too Large style error, switch to payload guard mode: avoid unbounded shell dumps, prefer bounded MCP tools, and summarize outputs instead of pasting large raw blocks.",
-        "- In payload guard mode, do not use full-repo recursive listings, whole-file dumps, or broad raw match echo unless the user explicitly requests that raw output and accepts the size risk.",
-        "- Thread-switch judgment must not rely on a fixed token threshold; use observable signals plus the weight of the upcoming work. If the current thread is heavy, repeatedly compacting, slow, or has already hit a 413 / Payload Too Large style error and the next work still needs broad analysis, cross-module investigation, release validation, or other substantial continuation, pause once and ask whether to switch to a fresh thread before continuing.",
-        "- If the user declines that switch, continue in the current thread and do not raise the thread-switch reminder again in the same session.",
-        "- If the user accepts, or explicitly asks you to pack the current conversation for a new thread, do not attempt to create a new thread on the user's behalf and do not claim that you already created one. Use add_note(...) to persist a concise handoff note, include other relevant existing note ids only when they are truly needed, then reply briefly with the new handoff note id and tell the user that in the new thread they can say '读取 note <id> [和 note <id>] 继续'.",
         "- BEFORE editing code: call start_requirement(title, background) to set the active requirement.",
         "- AFTER editing + saving: call get_pending_changes() to see unsynced files, then call sync_change_intent(intent, files). (You can omit files to auto-link all pending changes.)",
         "- After major milestones/decisions: call upsert_project_summary(summary) and/or add_note(...) to persist durable context locally.",
+        "- When a requirement or user decision changes/reverses an older behavior, call upsert_decision(key, title, content, supersedes_req_ids?/supersedes_memory_ids?) and/or supersede_memory(...). Current decisions are shown in bootstrap_context/get_brain_dump and superseded memories are hidden from default semantic recall so stale requirements do not override newer facts.",
         "- If the user states a durable project convention (build commands, frameworks, naming rules, output paths): call upsert_convention(key, content, tags) so it is applied in future sessions.",
         "- When you need full text for a specific note/summary/match: call read_memory_item(id, offset, limit) and page through it.",
         "- When asked to locate code (class/function/type): call query_codebase(query) instead of guessing.",
         "- When you need to recall relevant context from history/code/docs: call semantic_search(query, ...) instead of guessing.",
-        "- If the current thread is already heavy or the user reports it has become slow, switch to a lighter workflow: avoid redundant retrieval, keep outputs compact, and if the user refuses thread switching, continue in light mode without repeating the switch reminder in that same session.",
         "- Use get_token_savings({ format: 'compact' }) when you need to verify how many tokens VectorMind compact outputs saved.",
         "",
         "If tool output conflicts with assumptions, trust the tool output.",
@@ -3211,6 +3585,9 @@ function initDatabase() {
     CREATE UNIQUE INDEX IF NOT EXISTS idx_memory_items_convention_key
       ON memory_items(kind, title) WHERE kind = 'convention';
 
+    CREATE UNIQUE INDEX IF NOT EXISTS idx_memory_items_decision_key
+      ON memory_items(kind, title) WHERE kind = 'decision';
+
     CREATE INDEX IF NOT EXISTS idx_memory_items_kind_updated_at
       ON memory_items(kind, updated_at DESC);
 
@@ -3307,6 +3684,23 @@ function initDatabase() {
      WHERE kind = 'convention'
      ORDER BY updated_at DESC, id DESC
      LIMIT ?`);
+    upsertDecisionStmt = db.prepare(`INSERT INTO memory_items (kind, title, content, metadata_json, content_hash)
+     VALUES ('decision', ?, ?, ?, ?)
+     ON CONFLICT DO UPDATE SET
+       content = excluded.content,
+       metadata_json = excluded.metadata_json,
+       content_hash = excluded.content_hash,
+       updated_at = CURRENT_TIMESTAMP`);
+    getDecisionByKeyStmt = db.prepare(`SELECT id, kind, title, content, file_path, start_line, end_line, req_id, metadata_json, content_hash, created_at, updated_at
+     FROM memory_items
+     WHERE kind = 'decision' AND title = ?
+     ORDER BY updated_at DESC, id DESC
+     LIMIT 1`);
+    listCurrentDecisionsStmt = db.prepare(`SELECT id, kind, title, content, file_path, start_line, end_line, req_id, metadata_json, content_hash, created_at, updated_at
+     FROM memory_items
+     WHERE kind = 'decision'
+     ORDER BY updated_at DESC, id DESC
+     LIMIT ?`);
     getRequirementMemoryItemIdStmt = db.prepare(`SELECT id
      FROM memory_items
      WHERE kind = 'requirement' AND req_id = ?
@@ -3329,6 +3723,11 @@ function initDatabase() {
      WHERE kind = 'note'
      ORDER BY updated_at DESC, id DESC
      LIMIT ?`);
+    getLatestChangeIntentForFileStmt = db.prepare(`SELECT id, kind, title, content, file_path, start_line, end_line, req_id, metadata_json, content_hash, created_at, updated_at
+     FROM memory_items
+     WHERE kind = 'change_intent' AND file_path = ?
+     ORDER BY updated_at DESC, id DESC
+     LIMIT 1`);
     deleteFileChunkItemsStmt = db.prepare(`DELETE FROM memory_items
      WHERE file_path = ?
        AND (kind = 'code_chunk' OR kind = 'doc_chunk')`);
@@ -3598,7 +3997,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             },
             {
                 name: "detect_rtk",
-                description: "Detect whether rtk is available on PATH. When available, prefer rtk-prefixed shell commands to reduce command-output tokens.",
+                description: "Detect whether rtk is available on PATH or via VectorMind's bundled RTK shim. When available, prefer the returned command as a shell prefix to reduce command-output tokens.",
                 inputSchema: toJsonSchemaCompat(DetectRtkArgsSchema),
             },
             {
@@ -3651,6 +4050,16 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                 description: "Save a durable project note (decision, constraint, TODO, architecture detail). Use this to persist important context locally instead of relying on chat memory.",
                 inputSchema: toJsonSchemaCompat(AddNoteArgsSchema),
             },
+            {
+                name: "upsert_decision",
+                description: "Save/update the current authoritative project decision for a key. Use it when requirements change, reverse, or supersede older behavior so future sessions prefer the latest decision over old history.",
+                inputSchema: toJsonSchemaCompat(UpsertDecisionArgsSchema),
+            },
+            {
+                name: "supersede_memory",
+                description: "Mark old requirements or memory items as superseded by a newer requirement/decision. Superseded items are hidden from default semantic recall to avoid reverting to stale behavior.",
+                inputSchema: toJsonSchemaCompat(SupersedeMemoryArgsSchema),
+            },
             {
                 name: "upsert_convention",
                 description: "Save/update a project convention (framework choice, build command, naming rules, etc). Conventions are durable and should be applied automatically in future sessions.",
@@ -3882,24 +4291,14 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 }
                 else {
                     const pendingAll = listPendingChangesStmt.all();
-                    if (pendingAll.length) {
-                        const pending = pendingAll.filter((p) => !shouldIgnoreDbFilePath(p.file_path));
-                        if (pending.length) {
-                            for (const p of pending) {
-                                targets.push({
-                                    rawFile: p.file_path,
-                                    dbFilePath: p.file_path,
-                                    event: p.last_event,
-                                    source: "pending",
-                                });
-                            }
-                        }
-                        else {
+                    const merged = mergePendingWithGit(pendingAll, { offset: 0, limit: MAX_PENDING_LIMIT });
+                    if (merged.page.length) {
+                        for (const p of merged.page) {
                             targets.push({
-                                rawFile: "(unspecified)",
-                                dbFilePath: "(unspecified)",
-                                event: "manual",
-                                source: "unspecified",
+                                rawFile: p.file_path,
+                                dbFilePath: p.file_path,
+                                event: p.last_event,
+                                source: p.source === "git" ? "pending" : "pending",
                             });
                         }
                         deleteAllPendingChangesStmt.run();
@@ -3917,7 +4316,12 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     const isUnspecified = t.dbFilePath === "(unspecified)";
                     const changeInfo = insertChangeLogStmt.run(active.id, t.dbFilePath, args.intent);
                     const change_log_id = Number(changeInfo.lastInsertRowid);
-                    const memoryInfo = insertMemoryItemStmt.run("change_intent", active.title, args.intent, isUnspecified ? null : t.dbFilePath, null, null, active.id, safeJson({ change_log_id, event: t.event, source: t.source }), sha256Hex(args.intent));
+                    const memoryInfo = insertMemoryItemStmt.run("change_intent", active.title, args.intent, isUnspecified ? null : t.dbFilePath, null, null, active.id, safeJson({
+                        change_log_id,
+                        event: t.event,
+                        source: t.source,
+                        file_state_hash: isUnspecified ? null : getFileStateHash(t.rawFile),
+                    }), sha256Hex(args.intent));
                     const memory_item_id = Number(memoryInfo.lastInsertRowid);
                     enqueueEmbedding(memory_item_id);
                     synced_files.push({ file_path: t.dbFilePath, event: t.event, source: t.source });
@@ -3968,6 +4372,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             const changesLimit = args.changes_limit;
             const notesLimit = args.notes_limit;
             const conventionsLimit = args.conventions_limit;
+            const decisionsLimit = args.decisions_limit;
             const recent = listRecentRequirementsStmt.all(requirementsLimit);
             const items = recent.map((req) => {
                 const changes = listChangeLogsForRequirementStmt.all(req.id, changesLimit);
@@ -3981,12 +4386,15 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 ? toMemoryItemPreview(projectSummaryRow, includeContent, previewChars, contentMaxChars)
                 : null;
             const recent_notes = listRecentNotesStmt.all(notesLimit).map((n) => toMemoryItemPreview(n, includeContent, previewChars, contentMaxChars));
+            const decisions = getDecisionPreviews(decisionsLimit, previewChars, contentMaxChars);
             const conventions = getConventionPreviews(conventionsLimit, previewChars, contentMaxChars);
-            const pending_total = Number(countPendingChangesStmt.get()?.total ?? 0);
             const pending_offset = args.pending_offset;
             const pending_limit = args.pending_limit;
-            const pending_truncated = pending_total > pending_offset + pending_limit;
-            const pending_changes = listPendingChangesPageStmt.all(pending_limit, pending_offset).filter((p) => !shouldIgnoreDbFilePath(p.file_path));
+            const pendingDbRows = listPendingChangesStmt.all();
+            const mergedPending = mergePendingWithGit(pendingDbRows, { offset: pending_offset, limit: pending_limit });
+            const pending_total = mergedPending.total;
+            const pending_truncated = mergedPending.truncated;
+            const pending_changes = mergedPending.page;
             const q = args.query?.trim() ?? "";
             const semantic = q
                 ? await Promise.race([
@@ -4009,6 +4417,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 pending_total,
                 pending_returned: pending_changes.length,
                 requirements_returned: items.length,
+                decisions_returned: decisions.length,
                 conventions_returned: conventions.length,
                 semantic_mode: semantic?.mode ?? null,
                 semantic_matches: semantic?.matches?.length ?? 0,
@@ -4034,9 +4443,11 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     requirements_limit: requirementsLimit,
                     changes_limit: changesLimit,
                     notes_limit: notesLimit,
+                    decisions_limit: decisionsLimit,
                     conventions_limit: conventionsLimit,
                 },
                 project_summary,
+                decisions,
                 conventions,
                 recent_notes,
                 pending_total,
@@ -4066,6 +4477,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             const changesLimit = args.changes_limit;
             const notesLimit = args.notes_limit;
             const conventionsLimit = args.conventions_limit;
+            const decisionsLimit = args.decisions_limit;
             const recent = listRecentRequirementsStmt.all(requirementsLimit);
             const items = recent.map((req) => {
                 const changes = listChangeLogsForRequirementStmt.all(req.id, changesLimit);
@@ -4079,17 +4491,21 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 ? toMemoryItemPreview(projectSummaryRow, includeContent, previewChars, contentMaxChars)
                 : null;
             const recent_notes = listRecentNotesStmt.all(notesLimit).map((n) => toMemoryItemPreview(n, includeContent, previewChars, contentMaxChars));
+            const decisions = getDecisionPreviews(decisionsLimit, previewChars, contentMaxChars);
             const conventions = getConventionPreviews(conventionsLimit, previewChars, contentMaxChars);
-            const pending_total = Number(countPendingChangesStmt.get()?.total ?? 0);
             const pending_offset = args.pending_offset;
             const pending_limit = args.pending_limit;
-            const pending_truncated = pending_total > pending_offset + pending_limit;
-            const pending_changes = listPendingChangesPageStmt.all(pending_limit, pending_offset).filter((p) => !shouldIgnoreDbFilePath(p.file_path));
+            const pendingDbRows = listPendingChangesStmt.all();
+            const mergedPending = mergePendingWithGit(pendingDbRows, { offset: pending_offset, limit: pending_limit });
+            const pending_total = mergedPending.total;
+            const pending_truncated = mergedPending.truncated;
+            const pending_changes = mergedPending.page;
             logActivity("get_brain_dump", {
                 pending_total,
                 pending_returned: pending_changes.length,
                 requirements_returned: items.length,
                 notes_returned: recent_notes.length,
+                decisions_returned: decisions.length,
                 conventions_returned: conventions.length,
             });
             const outputValue = {
@@ -4113,9 +4529,11 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     requirements_limit: requirementsLimit,
                     changes_limit: changesLimit,
                     notes_limit: notesLimit,
+                    decisions_limit: decisionsLimit,
                     conventions_limit: conventionsLimit,
                 },
                 project_summary,
+                decisions,
                 conventions,
                 recent_notes,
                 pending_total,
@@ -4138,11 +4556,13 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         if (toolName === "get_pending_changes") {
             const args = GetPendingChangesArgsSchema.parse(rawArgs);
             flushPendingChangeBuffer();
-            const total = Number(countPendingChangesStmt.get()?.total ?? 0);
             const offset = args.offset;
             const limit = args.limit;
-            const truncated = total > offset + limit;
-            const pending = listPendingChangesPageStmt.all(limit, offset).filter((p) => !shouldIgnoreDbFilePath(p.file_path));
+            const pendingDbRows = listPendingChangesStmt.all();
+            const mergedPending = mergePendingWithGit(pendingDbRows, { offset, limit });
+            const total = mergedPending.total;
+            const truncated = mergedPending.truncated;
+            const pending = mergedPending.page;
             logActivity("get_pending_changes", {
                 total,
                 offset,
@@ -4315,8 +4735,8 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             DetectRtkArgsSchema.parse(rawArgs);
             const result = detectRtk();
             const text = result.available
-                ? `rtk available: ${result.version ?? result.command}\ngain_ok=${result.gain_ok ?? false}${result.path ? ` path=${result.path}` : ""}\n${result.note}`
-                : `rtk unavailable: ${result.command}\ngain_ok=${result.gain_ok ?? false}${result.version ? ` version=${result.version}` : ""}\n${result.note}`;
+                ? `rtk available: ${result.version ?? result.command}\ncommand=${result.command} source=${result.source ?? "unknown"} gain_ok=${result.gain_ok ?? false}${result.path ? ` path=${result.path}` : ""}\n${result.note}`
+                : `rtk unavailable: ${result.command}\nsource=${result.source ?? "none"} gain_ok=${result.gain_ok ?? false}${result.version ? ` version=${result.version}` : ""}${result.path ? ` path=${result.path}` : ""}\n${result.note}`;
             return { content: [{ type: "text", text }] };
         }
         if (toolName === "install_rtk") {
@@ -4812,6 +5232,95 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 ],
             };
         }
+        if (toolName === "upsert_decision") {
+            const args = UpsertDecisionArgsSchema.parse(rawArgs);
+            const key = args.key.trim();
+            const title = args.title.trim() || key;
+            const content = args.content.trim();
+            const meta = {
+                status: "current",
+                key,
+                title,
+                tags: args.tags ?? [],
+                supersedes_req_ids: args.supersedes_req_ids ?? [],
+                supersedes_memory_ids: args.supersedes_memory_ids ?? [],
+                related_files: (args.related_files ?? []).map((f) => normalizeToDbPath(f)),
+            };
+            upsertDecisionStmt.run(key, `${title}\n\n${content}`, safeJson(meta), sha256Hex(`${title}\n\n${content}`));
+            const row = getDecisionByKeyStmt.get(key);
+            if (row)
+                enqueueEmbedding(row.id);
+            const superseded_requirements = supersedeRequirementIds(args.supersedes_req_ids ?? [], {
+                decision_id: row?.id,
+                reason: `Superseded by decision ${key}: ${title}`,
+            });
+            const superseded_memory_items = supersedeMemoryItemIds(args.supersedes_memory_ids ?? [], {
+                decision_id: row?.id,
+                reason: `Superseded by decision ${key}: ${title}`,
+            });
+            logActivity("upsert_decision", {
+                key,
+                decision_id: row?.id ?? null,
+                superseded_requirements,
+                superseded_memory_items,
+            });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: toolJson({
+                            ok: true,
+                            decision: row ? { id: row.id, key, updated_at: row.updated_at } : null,
+                            superseded_requirements,
+                            superseded_memory_items,
+                        }),
+                    },
+                ],
+            };
+        }
+        if (toolName === "supersede_memory") {
+            const args = SupersedeMemoryArgsSchema.parse(rawArgs);
+            const supersededReqIds = args.superseded_req_ids ?? [];
+            const supersededMemoryIds = args.superseded_memory_ids ?? [];
+            if (!supersededReqIds.length && !supersededMemoryIds.length) {
+                return {
+                    isError: true,
+                    content: [
+                        {
+                            type: "text",
+                            text: toolJson({
+                                ok: false,
+                                error: "Provide superseded_req_ids and/or superseded_memory_ids.",
+                            }),
+                        },
+                    ],
+                };
+            }
+            const superseded_requirements = supersedeRequirementIds(supersededReqIds, {
+                req_id: args.replacement_req_id,
+                memory_id: args.replacement_memory_id,
+                reason: args.reason,
+            });
+            const superseded_memory_items = supersedeMemoryItemIds(supersededMemoryIds, {
+                req_id: args.replacement_req_id,
+                memory_id: args.replacement_memory_id,
+                reason: args.reason,
+            });
+            logActivity("supersede_memory", {
+                superseded_requirements,
+                superseded_memory_items,
+                replacement_req_id: args.replacement_req_id ?? null,
+                replacement_memory_id: args.replacement_memory_id ?? null,
+            });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: toolJson({ ok: true, superseded_requirements, superseded_memory_items }),
+                    },
+                ],
+            };
+        }
         if (toolName === "upsert_convention") {
             const args = UpsertConventionArgsSchema.parse(rawArgs);
             const key = args.key.trim();