@luckychen1993/pm-mcp 0.1.1

package/dist/dashboard.js

@@ -0,0 +1,241 @@
+import fs from "node:fs";
+import path from "node:path";
+import { atomicWrite, loadDebugLog, loadFeatures, loadProject, loadRoadmap, loadSecurity, loadSessions, loadTasks, } from "./store.js";
+import { decisionsDir, pmPath, dashboardFile } from "./paths.js";
+import { mermaidRoadmap, quotaWarnings, renderRoadmap, checkpointSuffix } from "./roadmap.js";
+import { churnStats, debtAging } from "./health.js";
+import { featureVerifyMark } from "./audit.js";
+import { loadGovernance } from "./governance-model.js";
+import { touchRegistry } from "./registry.js";
+/** 生成 PROJECT.md 全文 */
+export function buildDashboard(root) {
+    const project = loadProject(root);
+    const { milestones } = loadRoadmap(root);
+    const { tasks } = loadTasks(root);
+    const { features } = loadFeatures(root);
+    const { sessions } = loadSessions(root);
+    const { entries: debugEntries } = loadDebugLog(root);
+    const security = loadSecurity(root);
+    let governance = null;
+    try {
+        governance = loadGovernance(root);
+    }
+    catch {
+        // 旧项目迁移前在仪表盘显式显示缺失，不让派生刷新整体失败。
+    }
+    let latestQuality = null;
+    try {
+        const dir = pmPath(root, "quality-runs");
+        const latest = fs.readdirSync(dir).filter((name) => name.endsWith(".json")).sort().at(-1);
+        if (latest)
+            latestQuality = JSON.parse(fs.readFileSync(path.join(dir, latest), "utf8"));
+    }
+    catch {
+        // 尚未运行真实质量矩阵。
+    }
+    let latestAcceptance = null;
+    try {
+        const dir = pmPath(root, "acceptance", "reports");
+        const latest = fs.readdirSync(dir)
+            .filter((name) => name.endsWith(".json") && !name.endsWith(".sha256.json"))
+            .flatMap((name) => {
+            try {
+                const report = JSON.parse(fs.readFileSync(path.join(dir, name), "utf8"));
+                const timestamp = report ? Date.parse(report.report_generated_at) : Number.NaN;
+                return Number.isFinite(timestamp) ? [{ name, timestamp, report }] : [];
+            }
+            catch {
+                return [];
+            }
+        })
+            // Git checkout commonly gives every tracked report the same mtime, so
+            // report content—not filesystem metadata—must determine recency.
+            .sort((a, b) => b.timestamp - a.timestamp || b.name.localeCompare(a.name))[0];
+        if (latest)
+            latestAcceptance = latest.report;
+    }
+    catch {
+        // 尚未执行标准化验收。
+    }
+    const L = [];
+    L.push(`# ${project.name} — 项目仪表盘`);
+    L.push("");
+    L.push(`> ⚠️ 本文件由 pm-mcp 自动生成（勿手改）。状态账本写入后自动刷新；手动刷新用 regenerate_dashboard。`);
+    L.push(`> 生成时间: ${new Date().toISOString()}`);
+    if (project.description)
+        L.push(`> ${project.description}`);
+    L.push("");
+    /* 路线图置顶 */
+    L.push("## 🗺️ 路线图");
+    L.push("");
+    const mm = mermaidRoadmap(milestones);
+    if (mm.length > 0)
+        L.push(...mm, "");
+    L.push(...renderRoadmap(milestones, tasks, 1));
+    const warns = quotaWarnings(project, milestones, tasks);
+    for (const w of warns) {
+        L.push(`- ⚠️ 重构被挤出: ${w.milestone} 重构类占比 ${w.refactorPct}% < 配额 ${w.quotaPct}%`);
+    }
+    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 创建。）");
+    }
+    else {
+        for (const t of active.slice(0, 10)) {
+            const next = t.checkpoint ? ` → 下一步: ${t.checkpoint.next_step}${checkpointSuffix(t.checkpoint)}` : "";
+            const steps = t.steps.length > 0 ? `（步骤 ${t.steps.filter((s) => s.done).length}/${t.steps.length}）` : "";
+            L.push(`- ${t.status === "blocked" ? "🚫" : "🔄"} ${t.id} ${t.title}${steps}${next}`);
+        }
+    }
+    if (project.phase)
+        L.push(`- 当前阶段: ${project.phase}`);
+    L.push("");
+    /* 健康摘要 */
+    L.push("## 🩺 健康摘要");
+    const aging = debtAging(tasks);
+    const openFindings = security.findings.filter((f) => f.status === "open");
+    const highFindings = openFindings.filter((f) => f.severity === "high");
+    const churn = churnStats(sessions);
+    const implemented = features.filter((f) => f.status === "implemented");
+    const drifted = implemented.filter((f) => f.entry_files.some((p) => !fs.existsSync(path.join(root, p))));
+    L.push(`| 账本 | 状态 |`);
+    L.push(`|---|---|`);
+    L.push(`| 漂移（防幻觉） | ${drifted.length === 0 ? "✅ 无" : `⚠️ ${drifted.length} 个功能入口文件缺失`} |`);
+    L.push(`| 债务（反挤出） | ${aging.openDebt === 0 ? "✅ 无未清债务" : `⚠️ ${aging.openDebt} 条，最老 ${aging.oldestDays} 天`} |`);
+    L.push(`| churn（变更率） | ${churn.hotspots.length === 0 ? "✅ 无热点" : `⚠️ 热点 ${churn.hotspots.slice(0, 3).map((h) => `${h.file}(${h.count})`).join(", ")}`} |`);
+    L.push(`| 安全 | ${openFindings.length === 0 ? "✅ 无未处理发现" : `⚠️ ${openFindings.length} 个未处理（高危 ${highFindings.length}）`} |`);
+    L.push(`| 调试知识 | ${debugEntries.length} 条记录 |`);
+    L.push(`| 测试背书 | ${implemented.length === 0 ? "—" : `${implemented.filter((f) => f.test_files.length > 0).length}/${implemented.length} 个功能带测试`} |`);
+    L.push(`| 语义治理 | ${governance ? `${governance.modules.length} 模块 / ${governance.interfaces.length} 接口 / ${governance.repositories.length} 仓库` : "⚠️ 未初始化"} |`);
+    L.push(`| 质量矩阵 | ${latestQuality ? `${latestQuality.ok ? "✅" : "🚩"} ${latestQuality.run_at.slice(0, 16).replace("T", " ")}（${latestQuality.results.filter((item) => item.status === "passed").length}/${latestQuality.results.length}）` : "⚠️ 尚无真实执行记录"} |`);
+    L.push(`| 标准化验收 | ${latestAcceptance ? `${latestAcceptance.verdict === "accepted" ? "✅" : "🚩"} ${latestAcceptance.report_generated_at.slice(0, 16).replace("T", " ")}（需求 ${latestAcceptance.summary.requirements_passed}/${latestAcceptance.summary.requirements_total}，errors ${latestAcceptance.summary.errors}）` : "⚠️ 尚无正式评价报告"} |`);
+    L.push("");
+    /* 跨模块/语言治理（这里只读账本，不在每次写操作时重跑全仓语义图） */
+    L.push("## 🧭 模块与语言治理");
+    if (!governance) {
+        L.push("- ⚠️ governance.json 缺失；用 init_governance/upsert_module 完成迁移。");
+    }
+    else if (governance.modules.length === 0) {
+        L.push("- ⚠️ 尚未登记结构化模块；文件级账本可用，但依赖/owner/接口边界尚未启用。");
+    }
+    else {
+        for (const module of governance.modules.slice(0, 12)) {
+            L.push(`- ${module.id} [${module.kind}] ${module.languages.join("+") || "未知语言"} · owner ${module.owners.join(",") || "未声明"} · roots ${module.roots.join(",")}`);
+        }
+        L.push(`- 策略: ownership=${governance.policies.enforce_ownership} · declared-deps=${governance.policies.enforce_declared_dependencies} · public-interfaces=${governance.policies.enforce_public_interfaces} · unresolved=${governance.policies.fail_on_unresolved} · source-coverage≥${governance.policies.minimum_coverage_pct}% · semantic≥${governance.policies.minimum_semantic_assurance} · regex-fallback=${governance.policies.fail_on_semantic_fallback ? "forbidden" : "allowed"} · quality=${governance.policies.required_quality_kinds.join(",")}`);
+        L.push("- 实时语义结果：pm://architecture / audit_governance；跨仓：pm://portfolio。");
+    }
+    L.push("");
+    /* 任务概览 */
+    L.push("## 📋 任务");
+    const byStatus = new Map();
+    for (const t of tasks)
+        byStatus.set(t.status, (byStatus.get(t.status) ?? 0) + 1);
+    L.push(`- 总览: ${[...byStatus.entries()].map(([k, v]) => `${k} ${v}`).join(" · ") || "（无任务）"}`);
+    const todo = tasks
+        .filter((t) => t.status === "todo" || t.status === "in_progress")
+        .slice(0, 8);
+    for (const t of todo)
+        L.push(`- [${t.status}] ${t.id} ${t.title} (${t.type}${t.milestone ? `, ${t.milestone}` : ""})`);
+    L.push("");
+    /* 功能清单（按模块分组，带验证状态） */
+    L.push("## 🧩 功能清单");
+    if (features.length === 0) {
+        L.push("- （暂无登记。功能落地后用 register_feature 登记，回答「这个项目有哪些功能」。）");
+    }
+    else {
+        const groups = new Map();
+        for (const f of features) {
+            const key = f.module || "未分组";
+            const arr = groups.get(key) ?? [];
+            arr.push(f);
+            groups.set(key, arr);
+        }
+        for (const [mod, list] of groups) {
+            L.push(`### ${mod}`);
+            for (const f of list) {
+                const mark = f.status !== "implemented" ? "○" : featureVerifyMark(root, f.entry_files, f.test_files);
+                L.push(`- ${mark} ${f.id} ${f.name} — ${f.description.slice(0, 80)}`);
+            }
+        }
+    }
+    L.push("");
+    /* 架构决策 */
+    L.push("## 🏛️ 架构决策（最近）");
+    const adrDir = decisionsDir(root);
+    if (fs.existsSync(adrDir)) {
+        const names = fs.readdirSync(adrDir).filter((n) => n.endsWith(".md")).sort().reverse().slice(0, 5);
+        if (names.length === 0)
+            L.push("- （暂无）");
+        for (const n of names)
+            L.push(`- [${n.replace(/\.md$/, "")}](${`.pm/decisions/${n}`})`);
+    }
+    else {
+        L.push("- （暂无）");
+    }
+    L.push("");
+    /* 最近会话 */
+    L.push("## 📜 最近会话");
+    if (sessions.length === 0) {
+        L.push("- （暂无。收工时用 log_session 记录。）");
+    }
+    else {
+        for (const s of sessions.slice(-5).reverse()) {
+            L.push(`- ${s.date.slice(0, 10)} [${s.author || "?"}] ${s.summary}`);
+            if (s.files.length > 0)
+                L.push(`  - 改动: ${s.files.slice(0, 8).join(", ")}${s.files.length > 8 ? ` 等 ${s.files.length} 个` : ""}`);
+        }
+    }
+    L.push("");
+    L.push("---");
+    L.push(`stack: ${project.stack.join(", ") || "—"} · modules: ${project.modules.join(", ") || "—"} · exposure: ${project.exposure} · license: ${project.license || "未声明"}`);
+    return L.join("\n") + "\n";
+}
+/** 从 sessions.json 生成 changelog.md */
+export function buildChangelog(root) {
+    const { sessions } = loadSessions(root);
+    const L = ["# 变更日志（自动生成，来自 sessions.json）", ""];
+    for (const s of [...sessions].reverse()) {
+        L.push(`## ${s.date.slice(0, 10)} — ${s.author || "未知"}`);
+        L.push("");
+        L.push(s.summary);
+        if (s.files.length > 0) {
+            L.push("");
+            L.push(`改动文件（${s.files.length}）: ${s.files.join(", ")}`);
+        }
+        if (s.next_steps.length > 0) {
+            L.push("");
+            L.push(`下一步: ${s.next_steps.join("；")}`);
+        }
+        L.push("");
+    }
+    if (sessions.length === 0)
+        L.push("（暂无会话记录。）");
+    return L.join("\n") + "\n";
+}
+/**
+ * 派生刷新：每次写操作后调用。重写 PROJECT.md 与 changelog.md，并 touch 全局注册表。
+ * 任何派生失败只写 stderr，绝不回滚主操作。
+ */
+export function refreshDerived(root) {
+    try {
+        let name = "";
+        try {
+            name = loadProject(root).name;
+        }
+        catch {
+            return;
+        }
+        // 原子写：多进程并发刷新仪表盘时不会产生半截文件
+        atomicWrite(dashboardFile(root), buildDashboard(root));
+        atomicWrite(pmPath(root, "changelog.md"), buildChangelog(root));
+        if (name)
+            touchRegistry(root, name);
+    }
+    catch (e) {
+        console.error(`[pm-mcp] 派生刷新失败（不影响主操作）: ${e.message}`);
+    }
+}

package/dist/governance-audit.js

@@ -0,0 +1,126 @@
+import fs from "node:fs";
+import path from "node:path";
+import { foldLines } from "./budget.js";
+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";
+function languageIssues(governance, graph) {
+    const issues = [];
+    for (const module of governance.modules) {
+        const matching = graph.files.filter((file) => file.module === module.id && file.status === "parsed");
+        const discovered = new Set(matching.map((file) => file.language).filter((language) => language !== "protobuf" && language !== "graphql" && language !== "openapi"));
+        if (module.languages.length === 0) {
+            issues.push({ severity: "error", code: "module-language-missing", message: `模块 ${module.id} 未声明语言`, evidence: module.roots });
+            continue;
+        }
+        const missing = [...discovered].filter((language) => !module.languages.includes(language));
+        if (missing.length > 0) {
+            issues.push({
+                severity: "error",
+                code: "module-language-drift",
+                message: `模块 ${module.id} 发现未声明语言: ${missing.join(", ")}`,
+                evidence: matching.slice(0, 10).map((file) => `${file.path} => ${file.language}`),
+            });
+        }
+    }
+    return issues;
+}
+function declaredArtifactIssues(root, governance) {
+    const issues = [];
+    for (const module of governance.modules) {
+        for (const declaredRoot of module.roots) {
+            const absolute = path.resolve(root, declaredRoot);
+            if (!fs.existsSync(absolute)) {
+                issues.push({ severity: "error", code: "module-root-missing", message: `模块 ${module.id} 的 root 不存在: ${declaredRoot}`, evidence: [declaredRoot] });
+            }
+            else if (!fs.statSync(absolute).isDirectory()) {
+                issues.push({ severity: "error", code: "module-root-not-directory", message: `模块 ${module.id} 的 root 不是目录: ${declaredRoot}`, evidence: [declaredRoot] });
+            }
+        }
+    }
+    for (const contract of governance.interfaces) {
+        for (const file of contract.contract_files) {
+            const absolute = path.resolve(root, file);
+            if (!fs.existsSync(absolute)) {
+                issues.push({ severity: "error", code: "contract-file-missing", message: `接口 ${contract.id} 的契约文件不存在: ${file}`, evidence: [file] });
+                continue;
+            }
+            const owner = moduleForFile(file, governance.modules);
+            if (owner !== contract.provider) {
+                issues.push({ severity: "error", code: "contract-provider-mismatch", message: `接口 ${contract.id} 契约文件归属 ${owner ?? "未归属"}，不是 provider ${contract.provider}`, evidence: [file] });
+            }
+        }
+    }
+    return issues;
+}
+function graphIssues(graph) {
+    const issues = graph.violations.map((violation) => ({
+        severity: "error",
+        code: violation.type,
+        message: `${violation.type}: ${violation.from} -> ${violation.to}`,
+        evidence: violation.evidence,
+    }));
+    for (const cycle of graph.cycles) {
+        issues.push({ severity: "error", code: "module-cycle", message: `模块依赖循环: ${cycle.join(" -> ")} -> ${cycle[0]}`, evidence: cycle });
+    }
+    return issues;
+}
+function render(governance, graph, units, qualityCoverage, issues, maxLines) {
+    const errors = issues.filter((issue) => issue.severity === "error");
+    const warnings = issues.filter((issue) => issue.severity === "warning");
+    const lines = [
+        "## 跨文件/模块/语言治理审计",
+        `${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}`,
+        `质量矩阵: 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(", ") || "未发现"}`,
+        `> 语义引擎 hybrid-semantic-v2；最低保证 ${governance.policies.minimum_semantic_assurance}，正则 fallback ${governance.policies.fail_on_semantic_fallback ? "禁止" : "允许"}。AST 不能证明动态执行；反射、生成代码和数据驱动分发须补 hash-bound runtime evidence。`,
+    ];
+    if (qualityCoverage.withoutCommands.length > 0) {
+        lines.push(`- 🚩 有 manifest 但没有质量命令的单元: ${qualityCoverage.withoutCommands.join(", ")}`);
+    }
+    for (const issue of issues.slice(0, 25)) {
+        lines.push(`- ${issue.severity === "error" ? "🚩" : "⚠️"} [${issue.code}] ${issue.message}${issue.evidence.length ? ` — ${issue.evidence.slice(0, 3).join(", ")}` : ""}`);
+    }
+    if (issues.length > 25)
+        lines.push(`…另有 ${issues.length - 25} 个问题未展开`);
+    if (graph.coverage.unknownFiles.length > 0)
+        lines.push(`- ⚠️ 未识别文件样例: ${graph.coverage.unknownFiles.slice(0, 8).join(", ")}`);
+    if (graph.coverage.skippedFiles.length > 0)
+        lines.push(`- 🚩 未读取/超限文件样例: ${graph.coverage.skippedFiles.slice(0, 8).join(", ")}`);
+    return foldLines(lines, { maxLines, hint: "用 impact_analysis 或治理过滤参数缩小范围" });
+}
+export function auditGovernance(root, maxLines = 150) {
+    const absolute = path.resolve(root);
+    const governance = loadGovernance(absolute);
+    const graph = buildSemanticGraph(absolute, governance, { semanticEvidence: loadAllSemanticEvidence(absolute) });
+    const units = discoverProjectUnits(absolute);
+    const qualityPlan = createQualityPlan(units);
+    const qualityCoverage = assessQualityCoverage(units);
+    const issues = [
+        ...declaredArtifactIssues(absolute, governance),
+        ...languageIssues(governance, graph),
+        ...graphIssues(graph),
+    ];
+    if (units.length === 0) {
+        issues.push({ severity: "error", code: "quality-units-missing", message: "未发现任何受支持语言 manifest，无法建立质量矩阵", evidence: [] });
+    }
+    if (qualityCoverage.withoutCommands.length > 0) {
+        issues.push({ severity: "error", code: "quality-command-missing", message: `${qualityCoverage.withoutCommands.length} 个单元没有质量命令`, evidence: qualityCoverage.withoutCommands });
+    }
+    for (const unit of units) {
+        for (const error of unit.dependencyErrors) {
+            issues.push({ severity: "error", code: "dependency-parse-error", message: `依赖清单解析失败 ${unit.id}: ${error.message}`, evidence: [`${error.sourceManifest}${error.line ? `:${error.line}` : ""} (${error.parser})`] });
+        }
+        const present = new Set(unit.qualityCommands.map((command) => command.kind));
+        const missing = governance.policies.required_quality_kinds.filter((kind) => !present.has(kind));
+        if (missing.length > 0) {
+            issues.push({ severity: "error", code: "quality-kind-missing", message: `质量单元 ${unit.id} 缺少必需门禁: ${missing.join(", ")}`, evidence: unit.manifest.map((item) => item.path) });
+        }
+    }
+    const ok = !issues.some((issue) => issue.severity === "error");
+    return { ok, governance, graph, units, qualityPlan, qualityCoverage, issues, report: render(governance, graph, units, qualityCoverage, issues, maxLines) };
+}

package/dist/governance-model.js

@@ -0,0 +1,306 @@
+import fs from "node:fs";
+import path from "node:path";
+import { z } from "zod";
+import { pmPath } from "./paths.js";
+import { loadJson, saveJson, withLedgerLock } from "./store.js";
+export const GOVERNANCE_SCHEMA_VERSION = 1;
+export const GOVERNANCE_FILE = "governance.json";
+const IdSchema = z.string().trim().min(1);
+const TextSchema = z.string().trim().min(1);
+/**
+ * Governance paths are persisted with POSIX separators so the ledger has the
+ * same identity on Windows and Unix. Resolution against a checkout is left to
+ * callers because repository roots may intentionally be absolute or external.
+ */
+export function normalizeGovernancePath(value) {
+    const slashed = value.trim().replace(/\\/g, "/").replace(/\/{2,}/g, "/");
+    const normalized = path.posix.normalize(slashed);
+    return normalized.length > 1 ? normalized.replace(/\/+$/, "") : normalized;
+}
+const GovernancePathSchema = z
+    .string()
+    .trim()
+    .min(1)
+    .transform(normalizeGovernancePath)
+    .pipe(z.string().min(1));
+const IdListSchema = z.array(IdSchema).default([]);
+const TextListSchema = z.array(TextSchema).default([]);
+const PathListSchema = z.array(GovernancePathSchema).default([]);
+const ModuleRootsSchema = z.array(GovernancePathSchema).min(1, "模块至少需要一个 root");
+export const ModuleSpecSchema = z.object({
+    id: IdSchema,
+    name: TextSchema,
+    roots: ModuleRootsSchema,
+    kind: TextSchema,
+    owners: TextListSchema,
+    languages: TextListSchema,
+    public_interfaces: IdListSchema,
+    depends_on: IdListSchema,
+    allowed_dependencies: IdListSchema,
+    denied_dependencies: IdListSchema,
+});
+export const InterfaceSpecSchema = z.object({
+    id: IdSchema,
+    kind: TextSchema,
+    provider: IdSchema,
+    consumers: IdListSchema,
+    contract_files: PathListSchema,
+    version: TextSchema,
+});
+export const RepositoryDependencySchema = z.object({
+    repository: IdSchema,
+    /** 支持 *、精确 semver、^、~、>=、<=、>、<；其他形式由组合审计标为未知。 */
+    constraint: TextSchema.default("*"),
+});
+export const RepositorySpecSchema = z.object({
+    id: IdSchema,
+    name: TextSchema,
+    root: GovernancePathSchema,
+    version: TextSchema,
+    dependencies: z.array(RepositoryDependencySchema).default([]),
+});
+export const GovernancePoliciesSchema = z.object({
+    enforce_ownership: z.boolean().default(true),
+    enforce_declared_dependencies: z.boolean().default(true),
+    enforce_public_interfaces: z.boolean().default(true),
+    fail_on_unresolved: z.boolean().default(true),
+    minimum_coverage_pct: z.number().min(0).max(100).default(80),
+    minimum_semantic_assurance: z.enum(["heuristic", "ast", "runtime"]).default("heuristic"),
+    fail_on_semantic_fallback: z.boolean().default(false),
+    required_quality_kinds: z.array(z.enum(["test", "build", "lint", "typecheck", "coverage", "security"])).default(["test", "build"]),
+});
+function addDuplicateIssues(values, collection, ctx) {
+    const first = new Map();
+    values.forEach((value, index) => {
+        const previous = first.get(value);
+        if (previous === undefined) {
+            first.set(value, index);
+            return;
+        }
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: [collection, index, "id"],
+            message: `重复 ID "${value}"（首次出现在 ${collection}.${previous}.id）`,
+        });
+    });
+}
+function addDuplicateListIssues(values, pathPrefix, label, ctx) {
+    const seen = new Set();
+    values.forEach((value, index) => {
+        if (!seen.has(value)) {
+            seen.add(value);
+            return;
+        }
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: [...pathPrefix, index],
+            message: `${label}包含重复引用 "${value}"`,
+        });
+    });
+}
+export const GovernanceSchema = z
+    .object({
+    schema_version: z.literal(GOVERNANCE_SCHEMA_VERSION).default(GOVERNANCE_SCHEMA_VERSION),
+    modules: z.array(ModuleSpecSchema).default([]),
+    interfaces: z.array(InterfaceSpecSchema).default([]),
+    repositories: z.array(RepositorySpecSchema).default([]),
+    policies: GovernancePoliciesSchema.default({
+        enforce_ownership: true,
+        enforce_declared_dependencies: true,
+        enforce_public_interfaces: true,
+        fail_on_unresolved: true,
+        minimum_coverage_pct: 80,
+        minimum_semantic_assurance: "heuristic",
+        fail_on_semantic_fallback: false,
+        required_quality_kinds: ["test", "build"],
+    }),
+})
+    .superRefine((governance, ctx) => {
+    addDuplicateIssues(governance.modules.map((module) => module.id), "modules", ctx);
+    addDuplicateIssues(governance.interfaces.map((item) => item.id), "interfaces", ctx);
+    addDuplicateIssues(governance.repositories.map((repository) => repository.id), "repositories", ctx);
+    const moduleIds = new Set(governance.modules.map((module) => module.id));
+    const interfaceById = new Map(governance.interfaces.map((item) => [item.id, item]));
+    const rootOwner = new Map();
+    const repositoryRootOwner = new Map();
+    governance.modules.forEach((module, moduleIndex) => {
+        addDuplicateListIssues(module.roots, ["modules", moduleIndex, "roots"], "roots", ctx);
+        addDuplicateListIssues(module.owners, ["modules", moduleIndex, "owners"], "owners", ctx);
+        addDuplicateListIssues(module.languages, ["modules", moduleIndex, "languages"], "languages", ctx);
+        addDuplicateListIssues(module.public_interfaces, ["modules", moduleIndex, "public_interfaces"], "public_interfaces", ctx);
+        addDuplicateListIssues(module.depends_on, ["modules", moduleIndex, "depends_on"], "depends_on", ctx);
+        addDuplicateListIssues(module.allowed_dependencies, ["modules", moduleIndex, "allowed_dependencies"], "allowed_dependencies", ctx);
+        addDuplicateListIssues(module.denied_dependencies, ["modules", moduleIndex, "denied_dependencies"], "denied_dependencies", ctx);
+        if (governance.policies.enforce_ownership && module.owners.length === 0) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ["modules", moduleIndex, "owners"],
+                message: `模块 "${module.id}" 在 enforce_ownership=true 时必须声明 owner`,
+            });
+        }
+        module.roots.forEach((root, rootIndex) => {
+            const key = root.toLocaleLowerCase("en-US");
+            const owner = rootOwner.get(key);
+            if (owner && owner.moduleId !== module.id) {
+                ctx.addIssue({
+                    code: z.ZodIssueCode.custom,
+                    path: ["modules", moduleIndex, "roots", rootIndex],
+                    message: `root "${root}" 已归属模块 "${owner.moduleId}"（modules.${owner.index}.roots）`,
+                });
+            }
+            else if (!owner) {
+                rootOwner.set(key, { moduleId: module.id, index: moduleIndex });
+            }
+        });
+        const dependencyFields = [
+            ["depends_on", module.depends_on],
+            ["allowed_dependencies", module.allowed_dependencies],
+            ["denied_dependencies", module.denied_dependencies],
+        ];
+        for (const [field, references] of dependencyFields) {
+            references.forEach((reference, referenceIndex) => {
+                if (!moduleIds.has(reference)) {
+                    ctx.addIssue({
+                        code: z.ZodIssueCode.custom,
+                        path: ["modules", moduleIndex, field, referenceIndex],
+                        message: `未知 module 引用 "${reference}"`,
+                    });
+                }
+                else if (reference === module.id) {
+                    ctx.addIssue({
+                        code: z.ZodIssueCode.custom,
+                        path: ["modules", moduleIndex, field, referenceIndex],
+                        message: `模块 "${module.id}" 不能在 ${field} 中引用自身`,
+                    });
+                }
+            });
+        }
+        const denied = new Set(module.denied_dependencies);
+        module.allowed_dependencies.forEach((dependency, dependencyIndex) => {
+            if (denied.has(dependency)) {
+                ctx.addIssue({
+                    code: z.ZodIssueCode.custom,
+                    path: ["modules", moduleIndex, "allowed_dependencies", dependencyIndex],
+                    message: `依赖 "${dependency}" 不能同时允许和禁止`,
+                });
+            }
+        });
+        module.depends_on.forEach((dependency, dependencyIndex) => {
+            if (denied.has(dependency)) {
+                ctx.addIssue({
+                    code: z.ZodIssueCode.custom,
+                    path: ["modules", moduleIndex, "depends_on", dependencyIndex],
+                    message: `已声明依赖 "${dependency}" 同时出现在 denied_dependencies`,
+                });
+            }
+        });
+        module.public_interfaces.forEach((interfaceId, interfaceIndex) => {
+            const item = interfaceById.get(interfaceId);
+            if (!item) {
+                ctx.addIssue({
+                    code: z.ZodIssueCode.custom,
+                    path: ["modules", moduleIndex, "public_interfaces", interfaceIndex],
+                    message: `未知 interface 引用 "${interfaceId}"`,
+                });
+            }
+            else if (item.provider !== module.id) {
+                ctx.addIssue({
+                    code: z.ZodIssueCode.custom,
+                    path: ["modules", moduleIndex, "public_interfaces", interfaceIndex],
+                    message: `interface "${interfaceId}" 的 provider 是 "${item.provider}"，不是 "${module.id}"`,
+                });
+            }
+        });
+    });
+    governance.interfaces.forEach((item, interfaceIndex) => {
+        if (!moduleIds.has(item.provider)) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ["interfaces", interfaceIndex, "provider"],
+                message: `未知 module 引用 "${item.provider}"`,
+            });
+        }
+        addDuplicateListIssues(item.consumers, ["interfaces", interfaceIndex, "consumers"], "consumers", ctx);
+        addDuplicateListIssues(item.contract_files, ["interfaces", interfaceIndex, "contract_files"], "contract_files", ctx);
+        item.consumers.forEach((consumer, consumerIndex) => {
+            if (!moduleIds.has(consumer)) {
+                ctx.addIssue({
+                    code: z.ZodIssueCode.custom,
+                    path: ["interfaces", interfaceIndex, "consumers", consumerIndex],
+                    message: `未知 module 引用 "${consumer}"`,
+                });
+            }
+        });
+        if (governance.policies.enforce_public_interfaces) {
+            const provider = governance.modules.find((module) => module.id === item.provider);
+            if (provider && !provider.public_interfaces.includes(item.id)) {
+                ctx.addIssue({
+                    code: z.ZodIssueCode.custom,
+                    path: ["interfaces", interfaceIndex, "provider"],
+                    message: `interface "${item.id}" 未登记在 provider "${item.provider}" 的 public_interfaces`,
+                });
+            }
+        }
+    });
+    governance.repositories.forEach((repository, repositoryIndex) => {
+        const rootKey = repository.root.toLocaleLowerCase("en-US");
+        const owner = repositoryRootOwner.get(rootKey);
+        if (owner && owner.repositoryId !== repository.id) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ["repositories", repositoryIndex, "root"],
+                message: `repository root "${repository.root}" 已归属仓库 "${owner.repositoryId}"（repositories.${owner.index}.root）`,
+            });
+        }
+        else if (!owner) {
+            repositoryRootOwner.set(rootKey, { repositoryId: repository.id, index: repositoryIndex });
+        }
+        addDuplicateListIssues(repository.dependencies.map((dependency) => dependency.repository), ["repositories", repositoryIndex, "dependencies"], "dependencies", ctx);
+        repository.dependencies.forEach((dependency, dependencyIndex) => {
+            // Repository dependencies are portfolio-wide references: the target may
+            // live in another governance file, so missing-target checks belong to
+            // the composition layer rather than this single-file schema.
+            if (dependency.repository === repository.id) {
+                ctx.addIssue({
+                    code: z.ZodIssueCode.custom,
+                    path: ["repositories", repositoryIndex, "dependencies", dependencyIndex, "repository"],
+                    message: `仓库 "${repository.id}" 不能依赖自身`,
+                });
+            }
+        });
+    });
+});
+export function governancePath(root) {
+    return pmPath(path.resolve(root), GOVERNANCE_FILE);
+}
+export function loadGovernance(root) {
+    const file = governancePath(root);
+    if (!fs.existsSync(file)) {
+        throw new Error(`治理模型未初始化（缺少 ${file}），请先调用 init_governance。`);
+    }
+    const governance = loadJson(file, GovernanceSchema);
+    if (governance === undefined) {
+        throw new Error(`治理模型未初始化（缺少 ${file}），请先调用 init_governance。`);
+    }
+    return governance;
+}
+export function saveGovernance(root, governance) {
+    const parsed = GovernanceSchema.parse(governance);
+    const file = governancePath(root);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    saveJson(file, parsed);
+    return parsed;
+}
+export function initGovernance(root, governance = {}) {
+    return withLedgerLock(root, () => {
+        const file = governancePath(root);
+        if (fs.existsSync(file)) {
+            throw new Error(`治理模型已初始化（${file} 已存在）。`);
+        }
+        return saveGovernance(root, governance);
+    });
+}
+/** Fail-closed existence and schema check for callers that require governance. */
+export function ensureGovernance(root) {
+    return loadGovernance(root);
+}