Knowledge Groom

---
name: knowledge-groom
description: >
  昇腾知识库的周期性维护引擎。批处理 postmortems/inbox/ 待审队列（预分诊 new/variant/covered 三分类），
  结构化升格到 Tier 2、校验 references 完整性、检测值重复、重算 confidence_score、
  软退休过期 case、重建生成索引；并行维护先验知识层（references/）——
  审核 references/ 的 draft 草稿、校验引用、失效降级信号、引用发现建议。建议每周运行。
  产出**变更摘要 + 待审项**交领域 owner 审；提交由 owner 自己来（不自动开 PR）。
disable-model-invocation: true
---

# Knowledge Groom

> **本地执行说明**：本 skill 标记 `disable-model-invocation`（防 agent 自发启动批量改库）——skill 工具加载会报 "not available for model invocation"，这是预期。用户明确要求 groom 时，agent 直接 `read` 本文件手动遵循流程即可，流程完整性不受影响；或用户输入 `/skill:knowledge-groom` 直接触发。

体系的演化引擎。不加控制的增长会摧毁检索效率——这个 skill 是知识库的"免疫系统 + 清道夫"。

## 触发

手动运行，建议每周一次；连续四周无新 postmortem 时可改双周——**这是人的节奏判断，不是脚本行为**（本仓没有 cadence 实现，别把它读成自动调度）。

**触发场景区分**：
- **人工使用场景（默认周批）**：人通过 diagnose/to-postmortem 等沉淀的草稿——攒 inbox
  到周批统一处理，人审 ~30s/条后升格提 PR（人的注意力是稀缺资源，批处理是预算分配，
  原则九）；
- **自动化 ingest 场景（可直接升格，不等周批）**：issue-ingest/S2 补 case 等自动化
  链路产出的草稿——verification 链完整（upstream-fix-merged 等外部验证）+ agent 已过
  语义校验 + pre-triage 判别完成，质量前提与人工场景不同，**产出后可直接走本流程升格
  入库提 PR**（同 2026-W36 round2 全自动轮 22 case 升格先例）。前提：owner 已预授权该
  自动化源（issue-ingest 链路本身即 owner 配置的持续管道，其产出视为预授权）。草稿头
  注释带完整 pre-triage/verification 证据 → 复核确认而非重判。

## groom 成本预算与脚本先行（token 预算纪律：确定性环节脚本先行、agent 只读摘要）

目标：单次 groom（含 inbox 段与 references 维护段）token 降至可读摘要量级（<30K），
功能不缺失。纪律：

1. **确定性环节一律跑脚本、只读输出摘要，不读全量原文**：
   - 引用完整性/悬挂/role：`scripts/verify_references.py --check`（输出进摘要）；
   - 索引/容量：`scripts/index_counts.py`（条数与逐格容量，现算）+ `scripts/capacity_health.py`（溢出/健康）输出进摘要；
   - 引用可观测性：`scripts/trace_metrics.py`（R6）；tag 聚类：读 `_index` tags 聚合（R8，零 token 机械）；
   - reference 规模/退化（R7）：按文件数/metrics 判断，不逐文件读。
2. **全量重扫默认关闭，改信号触发**：
   - R3（引用发现，需扫 case 正文）：**默认不跑**——仅当本轮 新升格 case ≥5 且 owner 要求时执行
     （R3 本就是可选项；防"每周全量扫 128 case 正文"常设成本）；
   - confidence 重算（步骤 4）：只对"结算/升格有变化的 case"重算（3.5/3.5b 输出 diff 涉及 + 新升格）；
     无变化跳过并说明；
   - references 维护段（R1/R5/R5.5/R6）：仅当 references/ 本轮有变更（新词条/修订/失效信号）才跑；
     无变更 → 摘要一句"references 无变更，跳过维护段"。
3. **预分诊比对不全文重读**：draft 与现有 case 比对用**命中 (namespace × category) 的索引分片行**
   `knowledge/_index/<ns>__<category>.list`（一行一条 case；category 未定回退 `<ns>.list`；不读全库总表）的
   title/tags/symptoms 摘要/score 定位
   候选 → 只读 1-2 个最高分候选全文核对；draft 头注释已有产出时分诊建议 → 复核证据成立即可，不重判。
4. 变更摘要 = 各脚本输出摘要 + agent 判断行；审计链在 EV 卡/PR，不靠每次重读全库。

## 流程（一次 groom 产出一个变更摘要）

1. **intake 队列处理（升格的前置）**：处理 `postmortems/inbox/`（`/skill:to-postmortem` / `/skill:issue-ingest` 的产出都落这里；**先解析一次**：`python3 scripts/shared_dir.py inbox` 给出主检出的绝对路径——草稿是锚在主检出的共享队列，在 worktree 里用相对 `postmortems/inbox/` 会读成一个空队列）：
   - **节律**：单仓集中可周批；**分布式（成员本地 inbox，远程仓不存）在提交主仓时处理**——产出时已做 pre-triage（见下），groom 复核确认而非重判；
   - 逐条**预分诊**（agent 判断，给证据；当前不引入 embedding，论证见 docs/adr/0002——可选论证层）：`new_pattern` / `variant_of:<case-id>` / `covered_by:<case-id>` + 置信度。比对对象：命中 namespace + `common/` 的现有 case——用**命中 (namespace × category) 的读侧视图** `knowledge/_index/<ns>__<category>.list` 行（一行一条：title/tags/symptoms 首条/score 等）按 symptoms/tags 定位候选，
   只读 1-2 个最高分候选全文核对 root_cause/fix（M5 成本预算 #3，不全文重读全库）。**draft 头注释已带 to-postmortem/issue-ingest 产出的分诊建议 → 复核证据是否成立，不重判**（建议与决定分离：判断在产出时做，groom 是审核者）；
   **先判后看（顺序纪律，改不了的自觉就别指望）**：读候选之前，先从草稿本身写出自己的判断——症状签名（错误码/关键日志行/数值阈值）、根因假设、修复族方向。看候选是**取证**（我这条假设能否被候选解释，还是只是"看起来像"）。先看候选再判断，判的是**像不像**而不是**对不对**：候选一旦在眼前，语义相近就会把判断拉过去（尤其是措辞相似但根因不同的 draft）。判断行写进批审清单：先写自己的判断，再写与候选的对照结论；两者不一致时**以证据为准**，别用"候选里有类似的"当理由；
   - 产出**批审清单**交 owner 处理（像清 PR inbox，~30 秒/条）：
     - `covered_by` → 建议关闭升格；postmortem 转正 `postmortems/YYYY-QN/`（Tier 3 语料，**不是丢弃**）
     - `variant_of` → 建议并入已有 case（扩 compat 区间、补 symptoms）；若要动 `expected`/`fix_on_mismatch` 按高风险变更走双签
     - `new_pattern` → 结构化 + 语义校验 → **过升格闸门** → 升格 `knowledge/<ns>/`。校验失败标 `needs-structurer-review`，语义不明标 `needs-human-review`
     - **升格闸门（按来源分，不是一刀切）**：跑 `python3 scripts/verify_case_draft.py --gate <草稿路径>`。
       - **外部来源（issue-ingest / reference-ingest 管道、无 `source_session`）→ 跳过闸门**。这类 case 的"闭环"是维护者结论 / fix PR 已经替它确认过的（其 `verification` 档位即证明），现场没有 session 可闭环；对它们要求现场闭环等于把知识注入的主通道堵死。
       - **自诊断来源（带 `source_session`）→ 默认须反馈闭环**：来源 trace 的 `feedback.outcome: resolved`（即 fix 被应用且问题消失）才升格。没解决的不必进知识库，留在本地即可。
       - **例外（未闭环但已有强外部证据）**：`verification` ∈ {`upstream-fix-merged`、`upstream-maintainer-confirmed`、`upstream-official-doc`、`engineer-report`} → **需 owner 双签**方可升格。理由：新根因当天发现、修复尚未应用是知识增长的主路径，不能一律挡掉；但这档必须是**外部验证**，不接受 `investigation` 纯推断。
       - `verification: investigation` 且未闭环 → **拦下**，提示三条出路（等闭环 / 补强外部证据 / 走双签例外）。
   - **转正后回写来源 trace 的沉淀状态（闭环，动作发生时写）**：每条被 accept 的草稿，若来源是诊断 trace（头注释记了 `traces/<session_id>.yaml`），转正落位后**回写该 trace 的 `sedimented.state`**——`new_pattern`/`variant_of` 升格 Tier 2 → `{state: knowledge, caseId: <case-id>}`；`covered_by` 仅 postmortem 转正 → `{state: archived, caseId: <case-id>}`。教训：曾因 groom 转正后未回写，trace 停留 `submitted`，诊断面板"沉淀漏斗"显示 4 沉淀 → 0 转正（数据滞后于实际入库）——零推断纪律同样约束转正侧：**转正是动作，发生时必须写**。
   - inbox 停留 >2 周的条目在摘要里标红（队列不是档案）
   - **建议与决定分离**：预分诊只排序注意力，accept / adjust / reject 由人
1.5. **case 分类校验（三分类强制，废弃 other）**：审核/升格 case 时校验 `category` ∈ {interrupt, precision, performance}——**不存在 other**。发现 other 的 case → 重新分类（按症状性质归入三分类：启动失败/崩溃/资源→interrupt，输出错误/乱码/数值异常→precision，吞吐/延迟→performance）；分不进去 → 标 `needs-human-review`，由 owner 定夺，不静默保留 other。reason：other 是分类残余，实践表明残余全部可归入三分类（曾重分类 5 条全部归入，无一条真属"其他"）；保留 other 会让路由层永远无法到达这些 case（triage-tree 无 other 分支）。
2. **引用完整性校验**:扫所有 case 的 `references`,检查指向真实存在的文件和锚点。悬挂引用进变更摘要（自演化系统的“坏账”，不校验会静默累积）。
3. **值重复检测**：框架 case 的 `expected`/`fix_on_mismatch` 是否硬编码了 `common/` 权威记录拥有的值？是 → 标 must-fix，要求改成引用。
3.5. **反馈结算（confidence 输入，先于重算）**：跑 `python3 scripts/settle_trace_feedback.py`（游标默认落 gitignored 的共享运行时件 `.settle-state.json`，故本步**不进 git、也不该由单次诊断自己开 PR**——这里是 confidence 变更入库的**唯一入口**，一次覆盖当期全部 case；`--state` 仅用于显式指定/测试） 把 traces/ 里的 `feedback` 事件确定性结算进 case 的 `confidence.hits`/`misdiagnoses`/`last_hit`（脚本默认 dry-run，确认 diff 后 `--apply`）。**幂等口径（按 session 逐事件记已落地）**：补一条新 feedback 只结算新增的那条，**不重放**已落地事件（重放会虚增）；事件未落地（case 还没落 knowledge/、或写回后复核没过）**保持待结算**并在下次重跑时补上，游标不越过它前进；事件序列被改写（非追加）时脚本拒绝结算并告警，不猜。**只读复核**：`python3 scripts/settle_trace_feedback.py --audit` 交叉核对"游标说已结算"与"case 里看得见痕迹"，报出「已结算但无效果」的条目（这是发现证据静默丢失的唯一手段，出条目就删该 session 的游标条目后重跑）。**结算规则（owner 设计决策）**：只有 `feedback.resolved` 才 `hits += 1`——命中（hit 事件）是系统检索行为，不代表 case 有效；可信反馈（用户确认"诊断解决了问题"）才是置信度信号。`not_resolved`/`partial` → `misdiagnoses += 1`。结算产出的 confidence 变更走 knowledge_modification PR（脚本本身不改 git）。**无 feedback 事件时如实跳过**（反馈闭环未发生=现状，不编造）。

3.5b. **S2 验证结算（validation_record 输入，与 3.5 并行）**：跑 `python3 scripts/settle_s2_feedback.py`（游标与 3.5 同一份 gitignored 共享件） 把 `.s2-replay/*.result.yaml` 的 S2 replay 结果确定性结算进 case 的 `validation_record`（幂等同 3.5；默认 dry-run，确认 diff 后 `--apply`）。**语义（selfevolve-loop 重构）**：S2 对照的是外部 ground truth（issue resolution / 维护者 fix PR / committer 确认），结果即 feedback——只是反馈对象是"内容被外部验证"（`consistent`/`self_consistent`），与 confidence 的 S1 现场 resolve 口径**分开、不混算**（resolve 仍只认 S1；S2 另立验证记录，不再被降格为无落点的旁证）。`inconsistent`（命中 case 但结论与 resolution 不符）是**复审信号**——按脚本输出候选清单走 case 复审（内容错/过时/判别力不足 → 改 case 或 rejected，走 knowledge_modification PR）。排序提示：`validation_record.consistent > 0` 的 case 在同等 score 下优先（内容被外部验证）。**无 result 文件时如实跳过**。
4. **置信度重算（M5：只对有变化的 case）**：从 `hits`/`misdiagnoses`/`last_hit` 重算 `confidence.score`（按时间衰减）——范围 = 3.5/3.5b 结算 diff 涉及的 case + 本轮新升格 case；无变化不重算（不每周全量扫 128 case 的 hits/mis 字段）。**新升格的 case 初始 score 不设 0**——由 `verification`（来源验证强度）与 `confidence`（调查质量）联合决定（Beta 先验超参 $(\alpha,\beta)$ 的实例化；参数治理见 roadmap 待定池，理论推导见 docs/spec/design-theory.md §4.1——该文档为可选论证层，本参数为执行值）：

   | verification \ confidence | high | medium | low |
   |---|---|---|---|
   | `upstream-fix-merged`（fix PR 合入） | **0.75** | 0.6 | 0.5 |
   | `upstream-official-doc`（上游官方案例/指南文档，含验证结论） | 0.7 | 0.55 | 0.45 |
   | `upstream-maintainer-confirmed` | 0.65 | 0.5 | 0.4 |
   | `engineer-report`（现场验证） | 0.85 | 0.7 | 0.6 |
   | `investigation` / 未填 | 0.6 | 0.3 | 0.1 |

   **语义（分层，防误读）**：verification 提升的是"内容正确性"先验——fix PR 合入的 case 根因/修复被外部验证过，**内容可默认高置信**，故即使 confidence(调查判断)=low 也有 0.5 起点（内容对但调查表述简略，仍可信）；`engineer-report` 同时证明现场有效，故最高。**score 仍 calibrate 现场解决率**——verification 只给冷启动先验，不替代 S1 现场校准（fix 在你环境是否适用仍需回报确认；无 S1 时 score 停在该先验并如实标注"内容已验证、现场待确认"）。score=0 意味着新 case 永远排候选最后，对已验证的高质量 case 不合理。
5. **软退休**：区分两种"未命中"——
   - **cold**（从未被 quickly_check 选中）→ **不退**（正确但罕见的 case 占索引成本极低，误删是静默损失）
   - **tried-and-failed**（被选中但近 12 周未解决）且 `score` 低 → 移入 `_archive/`
   - `compat` 版本过期 → 移入 `_archive/`（与命中无关）
   - 检查 `_archive/` 中 case 是否因新 `compat` 区间该复活（2.7 退休、2.8 恢复）
6. **容量治理**：被治理的量是**查一次问题要读进来多少字**（实读 token），不按条数——条数只作观察值记在容量表里。执行参数：**评估线 8000**（到线→评估能否再省：先看行宽/字段，再看平台轴切分）、**硬线 20000**（= 常驻指令面的量级→强制处理，先瘦身再评估拆分）；**两条读取路径各判一条线**（类视图与 ns 兜底视图；后者 vllm-ascend 已超硬线）；**先验层与阶段二候选全文只量不判**（先验层看检索残量：两刀切完剩多少行，随词条数线性涨）。健康指标阈值：候选溢出率 >20%、同根因重复率连续两轮上升、维护时长 >30 分钟/周。每次 groom 附**容量表**：各格子的条数与读入成本 + 一次诊断的四个读入分项（`python3 scripts/index_read_cost.py`）+ 三项健康指标。**不预拆目录**：拆分是超硬线之后才评估的选项，不是到线就做的动作（拆分轴与实测代价见 docs/adr/0004 与 roadmap 的「格子容量治理」行）。**越界清单与行动走 `python3 scripts/metrics_health.py`**（判据数值在 `metrics/gates.yaml`，与本节一致）——别只看 `_index.yaml` 头注的数字：头注只列数，不判越界，也不告诉你这条闸门已经越了多久。
7. **同 namespace 合并建议**：相似 case 对自动提示。
8. **索引维护（收尾必做）**：所有 KB 变更（升格/合并/退休/改 confidence）完成后，运行 `python3 scripts/build_index.py`，把分片与总表一起提交。门是**覆盖检查**（每条 case 的索引行都在、与内容对得上）：`--check` 报问题 = 变更不完整，或索引行被手改过。要归一化（顺序/注释回到生成器口径）就重跑一次；`--canonical` 是那个自检（不作门）。软退休的 case 移 `_archive/` 后自动从活跃索引消失。

## reference 维护（先验知识层——与 case 流程并行；M5：本轮 references 无变更则整段跳过并在摘要说明）

先验知识层（`references/`）是独立资产，维护动作与 case 平行：

**R1. reference 词条审核（修订 3：to-reference 产出即 active，PR review 即审核闸门——合入即生效，无常规 draft→active 翻牌流程）**：
- 新词条不再由 groom 翻牌：to-reference 产出 `status: active` 随 PR 提交，深审门槛（case-derived methodology ≥3 条 case 引用）由 PR CI 强制把关——产出时不达标直接红，不会以 active 合入未达门槛词条；
- groom 只处理**遗留 draft**（修订 3 前历史产出）：逐条审 accept → 改 `active` / adjust / reject / defer；停留 >2 周标红提醒（队列不是档案）；无遗留则跳过；
- **深审门槛**：case-derived + methodology 词条需 ≥3 条 case 引用（派生计数，`verify_references.py` 强制）才可 `active`——对遗留 draft 审核与 CI 一致。

**R2. 引用完整性校验**：case 的 `ref_knowledge.ref` 必须真实存在于 `references/`（`verify_references.py` 已强校验悬挂引用与非法 role——groom 把结果带进变更摘要，不重复计算）。

**R3. 引用发现（可选建议，不强制；M5 默认不跑，仅新升格 ≥5 且 owner 要求时）**：扫描 case 的 `diagnosis`/`fix` 内容，发现**隐式依赖**某 active reference（如 fix 提到"HCCL_BUFFSIZE 需重启生效"而该事实是独立词条）但未填 `ref_knowledge` → 变更摘要建议"该 case 可补 ref_knowledge"，由 owner 决定。**大多数 case 是自包含闭环（quickly_check/diagnosis/fix 都在体内），不需要连**——只有依赖命令副作用 / 平台硬事实 / 错误码含义等独立先验事实的少数 case 值得连；强制连接只会增加维护负担和脆弱引用。

**R4. 失效与降级信号**：见下方信号表新增行。

**R5. 校验**：改动 reference 后运行 `python3 scripts/verify_references.py --check`（与 build_index 并列，CI 同样强制）。

**R5.5. 修订中的 reference（内容修订机制）**：`pending-review` / 遗留 `draft` 词条在变更摘要里列出并标注**修订中/待修订**，提示 owner 安排：
- 有修订 PR 在走 → 摘要注明"修订中"（status 保持降级态，diagnose 不加载）；
- 无修订 PR 但已标降级 → 提示"待修订"，owner 决定：小修直接改 YAML + PR，大修用 `/skill:to-reference --update <ref-id>`；
- 修订走 PR 时按 **kb/high-risk** 处理（改 active 内容 = 修改已生效知识，双签）。

**R6. reference 可观测性回写**：跑 `python3 scripts/trace_metrics.py` 提取 reference 指标（hits / 引用后 resolve 率 / 平台分布），把结果带进变更摘要：
- **有数据才回写**：某 ref 被引用（hits ≥1）→ 更新其 `hits`/`last_hit` 字段（trace 数据积累后才有）；引用后 resolve 率异常低 → 触发降级信号（见信号表）；
- **无数据如实显示**：reference 刚建立时 trace 无 `reference_lookup` 事件 → 如实报 0，不编造指标（诚实退化）。

**R7. reference 索引触发检测（修订 2 渐进式）**：每次 groom 检查——
- `references/` 下文件数 >50，**或** metrics 显示 reference 检索退化（漏检增多 / 平台匹配耗时长）；
- 达到 → 变更摘要**建议**按层建索引——背景类走 `scripts/build_ref_summary_index.py`（生成 `references/_summary-index.yaml`），流程类走 `scripts/build_procedure_index.py`（生成 `references/_procedure-index.yaml`）；两层都已有生成物与 `--check`（CI 强制），**case 层 `build_index.py` 与之同构**。**建议不自动改生成物**（生成物只由脚本写，建议与决定分离）；未达到 → 不提及（目录 + grep 足够，不为不存在的规模购置基础设施）。

**R8. case 共性提炼候选（case-derived reference 触发信号）**：跑 `python3 scripts/tag_hygiene.py`（机械聚类，零 token 手扫）——**同 tag 的 case ≥3 条且 ≥3 条未被 reference 收录** → 变更摘要列出该组（tag + case id），**建议**走 `/skill:to-reference --ingest-cases "[id1, id2...]"` 提炼共性（methodology / error-code 表追加）——只建议不自动提炼（建议与决定分离；同 tag 是弱信号，是否提炼由 owner 定）。

- **按 tag 类别过滤**：脚本标注每组为「模型名 / 环境·特性 / 机制」。**只有「机制」族值得提炼**——模型名族（glm5/qwen3.5/deepseek-v4…）同模型 ≠ 同根因，提炼出来是"该模型排障清单"而非独立于事故的先验知识；环境·特性族（mtp/spec-decode/w8a8/310p/cudagraph）是"用了什么"而非"哪里坏了"，且多数已被现有方法论覆盖（如 `mtp` 归 `ascend-vllm-spec-decode-mtp-triage`）。摘要里模型名/特性族只列一行计数，不进候选。
- **先看形态**：组内根因**分散**（同现象不同根因）→ 适合提炼 methodology（给分流路径）；根因**收敛**（同根因）→ 不走提炼，走 case 合并 / `variant_of`（提炼只会得到一条 case 的复述）。
- **已覆盖排除由脚本做**：`references/**` 的 `sources[].cases` 与 `content.*.source_cases` 中的 case id 自动剔除——已被 reference 收录的 case 不再重复建议（教训：glm5 组 9 条中 6 条已在 `glm-quantized-startup-triage`，原 R8 仍重复建议）。
- **tag 归一前置**：脚本的 `--normalize` 负责删除与字段重复的 tag（category/namespace 名）、合并同义/拼写变体（`startup`/`startup-fail`/`startup-crash`→`startup-failure` 等，映射在脚本内）。tag 一乱 R8 就给噪声（曾实测：未归一前 tag 达 507 个，其中 ≥3 次者 70 个、聚类候选 35 组，还含 `precision`/`vllm-ascend` 这类零信息组）；**先修信号源再挑候选**。

理由：共性识别靠人工不可持续（曾从 42 条 case 里人工才发现 MoE 通信算子族，且仅 4 条同 tag）；tag 聚类是零 token 的机械信号，先把候选端到人眼前。

**R10. 流程留出检验（methodology 的"方法"地位核验）**：跑 `python3 scripts/flow_pool.py --flow-coverage`（该脚本随 `eval/flow/` 评测池引入；**脚本不存在时跳过并在摘要如实标注"评测池未就绪"**，不臆造覆盖数据）——按每条 methodology 的 `sources[].cases` 把评测池样本分成「收录（该词条的来源 case，train-on-test）」与「未收录（泛化证据）」两列：
- **无未收录样本通过记录的流程，其"方法"地位未验证** → 变更摘要建议：或补判据（把案例指纹改写成可对新变体执行的阈值/分支），或摘掉 procedure 绑定（`skills/diagnose/references/procedure-gates.yaml` 的 selector 不再选它）；
- 第三轮盲测的判据：给正确流程后，**收录样本 2/2 改善、未收录样本 0/5 改善**且 2 次被分支判别误导——即"能对上自己收录的 case"不等于"是方法"；
- 与 R8（case 共性提炼候选）配对：R8 决定"要不要提炼"，R10 决定"提炼出来的算不算方法"。
- 无样本覆盖对应流程时如实显示"无数据"，不编造（诚实退化）。

**R9. fixture 候选语义预核（agent 预核 → 人确认，A 的语义侧）**：跑 `python3 scripts/replay_trace.py --emit-fixtures` 产出 fixture 候选（`_candidate: true`，期望=实际命中 case，输入=多轮 user 原文折叠，已按覆盖去重）。**对每个候选做三项语义判断，填 `agent_review` 字段**（建议与决定分离——意见供人核，不替代人）：
- `expectation`：核对命中 case 的 `root_cause`/`fix` 与该 trace 的证据是否一致——`trustworthy`（证据一致，可信）/ `uncertain`（证据不足，需人重点核）/ `misdiagnosed`（命中 case 与证据矛盾，**建议不入 fixture**，并触发误诊归因）；
- `input_sufficient`：`true` / `false`——输入是否含判别信号（版本/错误码/配置），缺什么在 `redaction_notes` 旁补一句；
- `redaction_notes`：检查输入原文是否含客户敏感信息（内网 IP/路径/账号），含则标注需脱敏。
预核意见随候选交 owner，owner 确认后移除 `_candidate` 与 `agent_review` 字段入库 `eval/golden/`；`misdiagnosed` 的候选转误诊归因流程（trace 归因→case 错改库/执行错改 skill），不入 fixture。理由：脚本（确定性）只能保证结构正确，期望正确性与输入充分性是语义判断——agent 预核把人的核对负担从"从零核"降到"对齐意见判断"，与 E1（agent 自起草候选 case）同构。

## 变更摘要里的高风险变更标记（强制深审，不走 30 秒快通道）

- 新建 `common/` 权威记录
- 改 `expected` 值
- 改 `fix_on_mismatch`
- 改 `compat` 区间
- `confidence.score` 被手动覆盖

高风险变更要求两个 owner 签字（领域 owner + 体系维护人）。变更在 session 内**随机排序**审，对抗疲劳——一个 session 审 30 条变更，第 30 条得到的 scrutiny 远少于第 1 条，随机化缓解这个偏差。git 落地：变更走 PR 并打 `kb/high-risk` 标签，`CODEOWNERS` 双组路径强制对应 owner 审批（owner 未定前用 `CODEOWNERS.example` 占位，机制先跑；流程细节见 docs/guide/git-workflow.md——可选论证层）。

## 复核注意力的排序：按"对本改动声明了限制"排，不按新旧排

批审清单与变更摘要的复核顺序有一条落点：**把注意力放在"对本次正在改的那一面声明了限制"的条目上**，而不是放在"看起来旧"的条目上。

- **"这条 last_verified 过期了"不是有效的分派信号**：标出陈旧只让人知道它旧，不产生"必须去看"的动作——实测里，读起来已经定论的条目被复核的概率显著更低，而一旦它的来源被取代，基于它的判断会一致地错下去（错得还很有信心）。
- **有效的是内容型规则**：本改动触及哪一面（某 case 的 `compat` 区间 / `expected` 阈值 / `fix_on_mismatch` / 某 reference 的命令副作用或数值上限），就把**对该面声明了阈值、区间或限制**的条目排在前面复核——它们与改动直接冲突或直接支持，是真正会改变结论的那些。同 namespace 同 category 的条目优先于全库扫描；无此类条目的改动不进这条排序（不为排序而排序）。
- **落到哪个动作**：groom 的批审清单里，把这类条目单列一段（"本次改动面上声明了限制的条目"），排在常规清单之前；改 `compat`/`expected`/`fix_on_mismatch` 时，先把这些条目核完再签字（它们是高风险变更的双签依据）。
- 强度如实标注：这是**判断性规范**（哪些条目"声明了限制"要人判断），不进 CI；它约束的是复核顺序，不改变任何闸门的硬度。

## 信号 → 动作（演化信号表）

| 信号 | 动作 |
|---|---|
| 单 namespace 超 30 条 | 给拆分建议（首选 category 轴） |
| 两个框架 namespace 各有条 case 指向同 root cause | 在 `common/` 建权威记录，框架层加 `references` |
| Tier 2 未命中率 > 60% 持续两周 | **先看路由准确率**（见 docs/guide/metrics.md）：路由准确率低→改 triage-tree；路由准但未命中→加 case |
| 某 case `score` 高且命中频繁 | 进候选优先验证队列 |
| 某 case `score` 低仍被加载 | 标待复审；命中一次失败即转人工 |
| 某案例 `needs-structurer-review` 超 14 天 | 提醒领域 owner |
| inbox 条目停留 >2 周 | 变更摘要标红，提醒 owner（队列不是档案） |
| 某格子阶段一实读超评估线（8000 tok） | 评估能否再省：先看行宽/字段，再看要不要按平台轴切开 |
| 某格子实读超硬线（20000 tok，≈常驻指令面量级） | 强制处理：先瘦身，再评估平台轴切分（不预拆目录） |
| `references/` 有遗留 draft 草稿 | 审核 R1（修订 3 前历史产出）：accept 改 active / adjust / reject；case-derived methodology 未达 ≥3 引用禁止 active；新产出走 to-reference 即 active + PR 合入，不再产生新 draft |
| 某 reference `last_verified` 超 90 天未刷新 | 标 `needs-review`，owner 季度审 |
| case-derived methodology 被引用数 < 3（派生计数） | 不允许 active（verify_references 强制；已 active 的降 draft） |
| 工程师反馈某 reference 引用后诊断失败（trace `outcome_after_use` 恶化） | methodology → `draft` + 禁用 30 天；普通 → `pending-review` |
| 某 case 的 `diagnosis`/`fix` 隐式依赖 active reference 但未填 `ref_knowledge` | **建议**补 ref_knowledge（R3，可选——case 不强制连 reference，owner 决定） |
| 某 reference sources 链接失效（spot-check 发现） | 立即标 `pending-review` |
| 某 `tool` 词条全文读入 > 8K token（初始阈值，字节数/3.4）／`content.commands` key > 8／同文件内条目 `last_verified` 分化 > 90 天 | **split 建议**：拆成多个用途面条目（判据见 `references/_types.yaml` 的 tool 段注释），人确认后执行，不自动拆 |
| 两个 `tool` 词条在 ≥5 个 trace 里同 session 共现 `reference_lookup`（R6 数据）且 `sources[].url` 同源 | **merge 建议**：合并为一个用途面条目（子命令并入 `content.commands`），人确认 |

## 收尾 evolve-check（伴随演进评估，默认执行）

**先落执行记录**（evolve-check 读它作现场，不靠 agent 记忆）：
`python3 scripts/log_skill_exec.py --skill knowledge-groom --products "<升格 case id(knowledge),...>" --reason "<一句话：批审 N 条 / 升格 M 条 / 退休 K 条>" --source knowledge-groom --tokens <估算>`

批审产出、出变更摘要前，执行一次伴随演进评估（`read skills/evolve-check/SKILL.md`
遵循）：本轮暴露覆盖缺口（T2）、容量格子压线/健康指标恶化（T6）、reference 家族需扩
（T5）、或批审环节有重复手动动作与流程摩擦（T3/T4）时，**agent 自动产 idea 卡并自行验证
执行**（ev_proposal 产卡 → 验证 → 进攒批）；无信号则摘要加一行"evolve-check：无演进信号"。
这是流程默认收尾，**不需要用户另说"改进系统"**。

> 为什么 groom 也要挂：groom 是**批量改动知识库的收尾动作**（升格/退休/改 confidence），
> 一轮 groom 天然产生"同族沉淀是否达归纳阈值""格子是否压线""哪条 case 反复被复测"这类
> 演进信号——它不挂收尾，这批信号就只存在于 agent 记忆里（此前 groom 从未落过 exec-log、
> 也没有收尾协议，`docs/mechanism/run.md` 的"已落地含 groom"曾是纸面承诺）。

## v2 职责（路线图，v1 不做）

8. **结构挖掘**：挖 trace 语料，报告低判别力 `quickly_check`、噪声 triage 分支、高验证耗时 case。让库学结构，不只 bump 分数。
9. **trusted auto-promotion 审计**：近重复 + quickly_check 通过 + 连续 N 次兄弟命中未误诊的新 case 可 auto-promote，标 `auto_promoted: true`，进月度抽审。