cann-workbench 0.0.0-stage → 0.0.2-alpha

package/skills/asc-tools/tool-ops-tune/docs//347/224/250/344/276/213/346/236/204/345/273/272.md

@@ -0,0 +1,730 @@
+# 算子调优 AGENT 用例构建（评测体系设计）
+
+> **文档定位**：OpsTune 调优 Agent 的用例（评测）体系设计——把「性能用例怎么分层构建、
+> evals 怎么写、端到端怎么断言、CANNBench L1-L4 怎么复用、代码合入怎么自动触发执行」
+> 五个问题一次讲清。规划文档中的 U2/U3 在本文正式化，并前置补齐 U0/U1 两层。
+>
+> 版本：V1.3 ｜ 日期：2026-10-27 ｜ 状态：设计定稿（U1 现状 38/38 全绿：判定 E1-E26 + 门禁脚本 S1-S12；U0 冒烟 13 段已落地——第 11-13 段随 DB 格式通道交付；U2/U3 分期落地）
+>
+> 配套文档：套件根 [SKILL.md](../SKILL.md)（子域路由）｜ [知识库规范](知识库规范.md)（知识分类与标准化）
+>
+> 上游依赖：CANNBench（gitcode.com/cann/cann-bench，tasks L1-L4 共 53 算子 +
+> metadata t_hw/baseline + HAP 评分 + staged eval 框架）
+
+---
+
+## 目录
+
+1. [定位与设计原则](#1-定位与设计原则)
+2. [分层用例体系总览（U0-U3）](#2-分层用例体系总览u0-u3)
+3. [U0 离线冒烟与单元回归](#3-u0-离线冒烟与单元回归)
+4. [U1 判定回归（evals）](#4-u1-判定回归evals)
+5. [U2 端到端用例](#5-u2-端到端用例)
+6. [U3 场景矩阵](#6-u3-场景矩阵)
+7. [复用 CANNBench L1-L4](#7-复用-cannbench-l1-l4)
+8. [代码合入触发用例执行](#8-代码合入触发用例执行)
+9. [用例治理与生命周期](#9-用例治理与生命周期)
+
+---
+
+# 1. 定位与设计原则
+
+## 1.1 为什么用例必须分层
+
+检视意见（§7 根因）已经给出实证：**三个 P0 崩溃和大部分 P1 共享同一根因——「写了但从未
+在真实调用路径上运行过」+「evals 只测了设计者想到的路径」**。10 条 evals 全部由规则作者
+构造，天然绕开多包瀑布、反证指标解析、死指标路径、区间边界、
+路由副作用。判定质量的回归网眼，恰好都织在 bug 所在之外。
+
+结论：单一层级的用例（无论多少条）都无法同时满足「快反馈」与「全覆盖」——分层不是组织
+美学，是把三类风险分给三类成本结构不同的用例：
+
+| 风险 | 例子 | 承接层 |
+|------|------|--------|
+| 确定性 bug（脚本崩溃/死代码/区间重叠） | F1/F2/F3/F5/F6/F7/F18 | U0（无卡，秒级）+ U1（无卡，分钟级） |
+| 门禁与流程失效（口径/精度/噪声带/路由） | F9/F10/F11/F12 | U1 + U2 |
+| 调优能力退化（判定错/收益没了/精度劣化） | 判定误报率、geomean 回归 | U2（真机）+ U3（矩阵） |
+
+## 1.2 六条设计原则
+
+| # | 原则 | 含义 | 反例 |
+|---|------|------|------|
+| C1 | **断言进脚本** | 用例 = fixture + 断言器 + 退出码，不做文本评测 | 「让 LLM 看输出打分」（业界现状，判定质量零守护） |
+| C2 | **已知答案** | 每条用例的期望输出事先固化（真机标定 / 官方 PR 收益 / 机制卡区间），禁止事后追认 | 先跑一遍把输出抄下来当答案 |
+| C3 | **断言分级** | 机制断言（环境无关，CI 阻断）/ 锚定断言（随环境校准）/ 过程断言（无同型案例时断言降级策略合规）——见 §2.2 | 对一切用例硬编绝对加速比阈值（环境一换全红） |
+| C4 | **复用不重做** | 用例取材复用 CANNBench（P3），本仓只做适配层与断言器，不 fork 任务集 | 把 cann-bench 的 cases 拷贝进本仓散养 |
+| C5 | **门禁机械化** | 触发由变更路径驱动、退出码即 CI 动作，「跑不跑用例」不依赖自觉 | evals 存在但无自动触发点（现状） |
+| C6 | **一次采集多处沉淀** | 一次真机采集同时产出：阈值回写（thresholds.md）+ fixture 入库（U1）+ E 级案例候选（知识回流） | 上板一次只为写一个数字 |
+
+## 1.3 与既有资产的对应
+
+| 既有资产 | 在本体系中的位置 |
+|---------|----------------|
+| `skills/ops-verdict/evals/run_evals.py`（36 条，exit 1 阻断；CI + pre-push 双挂） | U1 主体（已达 30+ 目标） |
+| `skills/ops-verdict/fixtures/`（3 个 CSV） | U1 fixture，补生成脚本与标注 |
+| Roadmap「测试用例框架 / U3 矩阵」 | 本文 §5 / §6 正式化 |
+| 离线干跑框架 | 本文 U0 + U2 干跑模式 |
+| Roadmap「算子仓 CI 回归门禁」 | 本文 §8.5（算子仓侧） |
+| CANNBench tasks/metadata/staged eval | 本文 §7（取材与框架复用） |
+
+---
+
+# 2. 分层用例体系总览（U0-U3）
+
+## 2.1 四层金字塔
+
+```
+                        ┌──────────────────┐
+                        │  U3 场景矩阵      │  真机 · 小时-天级
+                        │  覆盖率断言       │  夜间 / 发版
+                      ┌─┴────────────────┴─┐
+                      │   U2 端到端用例      │  干跑（无卡）+ 真机
+                      │   五阶段全链断言     │  PR 定向 / 每日
+                    ┌─┴────────────────────┴─┐
+                    │    U1 判定回归（evals）   │  无卡 · 分钟级
+                    │   fixture → 断言 verdict │  每次 PR（阻断）
+                  ┌─┴────────────────────────┴─┐
+                  │   U0 离线冒烟 + 单元回归      │  无卡 · 秒级
+                  │   脚本可跑 / 引擎语义 / 校验器 │  每次推送
+                  └────────────────────────────┘
+     成本/时延递增 ▼        反馈速度/执行频次递增 ▲
+```
+
+| 层 | 名称 | 断言对象 | 环境 | 典型时长 | 触发时机 | 现状 |
+|----|------|---------|------|---------|---------|------|
+| **U0** | 离线冒烟与单元回归 | 脚本可运行性（shim 干跑）/ 引擎函数语义 / 规则包加载校验 / 契约互锁单元 | 无卡（PyYAML） | <2 min | 每次推送（含 pre-push） | 🔴 待建（~5 人日） |
+| **U1** | 判定回归（evals） | verdict / snapshot / delta_compare 对 fixture 的输出 == 已知答案 | 无卡 | <5 min | 每次 PR，**阻断**；安装自检（install.sh） | 🟢 38/38（E1-E26 判定 + S1-S12 门禁脚本；新规则必须带断言用例的纪律已多次兑现） |
+| **U2** | 端到端用例 | 五阶段全链：精度门禁 / 判定正确性 / 加速比 / 报告六要素 / 口径纪律 / 路由副作用 | 干跑无卡 + 真机 | 干跑 <30 min；真机 30-90 min/算子 | 干跑：PR 定向（阻断）；真机：每日 | 🟡 设计定稿（先行试点 3 算子） |
+| **U3** | 场景矩阵 | 维度覆盖率（族 × 等级 × 卡规模 × 采集模式 × soc × 场景）≥80% | 真机为主 | 小时-天级 | 夜间 / 发版出口 | 🔴 待建 |
+
+> 分层判断标准：**换一层环境才测得到的 bug，必须在那一层有用例**。U0/U1 无卡可跑是硬要求
+> ——CI 的快门禁不允许依赖 NPU 资源（历史事故已证明：全部 P0 均可用无卡干跑发现）。
+
+## 2.2 断言分级（用例稳定性的关键设计）
+
+对一条用例写断言时，先归类再写阈值——三类断言的稳定性完全不同，混用会让 CI 要么全红要么假绿：
+
+| 级别 | 断言什么 | 例子 | 稳定性 | CI 语义 |
+|------|---------|------|--------|---------|
+| **M 机制断言** | 门禁执行 / 路由 / 产物链 / 精度——流程是否按契约发生 | precision≠pass 的轮次数字不出现在 REPORT；HARD_KEYS 漂移 → exit 2；E8 污染命中后 L1_MTE2_BOUND 进 skipped | 环境无关，**永真** | 阻断 |
+| **A 锚定断言** | 与外部锚点比较的**区间**断言 | geomean speedup ≥1.1；HAP ≥0.5；target_rule 转 NOT_HIT 或降档 | 随环境/soc 漂移，阈值进用例卡并带校准来源 | 阻断（阈值随里程碑校准） |
+| **P 过程断言** | 无同型案例 / 无已知收益时，断言**降级策略合规** | FA 类用例：报告标注「无同型案例」、E 级候选生成、提高验证强度（多轮稳态） | 环境无关 | 阻断 |
+
+原则：**能用 M 不用 A，能用 A 不用 P**；A 类阈值禁止硬编码在断言器里，必须落在用例卡
+`goal.threshold`（带锚点来源），阈值进化走 §9.2 变更流程。
+
+## 2.3 统一退出码契约
+
+三层用例共用一个退出码契约（CI 只认码不认文本）——沿用并扩展现有先例
+（run_evals exit 1 = 阻断；delta_compare exit 2 = 门禁拒绝）：
+
+| 退出码 | 语义 | 先例 | CI 动作 |
+|-------|------|------|--------|
+| 0 | 全绿放行 | run_evals | 放行 |
+| 1 | 用例失败（断言不中 / 脚本崩溃） | run_evals「阈值纪律」 | **阻断合入** |
+| 2 | 门禁拒绝（口径漂移 / 精度失败） | delta_compare | **阻断合入** + 门禁标签 |
+| 3 | 环境不满足（无 NPU / shim 失败 / 上游取材失败） | 新增 | 跳过标记——**不计绿**，夜间补跑 |
+
+> 退出码 3 的设计动机：U2 真机层在无卡 CI 上必须能「体面地跳过」而不是假成功；但跳过
+> 不得静默——汇总报告必须显式列出 skipped-by-env 清单，防止「全绿」掩盖「根本没跑」。
+
+---
+
+# 3. U0 离线冒烟与单元回归
+
+**定位**：无 NPU 的前置门禁——历史事故证明全部 P0 崩溃（`local` 函数外使用、env 丢失）
+都无需真机即可发现。U0 是性价比最高的一层（估算 ~5 人日），M1.5 第一优先级。
+
+## 3.1 四类内容
+
+| # | 内容 | 断言 | 守护的缺口 |
+|---|------|------|-----------|
+| U0-1 脚本冒烟 | msprof **shim**（按参数产出预置 CSV 目录的假可执行）+ shellcheck + `collect_board.sh` 三模式干跑 + `isolation_test.py` env 模式干跑 | 退出码 0、manifest 结构合法、产物目录形态正确 | F1 / F2 / F17 / F23 |
+| U0-2 引擎单元回归 | `verdict.py` 以库形式 import，构造 facts 直接断言：severity 分档、routing 副作用、counter_evidence 求值、非数值 scalar 降级、全瀑布 facts 分包累积 | 函数级输出 == 期望 | F4 / F5 / F6 / F18 |
+| U0-3 规则包加载校验（负向用例） | 引擎加载时校验：condition/反证/severity 引用的指标必须在词汇表；`routing.on_hit` 目标规则存在；同层区间无重叠；derived 声明必须有计算实现。U0 用「坏规则包必须报错退出」守护校验器本身 | 非法包 → 加载失败 | 区间重叠 / 引用缺失 / 死分支类问题**合入即拦截** |
+| U0-4 契约互锁单元 | snapshot/delta_compare 的 HARD_KEYS 比对、MECHANISM_KEYS WARN、±5% 三段结论、exit 2 路径 | 构造快照对 → 断言结论与退出码 | F9 / F10 |
+
+> U0-3 是「产品代码 + 用例」双重形态：加载校验写进 verdict.py（合入非法规则包时直接报错），
+> U0 负责守护校验器自身不退化——纪律变机制，机制本身也要有回归。
+
+## 3.2 目录与入口
+
+**规划目录形态（U2/U3 分期落地时创建；当前未建）**——现状入口见段尾对照表：
+
+```
+tests/                      # 规划（U2/U3 落地时创建；当前仓库无此目录）
+├── smoke/                  # U0-1
+│   ├── shim/msprof         #   假 msprof（--help 探测 / 参数回放 → 预置 CSV）
+│   ├── run_smoke.sh
+│   └── cases/              #   三模式干跑参数化用例
+├── unit/                   # U0-2 / U0-4（pytest 或自研 runner，依赖仅 PyYAML）
+├── e2e/                    # U2（见 §5）
+├── matrix/                 # U3（见 §6）
+├── adapters/               # CANNBench 取材适配层（见 §7）
+└── run_all.py              # 统一入口：--layer U0,U1[,U2,U3] --mode dryrun|board
+```
+
+**现状对照（已存在，截至 U1 全绿态）**：
+
+| 规划路径 | 现状实现 |
+|---------|---------|
+| `tests/smoke/run_smoke.sh` | `ops-verdict/evals/smoke/run_smoke.sh`（SKILL 自包含，13+ 段） |
+| `tests/unit/`（U0-4 契约互锁） | 并入 `ops-verdict/evals/run_evals.py` 的 S 系用例 |
+| `tests/run_all.py --layer U0,U1` | `ops-verdict/evals/run_evals.py` + `ops-verdict/evals/smoke/run_smoke.sh` 两条命令 |
+| `tests/install_hooks.sh` | `ops-verdict/evals/smoke/install-hooks.sh`（pre-push 门禁） |
+| `tests/e2e/`、`tests/matrix/`、`tests/adapters/` | 未建（U2/U3 分期，见 §5/§6） |
+
+U1（`ops-verdict/evals/`）**留在 SKILL 内不迁移**——它属于 SKILL 的自包含回归
+（P4：SKILL 独立可用 + install.sh 安装自检都依赖它在原地）；未来 `tests/run_all.py`
+落地后以子进程方式调用它，退出码透传。
+
+---
+
+# 4. U1 判定回归（evals）
+
+**定位**：判定知识的执行式回归——fixture（已知答案的 CSV/标量）断言 verdict 输出。
+规则/阈值/引擎任何变更必须全绿才可合入（D8，CI 阻断语义）。这是四层中唯一已运行的一层。
+
+## 4.1 现状解剖（10 条）
+
+```
+run_evals.py = CASES[]（用例定义：args + assert） + run_case()（求值器） + main()（退出码）
+fixture：3 个真机脱敏 CSV（mte2_bound_a2 / core_tail_a5 / serial_no_overlap_a2）+ 标量注入
+断言键：hit / not_hit / hit_either / hit_or_insufficient / skipped_contains / verdict
+```
+
+| # | 用例 | 断言要点 |
+|---|------|---------|
+| E1 | MTE2 占比 78% 且主导 pipe | L1_MTE2_BOUND 命中、NEEDS_OPTIMIZATION |
+| E2 | E1 + active_bw=85% 峰值 | 反证「真带宽饱和」触发（优化方向改变仍 HIT） |
+| E3 | cube+mte2+mte1 求和≈1 | 串行无重叠指纹命中、单 pipe BOUND 不命中 |
+| E4 | 均值 93us 峰值 185us | 核间长尾 + 离散度严重双命中 |
+| E5 | 仅 8 个 block（A5 48 核） | 切核不足命中 |
+| E6 | R=2.10 | 强计算 bound 命中 |
+| E7 | R=1.01 | 完美平衡命中 |
+| E8 | full=62 / pure=41 | 污染命中 + 路由副作用生效 |
+| E9 | 无 CSV 无标量 | 全 SKIPPED + INSUFFICIENT_DATA（绑定契约兜底） |
+| E10 | 全 pipe <50% | LATENCY/SYNC 可疑命中而非「无 bound」 |
+
+## 4.2 用例编写规范（六条，新增/修改用例必守）
+
+1. **已知答案必须标来源**：fixture 源自真机调优案例的，用例 `desc` 标注案例指纹
+   （算子/soc/口径）；首期手工构造的标 🟡，M1.5 标定后替换——与阈值溯源同一纪律。
+2. **正例 + 至少一个反例/边界**（rule-schema.md 扩展流程第 2 条）：只测命中的用例
+   防不住误报，反例防误报、边界防区间错位（E11/E12 即为此补）。
+3. **断言键白名单**：求值器必须消费用例声明的每一个断言键，**未知键报错**（未知键
+   静默通过 = 死断言）。已知缺口：`counter_evidence` 键在 E2 声明但 `run_case()`
+   无对应分支——E2 的反证断言实际从未生效，修复以本条规范为准。
+4. **三态覆盖**：每条规则至少被三条用例覆盖 HIT / NOT_HIT（或 watch）/ SKIPPED（或
+   INSUFFICIENT_DATA）——对应规则状态机全分支，缺态即盲区（E9 是目前唯一的 SKIPPED 态用例）。
+5. **fixture 可复现**：CSV 用脚本生成（种子固定）或标注脱敏来源 commit，禁止手搓数字；
+   fixture 与阈值联动——改规则 YAML 必须检查关联 fixture 是否仍成立。
+6. **一用例一场景**：用例只断言一个判定场景（可多规则同命中，但必须是同一场景的自然结果），
+   禁止为凑覆盖把不相关标量拼进一个用例。
+
+## 4.3 已知缺口与修复（用例侧）
+
+| 缺口 | 现状 | 修复 |
+|------|------|------|
+| E2 反证死断言 | `counter_evidence` 键无求值分支 | 求值器补该键 + 白名单校验（规范 3） |
+| E8 路由副作用未断言 | 只断言污染命中，未断言 L1_MTE2_BOUND 被禁用 | E15（§4.4） |
+| 门禁脚本零回归 | snapshot / delta_compare 无任何用例 | E16-E19（§4.4） |
+| R 值边界盲区 | E7 只测 1.01，恰好避开 [0.9,1.0) 重叠区 | E11/E12 |
+| fixture 无生成脚本 | 3 个 CSV 为手工产物 | `fixtures/gen/` 脚本化 + 来源标注 |
+
+## 4.4 扩充清单：10 → 20（M1.5-5）
+
+E1-E10 保留，新增 E11-E20（每条映射既有回归缺口，全绿后 🟡 阈值项可回写）：
+
+| # | 用例 | 断言要点 | 对应缺口 |
+|---|------|---------|---------|
+| E11 | R=0.95 | 区间收窄后仅 COMM_BOUND 命中、BALANCED 不命中 | F3 |
+| E12 | R ∈ {0.5, 0.9, 1.1, 2.0} 逐点 | between 闭开区间语义精确无重叠 | F3 |
+| E13 | MTE2 占比 55% | NOT_HIT 且 watch 档提示存在于 verdict.json 与终端摘要 | watch 档 / F29 |
+| E14 | VEC 占比 85% / 60% | severity 三档分档正确（critical / light） | 死分档类 |
+| E15 | E8 强化 | `L1_MTE2_BOUND` 出现在 skipped 且 reason 含 disabled；reroute 目标正确 | F10 |
+| E16 | 快照对口径漂移 | HARD_KEYS 任一不一致 → delta_compare exit 2 | F10 |
+| E17 | 快照对精度门禁 | 任一侧 precision≠pass → exit 2 | F10 |
+| E18 | 噪声带边界 1.05 / 0.95 / 带内 | 三段结论正确 + 带内复测处置提示（含 repeat 重建基线提示，F9） | F9/F10 |
+| E19 | 机制变量变化 | block_dim / tiling_key 变化 → WARN 非 exit 2（--strict 恢复禁比） | D4 语义 |
+| E20 | L0 层 | icache_miss>15% 命中 / l2_hit<50% 命中 | L0 覆盖 |
+
+> E16-E19 使 U1 覆盖面从 verdict.py 扩展到三脚本；M1.5 验收「每条
+> L1/L2/L3 规则至少 1 正 1 反」在 E1-E20 基础上按规则清单核对补齐（23 条规则 → 全覆盖时
+> 用例数自然超过 20，20 是 M1.5 下限不是上限）。
+
+---
+
+# 5. U2 端到端用例
+
+**定位**：以「一个真实算子工程 + 全量 cases + 目标」为输入，跑完 OpsTuningAgent 五阶段
+闭环，断言**全链行为**——判定对不对、精度有没有劣化、收益达没达锚点、报告全不全、口径
+纪律有没有被绕过。U2 是唯一能发现「编排层退化」的层（U1 只测 SKILL 不测 Agent）。
+
+## 5.1 断言维度：六维
+
+U2 断言器 = `agent/workflows/task-prompts.md` 各 Step「完成验证」的机器化 + 门禁纪律
+（A1-A5 铁律）的执行证据检查 + 调优结果锚定。六维缺一即用例不完整：
+
+| 维度 | 断言内容 | 类型 | 数据源 |
+|------|---------|------|--------|
+| ① 精度零劣化 | Phase 0 全集 pass 才进入；每轮先精度后性能；fail 轮数字不进报告 | M | 逐 case PASS/FAIL 明细 vs golden |
+| ② 判定正确性 | verdict 与已知 bound 形态一致；优化后 target_rule 转 NOT_HIT 或 severity 降档 | A/M | verdict.json（前后两份） |
+| ③ 加速比锚定 | geomean speedup ∈ 用例卡区间；REVERT 轮处置正确（回滚 + 复跑确认） | A | round-*/result.json + comparison.md |
+| ④ 报告六要素 | 环境指纹 / 逐 case 全量表 / Bound 前后对照 / 保留回滚清单 / 预估 vs 实测 / 适用边界——六节齐且逐 case 行数 == cases 总数 | M | REPORT.md 结构化解析 |
+| ⑤ 口径纪律 | 基线与轮次 HARD_KEYS 全等；机制变量差异仅 WARN；噪声带内不宣称收益 | M | snapshot 对 + delta_compare |
+| ⑥ 路由与仲裁 | MC² 类：污染命中 → 单核访存机制不在 candidates；多 KEEP 仲裁规则执行 | M | candidates.json × verdict.json 交叉 |
+
+> ④ 的「逐 case 行数 == cases 总数」是 A1 全量铁律的机器化——人读报告很难发现少了一个
+> case，断言器数行数即可。⑥ 的交叉断言（candidates 的 target_rule ⊆ verdict findings、
+> 污染禁用规则 ∉ candidates）把 Step 3 的两条「完成验证」也机器化了。
+
+## 5.2 三种用例形态（按已知答案的强度分）
+
+| 形态 | 已知什么 | 断言什么 | 用例来源 |
+|------|---------|---------|---------|
+| **A 已知答案** | 基线工程的 bound 形态（fixture 先行标定） | 判定书命中预期规则；实施后转 NOT_HIT/降档 | 种子工程（§5.3）+ CANNBench L1/L2 |
+| **B 已知收益** | 官方仓已合并优化 PR 的实测收益（A 级证据） | Agent 达到该收益区间，或报告给出可信解释（不达标本身不FAIL，**无解释才 FAIL**） | 官方算子仓 PR（ops-nn / ops-transformer…） |
+| **C 能力边界** | 无同型案例（FA 类已知缺口） | 降级策略合规：报告标注「无同型案例」、候选卡证据链完整、E 级候选生成、验证强度提高（P 类断言） | CANNBench L4 + bench_lab FA 变体 |
+
+> B 形态的「不达标不 FAIL、无解释才 FAIL」是刻意设计：绝对收益随环境漂移（A 级案例的
+> speedup 绑定当时的口径指纹，禁止外推——案例卡纪律），但「解释义务」是机制性的。
+
+## 5.3 被测工程从哪来（种子工程机制）
+
+U2 需要一个「可运行、精度通过、bound 已知」的被测工程，三种来源：
+
+1. **种子工程（自建，首选）**：用 ops-family 模板货架**反向构造**——从模板的「优化后」
+   形态回退掉已知机制（去掉 Double Buffer → 串行指纹；单核大 block → 切核不足），得到
+   bound 可预测的基线实现。优点：自包含、bound 由构造决定（U1 fixture 同源标定）、
+   不依赖外部仓节奏；
+2. **CANNBench 取材**：L1-L4 任务的 golden 参考实现 / 示例工程作为基线（见 §7）；
+3. **官方仓历史版本**：优化 PR 的父 commit 作为基线（B 形态专用）。
+
+种子工程入 `tests/e2e/seed_projects/`（规划路径，U2 落地时创建），每个种子附 `bound_manifest.yaml`（预期 bound +
+构造说明 + 回退 diff），实现「U1 fixture 与 U2 种子同源」（C6 原则）。
+
+## 5.4 用例卡 schema 与示例
+
+```yaml
+id: U2-GELU-A2-001
+title: 单算子·elementwise·GELU 种子工程调优
+scenario: single_op              # single_op | fusion | regression | qa
+soc: a2                          # a2=910b2 / a5=950pr|950dt
+source:
+  bench_ref: adapters/cann_bench_ref.yaml@<锁定 commit>
+  task: tasks/level1/gelu        # CANNBench 取材任务（cases/golden/proto）
+  project: seed:elementwise/naive_gelu    # 被测工程（seed / official-pr:<repo>#<pr> / bench:example）
+timing:                          # 口径适配（§7.6）：与 CANNBench baseline 采集口径对齐
+  method: event                  # snapshot --timing-method 五选一
+  warmup: 5
+  repeat: 20
+goal:
+  metric: geomean_speedup        # geomean_speedup | hap | verdict_only
+  threshold: [1.10, 2.0]         # A 锚定断言区间（来源：机制卡 speedup_range / A 级案例）
+  anchor: metadata/910b2.json    # t_hw/baseline 锚点（HAP 备用）
+expect:
+  form: A                        # A | B | C（§5.2）
+  verdict_known: [L1_SERIAL_NO_OVERLAP]     # A 形态：基线 bound 已知
+  verdict_after: not_hit_or_downgrade
+  precision: zero_regression     # 20/20 case 零劣化
+  report_six_elements: true
+  full_case_rows: 20             # 逐 case 表行数 == case 总数（A1 铁律机器化）
+  noise_band_policy: enforced
+routing_expect: []               # fusion 类填：pollution_hit → 单核访存 ∉ candidates
+holdout: level1/gelu@internal    # 泛化集引用（§5.6，防特判）
+budget: {dryrun_minutes: 15, board_minutes: 40}
+runner: [dryrun, board-910b2]    # 干跑 + 真机两模式
+```
+
+## 5.5 干跑模式与真机模式
+
+同一张用例卡两种执行模式——这是 U2 能进 PR 门禁的关键（无卡 CI 跑干跑，真机留给夜间）：
+
+| | 干跑（dryrun） | 真机（board） |
+|---|---------------|--------------|
+| 环境 | 无 NPU；msprof shim + 预置 PROF 目录 | 910B2 / 950 runner 池 |
+| 跑什么 | 五阶段全链：隔离测试走 from-prof 模式（目录预置）、采集走 shim、性能数字取预置样本 | 真实采集与计时 |
+| 断言什么 | 产物链完整（scope→manifest→verdict→candidates→round→comparison→REPORT）、六维中 ①④⑤⑥ 全部 + ②判定正确 | 全部六维 + ③加速比锚定 |
+| 价值 | 编排层退化、契约断链在 PR 即暴露 | 调优能力真实水平、阈值标定数据、E 级案例产出 |
+
+> 干跑模式的性能数字是预置的，**只断言流程与判定，不断言收益**——收益断言（③）只在
+> 真机模式生效。断言器按 `runner` 字段自动裁剪断言集。
+
+## 5.6 防过拟合与反特判
+
+调优 Agent 可能「记住」用例而非「会调优」，两条防线（对齐 CANNBench 反作弊边界与
+「内部泛化验证集 80 条不公开」的机制）：
+
+1. **泛化 hold-out**：用例卡的 `holdout` 引用一份不随仓公开的泛化 case 集（shape/dtype
+   扰动生成，种子由评测方掌握）。A 类用例终检时在 holdout 上复跑精度与抽查性能——
+   特判了公开 case 的实现（按 shape 硬编码快路径）会在扰动 shape 上现形；
+2. **判定只出自脚本**（架构性防线）：收益与 bound 结论全部来自 verdict/snapshot/
+   delta_compare 契约文件，REPORT 六要素机器校验——Agent 无法「写出」一个不存在于
+   契约里的好数字。
+
+## 5.7 产物回灌：U2 是自进化回路的取材口
+
+U2 真机跑完的产物不白跑（C6 原则的体系级延伸）：
+
+```
+U2 真机执行
+  ├─ REPORT.md / verdict.json / calibration_data.json
+  │     ├─▶ E 级案例候选 → cases/（入库评审后）→ 又成为后续 B 形态用例的收益锚点
+  │     ├─▶ speedup_est vs 实测 → 校准回路（27-2）→ 机制卡 speedup_range 回写
+  │     └─▶ 阈值命中率/误报率统计 → 阈值进化建议（27-3，人审 + U1 全绿才生效）
+  └─ 判定盲区（INSUFFICIENT_DATA 高发 / 规则未覆盖形态）
+        └─▶ 缺口感知回路（27-4）→ U3 矩阵空白格排产
+```
+
+评测体系与知识体系共用同一批契约文件——**用例资产与知识资产互相喂数**，这是「经验可回流」
+在评测侧的落点。
+
+---
+
+# 6. U3 场景矩阵
+
+**定位**：覆盖率层——回答「这套 Agent 在哪些场景被验证过」。不新增断言类型，复用 U2
+断言器；U3 的产出是**覆盖报告**（矩阵格 → 用例卡 ID → 最近一次全绿时间）。
+
+## 6.1 维度设计
+
+| 维度 | 取值（首期） | 来源 |
+|------|------------|------|
+| 算子族 | matmul / mc2 / reduce / elementwise / broadcast / conversion / sort / scalar / simt / fa | ops-family 十族 |
+| 难度等级 | L1 / L2 / L3 / L4 | CANNBench 等级（族 × 等级映射见 §7.3） |
+| 卡规模 | 1 卡 / 2 卡 / 8 卡（mc2 采集模式必测多 rank） | 融合算子场景 |
+| 采集模式 | standard / quick / mc2 / cannsim | ops-collect 三模式 + 仿真 |
+| 芯片域 | a2（910B2）/ a5（950PR、950DT） | 规则包 soc 域（a3 待上游 metadata，见 §7.6） |
+| 调优场景 | single_op / fusion / regression / qa | Agent 场景路由四类 |
+
+覆盖判定：格内至少一张 U2 用例卡**最近 30 天内真机全绿**计「已覆盖」；有用例卡但未真机
+计「设计覆盖」；无卡计「空白格」。26 年出口验收 ≥80%（融合算子格优先），27 年验收 100% 已知格
+（与缺口感知看板同源——矩阵空白格就是 27-4 的排产输入）。
+
+## 6.2 取材与规模估算
+
+| 来源 | 可取格 |
+|------|--------|
+| CANNBench tasks L1-L4（53 算子 × 每算子 20 case） | 单算子场景主力：族 × 等级 × soc × standard 模式 |
+| bench_lab/cv_agent_fa_bench（25 个 attention 变体） | fa 族 × L4 格 + 26-2 FA 专项案例来源 |
+| 种子工程（§5.3） | 采集模式 quick / cannsim 格 + 「反向构造」的确定性 bound 格 |
+| 内部 MC² 工程（自建，cann-bench 主集合无 fork 多 rank 任务） | mc2 采集模式 × 多卡格——**已知取材缺口**，配平搜索专项联建 |
+
+> 25 attention 变体与 53 主集任务不重复建设 U2 断言器——U3 只是 U2 用例卡的**编目维度**，
+> 一张卡可占多格（如 `U2-MLA-A5-017` 同时占 fa × L4 × 1 卡 × standard × a5 × fusion）。
+
+---
+
+# 7. 复用 CANNBench L1-L4
+
+**定位**：CANNBench 是上游真源（P3 复用不重做），OpsTune 建适配层取材，不 fork 任务集、
+不自建评测框架。复用分四类资产 + 一条回写通道。
+
+## 7.1 复用三原则
+
+1. **不 fork 任务集**：cases / golden / proto / metadata 始终从 cann-bench 仓取，
+   本仓只存「引用清单」（锁定 commit + 任务路径列表），适配层拉取；
+2. **版本锁定**：`adapters/cann_bench_ref.yaml` 记录 cann-bench commit 与
+   `tasks/metadata/VERSION`（当前 1.0.0）；上游 bump → 适配层回归（U2 干跑全量）
+   → 更新锁定的 commit。禁止「永远跟 main」；
+3. **口径适配显式化**：cann-bench 与 OpsTune 的计时/口径参数差异必须在适配层覆写并
+   写进 HARD_KEYS（§7.6）——跨口径数字禁止混比是本仓铁律，复用不能破例。
+
+## 7.2 资产映射表（CANNBench → OpsTune 契约）
+
+| CANNBench 资产 | 内容 | OpsTune 消费点 | 落点 |
+|----------------|------|---------------|------|
+| `tasks/levelN/<op>/cases.csv`（每算子 20 开放用例） | shape/dtype/attrs/value_range | Agent 调优输入 cases——**每算子恰好 20 case，与 A1 铁律「>20 取前 20」天然对齐** | scope.json / 逐 case 对比表 |
+| `tasks/levelN/<op>/golden.py` | PyTorch 参考实现 | Phase 0 精度门禁预检的比对基准 + 每轮精度验证 | 精度指纹（snapshot precision） |
+| `tasks/levelN/<op>/proto.yaml` | 算子原型（dtype/shape_support/attrs/schema） | D2 算子元数据契约 → scope.json 口径字段 | scope.json |
+| `tasks/levelN/<op>/desc.md` | 算子说明 | 场景分类辅助（单算子 vs 融合识别） | Phase 0 |
+| `tasks/metadata/<hw>.json` | 逐 case `baseline_perf_us` / `t_hw_us` | Phase 1 理论标尺「还差多远」读数；U2 A 锚定断言；HAP 计算 | snapshot 锚点 / 用例卡 goal.anchor |
+| `scripts/run_evaluation.sh` + `staged_eval` | 编译→精度→性能三阶段评测 + HAP 评分 + 非零退出码 | U2 真机模式的精度/性能采集执行器（§7.5） | tests/e2e runner |
+| `bench_lab/`（25 attention 变体等） | 孵化区任务 | U3 矩阵 FA 格 + 26-2 FA 案例来源 | U3 编目 |
+| 内部泛化验证集（80 条，不公开） | 防特判 hold-out | U2 `holdout` 引用（§5.6） | 评测方掌握 |
+
+## 7.3 等级 × 用途映射（L1-L4 各取什么）
+
+| 等级 | 规模 | 代表算子 | 在本用例体系中的用途 |
+|------|-----|---------|---------------------|
+| **L1 基础**（elementwise/activation） | 8 | gelu / sigmoid / mish / swi_glu | U1 fixture 取材（VEC bound、latency 场景）+ U2 首批试点（调优周期短、bound 形态简单、性价比最高）+ M1.5-2 阈值标定数据源 |
+| **L2 中级**（norm/reduce/gather） | 16 | softmax / rms_norm / gather / group_norm | U2 单算子主力 + reduce/broadcast 族模板链路验证 + L2 层规则（长尾/离散度）正反例 fixture |
+| **L3 高级**（conv/MoE/matmul） | 21 | grouped_matmul / quant_matmul / conv_2d / top_k | matmul 六策略互斥判定树验证 + U3 主力格 + MC² 类种子工程母体（cann-bench 无现成 MC² 任务，见 §6.2） |
+| **L4 复杂**（attention/RNN） | 8 | mha / mla / gqa / sparse_flash_attention / lstm | C 形态用例（FA 降级策略断言）+ 路由副作用真机验证 + bench_lab 25 变体扩展 U3 fa 格 |
+
+> 试点顺序建议（M1.5 → 26 框架期）：L1 gelu（A 形态跑通断言器）→ L2 softmax（模板链路）→
+> L3 grouped_matmul（策略判定树）→ L4 mla（C 形态 + 降级策略）——与 M1.5-1「真机 3 算子
+> 全流程」的前三步重合，一次投入两处验收。
+
+## 7.4 metadata 标尺接入
+
+`tasks/metadata/{910b2,950pr}.json`（950dt 规划中，R8）提供逐 case 双锚点，接入三处：
+
+```
+t_hw_us（硬件理论下界）────▶ Phase 1「还差多远」读数（达上限百分比，SOL 语义）
+   │                          U2 A 锚定断言的物理上界（speedup 物理上限 = baseline/t_hw）
+baseline_perf_us（PyTorch 基线，实测封顶口径 max(10×t_hw, 10us)）
+   └──────────────────────▶ HAP = (T_baseline−T_HW)/((T_cand−T_HW)+(T_baseline−T_HW))
+                              U2 goal.metric=hap 时的评分锚点（饱和型，防「基线很慢→speedup 虚高」）
+```
+
+两个指标的分工：**speedup 管 KEEP/REVERT 决策**（OpsTune 内部，±5% 噪声带三段结论），
+**HAP 管跨系统可比性**（CANNBench 榜单口径，27-10 回写）。U2 用例卡二选一或并用
+（`goal.metric`），禁止把 HAP 当 speedup 用（HAP>0.5 只说明优于基线，不说明快了多少倍）。
+
+## 7.5 评测框架复用：staged eval 与 OpsTune 门禁链同构
+
+CANNBench 的三阶段评测与本仓门禁链结构同构，U2 真机模式直接外挂调用、不重写采集：
+
+| CANNBench staged eval | OpsTune 对应门禁 | U2 复用方式 |
+|----------------------|-----------------|------------|
+| compile（build.sh；失败**整批 0 分 + 非零退出码**） | implementer Release 编译门禁（禁 -O0） | 干跑模式复用其「编译失败即阻断 + 错误摘要」语义；真机模式直接调 |
+| correctness（cases + golden.py 精度比对） | Phase 0 精度预检 / 每轮门禁② | 直接调 `run_evaluation.sh --no-perf`（等价 correctness-only） |
+| performance（profiler 采集 + HAP） | Phase 4b 统一采集 + snapshot + delta_compare | 性能样本取其 profiler 口径 → OpsTune 侧落 snapshot（同口径铁律由主 agent 垄断不变） |
+
+调用形态（U2 真机 runner 内部，Docker 镜像复用 cann-bench `docker/eval`）：
+
+```bash
+# 精度阶段（Phase 0 预检 / 每轮门禁②）
+bash <cann-bench>/scripts/run_evaluation.sh --source-dir <被测工程> \
+    --task-dir tasks/level1/gelu --no-perf --device-id <id>
+# 性能阶段样本（喂 snapshot.py → delta_compare.py，判定与对比仍出自本仓脚本）
+bash <cann-bench>/docker/eval/run.sh <被测工程> --operator Gelu
+```
+
+## 7.6 口径适配细节（复用最容易翻车的地方）
+
+| 差异项 | CANNBench | OpsTune | 适配规则 |
+|--------|-----------|---------|---------|
+| warmup/repeat | run_evaluation 默认 3/5；**baseline 采集口径 5/20** | 示例口径 5/20 | 适配层显式 `--warmup 5 --repeat 20`，与 metadata baseline 采集口径一致——否则 snapshot HARD_KEYS `repeat` 不一致，delta_compare exit 2 |
+| 计时口径 | profiler / TorchNPU | 五选一（event 为默认首选） | 用 cann-bench 采集时 snapshot 记 `profiler_summary` 或 `msprof_task_duration` 并在报告注明；**禁止与 event 口径的基线混比** |
+| soc ↔ hardware 命名 | 910b2 / 950pr（metadata 键） | a2 / a3 / a5（规则包 soc 域） | 映射表见下；a3 无上游 metadata，该域 U2 用内部案例标定（R4 跨芯片风险的评测侧对策） |
+| 泛化集 | 内部 80 条不公开 | — | 以 `holdout` 引用接入评测方环境，不进本仓 |
+
+**soc ↔ hardware 映射表**（适配层唯一真源）：
+
+| OpsTune soc | CANNBench hardware | 架构 | metadata 现状 |
+|-------------|-------------------|------|--------------|
+| a2 | 910b2 | DAV_2201 | ✅ tasks/metadata/910b2.json |
+| a5 | 950pr | DAV_3510 | ✅ tasks/metadata/950pr.json |
+| a5 | 950dt | DAV_3510 | ⏳ 上游规划（R8：静态 JSON 先离线接入） |
+| a3 | —（待上游扩展） | — | 🔴 无 metadata；U3 该域暂以内部案例标定 |
+
+## 7.7 回写通道（27-10）
+
+复用是双向的：U2 真机跑出的调优结果，经基线库回写 CANNBench——调优前后 HAP 对比进榜单
+（「调优维度评分」），最优实现可反哺 baseline。回写走 PR（cann-bench 侧评审），不走
+自动覆盖——与自进化四纪律一致（进化只产生建议，人审才生效）。
+
+---
+
+# 8. 代码合入触发用例执行
+
+**定位**：把「跑用例」从自觉变成机制（C5）。触发分两个方向：**本仓**（ops-tune 的规则/
+脚本/知识/编排变更）与**算子仓**（被调优算子的 PR 性能回归，27-5）。
+
+## 8.1 本仓触发矩阵（变更路径 → 用例层级 → 阻断性）
+
+CI 按变更路径（diff filter）决定跑哪层——**全量跑一切变更**既慢又浪费 NPU：
+
+| 变更路径 | U0 | U1 | U2 | U3 | 阻断性 |
+|---------|----|----|----|----|--------|
+| `skills/ops-verdict/rules/**` | ✅ 加载校验（负向用例） | ✅ 全量 | ✅ 涉及机制卡/阈值时定向（用例卡 `expect.verdict_known` 引用了被改规则的） | — | **U0+U1 红即不合入** |
+| `skills/ops-verdict/scripts/**` | ✅ 冒烟+单元 | ✅ 全量 | ✅ 定向 | — | U0+U1 |
+| `skills/ops-collect/scripts/**` | ✅ shim 冒烟（三模式 + isolation env/from-prof） | — | ✅ mc2 类定向 | — | U0 |
+| `skills/ops-mechanism/**`、`skills/ops-family/**` | schema/链接/引用一致性校验（mechanism_refs 可达、模板路径存在） | — | ✅ 对应族定向 | — | 校验红即不合入 |
+| `agent/**`（AGENTS / task-prompts / agents） | — | — | ✅ 干跑联调用例（编排层唯一守护层） | — | 干跑红即不合入 |
+| `tests/**` | ✅ 自身回归 | ✅ | — | — | 自身 |
+| 发版 tag / 里程碑出口 | ✅ | ✅ | ✅ 全量真机 | ✅ 全矩阵 | 出口判定数据（门禁纪律第 4 条：验收数据留痕进 `tuning_artifacts/`） |
+
+> 「定向」的实现：U2 用例卡声明 `triggers`（其断言所依赖的规则 ID / 脚本 / 机制卡路径），
+> CI 由 diff ∩ triggers 计算受影响用例集——与 verdict 的「规则-指标绑定契约」同构
+> （**用例-变更绑定契约**：用例声明自己守护什么，变更反向找到该跑的用例）。
+
+## 8.2 三级触发机制
+
+```
+① pre-push hook（开发者本地，<8 min；现状已落地）
+     ops-verdict/evals/smoke/install-hooks.sh 一键安装
+     └─ evals/run_evals.py + evals/smoke/run_smoke.sh  # 快反馈，秒级-分钟级
+② 平台流水线（GitCode 流水线 / Jenkins，PR 必过）
+     ├─ fast-gate（无卡 runner）：U0 + U1              # 阻断
+     └─ targeted-e2e（无卡 runner）：U2 --mode dryrun --filter-by-diff   # 阻断
+③ 定时（夜间 / 发版）
+     ├─ nightly-board（NPU runner 池）：U2 真机全量    # 非阻断：告警 + 趋势看板
+     └─ release-matrix（NPU runner 池）：U3 全矩阵     # 阻断（出口判定）
+```
+
+要点：
+
+- **门禁必须平台侧执行**：pre-push 只是快反馈，不能作为唯一门禁（可被 `--no-verify`
+  绕过）——阻断语义只认平台流水线的退出码（§8.3）；
+- **夜间真机非阻断、发版矩阵阻断**：真机层受设备排队/环境噪声影响，失败当日修复、
+  连续两晚红自动升级为阻断（防「夜夜红没人管」）；发版出口按里程碑门禁纪律「只降范围
+  不放水」，矩阵红线即不放行；
+- 流水线描述的通用形态（触发 + 退出码契约是稳定内核，YAML 形态随平台能力落地）：
+
+```yaml
+# 示意（GitCode 流水线 / Jenkins 通用形态）
+fast-gate:      { run: "python3 tests/run_all.py --layer U0,U1",                 blocking: true,  runner: cpu }
+targeted-e2e:   { run: "python3 tests/run_all.py --layer U2 --mode dryrun --filter-by-diff",
+                                                                          blocking: true,  runner: cpu }
+nightly-board:  { run: "python3 tests/run_all.py --layer U2 --mode board",       blocking: false, runner: npu-pool, cron: daily }
+release-matrix: { run: "python3 tests/run_all.py --layer U3 --matrix full",      blocking: true,  runner: npu-pool, on: tag }
+```
+
+## 8.3 统一 runner 与退出码
+
+> `tests/run_all.py` 为**规划态**统一入口（U2 落地时创建，见 §3.2 现状对照表）；当前
+> U0+U1 无 runner——两条命令直跑（`ops-verdict/evals/run_evals.py` +
+> `ops-verdict/evals/smoke/run_smoke.sh`），退出码即门禁语义。
+
+落地后 `tests/run_all.py` 是唯一 CI 入口，职责：按 `--layer`/`--filter-by-diff` 选层选集 →
+调度（U0/U1 串行快跑；U2 干跑并行，受影响集内按用例卡 `budget` 控时）→ 汇总
+（绿/红/skip-by-env 三态清单 + 各层耗时）→ 按 §2.3 契约退出。退出码透传子 runner
+（U1 即 `skills/ops-verdict/evals/run_evals.py` 的 0/1）。
+
+**skip-by-env 必须显式**：汇总报告列出因环境跳过的用例（退出码 3），PR 界面显示
+「U2-dryrun 42/42 绿，U2-board 0/42 环境跳过（夜间补跑）」——防「全绿」掩盖「没跑」。
+
+## 8.4 NPU runner 池与镜像
+
+| 池 | 用途 | 镜像 |
+|----|------|------|
+| cpu（无卡） | U0/U1/U2-dryrun | 轻量：Python 3.8+ + PyYAML |
+| npu-910b2 | U2-board / U3（a2 域） | 复用 cann-bench `docker/eval`（toolkit 冻结镜像）+ 本仓 tests/ 注入 |
+| npu-950 | U2-board / U3（a5 域） | 同上 |
+
+镜像复用的关键收益：**CANN 版本一致性护栏**（cann-bench staged_eval 已内置「构建与运行
+CANN 版本错配 → 按编译失败终止」的 2026-08 incident 防线）直接继承，不必在本仓重造；
+snapshot 的 `cann_version` HARD_KEY 与镜像内 CANN 版本由 runner 注入对齐。
+
+## 8.5 算子仓侧门禁（27-5：被调优算子的 PR 性能回归）
+
+第二个方向：算子仓（ops-nn / ops-transformer / …）合入代码时，用本套件做「批量回归」
+场景的自动体检（对应 Agent 场景路由的第三类——Phase 1 简化 + 重跑判定 + 对比门禁，
+**不做机制迭代**）：
+
+```
+算子仓 PR
+  → CI job: opstune-regression（本仓套件以依赖形式接入）
+     ① 基线直取：基线库按 HARD_KEYS 匹配（op/soc/cann_version/device/shape/dtype/format/warmup/repeat）
+        匹配不到 → 该 PR 标记 baseline-rebuild，先重建基线
+     ② PR 分支同口径采集（cases = 仓内用例，或 CANNBench 取材适配）
+        精度比对（golden 或仓内基准）→ 任一 case fail：阻断
+     ③ snapshot → delta_compare（口径漂移/精度失败 exit 2；±5% 噪声带三段结论）
+     ④ verdict 复跑：出现新的 critical finding（bound 恶化）→ 告警
+     ⑤ 输出：回归体检报告（逐 case KEEP/劣化/噪声带 + verdict 前后对照）
+```
+
+阻断 vs 告警的边界（防 CI 噪声杀死贡献）：
+
+| 信号 | 动作 | 依据 |
+|------|------|------|
+| 精度回归（任一 case fail） | **阻断** | 精度三道门禁，零妥协 |
+| 口径漂移 / 无法比较 | **阻断**（exit 2） | 跨口径比较禁令 |
+| speedup < 0.95（性能劣化超噪声带） | 默认**告警**（阈值 per 仓可配升为阻断） | 批量回归场景语义：差异算子转单算子调优处理，不直接杀 PR |
+| 新增 critical finding | 告警 + 建议转调优域 | 判定是解释性信号 |
+
+27 年验收：≥1 个算子仓运行此门禁、拦截案例 ≥1；报告数据进校准与缺口
+感知回路（U2 产物回灌同机制，§5.7）。
+
+## 8.6 知识贡献通道共用门禁（27-6）
+
+外部/合作贡献的规则、机制卡、案例走**同一触发矩阵**（§8.1）——「门禁不豁免」的机制化：
+贡献 PR 的路径命中哪行就跑哪层，evals 全绿 + 人审才合入。首个外部贡献（27-6 验收）
+即以本矩阵为验证载体。
+
+---
+
+# 9. 用例治理与生命周期
+
+## 9.1 编号与命名规范
+
+| 层 | 规范 | 例子 |
+|----|------|------|
+| U0 | `S<nn>-<主题>`（smoke）/ `UT-<模块>-<nn>`（unit） | S01-collect-mc2-dryrun / UT-verdict-routing |
+| U1 | `E<nn>-<主题>`（沿用现有） | E11-r-boundary-095 |
+| U2 | `U2-<OP>-<SOC>-<nnn>` + scenario 标签 | U2-GELU-A2-001 / U2-MLA-A5-017（fusion） |
+| U3 | 矩阵坐标 `<family>:<level>:<cards>:<mode>:<soc>:<scenario>` | fa:L4:1:standard:a5:fusion |
+
+## 9.2 新增 / 变更 / 废弃流程
+
+```
+新增：用例卡（含已知答案来源 + triggers 绑定）→ 评审（断言分级是否恰当 / A 类阈值锚点
+      是否有源 / 正反例是否齐）→ 入库 → 纳入触发矩阵
+变更：改断言阈值（A 类）= 改锚点 → 标注校准来源与日期；改期望输出 = 必须先证明被测对象
+      错了或知识更新了（阈值进化纪律：人审 + U1 全绿）——禁止「跑不过就改答案」
+废弃：标 superseded_by 与原因，不删除（历史可追溯：某版本起不再守护 = 知识）
+```
+
+评审四问（U1 规范 §4.2 的体系级版）：① 已知答案哪来的？② 反例在哪？③ 断言分级对吗？
+④ 这个用例守护的变更路径（triggers）是什么？
+
+## 9.3 与 Roadmap 对应及验收指标
+
+| Roadmap 项 | 本文落点 | 验收 |
+|-----------|---------|------|
+| M1.5-5 evals 10→20 | §4.4（E11-E20 清单） | 全绿（CI 阻断语义不变）；每条 L1/L2/L3 规则 ≥1 正 1 反 |
+| 离线干跑框架 | §3（U0）+ §5.5（U2 干跑） | 语法/路由/区间/死代码类问题合入即拦截 |
+| 26-8 测试用例框架 / 27-4 U3 矩阵 | §5 / §6 + §7 取材 | 场景矩阵 ≥80%（26 出口）；100% 已知格（27） |
+| 26-4 CANNBench 标尺 | §7.4 | U2 用例卡含硬件锚定读数；HAP 备用锚点可用 |
+| 27-5 算子仓 CI 门禁 | §8.5 | ≥1 算子仓运行；拦截 ≥1 |
+| 27-6 贡献通道 | §8.6 | 首个外部贡献走完整门禁 |
+| 27-4 缺口感知 | §6.1 空白格 = 排产输入 | 看板周更 |
+
+**体系级北极星联动**：U2 真机用例的执行耗时数据直接支撑 TTFI 度量（用例计时 ≠ TTFI——
+TTFI 是真人打点，但 U2 执行时长是其上界参考）；U2 判定误报统计（findings 与已知 bound
+不符的比例）是 27 年「误报率 <10% 🟡」验收的唯一数据源。
+
+---
+
+## 附录 A：用例卡字段速查（U2）
+
+| 字段 | 必填 | 说明 |
+|------|------|------|
+| `id` / `title` / `scenario` / `soc` | ✅ | 编号见 §9.1；scenario ∈ single_op/fusion/regression/qa |
+| `source.bench_ref` / `source.task` / `source.project` | ✅ | CANNBench 引用（锁定 commit）/ 取材任务 / 被测工程（seed、official-pr、bench:example） |
+| `timing.method/warmup/repeat` | ✅ | 口径适配（§7.6），进 HARD_KEYS |
+| `goal.metric/threshold/anchor` | A 类 ✅ | geomean_speedup / hap / verdict_only；区间 + 锚点来源 |
+| `expect.form` | ✅ | A 已知答案 / B 已知收益 / C 能力边界（§5.2） |
+| `expect.verdict_known/verdict_after` | A 类 ✅ | 基线 bound 与优化后期望 |
+| `expect.precision/report_six_elements/full_case_rows/noise_band_policy` | ✅ | M 类断言开关 |
+| `routing_expect` | fusion ✅ | 污染 → 禁用机制的交叉断言 |
+| `holdout` | 建议 | 泛化集引用（防特判） |
+| `triggers` | ✅ | 用例-变更绑定（§8.1 定向触发） |
+| `budget` / `runner` | ✅ | 干跑/真机时长预算与执行域 |
+
+## 附录 B：触发矩阵速查
+
+```
+rules/**        → U0(加载校验) + U1(全量) + U2(定向)        阻断
+scripts/**      → U0(冒烟+单元) + U1(全量) + U2(定向)       阻断
+collect/**      → U0(shim 冒烟) + U2(mc2 定向)              阻断
+mechanism|family/** → schema/链接校验 + U2(定向)            阻断
+agent/**        → U2(dryrun 联调)                          阻断
+任意 + 发版 tag  → U0 + U1 + U2(全量真机) + U3(全矩阵)      阻断（出口）
+夜间定时        → U2(board 全量)                           告警（连续两晚红→升级阻断）
+```
+
+## 附录 C：CANNBench 引用清单示例（`adapters/cann_bench_ref.yaml`）
+
+```yaml
+schema: opstune.benchref/1.0
+upstream: https://gitcode.com/cann/cann-bench.git
+commit: <锁定 commit sha>            # 上游 bump 须过 U2 干跑全量回归
+tasks_metadata_version: "1.0.0"      # tasks/metadata/VERSION
+hardware: {a2: 910b2, a5: [950pr, 950dt-planned]}
+tasks:                               # 本仓取材的任务清单（路径 + 取材目的）
+  - {path: tasks/level1/gelu,    for: [U2-A, fixture-VEC]}
+  - {path: tasks/level2/softmax, for: [U2-A, reduce 族]}
+  - {path: tasks/level3/grouped_matmul, for: [U2-A, matmul 策略树]}
+  - {path: tasks/level4/mla,     for: [U2-C, FA 降级]}
+  - {path: bench_lab/cv_agent_fa_bench, for: [U3-fa 格]}
+timing_override: {warmup: 5, repeat: 20}   # §7.6 口径适配，与 baseline 采集口径一致
+```
+
+---
+
+*OpsTune 用例构建设计 · 2026-10 · V1.0 ｜ 断言进脚本 · 已知答案 · 门禁机械化*