add-coder 0.3.38 → 0.3.39

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "add-coder",
-  "version": "0.3.38",
+  "version": "0.3.39",
   "private": false,
   "description": "[codein2027](https://github.com/xiaomingming92/codein2027) - A complete scaffolding for building the ADD programming paradigm, the implementation layer for AI code governance. Core principle: Audit as Infrastructure. Breaks the black-box programming process and cross-session amnesia, evolving programming paradigms into an auditable, traceable, and convergent new era. npx-ready.\n\n[codein2027](https://github.com/xiaomingming92/codein2027) 快速构建 ADD 编程范式的完整脚手架——AI 代码治理的落地方案。以「审计即基础设施」为核心，彻底打破编程过程黑盒与跨轮失忆，让编程范式进化为可审计、可追溯、可收敛的新时代。npx 即用，人人可体验。",
   "repository": {

package/templates/.add-coder-src-hash.json

@@ -1,5 +1,5 @@
 {
-  "_version": "0.3.38",
+  "_version": "0.3.39",
   "adapters/claude/hooks/doc-format-guard.mjs": "b21350a0",
   "adapters/claude/hooks/doc-format-guard.ts": "2abf8013",
   "adapters/claude/hooks/lib/claude-env.ts": "170b40ca",
@@ -319,14 +319,15 @@
   "core/scripts/mcp-server/tools/context.ts": "d7d4e546",
   "core/scripts/mcp-server/tools/contract.ts": "14b6ab8f",
   "core/scripts/mcp-server/tools/docs.ts": "034e473c",
-  "core/scripts/mcp-server/tools/gateway/check_add_route_completeness.ts": "b58e76ee",
-  "core/scripts/mcp-server/tools/gateway/check_add_route_status.ts": "4caf552c",
+  "core/scripts/mcp-server/tools/gateway/check_add_route_completeness.ts": "a888c711",
+  "core/scripts/mcp-server/tools/gateway/check_add_route_status.ts": "1b6884bc",
   "core/scripts/mcp-server/tools/gateway/check_doc_similarity.ts": "2cba51c5",
-  "core/scripts/mcp-server/tools/gateway/check_dps.ts": "f52ef32c",
-  "core/scripts/mcp-server/tools/gateway/check_rahs.ts": "a786744d",
-  "core/scripts/mcp-server/tools/gateway/check_spec_sync.ts": "adad0b31",
+  "core/scripts/mcp-server/tools/gateway/check_dps.ts": "d4120356",
+  "core/scripts/mcp-server/tools/gateway/check_rahs.ts": "00a51678",
+  "core/scripts/mcp-server/tools/gateway/check_spec_sync.ts": "5dd01970",
   "core/scripts/mcp-server/tools/gateway/helpers.ts": "f8794a92",
   "core/scripts/mcp-server/tools/gateway/index.ts": "cffe9783",
+  "core/scripts/mcp-server/tools/gateway/plan-resolve.ts": "5c742655",
   "core/scripts/mcp-server/tools/gateway.backup": "65eae393",
   "core/scripts/mcp-server/tools/hitl.ts": "4488c338",
   "core/scripts/mcp-server/tools/hook-event-report.ts": "1d825b3f",
@@ -351,7 +352,7 @@
   "core/templates/add-route-template-heavyweight.md": "0e107ac0",
   "core/templates/add-route-template.md": "da7022df",
   "core/templates/add-route-template.schema.json": "cca77a6e",
-  "core/templates/checklist-template.md": "c1ea7aaf",
+  "core/templates/checklist-template.md": "8e3ddc28",
   "core/templates/checklist-template.schema.json": "fb3a73e8",
   "core/templates/collab-contract-template.md": "b8a52503",
   "core/templates/collab-contract-template.schema.json": "ae0f482c",
@@ -374,8 +375,8 @@
   "core/templates/prd-standard-template.schema.json": "2b76a919",
   "core/templates/report-template.md": "bc4602ac",
   "core/templates/report-template.schema.json": "44dd2bd0",
-  "core/templates/review-implementation-template.md": "6d7a46cb",
-  "core/templates/review-implementation-template.schema.json": "d97b9eb6",
+  "core/templates/review-implementation-template.md": "bac5be0b",
+  "core/templates/review-implementation-template.schema.json": "aeb598de",
   "core/templates/review-runtime-template.md": "c5960af1",
   "core/templates/review-runtime-template.schema.json": "c346ea7d",
   "core/templates/review-template.md": "644d2772",

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

@@ -17,6 +17,7 @@ import {
   PROJECT_ROOT,
   MAGIC_DIR,
 } from "../../shared/fs.js";
+import { resolvePlanArtifact } from "./plan-resolve.js";
 
 export function registerCheckAddRouteCompleteness(server: ToolRegistrar) {
   server.registerTool(
@@ -36,15 +37,26 @@ export function registerCheckAddRouteCompleteness(server: ToolRegistrar) {
         if (!existsSync(plansDir))
           return errorResponse(`plans 目录不存在: ${plansDir}`);
         const allFiles = await readdirRecursive(plansDir);
-        const arFile = allFiles.find(
-          (f) =>
-            f.toLowerCase().includes(pp.toLowerCase()) &&
-            f.includes("add-route"),
+        // 版本配对（2026-09-18 修复）：与 Plan 同目录同版本优先，不再"去版本取首个匹配"（永远命中 v1）
+        const { plan: resolvedPlan, artifact: resolvedAr } = resolvePlanArtifact(
+          allFiles,
+          pp,
+          "add-route",
         );
+        const arFile = resolvedAr?.file;
         if (!arFile)
           return errorResponse(`未找到匹配的 add-route 文件（关键词: ${pp}）`);
         const content = await readFileSafe(join(plansDir, arFile));
         if (!content) return errorResponse("add-route 文件无法读取");
+        const pairing: string[] = [];
+        if (resolvedPlan)
+          pairing.push(
+            `Plan: ${resolvedPlan.file}${resolvedPlan.version > 0 ? ` (v${resolvedPlan.version})` : ""}`,
+          );
+        pairing.push(
+          `add-route: ${arFile}${resolvedAr && resolvedAr.version > 0 ? ` (v${resolvedAr.version})` : ""} 〔配对依据: ${resolvedAr?.via}〕`,
+        );
+        if (resolvedAr?.warning) pairing.push(`⚠️ ${resolvedAr.warning}`);
         const steps: Record<string, { checked: number; unchecked: number }> =
           {};
         let cur = "";
@@ -71,6 +83,7 @@ export function registerCheckAddRouteCompleteness(server: ToolRegistrar) {
         const parts = [
           `=== add-route Step 完成度扫描 ===`,
           `文件: ${MAGIC_DIR}/plans/${arFile}`,
+          ...pairing,
           `整体: ${tu}/${tc} (${tc > 0 ? Math.round((tu / tc) * 100) : 0}%)`,
           "",
         ];

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

@@ -18,6 +18,7 @@ import {
 } from "../../shared/fs.js";
 import { prisma } from "../../shared/prisma.js";
 import { getRuntimeContext } from "../../shared/env.js";
+import { parseArtifactName, resolvePlanArtifact } from "./plan-resolve.js";
 
 function scanCheckboxes(content: string) {
   let t = 0,
@@ -162,8 +163,10 @@ export function registerCheckAddRouteStatus(server: ToolRegistrar) {
         }
         let fileExists = false;
         const matchedFiles: string[] = [];
+        let planDirEntries: string[] = [];
         try {
           const entries = await readdirRecursive(plansDir);
+          planDirEntries = entries;
           for (const e of entries) {
             const el = e.toLowerCase();
             if (
@@ -177,6 +180,33 @@ export function registerCheckAddRouteStatus(server: ToolRegistrar) {
         } catch {
           /* empty */
         }
+        // 版本配对（2026-09-18 修复）：存在性判定保留"任一命中"（不把 warn 翻成 never_generated），
+        // 但**扫描对象**改为与 Plan 配对的版本 —— 旧实现用 readdir 顺序里的 matchedFiles[0]，
+        // 多版本共存时扫的是最早的 v1，完成度与版本关系都失真。
+        const matchedSorted = matchedFiles
+          .map((f) => ({ f, version: parseArtifactName(f, "add-route")?.version ?? 0 }))
+          .sort((a, b) => b.version - a.version || (a.f < b.f ? 1 : -1));
+        const { plan: resolvedPlan, artifact: paired } = resolvePlanArtifact(
+          planDirEntries,
+          planKeyword,
+          "add-route",
+        );
+        const scanTarget =
+          paired?.file ?? matchedSorted[0]?.f ?? matchedFiles[0] ?? "";
+        const pairingNotes: string[] = [];
+        if (resolvedPlan)
+          pairingNotes.push(
+            `Plan: ${resolvedPlan.file}${resolvedPlan.version > 0 ? ` (v${resolvedPlan.version})` : ""}`,
+          );
+        if (paired)
+          pairingNotes.push(
+            `add-route: ${paired.file}${paired.version > 0 ? ` (v${paired.version})` : ""} 〔配对依据: ${paired.via}〕`,
+          );
+        if (matchedFiles.length > 1)
+          pairingNotes.push(
+            `ℹ️ 多版本共存：${matchedSorted.map((e) => `${e.f}(v${e.version})`).join(" / ")} —— 本次扫描 ${scanTarget}`,
+          );
+        if (paired?.warning) pairingNotes.push(`⚠️ ${paired.warning}`);
         const parts = [
           `=== ADD 守卫：add-route 存在性交叉校验 ===`,
           `Plan 关键词: "${planKeyword}"`,
@@ -184,14 +214,13 @@ export function registerCheckAddRouteStatus(server: ToolRegistrar) {
           "",
         ];
         if (auditHasRecord && fileExists) {
-          const sc = scanCheckboxes(
-            (await readFileSafe(join(plansDir, matchedFiles[0]))) || "",
-          );
+          const sc = scanCheckboxes((await readFileSafe(join(plansDir, scanTarget))) || "");
           const ok = sc.unchecked === 0;
           parts.push(
             `状态: ${ok ? "✅ normal" : "⚠️ warn_step_incomplete"}`,
             ok ? "操作: 继续执行后续流程" : "操作: ⚠️ 存在未闭环 Step",
             "",
+            ...pairingNotes,
           );
           parts.push("=== 审计记录 ===");
           for (const r of auditRecords.slice(0, 5))
@@ -248,14 +277,13 @@ export function registerCheckAddRouteStatus(server: ToolRegistrar) {
           );
           return errorResponse(parts.join("\n"));
         }
-        const scW = scanCheckboxes(
-          (await readFileSafe(join(plansDir, matchedFiles[0]))) || "",
-        );
+        const scW = scanCheckboxes((await readFileSafe(join(plansDir, scanTarget))) || "");
         const wOk = scW.unchecked === 0;
         parts.push(
           `状态: ⚠️ warn${scW.total > 0 && !wOk ? "_step_incomplete" : ""} — 文件存在但审计日志无记录`,
           "操作: 允许继续，但建议补记录",
           "",
+          ...pairingNotes,
           "=== 匹配文件 ===",
         );
         for (const f of matchedFiles) parts.push(`  ${MAGIC_DIR}/plans/${f}`);

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

@@ -38,6 +38,7 @@ import {
   writeGateMetric,
   GATE_METRIC_TYPE,
 } from "../../shared/memory/metrics/gate-writer.js";
+import { resolvePlanArtifact } from "./plan-resolve.js";
 
 export function registerCheckDps(server: ToolRegistrar) {
   const runtimeContext = getRuntimeContext();
@@ -68,22 +69,22 @@ export function registerCheckDps(server: ToolRegistrar) {
         const apf = (await readdirRecursive(plansDir)).filter(
           (f) => f.endsWith(".md") && !f.includes(".hitl"),
         );
-        // 多版本（-plan-vN）共存时取版本号最高者：活跃 Plan 优先，避免评分旧版（2026-08-12 修复）
-        const matched = apf.filter(
-          (f) =>
-            f.toLowerCase().includes(pp.toLowerCase()) && f.includes("-plan-v"),
+        // 版本配对解析（单一真源 plan-resolve）：Plan 取最高版本且排除 .hitl 提案；
+        // add-route / review 与 Plan 同目录同版本优先（2026-09-18 修复：旧实现去版本取首个匹配，永远命中 v1）
+        const { plan: resolvedPlan, artifact: resolvedAr } = resolvePlanArtifact(
+          apf,
+          pp,
+          "add-route",
         );
-        if (!matched.length)
+        if (!resolvedPlan)
           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 pm = resolvedPlan.file;
         const planPath = join(plansDir, pm);
         const pc = await readFileSafe(planPath);
         if (!pc) return errorResponse(`无法读取 Plan 文件: ${pm}`);
-        parts.push(`Plan: ${pm}`);
+        parts.push(
+          `Plan: ${pm}${resolvedPlan.version > 0 ? ` (v${resolvedPlan.version})` : ""}`,
+        );
 
         let sn = basename(pm).replace(/-plan-v\d+\.md$/, ""),
           sc = "";
@@ -97,25 +98,14 @@ export function registerCheckDps(server: ToolRegistrar) {
           rc = "";
         if (existsSync(reviewsDir)) {
           const rfs = await readdirRecursive(reviewsDir);
-          const rkNoVersion = pp.replace(/-plan-v\d+$/i, "");
-          rn =
-            rfs.find(
-              (f) =>
-                f.toLowerCase().includes(rkNoVersion.toLowerCase()) &&
-                f.includes("-review-v"),
-            ) || "";
+          rn = resolvePlanArtifact(rfs, pp, "review").artifact?.file || "";
           if (rn) rc = (await readFileSafe(join(reviewsDir, rn))) || "";
         }
-        // ★ 兼容精简版和标准版 Plan：剥离 -plan-vN 后缀匹配 add-route 和 review
-        const kwNoVersion = pp.replace(/-plan-v\d+$/i, "");
         let arContent = "";
-        const arFile = apf.find(
-          (f) =>
-            f.toLowerCase().includes(kwNoVersion.toLowerCase()) &&
-            f.toLowerCase().includes("add-route"),
-        );
+        const arFile = resolvedAr?.file;
         if (arFile)
           arContent = (await readFileSafe(join(plansDir, arFile))) || "";
+        if (resolvedAr?.warning) parts.push(`⚠️ ${resolvedAr.warning}`);
 
         // 维度一: 语义相关性
         //   子维度 A: 映射结构 (40%) — 映射表是否存在 + 覆盖行数

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

@@ -28,6 +28,11 @@ import {
   writeGateMetric,
   GATE_METRIC_TYPE,
 } from "../../shared/memory/metrics/gate-writer.js";
+import {
+  extractAppendixFiles,
+  resolvePlanArtifact,
+  splitGitPathList,
+} from "./plan-resolve.js";
 
 export function registerCheckRahs(server: ToolRegistrar) {
   const runtimeContext = getRuntimeContext();
@@ -50,14 +55,11 @@ export function registerCheckRahs(server: ToolRegistrar) {
         const apf = (await readdirRecursive(plansDir)).filter((f) =>
           f.endsWith(".md"),
         );
-        const pm = apf.find(
-          (f) =>
-            f.toLowerCase().includes(pp.toLowerCase()) &&
-            f.includes("-plan-v") &&
-            !f.includes(".hitl"),
-        );
-        if (!pm)
+        // 版本配对解析（2026-09-18 修复）：Plan 取版本最高者（旧实现取首个命中 → 多版本时命中旧版）
+        const resolvedPlan = resolvePlanArtifact(apf, pp, "plan").plan;
+        if (!resolvedPlan)
           return errorResponse(`未找到匹配的 Plan 文件（关键词: ${pp}）`);
+        const pm = resolvedPlan.file;
         // Plan 正文在多个维度（Spec 引用解析、采证 seed）共用，提到此处只读一次
         const planContent = (await readFileSafe(join(plansDir, pm))) || "";
         let scopeScore = 80,
@@ -142,28 +144,23 @@ export function registerCheckRahs(server: ToolRegistrar) {
         } catch { /* checklist progress unavailable */ }
         try {
           // 范围保真度：git diff 变更文件与 add-route 附录清单匹配率
-          const arFile = apf.find(
-            (f) =>
-              f.toLowerCase().includes(pp.toLowerCase()) &&
-              f.toLowerCase().includes("add-route"),
-          );
+          // 版本配对（2026-09-18 修复）：与 Plan 同目录同版本优先，不再"去版本取首个匹配"
+          const arFile = resolvePlanArtifact(apf, pp, "add-route").artifact?.file;
           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());
-            // core.quotepath=false：避免非 ASCII 路径被八进制转义后与附录清单比不中（与 check_spec_sync 同修）
-            const diff = runCommand("git", ["-c", "core.quotepath=false", "diff", "--name-only"], {
-              cwd: PROJECT_ROOT,
-              timeout: 5000,
-            });
-            const diffFiles = diff.stdout
-              .trim()
-              .split("\n")
-              .filter(Boolean)
-              .map((f: string) => f.toLowerCase());
+            const appendix = extractAppendixFiles(arContent).map((f) =>
+              f.toLowerCase(),
+            );
+            // -z（NUL 分隔）：git 不加引号/八进制转义，非 ASCII 路径与附录可直接比对（与 check_spec_sync 同源修复）
+            const diff = runCommand(
+              "git",
+              ["-c", "core.quotepath=false", "diff", "--name-only", "-z"],
+              { cwd: PROJECT_ROOT, timeout: 5000 },
+            );
+            const diffFiles = splitGitPathList(diff.stdout).map((f) =>
+              f.toLowerCase(),
+            );
             if (appendix.length > 0 && diffFiles.length > 0) {
               const matched = diffFiles.filter((f) =>
                 appendix.some((a) => f === a || f.endsWith(`/${a}`)),

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

@@ -20,6 +20,13 @@ import {
   MAGIC_DIR,
 } from "../../shared/fs.js";
 import { runCommand } from "../../shared/run-command.js";
+import {
+  attributeToOtherPlans,
+  extractAppendixFiles,
+  parseArtifactName,
+  resolvePlanArtifact,
+  splitGitPathList,
+} from "./plan-resolve.js";
 
 export function registerCheckSpecSync(server: ToolRegistrar) {
   server.registerTool(
@@ -44,55 +51,40 @@ export function registerCheckSpecSync(server: ToolRegistrar) {
           f.endsWith(".md"),
         );
         const kw = args.planKeyword as string;
-        // 多版本（-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()),
-          );
-        if (!planMatch)
+        // 版本配对解析（单一真源 plan-resolve）：Plan 取最高版本且排除 .hitl 提案；
+        // add-route 与 Plan 同目录同版本优先 —— 旧实现"去版本取首个匹配"永远命中 v1（2026-09-18 修复）
+        const { plan, artifact: ar } = resolvePlanArtifact(planFiles, kw, "add-route");
+        if (!plan)
           return errorResponse(`未找到匹配的 Plan 文件（关键词: ${kw}）`);
-        lines.push(`Plan: ${planMatch}`);
+        lines.push(`Plan: ${plan.file}${plan.version > 0 ? ` (v${plan.version})` : ""}`);
 
-        // 定位 add-route 文件
-        const kwNoVersion = kw.replace(/-plan-v\d+$/i, "");
-        const arFile = planFiles.find(
-          (f) =>
-            f.toLowerCase().includes(kwNoVersion.toLowerCase()) &&
-            f.toLowerCase().includes("add-route"),
-        );
-        if (!arFile) {
+        if (!ar) {
           lines.push("add-route: 未找到", "");
           lines.push("💡 提示：tasks.md/checklist.md 进度请用 plan_track 或 plan_status 查询");
         } else {
-          lines.push(`add-route: ${arFile}`);
-          const arContent = (await readFileSafe(join(plansDir, arFile))) || "";
+          lines.push(
+            `add-route: ${ar.file}${ar.version > 0 ? ` (v${ar.version})` : ""} 〔配对依据: ${ar.via}〕`,
+          );
+          if (ar.warning) lines.push(`⚠️ ${ar.warning}`);
+          const arContent = (await readFileSafe(join(plansDir, ar.file))) || "";
           // 提取 add-route 附录文件清单（toml 纳入：sync-magic-rules.toml 等控制面文件，2026-08-18 修复）
           // sql/prisma 纳入（2026-09-16 修复）：原生 DDL 与 schema 是常见交付物，此前不在白名单 →
           // 附录里明明登记了 `.../sqlite-fts5.sql` 仍被判"不在附录中"（假告警）。
-          const appendixFiles = (arContent.match(/`[^`]+\.(ts|tsx|js|jsx|sh|sql|prisma|md|json|yml|yaml|toml)`/g) || [])
-            .map((f: string) => f.replace(/`/g, ""));
+          const appendixFiles = extractAppendixFiles(arContent);
           lines.push(`附录文件: ${appendixFiles.length} 个`);
 
           // git diff 变更文件（win32 下 git 为 .cmd → runCommand 自动解析，issue #10 跨端修复）
           let diffFiles: string[] = [];
           try {
-            // core.quotepath=false：默认 git 会把非 ASCII 路径转成 "\346\236..." 八进制转义 →
-            // 与附录里的真实中文路径永远比不中（2026-09-16 修复：架构文档类路径的假告警）。
-            const diff = runCommand("git", ["-c", "core.quotepath=false", "diff", "--name-only"], {
-              cwd: PROJECT_ROOT,
-              timeout: 5000,
-            });
-            diffFiles = diff.stdout.trim().split("\n").filter(Boolean);
+            // -z（NUL 分隔）下 git 永不加引号/八进制转义 —— 比 core.quotepath=false 更硬：
+            // 后者在路径含特殊字符时仍可能加引号，而带引号的 `".codex/..."` 既躲过 magic 前缀豁免，
+            // 也与附录里的真实路径比不中（2026-09-18 修复：check_spec_sync / check_rahs 同源）
+            const diff = runCommand(
+              "git",
+              ["-c", "core.quotepath=false", "diff", "--name-only", "-z"],
+              { cwd: PROJECT_ROOT, timeout: 5000 },
+            );
+            diffFiles = splitGitPathList(diff.stdout);
           } catch {
             lines.push("Git diff: 无法获取");
           }
@@ -110,8 +102,34 @@ export function registerCheckSpecSync(server: ToolRegistrar) {
                 !appendixSet.has(f.toLowerCase()),
             );
             if (unmatched.length > 0) {
-              lines.push(`⚠️ ${unmatched.length} 个文件在 git diff 中但不在 add-route 附录中:`);
-              unmatched.forEach((f: string) => lines.push(`  - ${f}`));
+              // 工作区常有多个 Plan 同时在飞 —— 先分摊归属，把"其它 Plan 已登记"从本 Plan 的
+              // 未登记噪声里摘出来（按日期新者优先读，全部命中即提前结束）
+              const otherRoutes = planFiles
+                .filter((f) => {
+                  const parsed = parseArtifactName(f, "add-route");
+                  return parsed !== null && f !== ar.file;
+                })
+                .sort((a, b) => (a < b ? 1 : a > b ? -1 : 0));
+              const { owners, unowned } = await attributeToOtherPlans(
+                unmatched,
+                otherRoutes,
+                (rel) => readFileSafe(join(plansDir, rel)),
+              );
+              if (unowned.length > 0) {
+                lines.push(`⚠️ ${unowned.length} 个文件在 git diff 中但不在本 Plan 附录中:`);
+                unowned.forEach((f: string) => lines.push(`  - ${f}`));
+              } else {
+                lines.push("✅ 本 Plan 附录已覆盖全部非其它 Plan 的变更文件");
+              }
+              if (owners.size > 0) {
+                lines.push(
+                  "",
+                  `ℹ️ ${owners.size} 个文件属于其它 Plan 已登记的交付物（本 Plan 不判定）:`,
+                );
+                for (const { file, route } of owners.values()) {
+                  lines.push(`  - ${file} ← ${route}`);
+                }
+              }
             } else {
               lines.push("✅ git diff 变更文件全部在 add-route 附录中");
             }

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

@@ -0,0 +1,270 @@
+/*
+ * Plan ↔ 兄弟制品（add-route / handoff / review）版本配对解析 —— 单一真源
+ *
+ * 动因（2026-09-18，farm-agent 多 v2 Plan 暴露）：
+ *   旧实现按 planKeyword **去掉版本后缀取首个匹配** → 命中日期最早的 v1 add-route；
+ *   且 Plan 解析只要求文件名含 "-plan-v" → `...-plan-v2.hitl.md` 提案文件会顶替真正的 Plan。
+ *   后果：check_spec_sync 拿旧版路线图的附录比对当前 git diff，报出几十条「未登记」假告警；
+ *   check_dps / check_add_route_status / check_add_route_completeness 同样读错文档。
+ *   同类问题第三例：git diff 路径被引号+八进制转义（`".codex/plans/...\346\236..."`），
+ *   既躲过 magic 前缀豁免、也与附录里的真实中文路径比不中 → 统一走 `-z`（NUL 分隔，永不加引号）。
+ *
+ * 解析优先级（可否证伪、不静默降级）：
+ *   Plan      : 关键词命中且 `-plan-vN.md` **结尾**（`.hitl.md`/devlog/handoff/add-route/review 天然排除）
+ *               → 版本号最大；同版本按路径降序（日期新者优先）
+ *               兜底：关键词命中、含 "plan"、非兄弟产物的 `.md`
+ *   add-route : ① 同目录 + 同基名 + 同版本  ② 同基名最高版本（同版本优先 Plan 所在目录）
+ *               ③ 关键词命中最高版本（基名与 Plan 不同时的兼容路径）
+ *   版本落后（add-route vN < Plan vM）→ 显式 warning，不静默
+ */
+
+export type ArtifactKind = "plan" | "add-route" | "handoff" | "review";
+
+export type ResolveVia =
+  | "plan-max-version"
+  | "plan-fallback"
+  | "paired-same-dir-version"
+  | "paired-base-max-version"
+  | "keyword-max-version";
+
+export interface ResolvedArtifact {
+  /** 相对 plans 目录的路径（POSIX 分隔符） */
+  file: string;
+  kind: ArtifactKind;
+  /** 文件名解析出的版本号；无 `-vN` 后缀 = 0 */
+  version: number;
+  /** 去掉 `-<kind>-vN.md` 后的基名（review 的 `-review-implementation` 变体一并剥离） */
+  base: string;
+  /** 所在目录（相对，POSIX；根目录 = ""） */
+  dir: string;
+  /** 解析依据（可审计，便于区分「配对命中」与「关键词兜底」） */
+  via: ResolveVia;
+  /** 与 Plan 版本不匹配时的显式告警（null = 无） */
+  warning: string | null;
+}
+
+export interface ResolveResult {
+  plan: ResolvedArtifact | null;
+  /** kind 非 plan 时：与已解析 Plan 配对的制品；解析不到 = null */
+  artifact: ResolvedArtifact | null;
+}
+
+const KIND_SUFFIX: Record<ArtifactKind, RegExp> = {
+  plan: /-plan-v(\d+)\.md$/i,
+  "add-route": /-add-route-v(\d+)\.md$/i,
+  handoff: /-handoff-v(\d+)\.md$/i,
+  review: /-review(?:-[a-z0-9-]+)?-v(\d+)\.md$/i,
+};
+
+/** Plan 解析必须排除的兄弟产物（提案/日志/契约/下游文档） */
+const NON_PLAN_SUFFIX =
+  /(\.hitl\.md$)|(-add-route-v\d+\.md$)|(-handoff-v\d+\.md$)|(-review(?:-[a-z0-9-]+)?-v\d+\.md$)|(-contract-v\d+\.md$)|(^devlog-)/i;
+
+export function toPosix(p: string): string {
+  return p.replace(/\\/g, "/");
+}
+
+function baseOf(p: string): string {
+  const posix = toPosix(p);
+  const i = posix.lastIndexOf("/");
+  return i < 0 ? posix : posix.slice(i + 1);
+}
+
+function dirOf(p: string): string {
+  const posix = toPosix(p);
+  const i = posix.lastIndexOf("/");
+  return i < 0 ? "" : posix.slice(0, i);
+}
+
+/** 路径降序（日期新者优先，确定性；避免依赖 readdir 顺序） */
+function byPathDesc(a: string, b: string): number {
+  return a < b ? 1 : a > b ? -1 : 0;
+}
+
+export function parseArtifactName(
+  name: string,
+  kind: ArtifactKind,
+): { base: string; version: number } | null {
+  const base = baseOf(name);
+  const m = base.match(KIND_SUFFIX[kind]);
+  if (!m || m.index === undefined) return null;
+  return { base: base.slice(0, m.index), version: parseInt(m[1], 10) };
+}
+
+/**
+ * `git ... --name-only -z` 输出 → 路径数组。
+ * `-z` 下 git **永不**加引号/转义（非 ASCII 路径保持原样），因此这里只需切分。
+ * 无 NUL 时按行切分（兼容不支持的旧 git），并清掉 CR。
+ */
+export function splitGitPathList(stdout: string): string[] {
+  const parts = stdout.includes("\u0000") ? stdout.split("\u0000") : stdout.split("\n");
+  return parts
+    .map((p) => p.replace(/\r$/, ""))
+    .filter((p) => p !== "")
+    .map(toPosix);
+}
+
+/** add-route / review 附录里登记的文件清单（反引号内的路径） */
+export function extractAppendixFiles(content: string): string[] {
+  return (
+    content.match(/`[^`]+\.(ts|tsx|js|jsx|sh|sql|prisma|md|json|yml|yaml|toml)`/g) || []
+  ).map((f) => f.replace(/`/g, ""));
+}
+
+function build(
+  file: string,
+  kind: ArtifactKind,
+  parsed: { base: string; version: number },
+  via: ResolveVia,
+  warning: string | null = null,
+): ResolvedArtifact {
+  return {
+    file: toPosix(file),
+    kind,
+    version: parsed.version,
+    base: parsed.base,
+    dir: dirOf(file),
+    via,
+    warning,
+  };
+}
+
+/** 解析 Plan 文件：版本最高者优先；`.hitl.md` 等兄弟产物不入选 */
+export function resolvePlan(
+  files: readonly string[],
+  keyword: string,
+): ResolvedArtifact | null {
+  const kw = keyword.trim().toLowerCase();
+  if (!kw) return null;
+  const pool = files.map(toPosix).filter((f) => f.toLowerCase().includes(kw));
+
+  const versioned = pool
+    .map((f) => ({ f, parsed: parseArtifactName(f, "plan") }))
+    .filter(
+      (e): e is { f: string; parsed: { base: string; version: number } } =>
+        e.parsed !== null && !NON_PLAN_SUFFIX.test(baseOf(e.f)),
+    )
+    .sort((a, b) => b.parsed.version - a.parsed.version || byPathDesc(a.f, b.f));
+  if (versioned.length > 0) {
+    const { f, parsed } = versioned[0];
+    return build(f, "plan", parsed, "plan-max-version");
+  }
+
+  // 兜底：无 `-plan-vN` 后缀的 Plan（精简版/历史命名）——仍需排除兄弟产物
+  const fallback = pool
+    .filter(
+      (f) =>
+        f.toLowerCase().endsWith(".md") &&
+        /plan/i.test(baseOf(f)) &&
+        !NON_PLAN_SUFFIX.test(baseOf(f)),
+    )
+    .sort(byPathDesc);
+  if (fallback.length > 0) {
+    return build(fallback[0], "plan", { base: baseOf(fallback[0]).replace(/\.md$/i, ""), version: 0 }, "plan-fallback");
+  }
+  return null;
+}
+
+/** 与 Plan 配对的制品：同目录同版本 → 同基名最高版本 → 关键词最高版本 */
+export function resolvePairedArtifact(
+  files: readonly string[],
+  plan: ResolvedArtifact,
+  kind: ArtifactKind,
+  keyword: string,
+): ResolvedArtifact | null {
+  const posix = files.map(toPosix);
+  const suffix = `-${kind}-v${plan.version}.md`;
+  const expected = plan.dir ? `${plan.dir}/${plan.base}${suffix}` : `${plan.base}${suffix}`;
+  const exact = posix.find((f) => f.toLowerCase() === expected.toLowerCase());
+  if (exact) return build(exact, kind, { base: plan.base, version: plan.version }, "paired-same-dir-version");
+
+  const sameDirScore = (f: string) => (dirOf(f) === plan.dir ? 0 : 1);
+  const sameBase = posix
+    .map((f) => ({ f, parsed: parseArtifactName(f, kind) }))
+    .filter(
+      (e): e is { f: string; parsed: { base: string; version: number } } =>
+        e.parsed !== null && e.parsed.base.toLowerCase() === plan.base.toLowerCase(),
+    )
+    .sort(
+      (a, b) =>
+        b.parsed.version - a.parsed.version ||
+        sameDirScore(a.f) - sameDirScore(b.f) ||
+        byPathDesc(a.f, b.f),
+    );
+  if (sameBase.length > 0) {
+    const { f, parsed } = sameBase[0];
+    return build(f, kind, parsed, "paired-base-max-version", versionWarning(plan, parsed.version, kind));
+  }
+
+  const kw = keyword.trim().toLowerCase();
+  const byKeyword = posix
+    .filter((f) => f.toLowerCase().includes(kw))
+    .map((f) => ({ f, parsed: parseArtifactName(f, kind) }))
+    .filter(
+      (e): e is { f: string; parsed: { base: string; version: number } } => e.parsed !== null,
+    )
+    .sort((a, b) => b.parsed.version - a.parsed.version || byPathDesc(a.f, b.f));
+  if (byKeyword.length > 0) {
+    const { f, parsed } = byKeyword[0];
+    const warn = versionWarning(plan, parsed.version, kind);
+    const base = warn
+      ? warn
+      : `基名不同：Plan 基名 "${plan.base}"，${kind} 基名 "${parsed.base}"（按关键词兜底命中，请确认对应关系）`;
+    return build(f, kind, parsed, "keyword-max-version", base);
+  }
+  return null;
+}
+
+function versionWarning(
+  plan: ResolvedArtifact,
+  artifactVersion: number,
+  kind: ArtifactKind,
+): string | null {
+  if (plan.version > 0 && artifactVersion < plan.version) {
+    return `${kind} v${artifactVersion} 落后于 Plan v${plan.version}（Plan 基名 "${plan.base}"）——补齐对应版本，或确认沿用旧版路线图`;
+  }
+  return null;
+}
+
+/** 工具入口：一次拿到「Plan + 配对制品」 */
+export function resolvePlanArtifact(
+  files: readonly string[],
+  keyword: string,
+  kind: ArtifactKind,
+): ResolveResult {
+  const plan = resolvePlan(files, keyword);
+  if (!plan) return { plan: null, artifact: null };
+  if (kind === "plan") return { plan, artifact: plan };
+  return { plan, artifact: resolvePairedArtifact(files, plan, kind, keyword) };
+}
+
+/**
+ * 未登记文件的归属分摊：逐个读其它 add-route 的附录，命中即记为「属于该 Plan」。
+ * 全部命中即提前返回（不做无谓的全量读取）。顺序由调用方给定（建议新者优先）。
+ */
+export async function attributeToOtherPlans(
+  unmatched: readonly string[],
+  otherRoutes: readonly string[],
+  readRoute: (rel: string) => Promise<string | null>,
+): Promise<{
+  /** key = 小写路径（比对用），value = 原名 + 归属 add-route */
+  owners: Map<string, { file: string; route: string }>;
+  /** 任何 add-route 都未登记的变更文件（原名） */
+  unowned: string[];
+}> {
+  const owners = new Map<string, { file: string; route: string }>();
+  let remaining = unmatched.map((f) => ({ key: f.toLowerCase(), file: f }));
+  for (const route of otherRoutes) {
+    if (remaining.length === 0) break;
+    const content = await readRoute(route);
+    if (!content) continue;
+    const appendix = new Set(extractAppendixFiles(content).map((f) => f.toLowerCase()));
+    const stillRemaining: Array<{ key: string; file: string }> = [];
+    for (const e of remaining) {
+      if (appendix.has(e.key)) owners.set(e.key, { file: e.file, route });
+      else stillRemaining.push(e);
+    }
+    remaining = stillRemaining;
+  }
+  return { owners, unowned: remaining.map((e) => e.file) };
+}

package/templates/core/templates/checklist-template.md

@@ -4,6 +4,7 @@
 > - `[T]` = 编译期验证—证据: 命令+结果（如 `tsc=0` / `vitest 18/18`）
 > - `[R]` = 运行时验证—证据: 部署后确认（如 `curl 200`）
 > - `[E]` = 静态检查—证据: grep/diff 输出
+> - `[W]` = **接线验证（Wiring）**—证据: 生产调用点存在的 grep / 端到端一次真实产出（**实现存在 ≠ 生产可达**）
 >
 > **审计链（证据→devlog→checklist）**:
 > - 初验规则: 先找证据（命令+结果）→ 调 `record_dev_operation` 落库 → 将返回的真实 cuid（25位）写入 checklist。**禁止抄写 `cmq...` 占位符**。
@@ -14,6 +15,7 @@
 - [ ] [T] 检查项1 — 证据: (待填写)|审计: (初验从 record_dev_operation 返回值写入真实 cuid，**禁止写 `cmq...` 占位符**)
 - [ ] [T] 检查项2 — 证据: (待填写)|审计: (初验从 record_dev_operation 返回值写入真实 cuid，**禁止写 `cmq...` 占位符**)
 - [ ] [T] schema 变更后运行实例 client 新鲜度（`db:generate` + 重启校验）— 证据: (待填写)|审计: (待填写) [来源: farm-agent 9737ab4 回灌；Prisma+Atlas 项目通用]
+- [ ] [W] 新增的"被调用方"（策略/服务/工具/证据产生者）存在**生产调用点** — 证据: `grep -rn "<symbol>" src/ --include=*.ts` 有**非测试**命中且位于真实执行路径（非仅导出）| 审计: (待填写) [来源: farm-agent 2026-09-18 回流 P0 #R9；同类三例均为「纯函数+单测齐全、生产不可达」]
 
 ## ADD 规则合规检查
 

package/templates/core/templates/review-implementation-template.md

@@ -98,6 +98,24 @@
 
 ---
 
+## 6.2 接线可达性核对（`[W]` 接线判据 · 2026-09-18 增补）
+
+> **动因**：同类事故已发生**三次**（回流源：压缩通道 / 补向量 / 沉淀链），三次都是"**纯函数与单测齐全、生产不可达**"，
+> 而三项漂移指纹（范围扩散 / 类型错误 / 审计漏记）**全绿**——它们测的是"改得规不规矩"，不是"能力是否可达"。
+> 本节的判据是**可否证伪的 grep 与端到端产出**；"实现了 / 有单测 / 已导出"**不作为通过理由**。
+> [来源: farm-agent 2026-09-18 回流 P0 #R9；域符号名已泛化为占位符]
+
+对本次变更涉及的每个"被调用方"（策略 / 服务 / 工具 / 证据产生者 / 审计字面量）逐项核对：
+
+| # | 被调用方（symbol） | 期望调用点 | grep 证据（非测试命中） | 端到端产出证据 | 判定 |
+|---|-------------------|-----------|------------------------|---------------|:----:|
+| 1 | {symbol} | {文件:行} | `grep -rn "<symbol>" src/ --include=*.ts` 命中数 = {N} | {DB 行数 / SSE 帧 / 审计记录} | ✅/❌ |
+
+- [ ] 每个新增 symbol 有**非测试**调用点（**仅导出 / 仅被测试 import = 未接线 ⇒ 判 ❌**）
+- [ ] 涉及审计字面量时：该字面量在本次运行时**至少被写出过一次**（`query_audit_logs` 可查，而非"代码里有这行"）
+- [ ] 端到端产出可证（落库行数 / 帧 / 文件产物），而非"单测断言通过"
+- [ ] 本节表格已填；若本次变更**不含**新增被调用方，须显式写"本变更无新增被调用方"，不得静默跳过
+
 ## 7. 关联 Checklist
 
 - 本 review 的检查项与 `{checklist 文档路径}` 的"跨项目联调检查"章节一一对应

package/templates/core/templates/review-implementation-template.schema.json

@@ -42,6 +42,12 @@
             "heading": "## 6. E2E 逐端点 curl",
             "required": true
         },
+        {
+            "id": "wiring",
+            "heading": "## 6.2 接线可达性核对",
+            "required": true,
+            "note": "2026-09-18 增补（回流 farm-agent P0 #R9）：逐项核对新增被调用方的生产调用点与端到端产出（[W] 判据）。三次同类事故（纯函数与单测齐全、生产不可达）均在此节可被拦截。"
+        },
         {
             "id": "checklist",
             "heading": "## 7. 关联 Checklist",
@@ -61,4 +67,4 @@
         "阶段",
         "步骤"
     ]
-}
+}