add-coder 0.3.26 → 0.3.28

package/templates/core/scripts/mcp-server/tools/contract.ts

@@ -7,6 +7,7 @@ import { readdirRecursive, PROJECT_ROOT, MAGIC_DIR } from "../shared/fs.js"
 import { prisma } from "../shared/prisma.js"
 import type { CollabContractRow, PlanRow } from "../shared/db-types.js"
 import { CollabContractRowSchema, PlanRowSchema, validatedDelegate } from "../shared/db-types.js"
+import { getRuntimeContext } from "../shared/env.js"
 
 const db = {
   get collabContract() { return validatedDelegate<CollabContractRow>(prisma.collabContract, CollabContractRowSchema, "CollabContract") },
@@ -67,6 +68,7 @@ function parseContractDoc(content: string): ParsedContract {
 }
 
 export function registerContractTools(server: ToolRegistrar) {
+  const runtimeContext = getRuntimeContext()
 
   // ===== contract_track =====
   server.registerTool("contract_track", {
@@ -124,13 +126,30 @@ export function registerContractTools(server: ToolRegistrar) {
           results.push(`⚠️ ${name}  缺少「总控 Plan:」声明，跳过`)
           continue
         }
-        const existing = await db.collabContract.findFirst({ where: { contractName: name } })
+        const masterPlan = await db.plan.findFirst({
+          where: {
+            projectKey: runtimeContext.projectKey,
+            adapterKey: runtimeContext.adapterKey,
+            planName: masterPlanName,
+          },
+        })
+        if (!masterPlan) {
+          results.push(`⚠️ ${name}  当前 RuntimeContextKey 下不存在 Master Plan: ${masterPlanName}`)
+          continue
+        }
+        const existing = await db.collabContract.findFirst({
+          where: { projectKey: runtimeContext.projectKey, contractName: name },
+        })
         const version = (existing?.version as number ?? 0) + 1
 
         const data = {
           contractName: name,
+          projectKey: runtimeContext.projectKey,
+          ownerAdapterKey: runtimeContext.adapterKey,
           contractPath: path,
           masterPlanName,
+          masterProjectKey: runtimeContext.projectKey,
+          masterAdapterKey: runtimeContext.adapterKey,
           participants: parsed.participants as never,
           abilityMatrix: parsed.abilityMatrix as never,
           stages: parsed.stages as never,
@@ -142,7 +161,7 @@ export function registerContractTools(server: ToolRegistrar) {
         }
 
         if (existing) {
-          await db.collabContract.update({ where: { contractName: name }, data })
+          await db.collabContract.update({ where: { id: existing.id }, data })
           results.push(`📄 ${name}  ✅ 已更新 (v${version})`)
         } else {
           await db.collabContract.create({ data })
@@ -152,8 +171,12 @@ export function registerContractTools(server: ToolRegistrar) {
         // 若 masterPlan 存在，标记 PlanRecord 角色
         if (masterPlanName) {
           await db.plan.updateMany({
-            where: { planName: masterPlanName },
-            data: { contractRole: "MASTER", contractName: name } as never,
+            where: {
+              projectKey: runtimeContext.projectKey,
+              adapterKey: runtimeContext.adapterKey,
+              planName: masterPlanName,
+            },
+            data: { contractRole: "MASTER", contractName: name },
           })
         }
       }
@@ -173,7 +196,9 @@ export function registerContractTools(server: ToolRegistrar) {
   }, async (args: Record<string, unknown>) => {
     try {
       const { contractName } = args as { contractName: string }
-      const contract = await db.collabContract.findFirst({ where: { contractName } })
+      const contract = await db.collabContract.findFirst({
+        where: { projectKey: runtimeContext.projectKey, contractName },
+      })
       if (!contract) {
         return textResponse(`📋 契约: 未跟踪\ncontractName: ${contractName}\n\n操作: contract_track({ contractName: "${contractName}" })`)
       }
@@ -182,11 +207,11 @@ export function registerContractTools(server: ToolRegistrar) {
       const boundaries = (contract.fileBoundaries as unknown[]) || []
       const parallelCount = stages.filter((s) => (s as Record<string, unknown>).parallelism === "parallel").length
       const serialCount = stages.filter((s) => (s as Record<string, unknown>).parallelism === "serial").length
-      const versionStr = String(contract.version as number ?? "?")
-      const statusStr = String(contract.status as string ?? "?")
-      const masterStr = String(contract.masterPlanName as string ?? "(未绑定)")
+      const versionStr = String(contract.version ?? "?")
+      const statusStr = String(contract.status ?? "?")
+      const masterStr = String(contract.masterPlanName ?? "(未绑定)")
       const depStr = contract.dependencyGraph ? "已声明" : "未声明"
-      const pathStr = String(contract.contractPath as string ?? "(无)")
+      const pathStr = String(contract.contractPath ?? "(无)")
       return textResponse(
         `📊 ${contractName}\n` +
         `版本:      v${versionStr} (${statusStr})\n` +

package/templates/core/scripts/mcp-server/tools/gateway/check_add_route_status.ts

@@ -17,6 +17,7 @@ import {
   MAGIC_DIR,
 } from "../../shared/fs.js";
 import { prisma } from "../../shared/prisma.js";
+import { getRuntimeContext } from "../../shared/env.js";
 
 function scanCheckboxes(content: string) {
   let t = 0,
@@ -61,6 +62,7 @@ function scanCheckboxes(content: string) {
 }
 
 export function registerCheckAddRouteStatus(server: ToolRegistrar) {
+  const runtimeContext = getRuntimeContext();
   server.registerTool(
     "check_add_route_status",
     {
@@ -85,10 +87,13 @@ export function registerCheckAddRouteStatus(server: ToolRegistrar) {
             prisma.auditLog as Record<string, (...a: unknown[]) => unknown>
           ).findMany({
             where: {
-              OR: [
-                { targetId: { contains: "add-route", mode: "insensitive" } },
+              projectKey: runtimeContext.projectKey,
+              producerAdapterKey: runtimeContext.adapterKey,
+              // 按当前 Plan 精准定位：targetId 同时含 planKeyword 与 add-route（与文件匹配语义一致）
+              AND: [
+                { targetId: { startsWith: `${MAGIC_DIR}/` } },
                 { targetId: { contains: planKeyword, mode: "insensitive" } },
-                { reason: { contains: "add-route", mode: "insensitive" } },
+                { targetId: { contains: "add-route", mode: "insensitive" } },
               ],
             },
             orderBy: { createdAt: "desc" },
@@ -113,6 +118,48 @@ export function registerCheckAddRouteStatus(server: ToolRegistrar) {
         } catch {
           /* empty */
         }
+        // 补查 DevOperation 表（record_dev_operation 写入通道；R10 修复，2026-08-12 用户拍板不另立 Plan，本 Plan 内闭环）
+        try {
+          const devLogs = await (
+            prisma.devOperation as Record<string, (...a: unknown[]) => unknown>
+          ).findMany({
+            where: {
+              projectKey: runtimeContext.projectKey,
+              producerAdapterKey: runtimeContext.adapterKey,
+              // 按当前 Plan 精准定位（AND：planKeyword + add-route），命中集天然为当前 Plan 的 add-route 记录
+              AND: [
+                { targetId: { startsWith: `${MAGIC_DIR}/` } },
+                { targetId: { contains: planKeyword, mode: "insensitive" } },
+                { targetId: { contains: "add-route", mode: "insensitive" } },
+              ],
+            },
+            orderBy: { createdAt: "desc" },
+            take: 100,
+          }) as Array<{
+            targetId?: string;
+            reason?: string;
+            action: string;
+            createdAt: Date;
+          }>;
+          const pl = planKeyword.toLowerCase();
+          for (const l of devLogs) {
+            const ti = (l.targetId || "").toLowerCase();
+            const r = (l.reason || "").toLowerCase();
+            if (
+              (ti.includes("add-route") && ti.includes(pl)) ||
+              (r.includes("add-route") && r.includes(pl))
+            ) {
+              auditHasRecord = true;
+              auditRecords.push({
+                action: l.action,
+                targetId: l.targetId || "unknown",
+                createdAt: l.createdAt,
+              });
+            }
+          }
+        } catch {
+          /* empty */
+        }
         let fileExists = false;
         const matchedFiles: string[] = [];
         try {

package/templates/core/scripts/mcp-server/tools/gateway/check_doc_similarity.ts

@@ -0,0 +1,218 @@
+/*
+ * @Description  : 量化复检层 — 形似义异判定（锚点加权 Jaccard + TF-IDF cosine + RRF + EWMA ±kσ）
+ * @File         : templates/core/scripts/mcp-server/tools/gateway/check_doc_similarity.ts
+ * @契约          : 消费 v3 Spec §6 jsonl（anchor_hit/struct_score/override）与 quant-events.jsonl（自记录）
+ * @回流          : Specs Review P0-1(参照物章节全文)/P0-2(候选集)/P1-5(量纲解耦)/P1-6(校准样本)/P1-7(decide 事件)
+ */
+import * as z from "zod/v4";
+import type { ToolRegistrar } from "../registrar.js";
+import { join, basename } from "path";
+import { appendFileSync, mkdirSync, existsSync, readFileSync } from "fs";
+import { readFileSafe, readdirRecursive, PROJECT_ROOT, MAGIC_DIR } from "../../shared/fs.js";
+import { textResponse, errorResponse } from "../../shared/response.js";
+import { QUANT_RECHECK_CONFIG as CFG } from "../../shared/quant-recheck.strategy.js";
+import { tokenize, jaccard, tfVector } from "./helpers.js";
+import { cosineSimilarity } from "vector-cosine-similarity";
+
+// ── 锚点加权 Jaccard（锚点 token ×ANCHOR_WEIGHT，普通 token ×1）──
+export function weightedJaccard(a: Set<string>, b: Set<string>, anchors: Set<string>): number {
+  const w = (t: string) => (anchors.has(t) ? CFG.ANCHOR_WEIGHT : 1);
+  let num = 0, den = 0;
+  const all = new Set([...a, ...b]);
+  for (const t of all) {
+    const wa = a.has(t) ? w(t) : 0;
+    const wb = b.has(t) ? w(t) : 0;
+    num += Math.min(wa, wb);
+    den += Math.max(wa, wb);
+  }
+  return den > 0 ? num / den : 1;
+}
+
+// ── RRF 排名融合（Spec §2 语义：目标文档双路排名和，非候选均值）──
+export function rrfScore(candidates: { j: number; t: number }[]): number {
+  // 双路排名：分数降序得 rank（并列同 rank）
+  const rankBy = (get: (c: { j: number; t: number }) => number) => {
+    const sorted = [...candidates].sort((x, y) => get(y) - get(x));
+    const ranks = new Map<{ j: number; t: number }, number>();
+    sorted.forEach((c, i) => { if (!ranks.has(c)) ranks.set(c, i + 1); });
+    return ranks;
+  };
+  const rj = rankBy((c) => c.j);
+  const rt = rankBy((c) => c.t);
+  // 目标文档 = 双路综合最优候选（j+t 最高）
+  const best = candidates.reduce((a, b) => (a.j + a.t >= b.j + b.t ? a : b));
+  // RRF(文档) = 1/(K+rank_j) + 1/(K+rank_t)
+  return 1 / (CFG.RRF_K + (rj.get(best) ?? 1)) + 1 / (CFG.RRF_K + (rt.get(best) ?? 1));
+}
+
+// ── EWMA ±kσ 阈值（历史复合分序列；冷启动用保守基线）──
+export function ewmaThreshold(history: number[]): { mu: number; sigma: number; lower: number } {
+  if (history.length < CFG.EWMA_COLD_START) {
+    return { mu: CFG.EWMA_BASELINE, sigma: 0, lower: CFG.EWMA_BASELINE };
+  }
+  let mu = history[0], varEst = 0;
+  for (let i = 1; i < history.length; i++) {
+    const diff = history[i] - mu;
+    mu = CFG.EWMA_LAMBDA * history[i] + (1 - CFG.EWMA_LAMBDA) * mu;
+    varEst = CFG.EWMA_LAMBDA * diff * diff + (1 - CFG.EWMA_LAMBDA) * varEst;
+  }
+  const sigma = Math.sqrt(varEst);
+  return { mu, sigma, lower: mu - CFG.EWMA_K * sigma };
+}
+
+// ── 模板匹配（R3：目录扫描 + 特征序 + 存在性校验，与守卫注册表同序，不硬编码死模板）──
+const TEMPLATE_PATTERNS: [RegExp, string][] = [
+  [/add-route.*heavy|heavy.*add-route/, "add-route-template-heavyweight.md"],
+  [/add-route/, "add-route-template.md"],
+  [/hitl/, "hitl-template.md"],
+  [/handoff/, "handoff-multi-round-template.md"],
+  [/checklist/, "checklist-template.md"],
+  [/fix-verif/, "fix-verification-template.md"],
+  [/report.*runtime|runtime.*report/, "runtime-report-template.md"],
+  [/report/, "report-template.md"],
+  [/tasks/, "tasks-template.md"],
+  [/spec/, "spec-template.md"],
+  [/prd.*increment|increment.*prd/, "prd-incremental-template.md"],
+  [/prd/, "prd-standard-template.md"],
+  [/simple.*plan|plan.*simple/, "simple-plan-template.md"],
+  [/plan/, "standard-plan-template.md"],
+  [/review.*runtime|runtime.*review/, "review-runtime-template.md"],
+  [/review.*implement|implement.*review/, "review-implementation-template.md"],
+  [/review/, "review-template.md"],
+];
+
+async function matchTemplate(templatesDir: string, docPath: string): Promise<string> {
+  // 目录扫描可用模板清单（模板增删自动感知，不硬编码）
+  const all = (await readdirRecursive(templatesDir)) as string[];
+  const tmpls = new Set(all.filter((f) => f.endsWith("-template.md")));
+  // 只匹配文件名（basename），避免路径目录词污染（如 reports/ 误命中 report 模板——R4）
+  const base = basename(docPath || "");
+  const n = base.toLowerCase();
+  for (const [re, tmpl] of TEMPLATE_PATTERNS) {
+    if (re.test(n) && tmpls.has(tmpl)) return tmpl;
+  }
+  return "standard-plan-template.md";  // 缺省回退 Plan 模板
+}
+
+// ── 判定记录（P1-5：quant-events.jsonl 追加，与 hook-events 量纲解耦）──
+function appendQuantEvent(rec: Record<string, unknown>): void {
+  try {
+    const dir = join(PROJECT_ROOT, MAGIC_DIR, "reports");
+    mkdirSync(dir, { recursive: true });
+    appendFileSync(join(dir, "quant-events.jsonl"), `${JSON.stringify(rec)}\n`, "utf-8");
+  } catch { /* 旁路：判定不因落盘失败中断 */ }
+}
+
+// ── 建议清单（P1-7/Task 2.2：status + event 追加式流转，人类 decide 事件为校准样本）──
+function appendSuggestion(rec: Record<string, unknown>): void {
+  try {
+    const dir = join(PROJECT_ROOT, MAGIC_DIR, "reports");
+    mkdirSync(dir, { recursive: true });
+    appendFileSync(join(dir, "quant-suggestions.jsonl"), `${JSON.stringify(rec)}\n`, "utf-8");
+  } catch { /* 旁路 */ }
+}
+
+export function registerCheckDocSimilarity(server: ToolRegistrar) {
+  server.registerTool(
+    "check_doc_similarity",
+    {
+      description:
+        `量化复检层：「形似义异」语义判定。锚点加权 Jaccard + TF-IDF cosine 双路相似度，RRF 融合，EWMA ±kσ 自适应阈值。非关键路径调用（Step 3.5/收敛判断时）。`,
+      inputSchema: z.object({
+        planKeyword: z.string().describe("Plan 文件的关键词"),
+        docPath: z.string().optional().describe("目标文档相对路径（缺省取当前活跃 Plan）"),
+      }),
+    },
+    async (args: Record<string, unknown>, _ctx: unknown) => {
+      try {
+        const pp = args.planKeyword as string;
+        if (!pp) return errorResponse("planKeyword 参数不能为空");
+
+        // ── 候选集（P0-2）：模板全部 sections 章节全文（P0-1 参照物粒度）──
+        const templatesDir = join(PROJECT_ROOT, MAGIC_DIR, "templates");
+        const plansDir = join(PROJECT_ROOT, MAGIC_DIR, "plans");
+        const reportsDir = join(PROJECT_ROOT, MAGIC_DIR, "reports");
+
+        // 定位 Plan（递归扫日期子目录；排除 .hitl.md 提案）
+        const planFiles = (await readdirRecursive(plansDir)) as string[];
+        const planFile = planFiles.find((f) => f.toLowerCase().includes(pp.toLowerCase()) && f.includes("-plan-v") && !f.endsWith(".hitl.md"));
+        if (!planFile) return errorResponse(`未找到匹配的 Plan（关键词: ${pp}）`);
+        const planPath = join(plansDir, planFile);
+        const planContent = await readFileSafe(planPath) || "";
+        const anchorMatch = planContent.match(/anchor\s*[:：]\s*"?([A-Za-z_]+)/);
+        const anchor = anchorMatch ? anchorMatch[1] : "plan_track";
+
+        // 读模板文件全文（R3：按文档类型匹配模板，refText = 模板章节全文——P0-1）
+        const tmplName = await matchTemplate(templatesDir, String(args.docPath ?? ""));
+        const tmplPath = join(templatesDir, tmplName);
+        const tmplContent = await readFileSafe(tmplPath) || "";
+        const refTokens = tokenize(tmplContent);
+        const anchorTokens = new Set([...tokenize(anchor)]);
+
+        // 候选集：模板 sections（按 ## 切分）+ 历史文档抽样
+        const sections = tmplContent.split(/^##\s+/m).filter((s) => s.trim().length > 0);
+        const candidates = sections.map((sec) => tokenize(sec)).slice(0, 20);
+        const docContent = args.docPath
+          ? (await readFileSafe(join(PROJECT_ROOT, String(args.docPath))) || "")
+          : planContent;
+        const docTokens = tokenize(docContent);
+
+        // 双路打分（候选集内）
+        const scored = candidates.map((ct) => {
+          const j = weightedJaccard(docTokens, ct, anchorTokens);
+          const globalTokens = candidates.length >= CFG.IDF_MIN_DOCS ? candidates : [ct];
+          const t = cosineSimilarity(tfVector(docTokens, globalTokens), tfVector(ct, globalTokens));
+          return { j, t };
+        });
+
+        // RRF 融合（候选不足退保守路径）
+        const rrf = scored.length >= CFG.RRF_MIN_CANDIDATES ? rrfScore(scored) : Math.min(...scored.map((s) => s.j));
+
+        // EWMA 阈值（P1-5：序列仅量化层复合分）
+        let history: number[] = [];
+        try {
+          const evFile = join(reportsDir, "quant-events.jsonl");
+          if (existsSync(evFile)) {
+            history = readFileSync(evFile, "utf-8").trim().split("\n")
+              .map((l) => { try { return (JSON.parse(l) as { rrf?: number }).rrf ?? NaN; } catch { return NaN; } })
+              .filter((v) => Number.isFinite(v)) as number[];
+          }
+        } catch { /* 冷启动 */ }
+        const th = ewmaThreshold(history);
+        // 复合判定：RRF 相对排名 ≥ 自适应阈值 且 双路综合绝对匹配达标（双闸门）
+        // 绝对闸门用 max(j, t)：真实文档与模板全文 token 重叠天然低（骨架 vs 实例），Jaccard 单路会误杀
+        const bestMatch = Math.max(...scored.map((s) => Math.max(s.j, s.t)));
+        const absOk = bestMatch >= CFG.MIN_ABS_SIMILARITY;
+        const verdict = rrf >= th.lower && absOk ? "PASS" : "WARN_BLOCKED";
+
+        // 判定记录（P1-5/6/7：decide 事件由建议清单人类裁决写入）
+        appendQuantEvent({ ts: new Date().toISOString(), planKeyword: pp, jaccard: scored[0]?.j ?? 0, tfidf: scored[0]?.t ?? 0, rrf, ewmaThreshold: th.lower, verdict });
+
+        const suggestion = verdict === "WARN_BLOCKED"
+          ? { schemaHint: `${tmplName} anchor=${anchor}`, evidence: `j=${scored[0]?.j.toFixed(3)} t=${scored[0]?.t.toFixed(3)} rrf=${rrf.toFixed(4)}`, suggestion: "review schema 声明松紧（guard-rules.toml）" }
+          : null;
+
+        // 建议落盘（P1-7：status=open + event=create；人类 decide 后追加 event=decide + status=closed）
+        if (suggestion) {
+          appendSuggestion({
+            ts: new Date().toISOString(), planKeyword: pp, docPath: args.docPath ?? planFile,
+            ...suggestion, status: "open", event: "create",
+          });
+        }
+
+        return textResponse(
+          `=== check_doc_similarity（量化复检）===\n` +
+          `Plan: ${planFile}\n` +
+          `Jaccard: ${(scored[0]?.j ?? 0).toFixed(3)}（锚点加权 ×${CFG.ANCHOR_WEIGHT}）\n` +
+          `TF-IDF: ${(scored[0]?.t ?? 0).toFixed(3)}（候选集 ${scored.length}，IDF 语料锚 ${candidates.length >= CFG.IDF_MIN_DOCS ? "启用" : "退化" }）\n` +
+          `RRF: ${rrf.toFixed(4)}（K=${CFG.RRF_K}）\n` +
+          `EWMA 阈值: ${th.lower.toFixed(4)}（历史 ${history.length} 条${history.length < CFG.EWMA_COLD_START ? "，冷启动基线" : "，自适应"}）\n` +
+          `判定: ${verdict}\n` +
+          (suggestion ? `建议: ${JSON.stringify(suggestion)}\n` : "")
+        );
+      } catch (e) {
+        return errorResponse(`check_doc_similarity 异常: ${e instanceof Error ? e.message : String(e)}`);
+      }
+    },
+  );
+}

package/templates/core/scripts/mcp-server/tools/gateway/check_dps.ts

@@ -28,8 +28,10 @@ import {
   fftWeights,
   getEmbeddings,
 } from "./helpers.js";
+import { getRuntimeContext } from "../../shared/env.js";
 
 export function registerCheckDps(server: ToolRegistrar) {
+  const runtimeContext = getRuntimeContext();
   server.registerTool(
     "check_dps",
     {
@@ -57,12 +59,18 @@ export function registerCheckDps(server: ToolRegistrar) {
         const apf = (await readdirRecursive(plansDir)).filter(
           (f) => f.endsWith(".md") && !f.includes(".hitl"),
         );
-        const pm = apf.find(
+        // 多版本（-plan-vN）共存时取版本号最高者：活跃 Plan 优先，避免评分旧版（2026-08-12 修复）
+        const matched = apf.filter(
           (f) =>
             f.toLowerCase().includes(pp.toLowerCase()) && f.includes("-plan-v"),
         );
-        if (!pm)
+        if (!matched.length)
           return errorResponse(`未找到匹配的 Plan 文件（关键词: ${pp}）`);
+        const pm = matched.sort((a, b) => {
+          const va = parseInt(a.match(/-plan-v(\d+)/)?.[1] ?? "0", 10);
+          const vb = parseInt(b.match(/-plan-v(\d+)/)?.[1] ?? "0", 10);
+          return vb - va;
+        })[0];
         const planPath = join(plansDir, pm);
         const pc = await readFileSafe(planPath);
         if (!pc) return errorResponse(`无法读取 Plan 文件: ${pm}`);
@@ -106,8 +114,7 @@ export function registerCheckDps(server: ToolRegistrar) {
         //   子维度 A: 映射结构 (40%) — 映射表是否存在 + 覆盖行数
         //   子维度 B: 延续性 (60%) — Plan 决策文本 vs Spec §N 内容的 embedding 余弦相似度
         const planTerms = tokenize(pc),
-          specTermsRaw = tokenize(sc),
-          reviewTerms = tokenize(rc);
+          specTermsRaw = tokenize(sc);
         const planMapping = pc.match(/###\s+\d+\.\d+\s+Plan.*?Spec.*?实施映射/);
         let mappingTotal = 0,
           mappingMatched = 0;
@@ -456,12 +463,16 @@ export function registerCheckDps(server: ToolRegistrar) {
 
         // FFT 自适应权重
         const fourScores = [semScore, entropyScore, cpmScore, structFinal];
-        let histMatrix: number[][] = [];
+        const histMatrix: number[][] = [];
         try {
           const history = (await (
             prisma.planRecord as Record<string, (...a: unknown[]) => unknown>
           ).findMany({
-            where: { dpsComposite: { not: null } },
+            where: {
+              projectKey: runtimeContext.projectKey,
+              adapterKey: runtimeContext.adapterKey,
+              dpsComposite: { not: null },
+            },
             orderBy: { updatedAt: "desc" },
             take: CFG.FFT_HISTORY_LIMIT,
           })) as {
@@ -534,7 +545,11 @@ export function registerCheckDps(server: ToolRegistrar) {
             (...a: unknown[]) => unknown
           >;
           await planRec.updateMany({
-            where: { planName: { contains: pp } },
+            where: {
+              projectKey: runtimeContext.projectKey,
+              adapterKey: runtimeContext.adapterKey,
+              planName: { contains: pp },
+            },
             data: {
               dpsSemScore: semScore,
               dpsEntropyScore: entropyScore,

package/templates/core/scripts/mcp-server/tools/gateway/check_rahs.ts

@@ -9,7 +9,7 @@
 import * as z from "zod/v4";
 import type { ToolRegistrar } from "../registrar.js";
 import { existsSync } from "fs";
-import { join } from "path";
+import { join, basename } from "path";
 import { textResponse, errorResponse } from "../../shared/response.js";
 import {
   readFileSafe,
@@ -19,8 +19,10 @@ import {
 } from "../../shared/fs.js";
 import { prisma } from "../../shared/prisma.js";
 import { runCommand } from "../../shared/run-command.js";
+import { getRuntimeContext } from "../../shared/env.js";
 
 export function registerCheckRahs(server: ToolRegistrar) {
+  const runtimeContext = getRuntimeContext();
   server.registerTool(
     "check_rahs",
     {
@@ -42,7 +44,9 @@ export function registerCheckRahs(server: ToolRegistrar) {
         );
         const pm = apf.find(
           (f) =>
-            f.toLowerCase().includes(pp.toLowerCase()) && f.includes("-plan-v"),
+            f.toLowerCase().includes(pp.toLowerCase()) &&
+            f.includes("-plan-v") &&
+            !f.includes(".hitl"),
         );
         if (!pm)
           return errorResponse(`未找到匹配的 Plan 文件（关键词: ${pp}）`);
@@ -64,12 +68,14 @@ export function registerCheckRahs(server: ToolRegistrar) {
                   0,
                   100 - tsc.stderr.split("\n").filter(Boolean).length * 5,
                 );
-        } catch {}
+        } catch { /* type check is best-effort */ }
         try {
           const logs = (await (
             prisma.devOperation as Record<string, (...a: unknown[]) => unknown>
           ).findMany({
             where: {
+              projectKey: runtimeContext.projectKey,
+              producerAdapterKey: runtimeContext.adapterKey,
               OR: [
                 { planKeyword: { contains: pp, mode: "insensitive" } },
                 { targetId: { contains: pp, mode: "insensitive" } },
@@ -79,7 +85,83 @@ export function registerCheckRahs(server: ToolRegistrar) {
             take: 20,
           })) as Array<{ id: string }>;
           auditScore = Math.min(100, logs.length * 10);
-        } catch {}
+        } catch { /* audit score remains conservative */ }
+        // ── 范围保真度 / Spec 合规 / 阶段对称性：从静态基线改为动态计算（修复：
+        //    三个维度原为固定 80，任何 Plan 的 RAHS 上限 88 永远无法通过）──
+        try {
+          const arFile = apf.find(
+            (f) =>
+              f.toLowerCase().includes(pp.toLowerCase()) &&
+              f.toLowerCase().includes("add-route"),
+          );
+          if (arFile) {
+            const arContent =
+              (await readFileSafe(join(plansDir, arFile))) || "";
+            const checks = arContent.match(/^- \[[ x]\]/gm) || [];
+            const done = checks.filter((c) => c.includes("[x]")).length;
+            // 阶段对称性：add-route Step 产出项勾选率（Handoff/Report Closure 等
+            //    条件项未勾选时按比例折算，不阻塞）
+            symScore = checks.length > 0
+              ? Math.max(70, Math.round((done / checks.length) * 100))
+              : 70;
+          }
+        } catch { /* add-route progress unavailable */ }
+        try {
+          // Spec 合规：checklist [T] 项勾选率（[R] 运行时项不计入）
+          const specDir = join(PROJECT_ROOT, MAGIC_DIR, "specs");
+          // spec 目录名可能带 -vN 版本后缀：优先带版本匹配，回退不带版本 [Task 1.8 修复]
+          const rahsPlanBase = basename(pm, ".md").replace(/-plan-v\d+$/i, "");
+          const rahsVersionSuffix = /-plan-(v\d+)$/i.exec(basename(pm, ".md"))?.[1] ?? "";
+          const rahsCandidates = rahsVersionSuffix
+            ? [`${rahsPlanBase}-${rahsVersionSuffix}`, rahsPlanBase]
+            : [rahsPlanBase];
+          const planContent = (await readFileSafe(join(plansDir, pm))) || "";
+          const rahsSpecRef = planContent.match(/specs\/([^/`\s]+)/);
+          if (rahsSpecRef) rahsCandidates.push(rahsSpecRef[1]);
+          const sn =
+            rahsCandidates.find((d) => existsSync(join(specDir, d))) ??
+            rahsCandidates[0];
+          const clPath = join(specDir, sn, "checklist.md");
+          if (existsSync(clPath)) {
+            const cl = (await readFileSafe(clPath)) || "";
+            const tItems = cl.match(/^- \[[ x]\] \[T\]/gm) || [];
+            const tDone = tItems.filter((c) => c.includes("[x]")).length;
+            specScore = tItems.length > 0
+              ? Math.max(70, Math.round((tDone / tItems.length) * 100))
+              : 70;
+          }
+        } catch { /* checklist progress unavailable */ }
+        try {
+          // 范围保真度：git diff 变更文件与 add-route 附录清单匹配率
+          const arFile = apf.find(
+            (f) =>
+              f.toLowerCase().includes(pp.toLowerCase()) &&
+              f.toLowerCase().includes("add-route"),
+          );
+          if (arFile) {
+            const arContent =
+              (await readFileSafe(join(plansDir, arFile))) || "";
+            const appendix = (
+              arContent.match(/`[^`]+\.(ts|js|sh|md|tsx|json|yml|yaml)`/g) ||
+              []
+            ).map((f: string) => f.replace(/`/g, "").toLowerCase());
+            const diff = runCommand("git", ["diff", "--name-only"], {
+              cwd: PROJECT_ROOT,
+              timeout: 5000,
+            });
+            const diffFiles = diff.stdout
+              .trim()
+              .split("\n")
+              .filter(Boolean)
+              .map((f: string) => f.toLowerCase());
+            if (appendix.length > 0 && diffFiles.length > 0) {
+              const matched = diffFiles.filter((f) =>
+                appendix.some((a) => f === a || f.endsWith(`/${a}`)),
+              ).length;
+              scopeScore = Math.max(70, Math.round((matched / diffFiles.length) * 100));
+            }
+          }
+        } catch { /* git scope evidence unavailable */ }
         const parts = [
           "=== RAHS：Runtime Architecture Health Score ===",
           `Plan 关键词: "${pp}"`,

package/templates/core/scripts/mcp-server/tools/gateway/check_spec_sync.ts

@@ -9,6 +9,7 @@
  */
 import * as z from "zod/v4";
 import type { ToolRegistrar } from "../registrar.js";
+import { MAGIC_PREFIXES } from "../../shared/fs.js";
 import { existsSync } from "fs";
 import { join, basename } from "path";
 import { textResponse, errorResponse } from "../../shared/response.js";
@@ -43,10 +44,17 @@ export function registerCheckSpecSync(server: ToolRegistrar) {
           f.endsWith(".md"),
         );
         const kw = args.planKeyword as string;
-        let planMatch = planFiles.find(
-          (f) =>
-            f.toLowerCase().includes(kw.toLowerCase()) && f.includes("-plan-v"),
-        );
+        // 多版本（-plan-vN）共存时取版本号最高者：活跃 Plan 优先，避免评分旧版（2026-08-12 修复，同 check_dps R9）
+        let planMatch: string | undefined = planFiles
+          .filter(
+            (f) =>
+              f.toLowerCase().includes(kw.toLowerCase()) && f.includes("-plan-v"),
+          )
+          .sort((a, b) => {
+            const va = parseInt(a.match(/-plan-v(\d+)/)?.[1] ?? "0", 10);
+            const vb = parseInt(b.match(/-plan-v(\d+)/)?.[1] ?? "0", 10);
+            return vb - va;
+          })[0];
         if (!planMatch)
           planMatch = planFiles.find((f) =>
             f.toLowerCase().includes(kw.toLowerCase()),
@@ -69,7 +77,7 @@ export function registerCheckSpecSync(server: ToolRegistrar) {
           lines.push(`add-route: ${arFile}`);
           const arContent = (await readFileSafe(join(plansDir, arFile))) || "";
           // 提取 add-route 附录文件清单
-          const appendixFiles = (arContent.match(/`[^`]+\.(ts|js|sh|md|tsx|json)`/g) || [])
+          const appendixFiles = (arContent.match(/`[^`]+\.(ts|js|sh|md|tsx|json|yml|yaml)`/g) || [])
             .map((f: string) => f.replace(/`/g, ""));
           lines.push(`附录文件: ${appendixFiles.length} 个`);
 
@@ -89,8 +97,13 @@ export function registerCheckSpecSync(server: ToolRegistrar) {
           // 交叉比对
           if (appendixFiles.length > 0 && diffFiles.length > 0) {
             const appendixSet = new Set(appendixFiles.map((f: string) => f.toLowerCase()));
+            // 豁免 sync 自动生成产物（mirror 副本 + 备份）——非本 Plan 实施文件（2026-08-12 修复）
+            const isSyncGenerated = (lf: string) =>
+              MAGIC_PREFIXES.some((p) => lf.startsWith(`${p}/`));
             const unmatched = diffFiles.filter(
-              (f: string) => !appendixSet.has(f.toLowerCase()),
+              (f: string) =>
+                !isSyncGenerated(f.toLowerCase()) &&
+                !appendixSet.has(f.toLowerCase()),
             );
             if (unmatched.length > 0) {
               lines.push(`⚠️ ${unmatched.length} 个文件在 git diff 中但不在 add-route 附录中:`);

package/templates/core/scripts/mcp-server/tools/gateway/index.ts

@@ -6,6 +6,7 @@ import { registerCheckSpecSync } from "./check_spec_sync.js";
 import { registerCheckAddRouteCompleteness } from "./check_add_route_completeness.js";
 import { registerCheckDps } from "./check_dps.js";
 import { registerCheckRahs } from "./check_rahs.js";
+import { registerCheckDocSimilarity } from "./check_doc_similarity.js";
 
 export function registerGatewayTools(server: ToolRegistrar) {
   registerCheckAddRouteStatus(server);
@@ -13,4 +14,5 @@ export function registerGatewayTools(server: ToolRegistrar) {
   registerCheckAddRouteCompleteness(server);
   registerCheckDps(server);
   registerCheckRahs(server);
+  registerCheckDocSimilarity(server);
 }