add-coder 0.3.34 → 0.3.37

package/templates/core/scripts/mcp-server/shared/memory/calibration/batch-fit.ts

@@ -0,0 +1,250 @@
+/*
+ * 冷启动批量拟合（Plan rank-calibration Task 2.1 / Spec §2 §BatchFit）
+ *
+ * 三工具分工里"**从无到有**"的那一件：给定一批带 ground truth 的样本 → 输出一个**点估计**权重。
+ * 不做在线跟踪（那是 Kalman），不做频谱诊断（那是 FFT）。
+ *
+ * 两个关键约束：
+ *  1. **train/test 切分**：标注集派生的样本必须按 query 维度切分，拟合只用 train，
+ *     验收只在 test —— 用验收集拟合会虚高 MRR（Spec §2 [2026-09-13 修订]）；
+ *  2. **目标函数可注入**：本模块默认用内置代理目标（按通道位次加权的命中率），
+ *     真实校准由 `rank-calibrate.ts` 注入"跑 recallPipeline + 算 MRR"的目标函数。
+ *     这样模块保持纯函数可测，而线上用真指标而非代理指标。
+ */
+import { createHash } from "node:crypto"
+import type { FeedbackChannel } from "./feedback-stats.js"
+
+export const DEFAULT_MIN_SAMPLES = 5
+
+/** 现行排序常数（无快照时的回落值 = 改造前行为，必须保持一致） */
+export const DEFAULT_WEIGHTS_V3 = {
+  vectorWeight: 0.3,
+  boostScale: 1,
+  rrfK: 10,
+} as const
+
+export interface FitWeights {
+  vectorWeight: number
+  boostScale: number
+  rrfK: number
+}
+
+/** 一条样本：query 归属 + ground truth + 各通道位次 */
+export interface FitSample {
+  queryId: string
+  memoryId: string
+  relevant: boolean
+  /** 该条在各通道中的位次（未命中该通道则不出现） */
+  ranks: Partial<Record<FeedbackChannel, number>>
+}
+
+export interface FitSplit {
+  splitId: string
+  trainQueries: string[]
+  testQueries: string[]
+}
+
+export interface WeightFitResult {
+  weights: FitWeights
+  /** 1 − 目标函数最优值（目标函数应返回 0..1 的归一化收益） */
+  residual: number
+  samples: number
+  trainSamples: number
+  testSamples: number
+  method: "default" | "grid"
+  splitId: string
+  /** 最优解落在搜索空间边界（提示空间可能过窄） */
+  boundaryHit: boolean
+}
+
+export interface SearchSpace {
+  vectorWeight: number[]
+  boostScale: number[]
+  rrfK: number[]
+}
+
+export const DEFAULT_SEARCH_SPACE: SearchSpace = {
+  vectorWeight: [0, 0.1, 0.2, 0.3, 0.5, 0.8],
+  boostScale: [0.5, 1, 2],
+  rrfK: [5, 10, 20, 60],
+}
+
+/** 目标函数：返回 0..1 的归一化收益（越大越好），由调用方决定是代理指标还是真实 MRR */
+export type FitObjective = (weights: FitWeights, samples: readonly FitSample[]) => number
+
+/**
+ * 切分分组 = **Plan 业务闭包**（架构事实，非算法聚类）。
+ * 见 Spec §2.2：单元素自身迭代（单元内）与跨单元流转（跨单元）是两条不同数据流，
+ * 用临时聚类代替 Plan 闭包会让"防泄漏"退化成口径游戏。
+ */
+export interface QueryGroup {
+  /** = planKeyword（业务闭包标识） */
+  groupId: string
+  queryIds: string[]
+  /** 单元状态：未收敛单元的样本默认不进训练集（Spec §2.2） */
+  unitState?: "closed" | "in-flight"
+}
+
+export interface GroupFold {
+  testGroupId: string
+  trainGroups: string[]
+  testQueries: string[]
+  trainQueries: string[]
+}
+
+export interface GroupedSplit {
+  mode: "leave-one-group-out" | "single-holdout"
+  folds: GroupFold[]
+  splitId: string
+  /** 簇数 < 3 → 结论不稳（明示，不隐瞒） */
+  lowGroupCount: boolean
+}
+
+function hashId(input: string): string {
+  return createHash("sha256").update(input).digest("hex").slice(0, 8)
+}
+
+/**
+ * 按 query 维度确定性切分（同输入 → 同 split，可复现）。
+ * 切分单位是 **query** 而非样本：同一 query 的样本不能跨集，否则信息泄漏。
+ */
+export function splitByQuery(queryIds: readonly string[], opts: { testRatio?: number } = {}): FitSplit {
+  const testRatio = opts.testRatio ?? 0.4
+  const unique = [...new Set(queryIds)]
+  // 以 queryId 哈希排序 → 与传入顺序无关，可复现
+  const ordered = [...unique].sort((a, b) => hashId(a).localeCompare(hashId(b)))
+  const testCount = Math.max(1, Math.round(ordered.length * testRatio))
+  const testQueries = ordered.slice(0, Math.min(testCount, Math.max(0, ordered.length - 1)))
+  const testSet = new Set(testQueries)
+  const trainQueries = ordered.filter((q) => !testSet.has(q))
+  return {
+    splitId: hashId(`split|${ordered.join(",")}|${testRatio}`),
+    trainQueries,
+    testQueries,
+  }
+}
+
+/**
+ * 按**业务闭包**切分（Spec §2.1/§2.2）。
+ *
+ * - 默认 `leave-one-group-out`：逐簇留出作 test、其余作 train（每折的 test query 一条都不在 train 中）
+ * - `single-holdout`：按簇哈希确定性挑 test 簇（用于簇数不足时的退化路径）
+ * - 未收敛单元（`unitState:"in-flight"`）参与分组但**默认不进训练集**，避免把"进行中的偏差"学进权重
+ */
+export function splitByGroup(
+  groups: readonly QueryGroup[],
+  opts: { mode?: "leave-one-group-out" | "single-holdout"; testRatio?: number; includeInFlight?: boolean } = {},
+): GroupedSplit {
+  const usable = groups.filter((g) => opts.includeInFlight === true || (g.unitState ?? "closed") === "closed")
+  const all = usable.length > 0 ? usable : groups
+  const mode = opts.mode ?? "leave-one-group-out"
+  const splitId = hashId(`groupsplit|${mode}|${all.map((g) => g.groupId).sort().join(",")}`)
+  const lowGroupCount = all.length < 3
+
+  if (mode === "single-holdout") {
+    const testRatio = opts.testRatio ?? 0.4
+    const ordered = [...all].sort((a, b) => hashId(a.groupId).localeCompare(hashId(b.groupId)))
+    const testCount = Math.max(1, Math.min(ordered.length - 1, Math.round(ordered.length * testRatio)))
+    const testGroups = ordered.slice(0, Math.max(0, testCount))
+    const trainGroups = ordered.slice(testGroups.length)
+    return {
+      mode,
+      splitId,
+      lowGroupCount,
+      folds: [
+        {
+          testGroupId: testGroups.map((g) => g.groupId).join("+"),
+          trainGroups: trainGroups.map((g) => g.groupId),
+          testQueries: testGroups.flatMap((g) => g.queryIds),
+          trainQueries: trainGroups.flatMap((g) => g.queryIds),
+        },
+      ],
+    }
+  }
+
+  return {
+    mode,
+    splitId,
+    lowGroupCount,
+    folds: all.map((test) => ({
+      testGroupId: test.groupId,
+      trainGroups: all.filter((g) => g.groupId !== test.groupId).map((g) => g.groupId),
+      testQueries: [...test.queryIds],
+      trainQueries: all.filter((g) => g.groupId !== test.groupId).flatMap((g) => g.queryIds),
+    })),
+  }
+}
+
+/** 内置代理目标：按通道位次加权命中率（AA 于 recall 的粗略替代，仅用于无注入场景与测试） */
+export function surrogateObjective(weights: FitWeights, samples: readonly FitSample[]): number {
+  if (samples.length === 0) return 0
+  let good = 0
+  let total = 0
+  for (const s of samples) {
+    const lexical = s.ranks.lexical != null ? (1 - weights.vectorWeight) / (weights.rrfK + s.ranks.lexical) : 0
+    const vector = s.ranks.vector != null ? weights.vectorWeight / (weights.rrfK + s.ranks.vector) : 0
+    const score = lexical + vector
+    total += 1
+    if (s.relevant && score > 0) good += 1
+    else if (!s.relevant && score === 0) good += 1
+  }
+  return total === 0 ? 0 : Number((good / total).toFixed(6))
+}
+
+export function fitWeights(
+  samples: readonly FitSample[],
+  split: FitSplit,
+  opts: { minSamples?: number; space?: SearchSpace; objective?: FitObjective } = {},
+): WeightFitResult {
+  const minSamples = opts.minSamples ?? DEFAULT_MIN_SAMPLES
+  const trainSet = new Set(split.trainQueries)
+  const testSet = new Set(split.testQueries)
+  const train = samples.filter((s) => trainSet.has(s.queryId))
+  const test = samples.filter((s) => testSet.has(s.queryId))
+
+  const base = {
+    samples: samples.length,
+    trainSamples: train.length,
+    testSamples: test.length,
+    splitId: split.splitId,
+  }
+
+  // 冷启动门控：样本不足 → 回落现行常数，且**不产出"拟合结果"**
+  if (train.length < minSamples) {
+    return { ...base, weights: { ...DEFAULT_WEIGHTS_V3 }, residual: 1, method: "default", boundaryHit: false }
+  }
+
+  const space = opts.space ?? DEFAULT_SEARCH_SPACE
+  const objective = opts.objective ?? surrogateObjective
+  let best: FitWeights = { ...DEFAULT_WEIGHTS_V3 }
+  let bestScore = -Infinity
+  let hit = false
+
+  for (const vectorWeight of space.vectorWeight) {
+    for (const boostScale of space.boostScale) {
+      for (const rrfK of space.rrfK) {
+        const weights: FitWeights = { vectorWeight, boostScale, rrfK }
+        const score = objective(weights, train)
+        if (score > bestScore) {
+          bestScore = score
+          best = weights
+          hit =
+            vectorWeight === space.vectorWeight[0] ||
+            vectorWeight === space.vectorWeight[space.vectorWeight.length - 1] ||
+            boostScale === space.boostScale[0] ||
+            boostScale === space.boostScale[space.boostScale.length - 1] ||
+            rrfK === space.rrfK[0] ||
+            rrfK === space.rrfK[space.rrfK.length - 1]
+        }
+      }
+    }
+  }
+
+  return {
+    ...base,
+    weights: best,
+    residual: Number((1 - Math.max(0, Math.min(1, bestScore))).toFixed(6)),
+    method: "grid",
+    boundaryHit: hit,
+  }
+}

package/templates/core/scripts/mcp-server/shared/memory/calibration/feedback-stats.ts

@@ -0,0 +1,101 @@
+/*
+ * 反馈统计（Plan rank-calibration Task 1.1 / Spec §1 §FeedbackStats）
+ *
+ * 职责边界（**这是三工具分工的第一环**）：只做**聚合**，不做拟合、不做权重建议。
+ * 通道归属由调用方提供（从 Recall 审计的 scoreBreakdown/fusedChannels + 各通道位次推导），
+ * 本模块不猜测来源 —— 猜错通道会让后续拟合学到错的信号。
+ *
+ * 统计口径（Spec §1）：
+ *  - 有用 = USED | USEFUL；无用 = IRRELEVANT | OUTDATED | CONTRADICTED | HARMFUL；
+ *  - **UNKNOWN 及其他未知取值不计入分母**（避免用未知样本稀释/污染有用率）；
+ *  - 样本数不足 → status="insufficient"（**此时不得据此改权重**）；
+ *  - 无样本的通道返回 total=0 / usefulRate=0，不用默认值伪装。
+ */
+
+export type FeedbackChannel = "lexical" | "vector"
+
+export const USEFUL_OUTCOMES = ["USED", "USEFUL"] as const
+export const NOT_USEFUL_OUTCOMES = ["IRRELEVANT", "OUTDATED", "CONTRADICTED", "HARMFUL"] as const
+export const DEFAULT_MIN_SAMPLES = 5
+
+export interface FeedbackSample {
+  memoryId: string
+  /** 该条在最终排序中的位次（null = 未入选） */
+  rank: number | null
+  outcome: string
+  /** 检出该条的通道集合（调用方从召回审计推导，可多通道） */
+  channels: readonly FeedbackChannel[]
+}
+
+export interface ChannelStat {
+  useful: number
+  total: number
+  usefulRate: number
+}
+
+export interface ChannelOutcomeStats {
+  /** 可分类样本数（分母：排除 UNKNOWN 等未分类 outcome） */
+  samples: number
+  status: "ok" | "insufficient"
+  byChannel: Record<FeedbackChannel, ChannelStat>
+  byRankBucket: { rank: 1 | 2 | 3 | 4 | 5; useful: number; total: number; usefulRate: number }[]
+  /** 未分类 outcome 的数量（可审计：有多少样本被排除在分母外） */
+  unclassified: number
+}
+
+function classify(outcome: string): "useful" | "not-useful" | "unclassified" {
+  if ((USEFUL_OUTCOMES as readonly string[]).includes(outcome)) return "useful"
+  if ((NOT_USEFUL_OUTCOMES as readonly string[]).includes(outcome)) return "not-useful"
+  return "unclassified"
+}
+
+function rate(useful: number, total: number): number {
+  return total === 0 ? 0 : Number((useful / total).toFixed(4))
+}
+
+export function aggregateFeedback(
+  samples: readonly FeedbackSample[],
+  opts: { minSamples?: number } = {},
+): ChannelOutcomeStats {
+  const minSamples = opts.minSamples ?? DEFAULT_MIN_SAMPLES
+
+  const byChannel: Record<FeedbackChannel, ChannelStat> = {
+    lexical: { useful: 0, total: 0, usefulRate: 0 },
+    vector: { useful: 0, total: 0, usefulRate: 0 },
+  }
+  const buckets = [1, 2, 3, 4, 5].map((rank) => ({ rank: rank as 1 | 2 | 3 | 4 | 5, useful: 0, total: 0 }))
+
+  let classified = 0
+  let unclassified = 0
+
+  for (const sample of samples) {
+    const kind = classify(sample.outcome)
+    if (kind === "unclassified") {
+      unclassified++
+      continue
+    }
+    classified++
+    const useful = kind === "useful"
+    for (const channel of new Set(sample.channels)) {
+      if (!byChannel[channel]) continue
+      byChannel[channel].total++
+      if (useful) byChannel[channel].useful++
+    }
+    if (sample.rank != null && sample.rank >= 1 && sample.rank <= 5) {
+      const bucket = buckets[sample.rank - 1]
+      bucket.total++
+      if (useful) bucket.useful++
+    }
+  }
+
+  return {
+    samples: classified,
+    status: classified < minSamples ? "insufficient" : "ok",
+    byChannel: {
+      lexical: { ...byChannel.lexical, usefulRate: rate(byChannel.lexical.useful, byChannel.lexical.total) },
+      vector: { ...byChannel.vector, usefulRate: rate(byChannel.vector.useful, byChannel.vector.total) },
+    },
+    byRankBucket: buckets.map((b) => ({ ...b, usefulRate: rate(b.useful, b.total) })),
+    unclassified,
+  }
+}

package/templates/core/scripts/mcp-server/shared/memory/calibration/unit-state.ts

@@ -0,0 +1,224 @@
+/*
+ * 单元状态解析（Plan rank-calibration Task 2.1.9 / Spec §2.2 + §2.3）
+ *
+ * 架构约束：单元（Plan 业务闭包）的状态是**既有事实**，必须读出来——不能手填、不能另建状态表。
+ *   closed    = add-route 全部产出项 [x] 且存在 ROUND_CLOSED devlog
+ *   in-flight = add-route 存在但仍有 [ ]，或缺少 ROUND_CLOSED（并发协议下的飞行中单元）
+ *   unknown   = 连 add-route 都没有（§2.3 视为缺制品，样本不可作训练依据）
+ *
+ * 同时产出**单元引用表**（refs）：报告按单元分层时直接引用这些制品，不复制内容（§2.3）。
+ */
+
+import { validate as coreValidate, type ValidationIssue } from "../../../../../validation/index.js"
+
+export interface UnitRefs {
+  planPath?: string
+  addRoutePath?: string
+  handoffPath?: string
+  specsDir?: string
+  planRecordId?: string
+  roundClosedAuditId?: string
+}
+
+export interface UnitState {
+  planKeyword: string
+  state: "closed" | "in-flight" | "unknown"
+  /**
+   * 诊断量（**不参与 closed 判定**）：add-route 勾选与事实的差距。
+   * 勾选是过程进度，不是收敛证据——用它判 closed 会把"过程"当"结果"。
+   */
+  documentationLag: { openSteps: number; totalSteps: number; lagging: boolean }
+  /** 封口四要素（Spec §2.2：四项合取） */
+  evidence: {
+    roundClosed: boolean
+    handoff: boolean
+    acceptance: boolean
+    planStatus: boolean
+  }
+  /** handoff 合规校验明细（来自 core 校验层；存在 ≠ 合规，Spec §2.2） */
+  handoffValidation?: { type: "handoff.single" | "handoff.multi"; ok: boolean; issues: ValidationIssue[] }
+  /** 缺失的既有制品（§2.3：缺证据的单元不可作为训练依据） */
+  missingArtifacts: string[]
+  refs: UnitRefs
+}
+
+export interface UnitStateDeps {
+  projectRoot: string
+  magicDir: string
+  /** 读文件内容（不存在返回 null）；测试注入 */
+  readFile?: (absPath: string) => string | null
+  /** 列 plans 目录下的文件名（不存在返回 []）；测试注入 */
+  listDir?: (absDir: string) => string[]
+  /**
+   * 列 plans 目录下的**相对路径**（含日期子目录，如 `2026-09/12/x.md`）；生产路径必须用这个 ——
+   * ADD 约定制品按 `plans/{YYYY-MM}/{DD}/` 分层，扁平列目录会漏掉全部真实 Plan（2026-09-13 真实单元自检暴露）。
+   */
+  listFiles?: (absDir: string) => string[]
+  /** 是否存在（specs 目录判断）；测试注入 */
+  exists?: (absPath: string) => boolean
+  /** 查 ROUND_CLOSED devlog（测试注入） */
+  findRoundClosed?: (planKeyword: string) => Promise<{ id: string } | null>
+  /** 查 PlanRecord（测试注入） */
+  findPlanRecord?: (planKeyword: string) => Promise<{
+    id: string
+    lifecycle?: string
+    doneTasks?: number
+    totalTasks?: number
+  } | null>
+  /**
+   * handoff 合规校验（默认 = core 校验层，schema 真源）。
+   * 注入点仅供测试；生产路径必须走 core，不得再自解析模板（Spec §2.2/§2.4）。
+   */
+  validateHandoff?: (input: {
+    type: "handoff.single" | "handoff.multi"
+    path: string
+    expectRounds: number
+  }) => { ok: boolean; issues: ValidationIssue[] }
+}
+
+/**
+ * 轮次数推导（既有制品读取，不新建状态）。
+ *
+ * 语义：取各制品中 `轮次 N` 的最大编号；**编号从 0 起 → +1，从 1 起 → 不变**。
+ * 例：`轮次 0..3` → 4 轮；`轮次 1` → 1 轮（单轮）。
+ * 输入建议按真源优先级传入：[planContent, tasksContent, addRouteContent]
+ * （tasks.md 的「轮次拓扑」是最稳定的轮次真源；add-route 的轮次常写在代码块内）。
+ */
+export function planRounds(...contents: readonly string[]): number {
+  const nums: number[] = []
+  for (const content of contents) {
+    for (const m of content.matchAll(/轮次\s*(\d+)/g)) nums.push(Number(m[1]))
+  }
+  if (nums.length === 0) return 1
+  const max = Math.max(...nums)
+  const min = Math.min(...nums)
+  return min === 0 ? max + 1 : max
+}
+
+/** 统计 add-route 产出项勾选情况（只认 `- [ ]` / `- [x]`） */
+export function countSteps(content: string): { open: number; total: number } {
+  let open = 0
+  let total = 0
+  for (const line of content.split("\n")) {
+    if (/^- \[ \]/.test(line)) {
+      open++
+      total++
+    } else if (/^- \[[xX]\]/.test(line)) {
+      total++
+    }
+  }
+  return { open, total }
+}
+
+export async function resolveUnitState(
+  planKeyword: string,
+  deps: UnitStateDeps,
+): Promise<UnitState> {
+  const plansDir = `${deps.projectRoot}/${deps.magicDir}/plans`
+  const specsDirRoot = `${deps.projectRoot}/${deps.magicDir}/specs`
+  const listDir = deps.listFiles ?? deps.listDir ?? (() => [])
+  const readFile = deps.readFile ?? (() => null)
+  const exists = deps.exists ?? (() => false)
+
+  const has = (name: string, must: string[]): boolean =>
+    must.every((m) => name.toLowerCase().includes(m.toLowerCase()))
+
+  const files = listDir(plansDir)
+  // ★ 匹配基准是 plan **base** 名（去掉 -plan-vN）：兄弟制品不带 plan 段——
+  //   Plan=`{base}-plan-v1.md`、add-route=`{base}-add-route-v1.md`、handoff=`{base}-handoff-v1.md`。
+  //   用完整 planKeyword 去匹配会漏掉后两者（2026-09-13 真实单元自检暴露）。
+  const base = planKeyword.replace(/-plan-v\d+$/i, "")
+  const planRel = files.find((f) => has(f, [base, "-plan-v"]) && !f.includes(".hitl"))
+  const addRouteRel = files.find((f) => has(f, [base, "add-route"]))
+  const handoffRel = files.find((f) => has(f, [base, "handoff"]))
+
+  const refs: UnitRefs = {}
+  const missingArtifacts: string[] = []
+
+  if (planRel) refs.planPath = `${deps.magicDir}/plans/${planRel}`
+  else missingArtifacts.push("plan")
+  if (addRouteRel) refs.addRoutePath = `${deps.magicDir}/plans/${addRouteRel}`
+  else missingArtifacts.push("add-route")
+  if (handoffRel) refs.handoffPath = `${deps.magicDir}/plans/${handoffRel}`
+  else missingArtifacts.push("handoff")
+
+  if (exists(`${specsDirRoot}/${base}`)) refs.specsDir = `${deps.magicDir}/specs/${base}`
+  else missingArtifacts.push("specs")
+
+  const [roundClosed, planRecord] = await Promise.all([
+    deps.findRoundClosed ? deps.findRoundClosed(planKeyword) : Promise.resolve(null),
+    deps.findPlanRecord ? deps.findPlanRecord(planKeyword) : Promise.resolve(null),
+  ])
+  if (roundClosed) refs.roundClosedAuditId = roundClosed.id
+  else missingArtifacts.push("round-closed")
+  if (planRecord) refs.planRecordId = planRecord.id
+  else missingArtifacts.push("plan-record")
+
+  const addRouteContent = addRouteRel ? (readFile(`${plansDir}/${addRouteRel}`) ?? "") : ""
+  const { open, total } = countSteps(addRouteContent)
+
+  // 验收证据：checklist 存在且 [T] 项无未勾选（缺证据的单元不可作训练依据）
+  const checklistAbs = refs.specsDir ? `${deps.projectRoot}/${refs.specsDir}/checklist.md` : ""
+  const checklistContent = checklistAbs ? (readFile(checklistAbs) ?? "") : ""
+  const unverifiedT = (checklistContent.match(/^- \[ \] \[T\]/gm) ?? []).length
+  const verifiedT = (checklistContent.match(/^- \[[xX]\] \[T\]/gm) ?? []).length
+  const acceptance = unverifiedT + verifiedT > 0 && unverifiedT === 0
+
+  // PlanRecord 状态：存在且进度收敛（done === total 且 total > 0）
+  const planStatus =
+    !!planRecord && (planRecord.totalTasks ?? 0) > 0 && planRecord.doneTasks === planRecord.totalTasks
+
+  const evidence = {
+    roundClosed: !!roundClosed,
+    handoff: false, // 由下方 handoff 合规校验填充（存在 ≠ 合规）
+    acceptance,
+    planStatus,
+  }
+
+  // 轮次真源：Plan 正文 + tasks.md（若有）+ add-route，取最大编号推导
+  const specBaseFromRefs = refs.specsDir ? `${deps.projectRoot}/${refs.specsDir}` : ""
+  const tasksContent = specBaseFromRefs ? (readFile(`${specBaseFromRefs}/tasks.md`) ?? "") : ""
+  const planContentForRounds = planRel ? (readFile(`${plansDir}/${planRel}`) ?? "") : ""
+
+  // handoff 合规校验：走 core 校验层（schema 真源）；缺文件即不合规
+  let handoffValidation: UnitState["handoffValidation"]
+  if (handoffRel) {
+    const rounds = planRounds(planContentForRounds, tasksContent, addRouteContent)
+    const type = rounds > 1 ? "handoff.multi" : "handoff.single"
+    const absPath = `${plansDir}/${handoffRel}`
+    const runner =
+      deps.validateHandoff ??
+      ((input: { type: "handoff.single" | "handoff.multi"; path: string; expectRounds: number }) => {
+        // core 校验层读 schema 真源；本模块不自解析模板（Spec §2.2/§2.4）
+        return coreValidate({
+          type: input.type,
+          path: input.path,
+          hook: "manual",
+          expectRounds: input.expectRounds,
+          projectRoot: deps.projectRoot,
+          magicDir: deps.magicDir,
+        })
+      })
+    const result = runner({ type, path: absPath, expectRounds: rounds })
+    handoffValidation = { type, ok: result.ok, issues: result.issues }
+    evidence.handoff = result.ok
+  }
+
+  let state: UnitState["state"]
+  if (!addRouteRel && !planRel) state = "unknown"
+  else if (evidence.roundClosed && evidence.handoff && evidence.acceptance && evidence.planStatus) {
+    state = "closed"
+  } else {
+    state = "in-flight"
+  }
+
+  return {
+    planKeyword,
+    state,
+    documentationLag: { openSteps: open, totalSteps: total, lagging: total > 0 && open > 0 },
+    evidence,
+    ...(handoffValidation ? { handoffValidation } : {}),
+    missingArtifacts,
+    refs,
+  }
+}

package/templates/core/scripts/mcp-server/shared/memory/domain/conflicts.ts

@@ -0,0 +1,59 @@
+/*
+ * 冲突检测（Plan §3 治理队列 / §7.2 同级冲突不得静默覆盖）
+ *
+ * 首版为保守启发式（无 embedding 依赖）：同 scope 且高文本相似的
+ * CONSTRAINT/DECISION 互为疑似冲突，必须进入 review，由人裁决。
+ */
+import { charBigrams, jaccardSimilarity } from "./dedup.js"
+
+export interface Conflict {
+  memoryId: string
+  topic: string
+  similarity: number
+  reason: string
+}
+
+export interface ConflictCandidate {
+  id?: string
+  kind: string
+  topic: string
+  content: string
+  scopeType: string
+  scopeValue: string
+}
+
+export interface ConflictOptions {
+  /** 相似度阈值（字符二元组 Jaccard），默认 0.6 */
+  threshold?: number
+  /** 参与冲突判定的 kind 集合 */
+  kinds?: readonly string[]
+}
+
+const DEFAULT_CONFLICT_KINDS = ["CONSTRAINT", "DECISION", "CONVENTION"] as const
+
+export function detectConflicts(
+  candidate: ConflictCandidate,
+  actives: ConflictCandidate[],
+  opts: ConflictOptions = {},
+): Conflict[] {
+  const threshold = opts.threshold ?? 0.6
+  const kinds = opts.kinds ?? DEFAULT_CONFLICT_KINDS
+  if (!kinds.includes(candidate.kind)) return []
+  const candVec = charBigrams(candidate.topic + " " + candidate.content)
+  const out: Conflict[] = []
+  for (const m of actives) {
+    if (m.id && m.id === candidate.id) continue
+    if (!kinds.includes(m.kind)) continue
+    if (m.scopeType !== candidate.scopeType || m.scopeValue !== candidate.scopeValue) continue
+    const sim = jaccardSimilarity(candVec, charBigrams(m.topic + " " + m.content))
+    if (sim >= threshold) {
+      out.push({
+        memoryId: m.id ?? "",
+        topic: m.topic,
+        similarity: Math.round(sim * 1000) / 1000,
+        reason: `同 scope(${m.scopeType}:${m.scopeValue}) 存在高相似 ${m.kind}，疑似冲突，需人工裁决`,
+      })
+    }
+  }
+  return out.sort((a, b) => b.similarity - a.similarity)
+}

package/templates/core/scripts/mcp-server/shared/memory/domain/dedup.ts

@@ -0,0 +1,45 @@
+/*
+ * 去重与内容规范化（Plan §4.4）
+ * contentHash = sha256(normalize(text))；幂等键 = repositoryRef + contentHash + scopeType + scopeValue
+ */
+import { createHash } from "crypto"
+
+/** 规范化：NFKC（全半角折叠）→ 小写 → 折叠全部空白为单空格 → trim */
+export function normalizeContent(s: string): string {
+  return s.normalize("NFKC").toLowerCase().replace(/\s+/g, " ").trim()
+}
+
+export function contentHash(s: string): string {
+  return createHash("sha256").update(normalizeContent(s), "utf8").digest("hex")
+}
+
+/** 幂等键（与 AddMemory 的 @@unique 约束一一对应） */
+export function memoryIdempotencyKey(input: {
+  repositoryRef: string
+  content: string
+  scopeType: string
+  scopeValue: string
+}): string {
+  return [
+    input.repositoryRef,
+    contentHash(input.content),
+    input.scopeType,
+    input.scopeValue,
+  ].join("|")
+}
+
+/** 字符二元组集合（冲突检测 / 近重复合并的轻量相似度基础，无需 embedding） */
+export function charBigrams(s: string): Set<string> {
+  const n = normalizeContent(s)
+  const out = new Set<string>()
+  for (let i = 0; i < n.length - 1; i++) out.add(n.slice(i, i + 2))
+  if (n.length === 1) out.add(n)
+  return out
+}
+
+export function jaccardSimilarity(a: Set<string>, b: Set<string>): number {
+  if (a.size === 0 && b.size === 0) return 1
+  let inter = 0
+  for (const x of a) if (b.has(x)) inter++
+  return inter / (a.size + b.size - inter || 1)
+}