add-coder 0.3.33 → 0.3.35

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)
+}

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

@@ -0,0 +1,33 @@
+/*
+ * Memory 子系统稳定错误码（Plan §12.3：MCP 错误采用稳定错误码，不能只返回自由文本）
+ * 契约：code 字符串冻结，变更需走 Review；message 可携带上下文细节。
+ */
+export const MEMORY_ERROR = {
+  ERR_REPOSITORY_MISMATCH: "调用方 repositoryRef 与运行时上下文不一致，越权访问被拒绝",
+  ERR_ORG_SCOPE_DISABLED: "ORGANIZATION scope 首版禁用（Plan §17-7 定案）",
+  ERR_ILLEGAL_TRANSITION: "非法状态迁移",
+  ERR_EVIDENCE_REQUIRED: "进入 ACTIVE 必须至少关联一条 Evidence",
+  ERR_APPROVAL_REQUIRED: "进入 ACTIVE 必须提供 approvedBy/approvedAt",
+  ERR_SUPERSESSION_INVALID: "supersede 需要有效的 supersededById 且 repository/scope 兼容",
+  ERR_INVARIANT: "字段不变量违反（如 importance/confidence 越出 [0,1]）",
+  ERR_FTS_UNAVAILABLE: "FTS 能力不可用且无法降级",
+  ERR_SECRET_DETECTED: "内容命中密钥/凭证模式，拒写",
+  ERR_NOT_FOUND: "记录不存在",
+  ERR_EMBEDDING_DISABLED: "EmbeddingProvider=none，向量能力未启用",
+  ERR_DIMENSION_MISMATCH: "嵌入维度与真源不一致（模型元数据 vs 声明维度），拒绝写入脏向量",
+} as const
+
+export type MemoryErrorCode = keyof typeof MEMORY_ERROR
+
+export class MemoryError extends Error {
+  readonly code: MemoryErrorCode
+  constructor(code: MemoryErrorCode, detail?: string) {
+    super(detail ? `${code}: ${MEMORY_ERROR[code]}（${detail}）` : `${code}: ${MEMORY_ERROR[code]}`)
+    this.name = "MemoryError"
+    this.code = code
+  }
+}
+
+export function isMemoryError(e: unknown): e is MemoryError {
+  return e instanceof MemoryError
+}

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

@@ -0,0 +1,92 @@
+/*
+ * Handoff Digest 候选构造（Plan §3.1 轮 2 / Spec §3 §HandoffDigest）
+ *
+ * 纯函数：输入 HANDOFF Evidence 行 → 输出可落库的 HANDOFF_DIGEST 候选提案。
+ * 三条不变量：
+ *  1. **绝不直接 ACTIVE**——提案只带 status=CANDIDATE 语义（由调用方落库时体现）；
+ *  2. **幂等**——dedupKey 由「来源引用 + 摘要内容」派生，同一 evidence 重放得到同一键；
+ *  3. **内容是可验证结论**，不是裸数值或空串：excerpt 为空时显式标注「摘要待人工补充」。
+ */
+import { contentHash, normalizeContent } from "./dedup.js"
+
+export const HANDOFF_DIGEST_KIND = "HANDOFF_DIGEST" as const
+
+/** 摘要正文最大字符数（超出截断并标注） */
+export const HANDOFF_EXCERPT_MAX = 300
+
+export interface HandoffDigestInput {
+  /** handoff 文档路径或引用（evidence.sourceRef） */
+  handoffRef: string
+  /** evidence 摘要原文 */
+  excerpt: string
+  /** 关联 Plan 关键词（evidence.planKeyword，可为空） */
+  planKeyword?: string | null
+}
+
+export interface HandoffDigestProposal {
+  kind: typeof HANDOFF_DIGEST_KIND
+  topic: string
+  content: string
+  scopeType: "PLAN" | "REPOSITORY"
+  scopeValue: string
+  contentHash: string
+  dedupKey: string
+  metadata: {
+    handoffRef: string
+    planKeyword: string | null
+    excerptTruncated: boolean
+  }
+}
+
+/** 从 handoff 引用提取主题名（去目录、去扩展名） */
+export function handoffTopicOf(handoffRef: string): string {
+  const base = handoffRef.split(/[\\/]/).pop() ?? handoffRef
+  const stem = base.replace(/\.(md|markdown|txt)$/i, "")
+  return stem.length > 0 ? stem : handoffRef
+}
+
+/**
+ * 构造 HANDOFF_DIGEST 候选提案。
+ *
+ * scope 选择：有 planKeyword → PLAN scope（历史语义，默认召回需显式放行）；
+ * 无 planKeyword → REPOSITORY scope（可被常规召回命中）。
+ */
+export function buildHandoffDigest(
+  input: HandoffDigestInput,
+  opts: { repositoryRef: string; maxExcerpt?: number },
+): HandoffDigestProposal {
+  const maxExcerpt = opts.maxExcerpt ?? HANDOFF_EXCERPT_MAX
+  const topic = handoffTopicOf(input.handoffRef)
+  const normalizedExcerpt = normalizeContent(input.excerpt ?? "")
+  const planKeyword = input.planKeyword && input.planKeyword.trim().length > 0
+    ? input.planKeyword.trim()
+    : null
+
+  const truncated = normalizedExcerpt.length > maxExcerpt
+  const body = truncated
+    ? `${normalizedExcerpt.slice(0, maxExcerpt)}…（已截断）`
+    : normalizedExcerpt
+
+  const content =
+    body.length > 0
+      ? `交接摘要 ${topic}：${body}（来源 ${input.handoffRef}）`
+      : `交接文档 ${input.handoffRef} 已归档，摘要待人工补充（自动摘要为空）。`
+
+  const scopeType: "PLAN" | "REPOSITORY" = planKeyword ? "PLAN" : "REPOSITORY"
+  const scopeValue = planKeyword ?? opts.repositoryRef
+
+  return {
+    kind: HANDOFF_DIGEST_KIND,
+    topic,
+    content,
+    scopeType,
+    scopeValue,
+    contentHash: contentHash(content),
+    dedupKey: contentHash(`${HANDOFF_DIGEST_KIND}|${input.handoffRef}|${normalizedExcerpt}`),
+    metadata: {
+      handoffRef: input.handoffRef,
+      planKeyword,
+      excerptTruncated: truncated,
+    },
+  }
+}

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

@@ -0,0 +1,79 @@
+/*
+ * 指标到知识的转换（Plan §10）
+ *
+ * entropy/code quality/Gate score 只写 AddMetricSnapshot；单个数值不能自动成为长期文本记忆。
+ * 候选生成需满足：同 scope 异常连续达阈值 / 多独立证据指向同根因 / 显著偏离基线且有可解释事件。
+ */
+
+export interface MetricPoint {
+  repositoryRef: string
+  metricType: string
+  value: number
+  baseline?: number | null
+  planKeyword?: string | null
+  measuredAt: Date
+  sourceRef: string
+}
+
+export interface MetricCandidateRule {
+  /** 同 scope 连续异常阈值（默认 3 次） */
+  streakThreshold: number
+  /** 显著偏离基线的相对幅度（默认 20%） */
+  deviationRatio: number
+  /** 判定"异常"的方向：高于基线为坏（higher-worse）或低于基线为坏（lower-worse） */
+  direction: "higher-worse" | "lower-worse"
+}
+
+export const DEFAULT_METRIC_RULE: MetricCandidateRule = {
+  streakThreshold: 3,
+  deviationRatio: 0.2,
+  direction: "lower-worse",
+}
+
+export interface MetricCandidateProposal {
+  topic: string
+  content: string
+  evidenceSourceRefs: string[]
+  rule: string
+}
+
+function isAnomaly(p: MetricPoint, rule: MetricCandidateRule): boolean {
+  if (p.baseline == null) return false
+  const dev = Math.abs(p.value - p.baseline) / (Math.abs(p.baseline) || 1)
+  if (dev < rule.deviationRatio) return false
+  return rule.direction === "lower-worse" ? p.value < p.baseline : p.value > p.baseline
+}
+
+/**
+ * 检测「同 scope 连续异常」：按时间排序后尾部连续异常数 ≥ streakThreshold 时生成候选建议。
+ * 纯函数；是否真正创建 Candidate 由调用方（consolidation job / 人工）决定。
+ */
+export function detectAnomalyStreak(
+  points: MetricPoint[],
+  rule: MetricCandidateRule = DEFAULT_METRIC_RULE,
+): MetricCandidateProposal | null {
+  if (points.length < rule.streakThreshold) return null
+  const sorted = [...points].sort((a, b) => a.measuredAt.getTime() - b.measuredAt.getTime())
+  let streak = 0
+  for (let i = sorted.length - 1; i >= 0; i--) {
+    if (isAnomaly(sorted[i], rule)) streak++
+    else break
+  }
+  if (streak < rule.streakThreshold) return null
+  const last = sorted[sorted.length - 1]
+  const streakPoints = sorted.slice(-streak)
+  return {
+    topic: `${last.metricType} 连续 ${streak} 次显著偏离基线`,
+    content:
+      `指标 ${last.metricType} 在最近 ${streak} 次测量中连续偏离基线超过 ${rule.deviationRatio * 100}%` +
+      `（baseline=${streakPoints[0].baseline}, 最新值=${last.value}）。` +
+      `建议人工审核是否形成可验证结论后再转为长期记忆。`,
+    evidenceSourceRefs: streakPoints.map((p) => p.sourceRef),
+    rule: `anomaly-streak>=${rule.streakThreshold} deviation>=${rule.deviationRatio} ${rule.direction}`,
+  }
+}
+
+/** Gate 执行后生成 sourceRef（Review P1 #2 回流：{gate}:{planKeyword}:{runId}） */
+export function metricSourceRef(gate: string, planKeyword: string, runId: string): string {
+  return `${gate}:${planKeyword}:${runId}`
+}