@luckychen1993/pm-mcp 0.1.1

package/dist/project-fingerprint.js

@@ -0,0 +1,83 @@
+import fs from "node:fs";
+import path from "node:path";
+import { createHash } from "node:crypto";
+const DEFAULT_IGNORED_DIRECTORIES = new Set([
+    ".git", ".pm", ".cache", ".gradle", ".idea", ".next", ".nuxt", ".output", ".turbo", ".venv", ".vscode", ".zcode",
+    "__pycache__", "build", "coverage", "dist", "env", "node_modules", "out", "target", "venv",
+]);
+function hashRegularFile(file) {
+    const handle = fs.openSync(file, "r");
+    const digest = createHash("sha256");
+    const buffer = Buffer.allocUnsafe(1024 * 1024);
+    try {
+        const before = fs.fstatSync(handle);
+        if (!before.isFile())
+            throw new Error(`项目指纹只接受普通文件: ${file}`);
+        let offset = 0;
+        while (offset < before.size) {
+            const read = fs.readSync(handle, buffer, 0, Math.min(buffer.length, before.size - offset), offset);
+            if (read === 0)
+                break;
+            digest.update(buffer.subarray(0, read));
+            offset += read;
+        }
+        const after = fs.fstatSync(handle);
+        if (offset !== before.size || after.size !== before.size || after.mtimeMs !== before.mtimeMs) {
+            throw new Error(`生成项目指纹时文件发生变化: ${file}`);
+        }
+        return { sha256: digest.digest("hex"), bytes: before.size };
+    }
+    finally {
+        fs.closeSync(handle);
+    }
+}
+/**
+ * Deterministic content fingerprint for source acceptance when no trusted VCS
+ * revision exists. Directory entries are sorted, symlinks are rejected, and
+ * generated/cache directories are excluded by an explicit stable policy.
+ */
+export function fingerprintProject(root) {
+    const absolute = path.resolve(root);
+    const rootStat = fs.lstatSync(absolute);
+    if (!rootStat.isDirectory() || rootStat.isSymbolicLink())
+        throw new Error(`项目根必须是普通目录: ${absolute}`);
+    const rootReal = fs.realpathSync.native(absolute);
+    const tree = createHash("sha256");
+    let files = 0;
+    let bytes = 0;
+    const visit = (directory, relativeDirectory) => {
+        const entries = fs.readdirSync(directory, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name, "en"));
+        for (const entry of entries) {
+            if (entry.isDirectory() && DEFAULT_IGNORED_DIRECTORIES.has(entry.name))
+                continue;
+            const absoluteEntry = path.join(directory, entry.name);
+            const relative = path.posix.join(relativeDirectory.replace(/\\/g, "/"), entry.name);
+            if (relative === "PROJECT.md")
+                continue; // generated dashboard; authoritative inputs live in .pm and source files
+            const stat = fs.lstatSync(absoluteEntry);
+            if (stat.isSymbolicLink())
+                throw new Error(`项目指纹拒绝符号链接: ${relative}`);
+            if (stat.isDirectory()) {
+                const real = fs.realpathSync.native(absoluteEntry);
+                const escaped = path.relative(rootReal, real);
+                if (escaped === ".." || escaped.startsWith(`..${path.sep}`) || path.isAbsolute(escaped))
+                    throw new Error(`目录逃逸项目根: ${relative}`);
+                visit(absoluteEntry, relative);
+                continue;
+            }
+            if (!stat.isFile())
+                throw new Error(`项目指纹拒绝非普通文件: ${relative}`);
+            const file = hashRegularFile(absoluteEntry);
+            tree.update(relative, "utf8");
+            tree.update("\0", "utf8");
+            tree.update(String(file.bytes), "utf8");
+            tree.update("\0", "utf8");
+            tree.update(file.sha256, "ascii");
+            tree.update("\n", "utf8");
+            files += 1;
+            bytes += file.bytes;
+        }
+    };
+    visit(absolute, "");
+    return { algorithm: "sha256-tree-v1", sha256: tree.digest("hex"), files, bytes };
+}

package/dist/project-tools.js

@@ -0,0 +1,217 @@
+import { z } from "zod";
+import { initProject } from "./init.js";
+import { pmPath, requireInitialized } from "./paths.js";
+import { refreshDerived } from "./dashboard.js";
+import { renderRoadmap, milestoneStats, checkpointSuffix } from "./roadmap.js";
+import { foldLines } from "./budget.js";
+import { loadGovernance } from "./governance-model.js";
+import { loadProject, loadRoadmap, loadSecurity, loadSessions, loadTasks, saveProject, saveRoadmap, } from "./store.js";
+import { now } from "./types.js";
+import { budgetLines, tool, toolW } from "./tool-base.js";
+function taskLine(t, withNext = false) {
+    const parts = [`[${t.status}]`, t.id, t.title, `(${t.type}${t.milestone ? `,${t.milestone}` : ""})`];
+    if (withNext && t.checkpoint) {
+        parts.push(`→ 下一步: ${t.checkpoint.next_step}${checkpointSuffix(t.checkpoint)}`);
+    }
+    return parts.join(" ");
+}
+export function registerProjectTools(server, root) {
+    toolW(server, root, "init_project", "初始化当前项目的 .pm/ 状态目录（单一事实来源）。每个新项目只调用一次；已初始化请用 update_project。", {
+        name: z.string().min(1).describe("项目名"),
+        description: z.string().optional().describe("一句话描述"),
+        stack: z.array(z.string()).optional().describe("技术栈，如 [\"TypeScript\",\"React\"]"),
+        goals: z.array(z.string()).optional().describe("项目目标列表"),
+        license: z.string().optional().describe("项目许可证（SPDX 名，如 MIT）"),
+        exposure: z.enum(["local", "network", "public"]).optional().describe("暴露面，影响安全告警力度"),
+        modules: z.array(z.string()).optional().describe("初始模块登记"),
+    }, (args) => {
+        const project = initProject(root, args);
+        refreshDerived(root);
+        return [
+            `✅ 项目已初始化: ${project.name}`,
+            `状态目录: ${pmPath(root, "")}（随 git 提交，团队/AI 共享）`,
+            "仪表盘已生成: PROJECT.md",
+            "建议顺序: upsert_module 声明模块/owner/语言 → add_milestone 建里程碑 → add_task 拆任务 → 开工前 get_status / 收工后 log_session。",
+        ].join("\n");
+    });
+    tool(server, "get_status", "一站式「我在哪」：项目阶段 + 里程碑进度 + 进行中任务（含断点下一步）+ 健康摘要 + 最近变更。会话开工第一件事。since 可只看某日期以来的任务/会话变化。", { since: z.string().optional().describe("ISO 日期，如 2026-09-01：只看该日期以来的任务/会话变化") }, (args) => {
+        requireInitialized(root);
+        const project = loadProject(root);
+        const { milestones } = loadRoadmap(root);
+        const { tasks } = loadTasks(root);
+        const { sessions } = loadSessions(root);
+        const security = loadSecurity(root);
+        const L = [];
+        L.push(`# ${project.name}${project.phase ? ` — ${project.phase}` : ""}`);
+        if (project.description)
+            L.push(project.description);
+        L.push("");
+        L.push("## 里程碑");
+        L.push(...renderRoadmap(milestones, tasks, 1));
+        L.push("");
+        L.push("## 当前焦点（断点恢复点）");
+        const active = tasks.filter((t) => t.status === "in_progress" || t.status === "blocked");
+        if (active.length === 0)
+            L.push("（无进行中任务——从 backlog 挑一个，或 add_task。）");
+        for (const t of active.slice(0, 10)) {
+            L.push(`- ${taskLine(t, true)}`);
+            if (t.steps.length > 0) {
+                const doneN = t.steps.filter((s) => s.done).length;
+                L.push(`  步骤 ${doneN}/${t.steps.length}: ${t.steps.filter((s) => !s.done)[0]?.text ?? "全部完成"}`);
+            }
+        }
+        L.push("");
+        L.push("## 健康摘要");
+        const openDebt = tasks.filter((t) => t.type === "debt" && t.status !== "done" && t.status !== "cancelled").length;
+        const openFindings = security.findings.filter((f) => f.status === "open");
+        L.push(`债务未清 ${openDebt} 条 · 安全未处理 ${openFindings.length} 个（高危 ${openFindings.filter((f) => f.severity === "high").length}）· 会话 ${sessions.length} 次。详细对账用 audit_structure / audit_security。`);
+        try {
+            const governance = loadGovernance(root);
+            L.push(`治理模型 ${governance.modules.length} 模块 / ${governance.interfaces.length} 接口 / ${governance.repositories.length} 仓库；实时语义门禁用 audit_governance。`);
+        }
+        catch {
+            L.push("⚠️ 治理模型未初始化；跨模块/语言边界尚未启用。");
+        }
+        const last = sessions[sessions.length - 1];
+        if (last) {
+            L.push("");
+            L.push("## 最近会话");
+            L.push(`${last.date.slice(0, 10)} [${last.author || "?"}] ${last.summary}`);
+            if (last.next_steps.length > 0)
+                L.push(`上次留下的下一步: ${last.next_steps.join("；")}`);
+        }
+        if (args.since) {
+            const parsed = Date.parse(args.since);
+            const since = Number.isNaN(parsed) ? args.since : new Date(parsed).toISOString();
+            const newTasks = tasks.filter((t) => t.updated >= since);
+            const newSessions = sessions.filter((s) => s.date >= since);
+            L.push("");
+            L.push(`## 自 ${since.slice(0, 10)} 以来`);
+            L.push(`新增/更新任务 ${newTasks.length} 个，会话 ${newSessions.length} 次。`);
+            for (const t of newTasks.slice(-8).reverse())
+                L.push(`- ${taskLine(t)}`);
+        }
+        L.push("");
+        L.push("> 三段式定位：本状态 → search_code 精确到行 → 才读具体文件。别全量读代码。");
+        return foldLines(L, { maxLines: budgetLines(root) });
+    });
+    toolW(server, root, "update_project", "更新项目元信息/预算（描述、技术栈、目标、阶段、模块登记、许可证、暴露面、复杂度与输出预算）。", {
+        description: z.string().optional(),
+        stack: z.array(z.string()).optional(),
+        goals: z.array(z.string()).optional(),
+        phase: z.string().optional().describe("当前阶段，如 MVP 开发中"),
+        license: z.string().optional(),
+        exposure: z.enum(["local", "network", "public"]).optional(),
+        modules: z.array(z.string()).optional().describe("模块登记（用于未登记目录检测）"),
+        max_file_loc: z.number().int().min(10).optional().describe("单文件行数预算"),
+        refactor_quota_pct: z.number().min(0).max(100).optional().describe("里程碑重构类任务最低占比%"),
+        session_blast_radius: z.number().int().min(1).optional().describe("单会话波及文件阈值"),
+        output_budget_lines: z.number().int().min(20).optional().describe("读类工具输出行数预算"),
+    }, (args) => {
+        requireInitialized(root);
+        const project = loadProject(root);
+        if (args.description !== undefined)
+            project.description = args.description;
+        if (args.stack !== undefined)
+            project.stack = args.stack;
+        if (args.goals !== undefined)
+            project.goals = args.goals;
+        if (args.phase !== undefined)
+            project.phase = args.phase;
+        if (args.license !== undefined)
+            project.license = args.license;
+        if (args.exposure !== undefined)
+            project.exposure = args.exposure;
+        if (args.modules !== undefined)
+            project.modules = args.modules;
+        if (args.max_file_loc !== undefined)
+            project.budgets.maxFileLoc = args.max_file_loc;
+        if (args.refactor_quota_pct !== undefined)
+            project.budgets.refactorQuotaPct = args.refactor_quota_pct;
+        if (args.session_blast_radius !== undefined)
+            project.budgets.sessionBlastRadius = args.session_blast_radius;
+        if (args.output_budget_lines !== undefined)
+            project.budgets.outputBudgetLines = args.output_budget_lines;
+        saveProject(root, project);
+        refreshDerived(root);
+        return `✅ 项目信息已更新（阶段: ${project.phase || "—"}，模块: ${project.modules.join(", ") || "—"}）。仪表盘已刷新。`;
+    });
+    tool(server, "regenerate_dashboard", "手动重新生成 PROJECT.md 仪表盘与 changelog.md（正常情况下每次写操作已自动刷新）。", {}, () => {
+        requireInitialized(root);
+        refreshDerived(root);
+        return "✅ PROJECT.md 与 changelog.md 已重新生成。";
+    });
+}
+export function registerRoadmapTools(server, root) {
+    toolW(server, root, "add_milestone", "添加里程碑（M1/M2…，按顺序自动编号）。路线图的骨架；任务挂到里程碑上。", { title: z.string().min(1), goal: z.string().optional().describe("这个里程碑要达成什么") }, (args) => {
+        requireInitialized(root);
+        const data = loadRoadmap(root);
+        const id = `M${data.seq + 1}`;
+        const t = now();
+        data.seq += 1;
+        data.milestones.push({
+            id,
+            title: args.title,
+            goal: args.goal ?? "",
+            status: "planned",
+            order: data.milestones.length + 1,
+            created: t,
+            updated: t,
+        });
+        saveRoadmap(root, data);
+        refreshDerived(root);
+        return `✅ 里程碑 ${id}「${args.title}」已创建（planned）。开始推进时用 update_milestone 置为 active。`;
+    });
+    toolW(server, root, "update_milestone", "更新里程碑（状态流转 planned/active/done/paused、标题、目标、顺序）。", {
+        id: z.string().describe("里程碑 id，如 M1"),
+        status: z.enum(["planned", "active", "done", "paused"]).optional(),
+        title: z.string().optional(),
+        goal: z.string().optional(),
+        order: z.number().int().optional(),
+    }, (args) => {
+        requireInitialized(root);
+        const data = loadRoadmap(root);
+        const m = data.milestones.find((x) => x.id === args.id);
+        if (!m)
+            throw new Error(`找不到里程碑 ${args.id}。现有: ${data.milestones.map((x) => x.id).join(", ") || "无"}`);
+        if (args.status !== undefined)
+            m.status = args.status;
+        if (args.title !== undefined)
+            m.title = args.title;
+        if (args.goal !== undefined)
+            m.goal = args.goal;
+        if (args.order !== undefined)
+            m.order = args.order;
+        m.updated = now();
+        const warnings = [];
+        if (m.status === "done") {
+            const skipped = data.milestones.filter((x) => x.id !== m.id && x.order < m.order && (x.status === "active" || x.status === "planned"));
+            if (skipped.length > 0) {
+                warnings.push(`⚠️ 跳过前置里程碑：${skipped.map((x) => x.id).join(", ")} 尚未完成就被置后完成——确认是有意为之。`);
+            }
+        }
+        saveRoadmap(root, data);
+        refreshDerived(root);
+        const { tasks } = loadTasks(root);
+        const s = milestoneStats(tasks, m.id);
+        return [`✅ ${m.id} 已更新（${m.status}）。进度: ${s.done}/${s.total}（${s.pct}%）。`, ...warnings].join("\n");
+    });
+    tool(server, "get_roadmap", "查看路线图。depth=1 每个里程碑一行摘要（功能再多也不乱）；depth=2 额外展开活跃里程碑的任务明细与断点。", { depth: z.number().int().min(1).max(2).optional().describe("默认 1") }, (args) => {
+        requireInitialized(root);
+        const { milestones } = loadRoadmap(root);
+        const { tasks } = loadTasks(root);
+        const project = loadProject(root);
+        const L = ["# 路线图", ""];
+        L.push(...renderRoadmap(milestones, tasks, args.depth ?? 1));
+        const warns = milestones
+            .map((m) => ({ m, s: milestoneStats(tasks, m.id) }))
+            .filter(({ m, s }) => m.status !== "done" && s.total >= 5 && s.refactorPct < project.budgets.refactorQuotaPct);
+        if (warns.length > 0) {
+            L.push("");
+            for (const { m, s } of warns) {
+                L.push(`⚠️ 重构被挤出: ${m.id}（${s.total} 个任务中重构类仅 ${s.refactorPct}%，配额 ${project.budgets.refactorQuotaPct}%）——建议立 refactor/debt 任务。`);
+            }
+        }
+        return foldLines(L, { maxLines: budgetLines(root) });
+    });
+}

package/dist/quality-store.js

@@ -0,0 +1,77 @@
+import fs from "node:fs";
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { atomicWrite, withLedgerLock } from "./store.js";
+import { refreshDerived } from "./dashboard.js";
+function numericDiagnostic(output, label) {
+    const match = output.match(new RegExp(`(?:^|\\n)(?:ℹ|#)?\\s*${label}\\s+(\\d+)(?:\\s|$)`, "i"));
+    return match ? Number(match[1]) : null;
+}
+function outputSummary(stdout, stderr) {
+    const combined = `${stdout}\n${stderr}`;
+    // Node's test reporter exposes line|branch|function, while Istanbul/c8 uses
+    // statement|branch|function|line. Preserve one normalized three-metric shape.
+    const coverage = combined.match(/(?:^|\n)(?:ℹ|#)?\s*all files\s*\|\s*([\d.]+)\s*\|\s*([\d.]+)\s*\|\s*([\d.]+)(?:\s*\|\s*([\d.]+))?/i);
+    return {
+        stdout_bytes: Buffer.byteLength(stdout),
+        stderr_bytes: Buffer.byteLength(stderr),
+        output_sha256: createHash("sha256").update(stdout, "utf8").update("\0", "utf8").update(stderr, "utf8").digest("hex"),
+        tests: numericDiagnostic(combined, "tests"),
+        passed: numericDiagnostic(combined, "pass"),
+        failed: numericDiagnostic(combined, "fail"),
+        cancelled: numericDiagnostic(combined, "cancelled"),
+        skipped: numericDiagnostic(combined, "skipped"),
+        todo: numericDiagnostic(combined, "todo"),
+        coverage: coverage ? { lines_pct: Number(coverage[4] ?? coverage[1]), branches_pct: Number(coverage[2]), functions_pct: Number(coverage[3]) } : null,
+    };
+}
+/** Persist a secret-minimised quality summary; raw stdout/stderr never enter the ledger. */
+export function saveQualityRun(root, result, provenance) {
+    const runAt = new Date();
+    const stamp = runAt.toISOString().replace(/[-:]/g, "").replace("T", "-").replace(".", "-").replace(/Z$/, "");
+    const effectiveOk = result.ok && result.execute && result.results.length > 0 && result.results.every((item) => item.status === "passed" && item.exitCode === 0 && item.signal === null);
+    const payload = JSON.stringify({
+        schema_version: 2,
+        run_at: runAt.toISOString(),
+        ok: effectiveOk,
+        reported_ok: result.ok,
+        execute: result.execute,
+        environment: { platform: process.platform, arch: process.arch, node: process.version },
+        source: provenance ? {
+            before: provenance.source_before,
+            after: provenance.source_after,
+            stable: provenance.source_before.sha256 === provenance.source_after.sha256,
+        } : null,
+        results: result.results.map((item) => ({
+            unit_root: item.command.cwd,
+            kind: item.command.kind,
+            command: item.command.command,
+            args: item.command.args,
+            status: item.status,
+            exit_code: item.exitCode,
+            signal: item.signal,
+            duration_ms: item.durationMs,
+            output_truncated: item.truncated,
+            output_summary: outputSummary(item.stdout, item.stderr),
+            error: item.error ?? "",
+        })),
+    }, null, 2) + "\n";
+    const absoluteRoot = path.resolve(root);
+    const relative = withLedgerLock(absoluteRoot, () => {
+        const directory = path.join(absoluteRoot, ".pm", "quality-runs");
+        fs.mkdirSync(directory, { recursive: true });
+        for (let sequence = 0; sequence < 10_000; sequence += 1) {
+            const name = `quality-${stamp}-${String(sequence).padStart(4, "0")}.json`;
+            const file = path.join(directory, name);
+            if (fs.existsSync(file))
+                continue;
+            atomicWrite(file, payload);
+            return `.pm/quality-runs/${name}`;
+        }
+        throw new Error(`同一毫秒内质量证据数量超过上限，拒绝覆盖: ${stamp}`);
+    });
+    // Quality evidence is user-visible project state. Keep PROJECT.md in sync so
+    // a failed run cannot remain hidden behind the previous green dashboard.
+    refreshDerived(absoluteRoot);
+    return relative;
+}

package/dist/registry.js

@@ -0,0 +1,38 @@
+import fs from "node:fs";
+import path from "node:path";
+import { RegistrySchema, now } from "./types.js";
+import { registryFile } from "./paths.js";
+import { atomicWrite } from "./store.js";
+export function loadRegistry() {
+    const file = registryFile();
+    if (!fs.existsSync(file))
+        return { projects: [] };
+    try {
+        return RegistrySchema.parse(JSON.parse(fs.readFileSync(file, "utf8")));
+    }
+    catch (e) {
+        // 注册表损坏不应拖垮任何工具，告警后按空表处理
+        console.error(`[pm-mcp] 全局注册表读取失败，按空表处理: ${e.message}`);
+        return { projects: [] };
+    }
+}
+export function saveRegistry(data) {
+    const file = registryFile();
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    atomicWrite(file, JSON.stringify(data, null, 2) + "\n");
+}
+/** 登记/刷新一个项目（init 与每次写操作都会 touch） */
+export function touchRegistry(root, name) {
+    const data = loadRegistry();
+    const abs = path.resolve(root);
+    const idx = data.projects.findIndex((p) => path.resolve(p.root) === abs);
+    const entry = { name, root: abs, last_seen: now() };
+    if (idx >= 0)
+        data.projects[idx] = entry;
+    else
+        data.projects.push(entry);
+    saveRegistry(data);
+}
+export function listRegistry() {
+    return loadRegistry().projects.sort((a, b) => b.last_seen.localeCompare(a.last_seen));
+}

package/dist/roadmap.js

@@ -0,0 +1,96 @@
+import { ageDays } from "./health.js";
+/** 断点展示后缀：超过 7 天的旧断点标注可能过期 */
+export function checkpointSuffix(cp) {
+    const days = ageDays(cp.at);
+    return days > 7 ? `（${days} 天前的断点，可能过期——建议刷新 checkpoint）` : "";
+}
+/** 进度条：10 格 */
+export function bar(pct) {
+    const filled = Math.round((Math.max(0, Math.min(100, pct)) / 100) * 10);
+    return "[" + "█".repeat(filled) + "░".repeat(10 - filled) + "]";
+}
+export function milestoneStats(tasks, milestoneId) {
+    const own = tasks.filter((t) => t.milestone === milestoneId && t.status !== "cancelled");
+    const done = own.filter((t) => t.status === "done");
+    const refactorish = own.filter((t) => t.type === "refactor" || t.type === "debt");
+    return {
+        total: own.length,
+        done: done.length,
+        pct: own.length === 0 ? 0 : Math.round((done.length / own.length) * 100),
+        refactorish: refactorish.length,
+        refactorPct: own.length === 0 ? 0 : Math.round((refactorish.length / own.length) * 100),
+    };
+}
+const STATUS_ICON = {
+    done: "✅",
+    active: "▶",
+    paused: "⏸",
+    planned: "○",
+};
+/**
+ * 分层渲染路线图。
+ * depth=1：每个里程碑一行摘要（功能再多也不乱）；
+ * depth=2：另展开活跃里程碑的任务明细（进行中优先，含断点 next_step）。
+ */
+export function renderRoadmap(milestones, tasks, depth = 1, maxTasksPerMilestone = 10) {
+    const lines = [];
+    const sorted = [...milestones].sort((a, b) => a.order - b.order);
+    if (sorted.length === 0) {
+        lines.push("（尚无里程碑，用 add_milestone 创建）");
+        return lines;
+    }
+    for (const m of sorted) {
+        const s = milestoneStats(tasks, m.id);
+        lines.push(`${STATUS_ICON[m.status] ?? "?"} ${bar(s.pct)} ${s.pct}% ${m.id} ${m.title}（${s.done}/${s.total}）`);
+        if (depth >= 2 && (m.status === "active" || m.status === "paused")) {
+            const own = tasks
+                .filter((t) => t.milestone === m.id && t.status !== "cancelled" && t.status !== "done")
+                .sort((a, b) => {
+                const order = ["in_progress", "blocked", "todo", "backlog"];
+                return order.indexOf(a.status) - order.indexOf(b.status);
+            })
+                .slice(0, maxTasksPerMilestone);
+            if (own.length === 0) {
+                lines.push(`   - （该里程碑暂无未完成任务）`);
+            }
+            for (const t of own) {
+                const mark = t.status === "in_progress" ? "🔄" : t.status === "blocked" ? "🚫" : "☐";
+                const next = t.checkpoint ? ` → 下一步: ${t.checkpoint.next_step}${checkpointSuffix(t.checkpoint)}` : "";
+                lines.push(`   - ${mark} ${t.id} ${t.title}${next}`);
+            }
+        }
+    }
+    return lines;
+}
+/** 里程碑重构配额检查：任务数达到阈值后，refactor+debt 占比低于配额即告警 */
+export function quotaWarnings(project, milestones, tasks) {
+    const out = [];
+    for (const m of milestones) {
+        const s = milestoneStats(tasks, m.id);
+        if (s.total >= 5 && m.status !== "done" && s.refactorPct < project.budgets.refactorQuotaPct) {
+            out.push({
+                milestone: `${m.id} ${m.title}`,
+                total: s.total,
+                refactorPct: s.refactorPct,
+                quotaPct: project.budgets.refactorQuotaPct,
+            });
+        }
+    }
+    return out;
+}
+/** mermaid 里程碑图（GitHub 可渲染；最多 8 个，防 token 膨胀） */
+export function mermaidRoadmap(milestones) {
+    const sorted = [...milestones].sort((a, b) => a.order - b.order).slice(0, 8);
+    if (sorted.length === 0)
+        return [];
+    const lines = ["```mermaid", "flowchart LR"];
+    for (const m of sorted) {
+        const label = `${m.id} ${m.title}`.replace(/["<>]/g, "");
+        lines.push(`  ${m.id.replace(/-/g, "_")}["${label}"]:::${m.status}`);
+    }
+    for (let i = 0; i + 1 < sorted.length; i++) {
+        lines.push(`  ${sorted[i].id.replace(/-/g, "_")} --> ${sorted[i + 1].id.replace(/-/g, "_")}`);
+    }
+    lines.push("  classDef done fill:#9ca3af,stroke:#6b7280", "  classDef active fill:#86efac,stroke:#16a34a", "  classDef planned fill:#e5e7eb,stroke:#9ca3af", "  classDef paused fill:#fde68a,stroke:#d97706", "```");
+    return lines;
+}