add-coder 0.3.37 → 0.3.39

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "add-coder",
-  "version": "0.3.37",
+  "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": {
@@ -112,9 +112,13 @@
     "lint": "eslint src/",
     "lint:fix": "eslint src/ --fix",
     "generate": "tsx src/caijuehub/transcribe/index.ts",
+    "contributors": "tsx scripts/gen-contributors.ts --write",
+    "contributors:check": "tsx scripts/gen-contributors.ts --check",
+    "contributors:audit": "tsx scripts/gen-contributors.ts --check --audit",
     "podman-add-coder-up": "podman-compose --env-file .env.development -f podman-compose.add.yml up -d",
     "podman-add-coder-down": "podman-compose --env-file .env.development -f podman-compose.add.yml down",
     "test": "vitest run",
-    "generate:check": "tsx scripts/generate-idempotency-check.ts"
+    "generate:check": "tsx scripts/generate-idempotency-check.ts",
+    "release:preflight": "tsx scripts/release-preflight.ts"
   }
 }

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

@@ -1,5 +1,5 @@
 {
-  "_version": "0.3.37",
+  "_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",
@@ -229,7 +229,7 @@
   "core/rules/profiles/webapp-profile.md": "e493ae7b",
   "core/rules/project_rules.md": "094821ad",
   "core/rules/theory-practice-map.toml": "b1db99fd",
-  "core/scripts/db-ensure.sh": "8f7ba569",
+  "core/scripts/db-ensure.sh": "d46a43c1",
   "core/scripts/gen-plan-index.sh": "47836bec",
   "core/scripts/mcp-server/elicitation/confirm.ts": "924857b8",
   "core/scripts/mcp-server/elicitation/index.ts": "44c5dc3f",
@@ -280,7 +280,7 @@
   "core/scripts/mcp-server/shared/memory/metrics/stage-words.ts": "a81db64b",
   "core/scripts/mcp-server/shared/memory/retrieval/context-builder.ts": "ea83c131",
   "core/scripts/mcp-server/shared/memory/retrieval/fts/pg.ts": "1275eef4",
-  "core/scripts/mcp-server/shared/memory/retrieval/fts/sqlite-fts5.sql": "8fade96f",
+  "core/scripts/mcp-server/shared/memory/retrieval/fts/sqlite-fts5.sql": "1a439c1a",
   "core/scripts/mcp-server/shared/memory/retrieval/fts/sqlite.ts": "09a6cf59",
   "core/scripts/mcp-server/shared/memory/retrieval/fusion.ts": "c3aa6a4f",
   "core/scripts/mcp-server/shared/memory/retrieval/pipeline.ts": "dbe4a472",
@@ -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": "88d2c549",
-  "core/scripts/mcp-server/tools/gateway/check_spec_sync.ts": "75c0d1e3",
+  "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/db-ensure.sh

@@ -37,8 +37,24 @@ EOF
   echo ">>> 已创建 .env.development"
 fi
 
-# ── SQLite：无需容器 ──
-if [ "$ENGINE" = "sqlite" ]; then exit 0; fi
+# ── SQLite：无需容器；但 FTS5 原生层不在 Prisma schema 内，必须显式应用期望态 ──
+#   背景（Plan add-coder-sqlite-memory-flow §3.2）：`prisma db push` 只建 Prisma 表，
+#   `add_memory_fts` 虚表 + 3 个同步触发器是原生 DDL → 此前 sqlite 项目 recall_memory 直接
+#   `no such table`。此处与 init.ts（src/lib/memory-expected-state.ts）消费**同一份** SQL 真源。
+#   失败语义：仅告警不阻断（exit 0 语义不变）——记忆检索是能力项，不该让环境准备硬失败。
+if [ "$ENGINE" = "sqlite" ]; then
+  MAGIC_DIR="${MAGIC_DIR:-.codex}"
+  FTS_SQL="$MAGIC_DIR/scripts/mcp-server/shared/memory/retrieval/fts/sqlite-fts5.sql"
+  if [ -f "$PROJECT_DIR/$FTS_SQL" ]; then
+    echo ">>> 应用记忆 FTS5 期望态（$FTS_SQL）..."
+    # Prisma 7：db execute 的 datasource 由项目 prisma.config.ts 提供，`--schema` 已移除（带=unknown option）
+    (cd "$PROJECT_DIR" && npm exec prisma -- db execute --file "$PROJECT_DIR/$FTS_SQL") \
+      || echo "!!! 记忆 FTS5 期望态应用失败（不阻断）：recall_memory 将按 fts-only 降级；修复入口 add-coder memory:reindex --apply"
+  else
+    echo ">>> 未找到 $FTS_SQL（跳过，不阻断）——请先执行 add-coder sync"
+  fi
+  exit 0
+fi
 
 # ── 自行管理 PostgreSQL ──
 if [ "$CONTAINER" = "none" ] || [ "$CONTAINER" = "manual" ]; then

package/templates/core/scripts/mcp-server/shared/memory/retrieval/fts/sqlite-fts5.sql

@@ -1,3 +1,6 @@
+-- 本文件由 scripts/memory/gen-sqlite-fts-sql.ts 生成（真源：src/lib/memory-fts-objects.ts 的 SQLITE_FTS_OBJECTS）
+-- 请勿手工编辑；新增/修改 DDL 请改真源后重跑生成脚本。
+--
 -- Agent Memory FTS 原生层（SQLite 后端）
 -- Plan §8.3 + §17-3 定案：FTS5 trigram 分词器（CJK 友好，≥3 字符 n-gram 匹配；
 -- 短于 3 字符的查询由 adapter 层回退 LIKE —— 见 retrieval/fts/sqlite.ts）
@@ -6,24 +9,10 @@
 -- （其要求 INTEGER rowid），故采用独立 FTS 表 + 触发器同步。
 -- 幂等：全部 IF NOT EXISTS，可重复应用。
 
-CREATE VIRTUAL TABLE IF NOT EXISTS add_memory_fts USING fts5(
-  memory_id UNINDEXED,
-  topic,
-  content,
-  tokenize = 'trigram'
-);
+CREATE VIRTUAL TABLE IF NOT EXISTS add_memory_fts USING fts5(memory_id UNINDEXED, topic, content, tokenize = 'trigram');
 
-CREATE TRIGGER IF NOT EXISTS add_memory_fts_ai AFTER INSERT ON "AddMemory" BEGIN
-  INSERT INTO add_memory_fts(memory_id, topic, content)
-  VALUES (new.id, new.topic, new.content);
-END;
+CREATE TRIGGER IF NOT EXISTS add_memory_fts_ai AFTER INSERT ON "AddMemory" BEGIN INSERT INTO add_memory_fts(memory_id, topic, content) VALUES (new.id, new.topic, new.content); END;
 
-CREATE TRIGGER IF NOT EXISTS add_memory_fts_au AFTER UPDATE ON "AddMemory" BEGIN
-  DELETE FROM add_memory_fts WHERE memory_id = old.id;
-  INSERT INTO add_memory_fts(memory_id, topic, content)
-  VALUES (new.id, new.topic, new.content);
-END;
+CREATE TRIGGER IF NOT EXISTS add_memory_fts_au AFTER UPDATE ON "AddMemory" BEGIN DELETE FROM add_memory_fts WHERE memory_id = old.id; INSERT INTO add_memory_fts(memory_id, topic, content) VALUES (new.id, new.topic, new.content); END;
 
-CREATE TRIGGER IF NOT EXISTS add_memory_fts_ad AFTER DELETE ON "AddMemory" BEGIN
-  DELETE FROM add_memory_fts WHERE memory_id = old.id;
-END;
+CREATE TRIGGER IF NOT EXISTS add_memory_fts_ad AFTER DELETE ON "AddMemory" BEGIN DELETE FROM add_memory_fts WHERE memory_id = old.id; END;

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,27 +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());
-            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());
+            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,51 +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 修复）
-          const appendixFiles = (arContent.match(/`[^`]+\.(ts|js|sh|md|tsx|json|yml|yaml|toml)`/g) || [])
-            .map((f: string) => f.replace(/`/g, ""));
+          // sql/prisma 纳入（2026-09-16 修复）：原生 DDL 与 schema 是常见交付物，此前不在白名单 →
+          // 附录里明明登记了 `.../sqlite-fts5.sql` 仍被判"不在附录中"（假告警）。
+          const appendixFiles = extractAppendixFiles(arContent);
           lines.push(`附录文件: ${appendixFiles.length} 个`);
 
           // git diff 变更文件（win32 下 git 为 .cmd → runCommand 自动解析，issue #10 跨端修复）
           let diffFiles: string[] = [];
           try {
-            const diff = runCommand("git", ["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: 无法获取");
           }
@@ -106,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 附录中");
             }