add-coder 0.3.34 → 0.3.35

package/templates/core/scripts/mcp-server/shared/memory/jobs/evidence-collector.ts

@@ -0,0 +1,153 @@
+/*
+ * Evidence 自动采集（Spec §10/§11，Plan §9.2 PostToolUse 行）
+ *
+ * 两段式：
+ *  ① Hook 侧（同步 ≤200ms，无 DB）：白名单判定 + 事件入队（evidence-queue.jsonl append-only）
+ *     —— classifyEvidenceSource / buildEvidenceEvent 为纯函数，供 post-tool-router 直接引用
+ *  ② Job 侧（异步，可重试）：drainEvidenceQueue 消费队列 → upsert Evidence（幂等键
+ *     repositoryRef+sourceType+sourceRef+contentHash，与 add.prisma @@unique 一一对应）
+ *     消费进度落 evidence-queue.offset（字节偏移），重放幂等：同偏移不重复处理，
+ *     同事件重复消费由 upsert 幂等吸收。
+ */
+import { createHash } from "node:crypto"
+import { existsSync, mkdirSync, openSync, readFileSync, readSync, closeSync, statSync, writeFileSync, renameSync } from "node:fs"
+import { dirname, join } from "node:path"
+import type { AddMemoryEvidenceRow, TableDelegate } from "../../db-types.js"
+import { EVIDENCE_OFFSET_FILE, EVIDENCE_QUEUE_FILE, MEMORY_DIR_NAME } from "../switches.js"
+
+// ── ① Hook 侧纯函数（无 IO 之外的依赖，无 DB） ──
+
+export type EvidenceSourceType = "PLAN" | "SPEC" | "HANDOFF" | "DEV_OPERATION"
+
+export interface EvidenceEvent {
+  dedupKey: string
+  sourceType: EvidenceSourceType
+  sourceRef: string
+  excerpt: string
+  occurredAt: string
+}
+
+/** 白名单分类：命中返回 sourceType，未命中返回 null（spec §10：按白名单采集） */
+export function classifyEvidenceSource(filePath: string): EvidenceSourceType | null {
+  const p = filePath.replace(/\\/g, "/")
+  if (/(^|\/)plans\/[^/]*-plan-v\d+\.md$/.test(p)) return "PLAN"
+  if (/(^|\/)plans\/[^/]*-add-route-v\d+\.md$/.test(p)) return "PLAN"
+  if (/(^|\/)specs\/.+\.md$/.test(p)) return "SPEC"
+  if (/handoff[^/]*\.md$/i.test(p)) return "HANDOFF"
+  if (/(^|\/)reviews\/.+\.md$/.test(p)) return "DEV_OPERATION"
+  return null
+}
+
+/** 构造采证事件（幂等 key = sha256(sourceType|sourceRef|excerpt)）：同文件同内容重复写入被吸收 */
+export function buildEvidenceEvent(filePath: string, excerpt: string, occurredAt = new Date()): EvidenceEvent {
+  const sourceType = classifyEvidenceSource(filePath)
+  if (!sourceType) throw new Error(`非白名单路径: ${filePath}`)
+  const sourceRef = filePath
+  const dedupKey = createHash("sha256")
+    .update(`${sourceType}|${sourceRef}|${excerpt}`, "utf8")
+    .digest("hex")
+    .slice(0, 32)
+  return { dedupKey, sourceType, sourceRef, excerpt: excerpt.slice(0, 500), occurredAt: occurredAt.toISOString() }
+}
+
+// ── ② Job 侧消费（异步、可重试） ──
+
+export interface DrainDeps {
+  projectDir: string
+  magicDir: string
+  repositoryRef: string
+  evidenceDb: Pick<TableDelegate<AddMemoryEvidenceRow>, "upsert">
+}
+
+export interface DrainResult {
+  processed: number
+  skipped: number
+  errors: string[]
+  newOffset: number
+}
+
+/** 读 offset 标记（缺失/损坏 → 0，从头重放；upsert 幂等保证安全） */
+export function readOffset(projectDir: string, magicDir: string): number {
+  try {
+    const f = join(projectDir, magicDir, MEMORY_DIR_NAME, EVIDENCE_OFFSET_FILE)
+    if (!existsSync(f)) return 0
+    const n = Number(readFileSync(f, "utf-8").trim())
+    return Number.isFinite(n) && n >= 0 ? n : 0
+  } catch {
+    return 0
+  }
+}
+
+/**
+ * 消费 evidence 队列：从上次偏移继续，逐行 upsert Evidence。
+ * fail-open 粒度到行：坏行跳过并计入 errors，不阻塞后续。
+ */
+export async function drainEvidenceQueue(deps: DrainDeps): Promise<DrainResult> {
+  const queueFile = join(deps.projectDir, deps.magicDir, MEMORY_DIR_NAME, EVIDENCE_QUEUE_FILE)
+  const result: DrainResult = { processed: 0, skipped: 0, errors: [], newOffset: readOffset(deps.projectDir, deps.magicDir) }
+  if (!existsSync(queueFile)) return result
+
+  const size = (() => { try { return statSync(queueFile).size } catch { return 0 } })()
+  if (size <= result.newOffset) return result // 无增量
+
+  // 按偏移读取增量字节（避免大文件全量加载）
+  const fd = openSync(queueFile, "r")
+  let chunk: string
+  try {
+    const buf = Buffer.alloc(size - result.newOffset)
+    readSync(fd, buf, 0, buf.length, result.newOffset)
+    chunk = buf.toString("utf-8")
+  } finally {
+    closeSync(fd)
+  }
+
+  let cursor = result.newOffset
+  for (const line of chunk.split("\n")) {
+    const lineBytes = Buffer.byteLength(line, "utf-8") + 1 // + '\n'
+    cursor += lineBytes
+    const trimmed = line.trim()
+    if (!trimmed) continue
+    let ev: EvidenceEvent
+    try {
+      ev = JSON.parse(trimmed) as EvidenceEvent
+    } catch {
+      result.skipped++
+      result.errors.push(`坏行@${cursor - lineBytes}: JSON 解析失败`)
+      continue
+    }
+    try {
+      await deps.evidenceDb.upsert({
+        where: {
+          repositoryRef_sourceType_sourceRef_contentHash: {
+            repositoryRef: deps.repositoryRef,
+            sourceType: ev.sourceType,
+            sourceRef: ev.sourceRef,
+            contentHash: ev.dedupKey,
+          },
+        },
+        create: {
+          repositoryRef: deps.repositoryRef,
+          sourceType: ev.sourceType,
+          sourceRef: ev.sourceRef,
+          excerpt: ev.excerpt,
+          contentHash: ev.dedupKey,
+          occurredAt: new Date(ev.occurredAt),
+        } as Partial<AddMemoryEvidenceRow>,
+        update: {},
+      })
+      result.processed++
+    } catch (e) {
+      result.skipped++
+      result.errors.push(`落库失败 ${ev.sourceRef}: ${e instanceof Error ? e.message : String(e)}`)
+    }
+  }
+
+  // 原子推进 offset（先写后改：offset 落后只会重放，upsert 幂等吸收）
+  result.newOffset = cursor
+  const offsetFile = join(deps.projectDir, deps.magicDir, MEMORY_DIR_NAME, EVIDENCE_OFFSET_FILE)
+  mkdirSync(dirname(offsetFile), { recursive: true })
+  const tmp = `${offsetFile}.tmp-${process.pid}`
+  writeFileSync(tmp, String(cursor), "utf-8")
+  renameSync(tmp, offsetFile)
+  return result
+}

package/templates/core/scripts/mcp-server/shared/memory/jobs/snapshot.ts

@@ -0,0 +1,114 @@
+/*
+ * L1/L2 召回快照生成（Spec §10：session-start 仅注入 repository 级 L1 小上下文）
+ *
+ * 设计约束（Plan §9.3）：同步 Hook ≤200ms 且无 DB 依赖 → Hook 只读本模块预计算的快照文件；
+ * 快照由本 job 异步刷新（consolidation / 手动 CLI / Gate 后触发）。
+ * 原子写：tmp + rename，Hook 读侧永不遇到半文件。
+ */
+import { mkdirSync, renameSync, writeFileSync } from "node:fs"
+import { dirname, join } from "node:path"
+import { recallPipeline, type MemoryRowLike } from "../retrieval/pipeline.js"
+import type { RecallAuditStore } from "../retrieval/recall-writer.js"
+import type { LexicalSearchAdapter, RecalledMemory } from "../retrieval/types.js"
+import { L1_SNAPSHOT_FILE, L2_SNAPSHOT_FILE, MEMORY_DIR_NAME, memoryMaxTokens } from "../switches.js"
+
+export interface SnapshotDeps {
+  repositoryRef: string
+  projectDir: string
+  magicDir: string
+  lexical: LexicalSearchAdapter[]
+  fetchByIds(ids: string[]): Promise<MemoryRowLike[]>
+  fetchEvidenceSourceRefs(memoryIds: string[]): Promise<Map<string, string[]>>
+  audit: RecallAuditStore
+  now?: Date
+}
+
+export interface SnapshotResult {
+  path: string
+  itemCount: number
+  injectedTokens: number
+  recallId: string | null
+}
+
+/** 渲染带来源边界标签的注入文本（Plan §9.3：Recall 注入采用明确的数据边界与来源标签） */
+export function renderSnapshotMarkdown(level: "L1" | "L2", items: RecalledMemory[], generatedAt: Date): string {
+  const lines = [
+    `[Memory ${level} · 来源: AddMemory 治理库 · 生成于 ${generatedAt.toISOString()}]`,
+    `<agent-memory source="add-memory" trust="governed">`,
+  ]
+  for (const it of items) {
+    lines.push(
+      `- [${it.kind}] ${it.topic}（置信 ${it.confidence.toFixed(2)}）`,
+      `  ${it.content.length > 120 ? it.content.slice(0, 120) + "…" : it.content}`,
+    )
+    if (it.sourceRefs.length > 0) lines.push(`  来源: ${it.sourceRefs.join(", ")}`)
+  }
+  lines.push(`</agent-memory>`)
+  return lines.join("\n") + "\n"
+}
+
+/** 刷新 L1 快照：repository 级核心约束/决策/陷阱/约定 */
+export async function refreshL1Snapshot(deps: SnapshotDeps): Promise<SnapshotResult> {
+  const maxTokens = memoryMaxTokens()
+  const result = await recallPipeline(
+    {
+      query: "核心约束 关键决策 常见陷阱 项目约定",
+      stage: "session-start",
+      repositoryRef: deps.repositoryRef,
+      scopeCtx: { repository: deps.repositoryRef },
+      maxTokens,
+      kinds: ["CONSTRAINT", "DECISION", "PITFALL", "CONVENTION"],
+      limit: 20,
+      consumerRef: "memory-jobs:refresh-l1",
+    },
+    {
+      lexical: deps.lexical,
+      fetchByIds: deps.fetchByIds,
+      fetchEvidenceSourceRefs: deps.fetchEvidenceSourceRefs,
+      audit: deps.audit,
+      degradedMode: "fts-only(snapshot-job)",
+      now: deps.now,
+    },
+  )
+  const path = join(deps.projectDir, deps.magicDir, MEMORY_DIR_NAME, L1_SNAPSHOT_FILE)
+  atomicWrite(path, renderSnapshotMarkdown("L1", result.items, deps.now ?? new Date()))
+  return { path, itemCount: result.items.length, injectedTokens: result.injectedTokens, recallId: result.recallId }
+}
+
+/** 刷新 L2 快照：按给定 query/stage/scope（供 prompt-router 提示与人工查阅） */
+export async function refreshL2Snapshot(
+  deps: SnapshotDeps,
+  query: string,
+  stage: string,
+  maxTokens = 1200,
+): Promise<SnapshotResult> {
+  const result = await recallPipeline(
+    {
+      query,
+      stage,
+      repositoryRef: deps.repositoryRef,
+      scopeCtx: { repository: deps.repositoryRef },
+      maxTokens,
+      limit: 20,
+      consumerRef: "memory-jobs:refresh-l2",
+    },
+    {
+      lexical: deps.lexical,
+      fetchByIds: deps.fetchByIds,
+      fetchEvidenceSourceRefs: deps.fetchEvidenceSourceRefs,
+      audit: deps.audit,
+      degradedMode: "fts-only(snapshot-job)",
+      now: deps.now,
+    },
+  )
+  const path = join(deps.projectDir, deps.magicDir, MEMORY_DIR_NAME, L2_SNAPSHOT_FILE)
+  atomicWrite(path, renderSnapshotMarkdown("L2", result.items, deps.now ?? new Date()))
+  return { path, itemCount: result.items.length, injectedTokens: result.injectedTokens, recallId: result.recallId }
+}
+
+function atomicWrite(path: string, content: string): void {
+  mkdirSync(dirname(path), { recursive: true })
+  const tmp = `${path}.tmp-${process.pid}`
+  writeFileSync(tmp, content, "utf-8")
+  renameSync(tmp, path)
+}

package/templates/core/scripts/mcp-server/shared/memory/metrics/gate-recall.ts

@@ -0,0 +1,134 @@
+/*
+ * 工具侧阶段确定性召回（Plan §3.1 方案 B1 / Spec §2 §DeterministicRecall）
+ *
+ * 与 stage-words.ts 的分工：
+ *  - stage-words.ts：纯函数，Hook 侧识别阶段词（无 DB）
+ *  - 本模块：有 DB 的工具侧落点，复用既有 recallPipeline（不另起一套召回实现）
+ *
+ * 三条硬约束：
+ *  1. 阶段白名单命中才召回——未命中直接返回，不访问 DB、不写审计；
+ *  2. ADD_MEMORY_RECALL_MODE=off 时整体停用（与 recall_memory 工具同语义）；
+ *  3. fail-open：管线异常只降级为 skippedReason="pipeline-error"，绝不抛出，
+ *     不阻塞调用它的门禁/交接流程。
+ */
+import { recallPipeline, type RecallPipelineDeps, type RecallPipelineResult } from "../retrieval/pipeline.js"
+import { buildContext, estimateTokens } from "../retrieval/context-builder.js"
+import { recallMode, type RecallMode } from "../switches.js"
+import type { ScopeContext } from "../domain/scope.js"
+import { isRecallStage, RECALL_STAGES, type RecallStage } from "./stage-words.js"
+
+/** 默认 token 预算（Spec §10：ADD_MEMORY_MAX_TOKENS 默认 600，此处与 Recall 通道对齐） */
+export const DEFAULT_STAGE_RECALL_MAX_TOKENS = 600
+
+export type StageRecallSkipReason = "stage-not-whitelisted" | "recall-off" | "pipeline-error"
+
+export interface StageRecallInput {
+  /** 调用方声明的阶段；不在白名单内即不召回 */
+  stage: string
+  query: string
+  repositoryRef: string
+  scopeCtx?: Partial<ScopeContext>
+  planKeyword?: string
+  specRef?: string
+  maxTokens?: number
+  limit?: number
+  consumerRef?: string
+  diagnostic?: boolean
+}
+
+export interface StageRecallResult {
+  injected: boolean
+  stage: RecallStage | null
+  context?: string
+  auditId?: string | null
+  degradedMode?: string | null
+  itemCount: number
+  usedTokens: number
+  latencyMs: number
+  skippedReason?: StageRecallSkipReason
+  error?: string
+}
+
+/**
+ * 按阶段执行确定性召回。deps 由调用方（MCP 工具）注入，便于测试与复用。
+ */
+export async function recallForStage(
+  input: StageRecallInput,
+  deps: RecallPipelineDeps,
+  options: { mode?: RecallMode } = {},
+): Promise<StageRecallResult> {
+  const startedAt = Date.now()
+  const empty = (): Omit<StageRecallResult, "skippedReason" | "stage"> => ({
+    injected: false,
+    itemCount: 0,
+    usedTokens: 0,
+    latencyMs: Math.max(0, Date.now() - startedAt),
+  })
+
+  if (!isRecallStage(input.stage)) {
+    return { ...empty(), stage: null, skippedReason: "stage-not-whitelisted" }
+  }
+  const mode = options.mode ?? recallMode()
+  if (mode === "off") {
+    return { ...empty(), stage: input.stage, skippedReason: "recall-off" }
+  }
+
+  const stage = input.stage
+  const maxTokens = input.maxTokens ?? DEFAULT_STAGE_RECALL_MAX_TOKENS
+  const scopeCtx: ScopeContext = {
+    repository: input.repositoryRef,
+    planKeyword: input.planKeyword,
+    specRef: input.specRef,
+    ...input.scopeCtx,
+  }
+
+  try {
+    const result: RecallPipelineResult = await recallPipeline(
+      {
+        query: input.query,
+        stage,
+        repositoryRef: input.repositoryRef,
+        scopeCtx,
+        maxTokens,
+        limit: input.limit ?? 20,
+        consumerRef: input.consumerRef ?? `mcp:stage-recall:${stage}`,
+        diagnostic: input.diagnostic ?? false,
+      },
+      deps,
+    )
+
+    const budget = buildContext(
+      result.items.map((item) => ({
+        memoryId: item.memoryId,
+        kind: item.kind,
+        finalScore: item.scoreBreakdown?.final ?? item.confidence,
+        tokens: estimateTokens(item.content),
+        content: item.content,
+        sourceRefs: item.sourceRefs,
+      })),
+      maxTokens,
+    )
+
+    return {
+      injected: budget.selected.length > 0,
+      stage,
+      context: budget.selected.map((i) => i.content).join("\n\n"),
+      auditId: result.recallId,
+      degradedMode: result.degradedMode,
+      itemCount: budget.selected.length,
+      usedTokens: budget.usedTokens,
+      latencyMs: result.latencyMs,
+    }
+  } catch (error) {
+    // fail-open：召回失败不阻塞门禁/交接；错误信息进审计与返回值
+    return {
+      ...empty(),
+      stage,
+      skippedReason: "pipeline-error",
+      error: error instanceof Error ? error.message : String(error),
+    }
+  }
+}
+
+/** 供工具/文档展示的白名单（单一事实源来自 stage-words） */
+export { RECALL_STAGES }

package/templates/core/scripts/mcp-server/shared/memory/metrics/gate-writer.ts

@@ -0,0 +1,217 @@
+/*
+ * Gate → MetricSnapshot 幂等采证（Plan §3.1 方案 A1 / Spec §1 §GateMetric）
+ *
+ * 设计要点：
+ *  1. 与评分解耦：评分逻辑保持只读，采证在评分完成后单独提交（Review P0 #1 / Plan §2.1）；
+ *  2. 幂等键：sourceRef = `{gate}:{planKeyword}:{runId}`，配合表级唯一键
+ *     (repositoryRef, metricType, sourceRef) —— 同 runId 重放不产生重复快照；
+ *  3. fail-open：任何异常都不向上抛，返回 outcome="bypassed" + degradedReason，
+ *     由调用方保证评分照常返回（验收项「采证失败旁路」）；
+ *  4. 失败路径审计密度不低于成功路径（ADD-6）：buildGateCaptureDetail 对三种 outcome
+ *     返回同构字段集。
+ */
+import type { AddMetricSnapshotRow, TableDelegate } from "../../db-types.js"
+import { AddMetricSnapshotRowSchema, validatedDelegate } from "../../db-types.js"
+import { MemoryError } from "../domain/errors.js"
+import { createHash } from "node:crypto"
+
+export type GateKind = "check_dps" | "check_rahs"
+export type GateWriteOutcome = "written" | "skipped_duplicate" | "bypassed"
+
+/** 门禁指标类型字面量（Spec §10 契约登记表） */
+export const GATE_METRIC_TYPE = {
+  check_dps: "DPS_TOTAL",
+  check_rahs: "RAHS_TOTAL",
+  latency: "GATE_LATENCY_MS",
+} as const
+
+/** 采证耗时增量上限（ms）——验收项「工具响应耗时增量 ≤50ms」 */
+export const GATE_CAPTURE_TOLERANCE_MS = 50
+
+export interface GateMetricWriteInput {
+  gate: GateKind
+  planKeyword: string
+  runId: string
+  metricType?: string
+  score: number
+  repository: string
+  dimensionScores?: Record<string, number>
+  baseline?: number | null
+  unit?: string | null
+  specRef?: string | null
+  commitSha?: string | null
+}
+
+export interface GateMetricWriteResult {
+  outcome: GateWriteOutcome
+  sourceRef: string
+  metricId?: string
+  degradedReason?: string
+  elapsedMs: number
+}
+
+export interface GateWriterDeps {
+  /** 采证目标表；测试可注入内存实现 */
+  metricDb: Pick<TableDelegate<AddMetricSnapshotRow>, "findUnique" | "upsert">
+  /** 时钟注入（测试用），默认 Date.now */
+  now?: () => number
+}
+
+/**
+ * 幂等键构造。空值归一为 "-"，避免出现 `::` 与前缀碰撞。
+ */
+export function buildGateSourceRef(gate: GateKind, planKeyword: string, runId: string): string {
+  const norm = (v: string | undefined | null): string => {
+    const t = (v ?? "").trim()
+    return t.length > 0 ? t : "-"
+  }
+  return `${gate}:${norm(planKeyword)}:${norm(runId)}`
+}
+
+/**
+ * 由被评分产物的内容派生 runId。
+ *
+ * 语义：同一份文档重复跑同一门禁 → 同一幂等键 → 判定为重复采证（skipped_duplicate）；
+ * 文档内容变化 → 新幂等键 → 产生新的证据快照。这样「重放」不会因为时间戳不同而假性去重，
+ * 也不需要调用方额外传参（门禁工具入参契约保持不变）。
+ */
+export function deriveGateRunId(gate: GateKind, planKeyword: string, seed: string): string {
+  const digest = createHash("sha256")
+    .update(`${gate}|${planKeyword}|${seed}`)
+    .digest("hex")
+  return `auto-${digest.slice(0, 12)}`
+}
+
+/** 唯一键参数（与 prisma @@unique([repositoryRef, metricType, sourceRef]) 对应） */
+function uniqueWhere(repositoryRef: string, metricType: string, sourceRef: string) {
+  return { repositoryRef_metricType_sourceRef: { repositoryRef, metricType, sourceRef } }
+}
+
+function isUniqueViolation(error: unknown): boolean {
+  const code = (error as { code?: string } | null)?.code
+  return code === "P2002"
+}
+
+/**
+ * 写入一次门禁指标快照。**不抛异常**：失败返回 bypassed，由调用方继续返回评分。
+ */
+export async function writeGateMetric(
+  input: GateMetricWriteInput,
+  deps: GateWriterDeps,
+): Promise<GateMetricWriteResult> {
+  const now = deps.now ?? Date.now
+  const startedAt = now()
+  const metricType = input.metricType ?? GATE_METRIC_TYPE[input.gate]
+  const sourceRef = buildGateSourceRef(input.gate, input.planKeyword, input.runId)
+  const elapsed = () => Math.max(0, now() - startedAt)
+
+  try {
+    if (!input.repository || input.repository.trim().length === 0) {
+      throw new MemoryError("ERR_REPOSITORY_MISMATCH", "repositoryRef 为空，拒绝采证")
+    }
+    if (!Number.isFinite(input.score)) {
+      throw new MemoryError("ERR_INVARIANT", "score 非有限数值，拒绝采证")
+    }
+
+    const existing = await deps.metricDb.findUnique({
+      where: uniqueWhere(input.repository, metricType, sourceRef),
+    })
+    if (existing) {
+      // 同 runId 重放：既有快照是证据，不覆写
+      return { outcome: "skipped_duplicate", metricId: existing.id, sourceRef, elapsedMs: elapsed() }
+    }
+
+    const created = await deps.metricDb.upsert({
+      where: uniqueWhere(input.repository, metricType, sourceRef),
+      create: {
+        repositoryRef: input.repository,
+        metricType,
+        value: input.score,
+        baseline: input.baseline ?? null,
+        delta: input.baseline == null ? null : input.score - input.baseline,
+        unit: input.unit ?? null,
+        planKeyword: input.planKeyword || null,
+        specRef: input.specRef ?? null,
+        commitSha: input.commitSha ?? null,
+        sourceRef,
+        metadata: {
+          gate: input.gate,
+          runId: input.runId,
+          dimensionScores: input.dimensionScores ?? null,
+          capture: "gate-writer",
+        },
+        measuredAt: new Date(now()),
+      },
+      // 幂等：并发下由唯一键裁定，update 不改写既有证据
+      update: {},
+    })
+    return { outcome: "written", metricId: created.id, sourceRef, elapsedMs: elapsed() }
+  } catch (error) {
+    if (isUniqueViolation(error)) {
+      return { outcome: "skipped_duplicate", sourceRef, elapsedMs: elapsed() }
+    }
+    // fail-open：采证失败绝不阻塞门禁返回评分
+    return {
+      outcome: "bypassed",
+      sourceRef,
+      degradedReason: error instanceof Error ? error.message : String(error),
+      elapsedMs: elapsed(),
+    }
+  }
+}
+
+/**
+ * 审计明细（ADD-6：成功/去重/旁路三态返回同构字段集，失败路径不得更稀疏）。
+ */
+export function buildGateCaptureDetail(
+  input: GateMetricWriteInput,
+  result: GateMetricWriteResult,
+): Record<string, unknown> {
+  return {
+    gate: input.gate,
+    planKeyword: input.planKeyword,
+    runId: input.runId,
+    metricType: input.metricType ?? GATE_METRIC_TYPE[input.gate],
+    sourceRef: result.sourceRef,
+    outcome: result.outcome,
+    metricId: result.metricId ?? null,
+    score: input.score,
+    dimensionCount: input.dimensionScores ? Object.keys(input.dimensionScores).length : 0,
+    baseline: input.baseline ?? null,
+    degradedReason: result.degradedReason ?? null,
+    elapsedMs: result.elapsedMs,
+    overTolerance: result.elapsedMs > GATE_CAPTURE_TOLERANCE_MS,
+  }
+}
+
+/** 单行摘要：供 MCP 工具在响应末尾追加（三态均返回非空文本） */
+export function formatGateCaptureSummary(detail: Record<string, unknown>): string {
+  const bits = [
+    `结果: ${String(detail.outcome)}`,
+    `幂等键: ${String(detail.sourceRef)}`,
+    `耗时: ${String(detail.elapsedMs)}ms`,
+  ]
+  if (typeof detail.metricId === "string" && detail.metricId.length > 0) {
+    bits.push(`metricId: ${detail.metricId}`)
+  }
+  if (typeof detail.degradedReason === "string" && detail.degradedReason.length > 0) {
+    bits.push(`旁路原因: ${detail.degradedReason}（评分不受影响）`)
+  }
+  if (detail.overTolerance === true) {
+    bits.push(`⚠️ 超出 ${GATE_CAPTURE_TOLERANCE_MS}ms 容差`)
+  }
+  return bits.join(" | ")
+}
+
+/**
+ * 便捷装配：把 MCP 工具侧的 prisma delegate 包装为通过行校验的采证依赖。
+ */
+export function createGateWriterDeps(rawMetricDelegate: unknown): GateWriterDeps {
+  return {
+    metricDb: validatedDelegate<AddMetricSnapshotRow>(
+      rawMetricDelegate,
+      AddMetricSnapshotRowSchema,
+      "AddMetricSnapshot",
+    ),
+  }
+}

package/templates/core/scripts/mcp-server/shared/memory/metrics/stage-words.ts

@@ -0,0 +1,69 @@
+/*
+ * 阶段词识别（Plan §9.1 / Spec §2 §DeterministicRecall）
+ *
+ * 本模块是**纯函数**：零运行时依赖、零 IO、零 DB。
+ * 存在意义：governance Hook（同步 spawn、≤200ms 预算、无 DB 访问权限）需要识别
+ * 「现在处于哪个 ADD 阶段」，以便产出确定性召回提示；而真正的召回落点在有 DB 的
+ * MCP 工具侧（gate-recall.ts）。两者共用同一份阶段白名单，避免 Hook 与工具侧漂移。
+ */
+
+export const RECALL_STAGES = ["plan-start", "spec-start", "dps", "rahs", "handoff"] as const
+export type RecallStage = (typeof RECALL_STAGES)[number]
+
+export function isRecallStage(value: string): value is RecallStage {
+  return (RECALL_STAGES as readonly string[]).includes(value)
+}
+
+export const STAGE_LABEL: Record<RecallStage, string> = {
+  "plan-start": "Plan 起草",
+  "spec-start": "Spec 起草",
+  dps: "DPS 门禁",
+  rahs: "RAHS 门禁",
+  handoff: "Handoff 交接",
+}
+
+/**
+ * 阶段词模式。按特异性从高到低排列——先命中者为准（handoff/rahs/dps 比 plan 更具体，
+ * 避免「交接 plan」被判成 plan-start）。
+ */
+const STAGE_PATTERNS: ReadonlyArray<{ stage: RecallStage; re: RegExp }> = [
+  { stage: "handoff", re: /handoff|交接(手册|文档|说明)?|交接给/i },
+  { stage: "rahs", re: /rahs|注意力漂移|执行健康度/i },
+  { stage: "dps", re: /dps|文档质量闸门|质量闸门|门禁(评分|检查)?/i },
+  { stage: "spec-start", re: /(生成|写|新建|起草|补)\s*(spec|规格|三元组)|specs?\s*三元组|WHEN-?THEN/i },
+  { stage: "plan-start", re: /(生成|写|新建|起草|补)\s*(plan|计划|方案)|plan\s*阶段|规划阶段/i },
+]
+
+/** 识别提示词所属的 ADD 阶段；无法判定返回 null（不猜测） */
+export function detectRecallStage(prompt: string): RecallStage | null {
+  if (!prompt) return null
+  for (const { stage, re } of STAGE_PATTERNS) {
+    if (re.test(prompt)) return stage
+  }
+  return null
+}
+
+export type RecallModeLike = "off" | "shadow" | "inject"
+
+/**
+ * 阶段召回提示文本（Hook 侧输出）。
+ * - off：返回 null（不提示、不召回）
+ * - shadow：提示可显式调用，并说明 Hook 不注入
+ * - inject：提示调用后将注入上下文
+ */
+export function buildStageRecallHint(
+  stage: RecallStage,
+  mode: RecallModeLike,
+): string | null {
+  if (mode === "off") return null
+  const label = STAGE_LABEL[stage]
+  const tail =
+    mode === "shadow"
+      ? "（当前 shadow 模式：Hook 不注入上下文，召回结果需显式消费）"
+      : "（当前 inject 模式：调用后上下文将被注入）"
+  return (
+    `[Memory] 检测到${label}阶段 → 建议调用 ` +
+    `recall_memory({ stage: "${stage}", query: <本阶段意图>, planKeyword: <Plan 关键词> }) ` +
+    `获取受治理的历史上下文（含来源与评分）。${tail}\n`
+  )
+}