add-coder 0.3.34 → 0.3.35

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

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

@@ -0,0 +1,94 @@
+/*
+ * Memory Scope 规则（Plan §7.2）
+ *
+ * 优先级：symbol > path > module > branch > repository > organization
+ * ORGANIZATION 首版禁用（写入拒绝，§17-7）；PLAN/SPEC 只在对应流程或显式历史查询中参与。
+ */
+import { MemoryError } from "./errors.js"
+
+export type MemoryScopeType =
+  | "ORGANIZATION" | "REPOSITORY" | "BRANCH" | "MODULE"
+  | "PATH" | "SYMBOL" | "PLAN" | "SPEC"
+
+export interface Scope {
+  type: MemoryScopeType
+  value: string
+}
+
+/** 召回时的上下文坐标（由调用方从运行时环境组装） */
+export interface ScopeContext {
+  repository: string
+  branch?: string
+  module?: string
+  paths?: string[]
+  symbols?: string[]
+  planKeyword?: string
+  specRef?: string
+  /** 显式历史查询时放行 PLAN/SPEC scope（默认 false） */
+  includePlanScope?: boolean
+}
+
+const RANK: Record<MemoryScopeType, number> = {
+  SYMBOL: 7,
+  PATH: 6,
+  MODULE: 5,
+  BRANCH: 4,
+  REPOSITORY: 3,
+  PLAN: 2,
+  SPEC: 2,
+  ORGANIZATION: 1,
+}
+
+export function scopeRank(t: MemoryScopeType): number {
+  return RANK[t]
+}
+
+/** 写入守卫：ORGANIZATION 首版禁用 */
+export function assertScopeWritable(scope: Scope): void {
+  if (scope.type === "ORGANIZATION") {
+    throw new MemoryError("ERR_ORG_SCOPE_DISABLED")
+  }
+}
+
+/** 判定一条 Memory 的 scope 在当前上下文是否有效（召回过滤用） */
+export function scopeApplies(memScope: Scope, ctx: ScopeContext): boolean {
+  switch (memScope.type) {
+    case "ORGANIZATION":
+      return false // 首版禁用
+    case "REPOSITORY":
+      return memScope.value === ctx.repository
+    case "BRANCH":
+      return !!ctx.branch && ctx.branch === memScope.value
+    case "MODULE":
+      // module 语义：当前任一路径以该模块目录为前缀
+      return !!ctx.module && ctx.module === memScope.value ||
+        (ctx.paths ?? []).some((p) => p === memScope.value || p.startsWith(memScope.value + "/"))
+    case "PATH":
+      return (ctx.paths ?? []).some(
+        (p) => p === memScope.value || p.startsWith(memScope.value.replace(/\/?$/, "/")),
+      )
+    case "SYMBOL":
+      return (ctx.symbols ?? []).includes(memScope.value)
+    case "PLAN":
+      return !!ctx.includePlanScope && !!ctx.planKeyword && ctx.planKeyword === memScope.value
+    case "SPEC":
+      return !!ctx.includePlanScope && !!ctx.specRef && ctx.specRef === memScope.value
+  }
+}
+
+/**
+ * supersede 兼容性（Plan §4.4）：新旧 Memory 的 repository/scope 必须兼容。
+ * 兼容 = 同类型同值；或 PATH/MODULE 类型间存在前缀覆盖；或一方为 REPOSITORY（全库覆盖）。
+ */
+export function scopesCompatible(a: Scope, b: Scope): boolean {
+  if (a.type === b.type && a.value === b.value) return true
+  if (a.type === "REPOSITORY" || b.type === "REPOSITORY") {
+    return a.type === "REPOSITORY" && b.type === "REPOSITORY" ? a.value === b.value : true
+  }
+  const pathLike = (t: MemoryScopeType) => t === "PATH" || t === "MODULE"
+  if (pathLike(a.type) && pathLike(b.type)) {
+    return a.value.startsWith(b.value.replace(/\/?$/, "/")) ||
+      b.value.startsWith(a.value.replace(/\/?$/, "/"))
+  }
+  return false
+}

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

@@ -0,0 +1,50 @@
+/*
+ * 密钥/凭证扫描（Plan §11：Evidence 摘录在写入前执行秘密与敏感信息检测）
+ * 命中即拒写（ERR_SECRET_DETECTED）。宁可误报，不可漏报。
+ */
+import { MemoryError } from "./errors.js"
+
+export interface SecretHit {
+  pattern: string
+  index: number
+  preview: string
+}
+
+interface SecretPattern {
+  name: string
+  re: RegExp
+}
+
+const PATTERNS: SecretPattern[] = [
+  { name: "private-key-block", re: /-----BEGIN (?:RSA |EC |OPENSSH |PGP )?PRIVATE KEY-----/ },
+  { name: "aws-access-key", re: /\bAKIA[0-9A-Z]{16}\b/ },
+  { name: "github-token", re: /\b(?:ghp|gho|ghu|ghs|ghr|github_pat)_[A-Za-z0-9_]{20,}\b/ },
+  { name: "openai-style-key", re: /\bsk-[A-Za-z0-9_-]{20,}\b/ },
+  { name: "slack-token", re: /\bxox[baprs]-[A-Za-z0-9-]{10,}\b/ },
+  { name: "bearer-token", re: /\bBearer\s+[A-Za-z0-9._~+/=-]{20,}\b/i },
+  { name: "conn-string-password", re: /(?:postgres(?:ql)?|mysql|mongodb(?:\+srv)?|redis):\/\/[^:\s/]+:[^@\s]+@/i },
+  { name: "generic-secret-assign", re: /\b(?:password|passwd|secret|api[_-]?key|access[_-]?token)\b\s*[:=]\s*["'][^"'\s]{8,}["']/i },
+  { name: "jwt", re: /\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\b/ },
+]
+
+export function scanSecrets(text: string): SecretHit[] {
+  const hits: SecretHit[] = []
+  for (const p of PATTERNS) {
+    const m = p.re.exec(text)
+    if (m) {
+      hits.push({
+        pattern: p.name,
+        index: m.index,
+        preview: text.slice(Math.max(0, m.index - 10), m.index + 20).replace(/\s+/g, " ").slice(0, 40),
+      })
+    }
+  }
+  return hits
+}
+
+export function assertNoSecrets(text: string): void {
+  const hits = scanSecrets(text)
+  if (hits.length > 0) {
+    throw new MemoryError("ERR_SECRET_DETECTED", hits.map((h) => h.pattern).join(","))
+  }
+}