@luckychen1993/pm-mcp 0.1.5 → 0.4.0

package/dist/duplicates.js

@@ -0,0 +1,228 @@
+import fs from "node:fs";
+import path from "node:path";
+import { foldLines } from "./budget.js";
+import { ensureFresh, getIndex } from "./index-store.js";
+/**
+ * 重复代码检测（零依赖、确定性）：行指纹滑动窗口聚类。
+ *
+ * 归一化规则：剥离注释（按语言族：// 与 # 、块注释 /* *\/）、字符串字面量内容替换为占位符、
+ * 空白折叠——因此注释/空白/字面量文本的差异不算差异，标识符与结构差异才算。
+ * 聚类：对每个哈希相同且出现在 ≥2 个文件的窗口做连续对齐合并（成对扩展成长块），
+ * 长度 ≥ minLines（有效代码行）的块按长度降序输出。仅跨文件重复计入 v1。
+ */
+export const DUPLICATE_SOURCE_EXTENSIONS = new Set([
+    ".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".mts", ".cts",
+    ".py", ".go", ".rs", ".java", ".kt", ".kts", ".cs", ".c", ".h", ".cpp", ".hpp",
+    ".php", ".rb", ".swift", ".scala", ".vue", ".svelte",
+]);
+const MAX_FILE_BYTES = 400 * 1024;
+const MAX_RUNS = 5000;
+const MAX_LOCATIONS_PER_HASH = 8;
+const SLASH_STYLE = { lineMarkers: ["//"], blockOpen: "/*", blockClose: "*/" };
+const HASH_STYLE = { lineMarkers: ["#"], blockOpen: null, blockClose: null };
+function styleFor(ext) {
+    return ext === ".py" || ext === ".rb" ? HASH_STYLE : SLASH_STYLE;
+}
+/** 单遍扫描：跨行维护块注释与字符串状态；字符串内容丢弃、留一个占位符。 */
+function normalizeLines(content, style) {
+    const out = [];
+    let inBlock = false;
+    let inString = null;
+    let buffer = "";
+    let lineNo = 1;
+    const flush = () => {
+        const norm = buffer.replace(/\s+/g, " ").trim();
+        if (norm.length > 0)
+            out.push({ norm, line: lineNo });
+        buffer = "";
+    };
+    for (let i = 0; i < content.length; i++) {
+        const ch = content[i];
+        if (ch === "\n") {
+            flush();
+            lineNo += 1;
+            continue;
+        }
+        if (inBlock) {
+            if (style.blockClose && content.startsWith(style.blockClose, i)) {
+                inBlock = false;
+                i += style.blockClose.length - 1;
+            }
+            continue;
+        }
+        if (inString) {
+            if (ch === "\\") {
+                i += 1;
+                continue;
+            }
+            if (ch === inString)
+                inString = null;
+            continue;
+        }
+        if (style.blockOpen && content.startsWith(style.blockOpen, i)) {
+            inBlock = true;
+            i += style.blockOpen.length - 1;
+            continue;
+        }
+        if (style.lineMarkers.some((marker) => content.startsWith(marker, i))) {
+            while (i < content.length && content[i] !== "\n")
+                i += 1;
+            i -= 1;
+            continue;
+        }
+        if (ch === '"' || ch === "'" || ch === "`") {
+            inString = ch;
+            buffer += "s";
+            continue;
+        }
+        buffer += ch;
+    }
+    flush();
+    return out;
+}
+/** 双 32 位 djb2 变体拼成 64-bit 指纹；跨平台确定性，够抵御行级指纹碰撞。 */
+function hashLines(joined) {
+    let h1 = 5381;
+    let h2 = 52711;
+    for (let i = 0; i < joined.length; i++) {
+        const code = joined.charCodeAt(i);
+        h1 = ((h1 * 33) ^ code) >>> 0;
+        h2 = (h2 * 31 + code) >>> 0;
+    }
+    return h1.toString(16).padStart(8, "0") + h2.toString(16).padStart(8, "0");
+}
+const clamp = (value, min, max, fallback) => {
+    const n = Math.trunc(value ?? fallback);
+    return Math.min(max, Math.max(min, Number.isFinite(n) ? n : fallback));
+};
+export function findDuplicateBlocks(root, options = {}) {
+    const started = Date.now();
+    const minLines = clamp(options.minLines, 4, 20, 6);
+    const limit = clamp(options.limit, 1, 100, 20);
+    ensureFresh(root);
+    const db = getIndex(root);
+    const rows = db.prepare("SELECT rel, size, oversize FROM files WHERE skip = 0").all();
+    let skippedOversize = rows.filter((row) => row.oversize !== 0).length;
+    const normalized = new Map();
+    let scannedFiles = 0;
+    for (const row of rows) {
+        const ext = path.extname(row.rel).toLowerCase();
+        if (!DUPLICATE_SOURCE_EXTENSIONS.has(ext))
+            continue;
+        if (row.oversize !== 0 || row.size > MAX_FILE_BYTES) {
+            skippedOversize += 1;
+            continue;
+        }
+        let content;
+        try {
+            content = fs.readFileSync(path.join(root, row.rel), "utf8");
+        }
+        catch {
+            continue;
+        }
+        normalized.set(row.rel, normalizeLines(content, styleFor(ext)));
+        scannedFiles += 1;
+    }
+    // 窗口指纹 → 位置（按文件名规范排序，保证成对遍历确定性）
+    const windows = new Map();
+    for (const [rel, lines] of normalized) {
+        if (lines.length < minLines)
+            continue;
+        for (let i = 0; i + minLines <= lines.length; i++) {
+            const slice = lines.slice(i, i + minLines);
+            const key = hashLines(slice.map((item) => item.norm).join("\n"));
+            const bucket = windows.get(key);
+            if (bucket)
+                bucket.push({ file: rel, index: i, line: slice[0].line });
+            else
+                windows.set(key, [{ file: rel, index: i, line: slice[0].line }]);
+        }
+    }
+    // 先按哈希收集全部成对匹配，再按索引排序做连续对齐合并——顺序处理才能拼出完整长块
+    const pairMatches = new Map();
+    let truncated = false;
+    for (const locations of windows.values()) {
+        if (locations.length < 2)
+            continue;
+        const sorted = [...locations].sort((x, y) => x.file.localeCompare(y.file) || x.index - y.index);
+        if (sorted.length > MAX_LOCATIONS_PER_HASH)
+            truncated = true;
+        const capped = sorted.slice(0, MAX_LOCATIONS_PER_HASH);
+        for (let i = 0; i < capped.length; i++) {
+            for (let j = i + 1; j < capped.length; j++) {
+                const p = capped[i], q = capped[j];
+                if (p.file === q.file)
+                    continue; // v1 只报跨文件重复
+                const pairKey = p.file < q.file ? `${p.file}\u0000${q.file}` : `${q.file}\u0000${p.file}`;
+                const forward = p.file < q.file;
+                const match = forward
+                    ? { a: p.file, b: q.file, indexA: p.index, indexB: q.index }
+                    : { a: q.file, b: p.file, indexA: q.index, indexB: p.index };
+                const list = pairMatches.get(pairKey);
+                if (list)
+                    list.push(match);
+                else
+                    pairMatches.set(pairKey, [match]);
+            }
+        }
+    }
+    const pairRuns = new Map();
+    const runs = [];
+    for (const [pairKey, matches] of pairMatches) {
+        matches.sort((x, y) => x.indexA - y.indexA || x.indexB - y.indexB);
+        for (const match of matches) {
+            const list = pairRuns.get(pairKey);
+            const previous = list?.[list.length - 1];
+            if (previous && previous.endA === match.indexA - 1 && previous.endB === match.indexB - 1) {
+                previous.endA = match.indexA;
+                previous.endB = match.indexB;
+                previous.len += 1;
+                continue;
+            }
+            if (runs.length >= MAX_RUNS) {
+                truncated = true;
+                break;
+            }
+            const run = { a: match.a, b: match.b, startA: match.indexA, startB: match.indexB, endA: match.indexA, endB: match.indexB, len: 1 };
+            if (list)
+                list.push(run);
+            else
+                pairRuns.set(pairKey, [run]);
+            runs.push(run);
+        }
+        if (truncated)
+            break;
+    }
+    const linesOf = (rel) => normalized.get(rel) ?? [];
+    const toRange = (file, startIndex, len) => {
+        const lines = linesOf(file);
+        const first = lines[startIndex]?.line ?? startIndex + 1;
+        const last = lines[Math.min(startIndex + len - 1, lines.length - 1)]?.line ?? first;
+        return { file, start: first, end: Math.max(first, last) };
+    };
+    const groups = runs
+        .sort((x, y) => y.len - x.len || x.a.localeCompare(y.a) || x.b.localeCompare(y.b) || x.startA - y.startA)
+        .slice(0, limit)
+        .map((run) => ({
+        lines: run.len + minLines - 1,
+        members: [toRange(run.a, run.startA, run.len + minLines - 1), toRange(run.b, run.startB, run.len + minLines - 1)],
+    }));
+    return { scannedFiles, skippedOversize, threshold: minLines, groups, truncated, durationMs: Date.now() - started };
+}
+export function renderDuplicates(root, options = {}, maxLines = 150) {
+    const scan = findDuplicateBlocks(root, options);
+    const lines = [
+        "## 重复代码",
+        `- 扫描: ${scan.scannedFiles} 个源文件（超限跳过 ${scan.skippedOversize}）· 阈值 ≥${scan.threshold} 有效代码行 · 跨文件 · 耗时 ${scan.durationMs}ms`,
+    ];
+    if (scan.groups.length === 0)
+        lines.push("- ✅ 未发现跨文件重复块");
+    else {
+        lines.push(`- 共列出 ${scan.groups.length} 组重复（按长度降序${scan.truncated ? "，已达运行上限截断" : ""}）：`);
+        scan.groups.forEach((group, index) => {
+            const members = group.members.map((m) => `${m.file}:${m.start}-${m.end}`).join(" ↔ ");
+            lines.push(`- 组${index + 1}（${group.lines} 行）${members}`);
+        });
+    }
+    return foldLines(lines, { maxLines, hint: "调高 min_lines 只看大块克隆；检测不改变任何台账状态" });
+}

package/dist/git-state.js

@@ -0,0 +1,75 @@
+import fs from "node:fs";
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { spawnSync } from "node:child_process";
+import { normSep } from "./budget.js";
+import { hashRegularFile } from "./project-fingerprint.js";
+export function projectFilePath(relative) {
+    const rel = path.posix.normalize(normSep(relative));
+    if (!relative || path.isAbsolute(rel) || /^[a-z]:/i.test(rel) || rel === "." || rel === ".." || rel.startsWith("../")) {
+        throw new Error("文件必须是项目内的相对路径");
+    }
+    return rel;
+}
+/** 使用 NUL 分隔，避免中文转义、空格及文件名中的箭头被误解析。 */
+export function changedGitFiles(root) {
+    const result = spawnSync("git", ["status", "--porcelain=v1", "-z", "-uall"], { cwd: root, encoding: "utf8", timeout: 10000, maxBuffer: 16 * 1024 * 1024 });
+    if (result.error || result.status !== 0)
+        throw new Error(result.error?.message ?? `git status 退出码 ${result.status}`);
+    const records = result.stdout.split("\0");
+    const changed = new Set();
+    const add = (file) => {
+        const rel = projectFilePath(file);
+        if (!rel.startsWith(".pm/") && rel !== "PROJECT.md" && rel !== ".gitignore")
+            changed.add(rel);
+    };
+    for (let i = 0; i < records.length; i++) {
+        const row = records[i];
+        if (!row)
+            continue;
+        add(row.slice(3));
+        const status = row.slice(0, 2);
+        if (/[RC]/.test(status)) {
+            const original = records[++i]; // -z 先输出目标，再输出原路径
+            if (/R/.test(status))
+                add(original); // 重命名还需要核对旧路径的删除；复制不改原文件
+        }
+    }
+    return [...changed];
+}
+/** 只对调用者声明的文件流式取摘要，不跟随父目录链接或读取链接指向的内容。 */
+export function captureFileHashes(root, files) {
+    const hashes = Object.create(null);
+    for (const file of files) {
+        const rel = projectFilePath(file);
+        let current = path.resolve(root);
+        let signature = "missing";
+        const parts = rel.split("/");
+        for (let index = 0; index < parts.length; index++) {
+            current = path.join(current, parts[index]);
+            let stat;
+            try {
+                stat = fs.lstatSync(current);
+            }
+            catch (error) {
+                if (error.code === "ENOENT")
+                    break;
+                throw error;
+            }
+            if (stat.isSymbolicLink()) {
+                if (index !== parts.length - 1)
+                    throw new Error(`文件路径穿过符号链接: ${rel}`);
+                signature = `link\0${fs.readlinkSync(current)}`;
+            }
+            else if (index === parts.length - 1) {
+                if (!stat.isFile())
+                    throw new Error(`会话文件必须是普通文件或已删除文件: ${rel}`);
+                signature = `file\0${hashRegularFile(current).sha256}`;
+            }
+            else if (!stat.isDirectory())
+                throw new Error(`文件路径不是目录: ${rel}`);
+        }
+        hashes[rel] = createHash("sha256").update(signature).digest("hex");
+    }
+    return hashes;
+}

package/dist/governance-audit.js

@@ -5,6 +5,7 @@ import { loadGovernance } from "./governance-model.js";
 import { assessQualityCoverage, createQualityPlan, discoverProjectUnits } from "./language-adapters.js";
 import { buildSemanticGraph, moduleForFile } from "./semantic-graph.js";
 import { loadAllSemanticEvidence } from "./semantic-evidence-store.js";
+import { relPath } from "./semantic-parsers.js";
 function languageIssues(governance, graph) {
     const issues = [];
     for (const module of governance.modules) {
@@ -64,6 +65,13 @@ function graphIssues(graph) {
     for (const cycle of graph.cycles) {
         issues.push({ severity: "error", code: "module-cycle", message: `模块依赖循环: ${cycle.join(" -> ")} -> ${cycle[0]}`, evidence: cycle });
     }
+    // 文件级循环通常是 barrel/重导出或真实的循环依赖；比模块环轻，作警告可见。
+    for (const cycle of graph.fileCycles.slice(0, 10)) {
+        issues.push({ severity: "warning", code: "file-cycle", message: `文件级依赖循环: ${cycle.join(" -> ")} -> ${cycle[0]}`, evidence: cycle });
+    }
+    if (graph.fileCycles.length > 10) {
+        issues.push({ severity: "warning", code: "file-cycle-truncated", message: `文件级依赖循环共 ${graph.fileCycles.length} 个，仅列出前 10 个`, evidence: [] });
+    }
     return issues;
 }
 function render(governance, graph, units, qualityCoverage, issues, maxLines) {
@@ -73,7 +81,7 @@ function render(governance, graph, units, qualityCoverage, issues, maxLines) {
         "## 跨文件/模块/语言治理审计",
         `${errors.length === 0 ? "✅" : "🚩"} modules=${governance.modules.length} · interfaces=${governance.interfaces.length} · repositories=${governance.repositories.length} · errors=${errors.length} · warnings=${warnings.length}`,
         `语义覆盖: source ${graph.coverage.sourceCoveragePct}%（${graph.coverage.parsedFiles}/${graph.coverage.sourceCandidateFiles}）· assurance ${graph.coverage.semanticAssurancePct}% · AST ${graph.coverage.astFiles} · runtime ${graph.coverage.runtimeFiles} · heuristic ${graph.coverage.heuristicFiles} · internal resolution ${graph.coverage.resolutionPct}% · unresolved ${graph.coverage.unresolvedInternal}`,
-        `关系: files ${graph.files.length} · file edges ${graph.fileEdges.length} · module edges ${graph.moduleEdges.length} · contracts ${graph.contracts.length} · cycles ${graph.cycles.length}`,
+        `关系: files ${graph.files.length} · file edges ${graph.fileEdges.length} · module edges ${graph.moduleEdges.length} · contracts ${graph.contracts.length} · cycles ${graph.cycles.length} · file cycles ${graph.fileCycles.length}`,
         `质量矩阵: units ${qualityCoverage.totalUnits} · covered ${qualityCoverage.unitsWithCommands} · coverage ${qualityCoverage.coveragePct}% · commands ${qualityCoverage.commandKinds.join(", ") || "无"}`,
         `manifest 依赖: ${units.reduce((sum, unit) => sum + unit.dependencies.length, 0)} · parse errors ${units.reduce((sum, unit) => sum + unit.dependencyErrors.length, 0)}`,
         `语言: ${[...new Set(units.flatMap((unit) => unit.languages))].sort().join(", ") || "未发现"}`,
@@ -124,3 +132,92 @@ export function auditGovernance(root, maxLines = 150) {
     const ok = !issues.some((issue) => issue.severity === "error");
     return { ok, governance, graph, units, qualityPlan, qualityCoverage, issues, report: render(governance, graph, units, qualityCoverage, issues, maxLines) };
 }
+const MAX_CYCLE_LIST = 10;
+const MAX_FOCUS_NODES = 80;
+/** 依赖图查询：全局摘要（关系/环/枢纽）+ 模块与文件级循环 + 聚焦文件邻域；输出折叠在行预算内。 */
+export function dependencyGraphReport(root, args = {}, maxLines = 150) {
+    const absolute = path.resolve(root);
+    const governance = loadGovernance(absolute);
+    const graph = buildSemanticGraph(absolute, governance, { semanticEvidence: loadAllSemanticEvidence(absolute) });
+    const lines = [
+        "## 依赖图",
+        `- 关系: files ${graph.files.length} · file edges ${graph.fileEdges.length} · module edges ${graph.moduleEdges.length} · unresolved ${graph.unresolved.length}`,
+        `- 环: module cycles ${graph.cycles.length} · file cycles ${graph.fileCycles.length}`,
+    ];
+    const fanOut = new Map();
+    const fanIn = new Map();
+    for (const edge of graph.fileEdges) {
+        if (edge.to === null || edge.resolution !== "file")
+            continue;
+        fanOut.set(edge.from, (fanOut.get(edge.from) ?? 0) + 1);
+        fanIn.set(edge.to, (fanIn.get(edge.to) ?? 0) + 1);
+    }
+    const hubs = (counts) => [...counts.entries()].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0])).slice(0, 5).map(([file, n]) => `${file}(${n})`).join(", ") || "无";
+    lines.push(`- 出边枢纽: ${hubs(fanOut)}`);
+    lines.push(`- 入边枢纽: ${hubs(fanIn)}`);
+    for (const cycle of graph.cycles.slice(0, 5))
+        lines.push(`- 🔴 模块循环: ${cycle.join(" -> ")} -> ${cycle[0]}`);
+    for (const cycle of graph.fileCycles.slice(0, MAX_CYCLE_LIST))
+        lines.push(`- ⚠️ 文件循环: ${cycle.join(" -> ")} -> ${cycle[0]}`);
+    if (args.focus) {
+        // focus 可传相对或绝对路径：先解析并转成项目内相对 posix 路径，再与语义图对表。
+        const focusRel = relPath(path.relative(absolute, path.resolve(absolute, args.focus)));
+        if (!graph.files.some((file) => file.path === focusRel)) {
+            lines.push(`- 🚩 聚焦文件不在语义图中（未解析或不在治理范围）: ${focusRel}`);
+            return foldLines(lines, { maxLines, hint: "先确认路径在模块 root 下且语言已登记" });
+        }
+        const forward = new Map();
+        const backward = new Map();
+        for (const edge of graph.fileEdges) {
+            if (edge.to === null || edge.resolution !== "file")
+                continue;
+            forward.set(edge.from, [...(forward.get(edge.from) ?? []), edge.to]);
+            backward.set(edge.to, [...(backward.get(edge.to) ?? []), edge.from]);
+        }
+        const depth = args.depth ?? 2;
+        const walk = (start, adjacency) => {
+            const seen = new Map([[start, 0]]);
+            let frontier = [start];
+            for (let level = 1; level <= depth; level += 1) {
+                const next = [];
+                for (const node of frontier)
+                    for (const neighbor of adjacency.get(node) ?? []) {
+                        if (!seen.has(neighbor)) {
+                            seen.set(neighbor, level);
+                            next.push(neighbor);
+                        }
+                    }
+                if (next.length === 0)
+                    break;
+                frontier = next.sort();
+            }
+            return seen;
+        };
+        lines.push(`### 聚焦 ${focusRel}（depth=${depth}）`);
+        const sides = [
+            { title: "依赖（出边）", adjacency: forward, enabled: args.direction !== "dependents" },
+            { title: "被依赖（入边）", adjacency: backward, enabled: args.direction !== "deps" },
+        ];
+        for (const side of sides) {
+            if (!side.enabled)
+                continue;
+            const seen = walk(focusRel, side.adjacency);
+            const levels = [...seen.entries()].filter(([file]) => file !== focusRel).sort((a, b) => a[1] - b[1] || a[0].localeCompare(b[0]));
+            if (levels.length === 0) {
+                lines.push(`- ${side.title}: 无`);
+                continue;
+            }
+            const byLevel = new Map();
+            for (const [file, level] of levels.slice(0, MAX_FOCUS_NODES))
+                byLevel.set(level, [...(byLevel.get(level) ?? []), file]);
+            for (const level of [...byLevel.keys()].sort((a, b) => a - b))
+                lines.push(`- ${side.title} L${level}: ${byLevel.get(level).join(", ")}`);
+            if (levels.length > MAX_FOCUS_NODES)
+                lines.push(`  …另有 ${levels.length - MAX_FOCUS_NODES} 个节点未展开（提高 depth 或改用 impact_analysis 反向闭包）`);
+        }
+        const focusUnresolved = graph.unresolved.filter((edge) => edge.from === focusRel).slice(0, 10).map((edge) => edge.specifier);
+        if (focusUnresolved.length > 0)
+            lines.push(`- 未解析引用: ${focusUnresolved.join(", ")}`);
+    }
+    return foldLines(lines, { maxLines, hint: "用 focus 参数聚焦单个文件，或提高 depth 扩大邻域" });
+}

package/dist/governance-tools.js

@@ -5,13 +5,14 @@ import { foldLines } from "./budget.js";
 import { refreshDerived } from "./dashboard.js";
 import { requireInitialized } from "./paths.js";
 import { initGovernance, loadGovernance, saveGovernance, } from "./governance-model.js";
-import { auditGovernance } from "./governance-audit.js";
+import { auditGovernance, dependencyGraphReport } from "./governance-audit.js";
 import { impactAnalysis } from "./semantic-graph.js";
 import { assessQualityCoverage, createQualityPlan, discoverProjectUnits, runQualityPlan } from "./language-adapters.js";
 import { buildPortfolioFromRegistry, buildPortfolioReport, loadPortfolioProject } from "./portfolio.js";
 import { saveQualityRun } from "./quality-store.js";
+import { evidenceLabel, qualityResultSummary } from "./quality-evidence.js";
 import { SemanticEvidenceDocumentSchema } from "./semantic-evidence.js";
-import { listSemanticEvidence, saveSemanticEvidence } from "./semantic-evidence-store.js";
+import { listSemanticEvidence, replaceSemanticEvidenceForFile, saveSemanticEvidence } from "./semantic-evidence-store.js";
 import { fingerprintProject } from "./project-fingerprint.js";
 const id = z.string().trim().min(1);
 const texts = z.array(z.string().trim().min(1));
@@ -155,10 +156,26 @@ export function registerGovernanceTools(server, root) {
         requireInitialized(root);
         return auditGovernance(root, budgetLines(root)).report;
     });
+    toolR(server, root, "dependency_graph", "查询跨文件/模块依赖图：全局摘要（关系/环/入出边枢纽）、模块与文件级循环、聚焦文件的依赖邻域（BFS 方向与深度可调、未解析引用）。", {
+        focus: z.string().trim().min(1).max(512).optional().describe("聚焦文件（相对项目根路径）"),
+        direction: z.enum(["deps", "dependents", "both"]).optional().describe("邻域方向，默认 both"),
+        depth: z.number().int().min(1).max(6).optional().describe("邻域深度 1-6，默认 2"),
+    }, (args) => {
+        requireInitialized(root);
+        return dependencyGraphReport(root, args ?? {}, budgetLines(root));
+    });
     toolR(server, root, "list_semantic_evidence", "列出已登记的语言原生 AST、编译器或运行时语义证据；损坏文档会使整次读取失败。", {}, () => {
         requireInitialized(root);
         return JSON.stringify(listSemanticEvidence(root), null, 2);
     });
+    toolI(server, root, "replace_semantic_evidence_for_file", "按源码文件原子替换语义证据：删除该文件旧 evidence，仅保留当前 hash-bound evidence。", {
+        id: z.string().trim().min(1).max(128),
+        document: SemanticEvidenceDocumentSchema,
+    }, (args) => {
+        requireInitialized(root);
+        const saved = replaceSemanticEvidenceForFile(root, args.id, args.document);
+        return `✅ semantic evidence replaced ${args.id}：${saved.file} · ${saved.analyzer.id} · ${saved.analyzer.assurance} · ${saved.status}`;
+    });
     toolI(server, root, "save_semantic_evidence", "保存一份绑定源码 SHA-256 的语言原生 AST/编译器/运行时证据；过期摘要在治理审计中严格失败。", {
         id: z.string().trim().min(1).max(128),
         document: SemanticEvidenceDocumentSchema,
@@ -216,7 +233,8 @@ export function registerGovernanceTools(server, root) {
         if (!sourceStable)
             lines.push(`- 🚩 源码在执行期间变化：before=${sourceBefore.sha256} after=${sourceAfter.sha256}`);
         for (const item of result.results)
-            lines.push(`- [${item.status}] ${item.command.kind} ${item.command.cwd} (${item.durationMs}ms${item.exitCode === null ? "" : `, exit ${item.exitCode}`})`);
+            lines.push(`- [${item.status}] ${item.command.kind} ${item.command.cwd} (${item.durationMs}ms${item.exitCode === null ? "" : `, exit ${item.exitCode}`}) · ${evidenceLabel(qualityResultSummary(item).evidence_level)}`);
+        lines.push("命令执行结果与任务完成证据分开判断；未知计数不等于已观察测试通过。");
         return foldLines(lines, { maxLines: budgetLines(root), hint: "查看 .pm/quality-runs 结构化摘要（不落原始输出）" });
     });
     toolR(server, root, "get_portfolio", "聚合当前项目或全局注册项目的阶段、里程碑、债务、安全、语言、跨仓依赖/版本/cycle；加载失败不能假绿。", {

package/dist/index-db.js

@@ -2,6 +2,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { DatabaseSync } from "node:sqlite";
 import { pmPath } from "./paths.js";
+import { watcherIsClean } from "./watcher-coordinator.js";
 /** Low-level SQLite lifecycle, metadata, row iteration, and aggregate queries. */
 const SCHEMA = `
 CREATE TABLE IF NOT EXISTS files(
@@ -95,3 +96,42 @@ export function aggregates(db) {
         indexCoverageBase: contentOk.c,
     };
 }
+const BEAT_STALE_MS = 90_000;
+export function freshness(root) {
+    const db = getIndex(root);
+    const files = db.prepare(`SELECT COUNT(*) c FROM files`).get().c;
+    const lastWalk = getMeta(db, "lastWalk");
+    const lastBeat = getMeta(db, "lastBeat");
+    const mode = (getMeta(db, "mode") ?? "walk");
+    const pending = Number(getMeta(db, "pending") ?? 0);
+    const beatAge = lastBeat ? Date.now() - Date.parse(lastBeat) : Number.POSITIVE_INFINITY;
+    // rootPath 守卫：索引库随项目目录被拷贝/移动时，旧心跳与行集都属于原路径——不可信任
+    const owned = getMeta(db, "rootPath") === path.resolve(root);
+    const lastEvent = getMeta(db, "lastEvent");
+    const eventAge = lastEvent ? Date.now() - Date.parse(lastEvent) : Number.POSITIVE_INFINITY;
+    const watcherSession = getMeta(db, "watcherSession");
+    const sessionReconciled = watcherSession !== null && getMeta(db, "lastWalkSession") === watcherSession;
+    const watcherHealthy = !(getMeta(db, "watcherError") ?? "");
+    const watcherClean = watcherIsClean(root);
+    // 卡死计数自愈：防抖 150ms，若计数>0 但 30s 无任何事件推进，说明计数器失真（如持锁期抛错），不再信任
+    const pendingClean = pending === 0 || eventAge > 30_000;
+    const fresh = files > 0 &&
+        lastWalk !== null &&
+        owned &&
+        mode === "watcher" &&
+        sessionReconciled &&
+        watcherHealthy &&
+        watcherClean &&
+        pendingClean &&
+        beatAge < BEAT_STALE_MS;
+    return { mode, fresh, files, lastWalk, lastBeat, pendingEvents: pending };
+}
+/** 巡检/诊断用：索引概况一行 */
+export function indexSummary(root) {
+    const f = freshness(root);
+    if (f.files === 0)
+        return "索引：空（未走查）";
+    const age = f.lastWalk ? `，走查于 ${f.lastWalk.slice(0, 16).replace("T", " ")}` : "";
+    const beat = f.fresh ? "，watcher 保鲜中" : `（watcher ${f.mode === "watcher" ? "心跳过期" : "未运行"}，下次审计将全量走查）`;
+    return `索引：${f.files} 文件${age}${beat}`;
+}