@cannbot-plugin/cannbot-harness 0.0.0-stage → 0.1.4

package/assets/ops-direct-invoke/skills/ascendc-blaze-best-practice/evals/evals.json

@@ -0,0 +1,234 @@
+{
+  "skill_name": "ascendc-blaze-best-practice",
+  "eval_mode": "text",
+  "evals": [
+    {
+      "id": 1,
+      "title": "Blaze Skill 触发与适用边界",
+      "config": {
+        "max_tokens": 200000,
+        "ascend_platforms": [
+          "A2"
+        ],
+        "eval_mode": "text"
+      },
+      "prompt": "这是 text-only 评测，不要执行外部工具或访问文件系统。我需要判断一个算子开发需求是否适合使用 Blaze MatMul 开发指南：需求一是在 Ascend 950 / DAV_3510 上开发 Basic、Batch、Grouped、Quantized 或 MX MatMul，或在 MatMul 最终输出后接 Vector Epilogue；需求二是在 A2 或 A3 平台开发 MatMul；需求三是在 DAV_3510 上开发纯 Vector 算子。请分别判断这些需求是否在该 Skill 的适用范围内，并说明判断依据。",
+      "expected_output": "回复应正确激活 ascendc-blaze-best-practice，并明确说明：Ascend 950 / DAV_3510 上的 Basic、Batch、Grouped、Quantized、MX MatMul 及 MatMul 后接 Vector Epilogue 属于适用范围；A2/A3 平台和纯 Vector 算子不属于适用范围。回复不得把该 Skill 描述为旧的三模板选型指南。",
+      "expectations": [],
+      "files": []
+    },
+    {
+      "id": 2,
+      "title": "优化构建挂起先核对类型化 Tiling 装载",
+      "config": {
+        "max_tokens": 100000,
+        "ascend_platforms": [
+          "A2"
+        ],
+        "eval_mode": "text"
+      },
+      "prompt": "请加载并使用 ascendc-blaze-best-practice 技能回答。假设场景：一个 Blaze MIX kernel 在 O3 下总是停在 Fixpipe，O0 或 -fno-strict-aliasing 下可完成；Host Tiling 打印正常；Device 端把 TilingData 地址转成 uint32_t*，逐 word 写入含 uint64_t、float 成员的 local TilingData，再读取成员。请按该技能「优化构建运行时挂起与数据损坏排查」中的运行时控制数据取证与 producer/consumer 因果闭合要求，以及 TilingData 类型化装载与编译边界要求，说明定位顺序、根因成立所需证据和正式修复边界。沙箱内没有对应的算子工程、测试数据或运行环境，不需要执行命令或运行测试。",
+      "expected_output": "1. 回复应说明先核对实际执行的构建产物与设备侧 Tiling 装载后的本地字段快照（M/N/K、base shape、控制 producer 次数的字段），并与 Host 序列化字节逐项对照，再建立 `runtime field -> loop bound -> producer count -> consumer count -> terminal wait` 的因果链，不应因终端等待点在 Fixpipe 就直接归因 Fixpipe。\n2. 回复应指出用不兼容的 `uint32_t*` 逐 word 写入后再按 `uint64_t`/`float` 成员读取构成类型别名违规，并说明 O0 与 `-fno-strict-aliasing` 只能作为诊断探针、不能作为最终修复。\n3. 回复应给出正式修复边界：entry 用当前项目生成的 `GET_TILING_DATA_WITH_STRUCT`/`GET_TILING_DATA_MEMBER` 或同一工具链已证明的 typed loader 解包，再把本地 POD 传给 Kernel，公共 Kernel 不直接持有 raw tiling `GM_ADDR`、逐字段复制或用 `reinterpret_cast` 掩盖。",
+      "expectations": [],
+      "files": []
+    },
+    {
+      "id": 3,
+      "title": "区分硬件 base shape 与逻辑 tail",
+      "config": {
+        "max_tokens": 100000,
+        "ascend_platforms": [
+          "A2"
+        ],
+        "eval_mode": "text"
+      },
+      "prompt": "请加载并使用 ascendc-blaze-best-practice 技能回答。假设场景：Host tiling 使用 baseM=min(M,preferredBaseM)。两个被标为 K-tail 和 N-tail 的失败 case 共享同一个小 M，且这个 M 小于当前 Block/Copy 已证明的硬件粒度；把 M 提升到合法粒度后对应 case 通过。开发者仍认为分别是 K 和 N tail 问题。请按该技能「Tiling 选择与 Scheduler Params 合同」中「硬件 base shape 与逻辑 tail」小节审查这个结论，并按该文档「PLAN 接线与验证」小节的验证矩阵给出设计和验证要求。沙箱内没有对应的算子工程、测试数据或运行环境，不需要执行命令或运行测试。",
+      "expected_output": "1. 回复应指出两个失败 case 的共同变量是小 M、不能按 K-tail/N-tail 标签分别归因，并区分满足 Block/Copy 粒度与对齐约束的硬件 base shape 与 Scheduler/`curM/curN/curK` 表达的逻辑 tail，禁止用 `min(logical_shape, preferred_base)` 把硬件 base 缩成不合法的小 tail。\n2. 回复应说明具体对齐/粒度值不能从单个算子样例的常数推广，必须来自本次选定的 Block/Copy/Scheduler 源码或 capability witness，并在 DESIGN 中记录 consumer 与合法谓词。\n3. 回复应给出验证要求：对每个有硬件粒度约束的轴至少覆盖小于粒度、恰好等于粒度、`base+1` 和 multi-tile；若目标为 Grouped 场景，还应覆盖空分组。",
+      "expectations": [],
+      "files": []
+    },
+    {
+      "id": 4,
+      "title": "CTest 零测试与交付状态一致性",
+      "config": {
+        "max_tokens": 100000,
+        "ascend_platforms": [
+          "A2"
+        ],
+        "eval_mode": "text"
+      },
+      "prompt": "最终验证中 ctest 返回码为 0，但日志显示 No tests were found。精度报告写 Full PASS，问题恢复记录写根因已修复，DESIGN 和 PLAN 仍写 BlockMmad blocked。请判断能否交付，并列出门禁，不执行工具。",
+      "expected_output": "不能交付。应先用 ctest -N 或等价命令证明预期测试名称和非零数量，再运行本次 clean build 产物；零测试即失败。还必须交叉核对 DESIGN、PLAN、README、精度/性能报告、问题恢复记录和 execution record，PASS、BLOCKED、unverified、NOT_EVALUATED 状态冲突即失败。",
+      "expectations": [],
+      "files": []
+    },
+    {
+      "id": 5,
+      "title": "RNE half-tie mismatch 不得改等价 GELU",
+      "config": {
+        "max_tokens": 100000,
+        "ascend_platforms": [
+          "A2"
+        ],
+        "eval_mode": "text"
+      },
+      "prompt": "请加载并使用 ascendc-blaze-best-practice 技能回答。假设场景：Full 结果只差一个接近 INT8 half-tie 的值，但 device workspace 和 yScale 尚未对比。开发者要求替换等价 GELU 公式或全局放宽误差阈值。请按该技能中 GLU 的公式与参数语义冻结要求（等价实现替换的授权条件），以及 per-token quant 的 RNE 边界分阶段诊断与同源 normalized 资产要求（含验收合同边界），说明应如何处理。沙箱内没有对应的算子工程、测试数据或运行环境，不需要执行命令或运行测试。",
+      "expected_output": "1. 回复应说明保留锁定的 Golden、GELU 公式和 dtype 路径，不接受用替换等价 GELU 公式或全局放宽误差阈值来消除该 mismatch；等价实现只有在用户合同允许且已证明 dtype 顺序与特殊值行为一致时才能替换，不能用放宽容差掩盖问题。\n2. 回复应要求先在相同输入、Tiling 和同一份 Golden 源下比较 device FP workspace、同源归一化值（normalized = activated / scale）、yScale 与 y，据此把 mismatch 归因到 MatMul/workspace、absmax/scale 或 device division/RNE/cast 路径，并先排除布局、地址/stride 与同步等非舍入根因。\n3. 回复应说明按 half-tie 归类有界 mismatch 必须以正式验收合同允许为前提；mismatch 比例、half 距离和 scale 阈值属于目标算子验收合同，不得写成通用 Skill 或可复用资产默认值。",
+      "expectations": [],
+      "files": []
+    },
+    {
+      "id": 6,
+      "title": "UB 清零与 MTE2 DMA 不能并发写同一 slot",
+      "config": {
+        "max_tokens": 100000,
+        "ascend_platforms": [
+          "A2"
+        ],
+        "eval_mode": "text"
+      },
+      "prompt": "请加载并使用 ascendc-blaze-best-practice 技能回答。假设场景：设备上 GM 的 x_scale 明确非零，但经过 MTE2 搬入 UB 后，VF 先执行 ZeroUb，最终 yScale 落到 floor；小 shape 偶尔通过。请按该技能「Blaze 同步模式」中「每个 UB staging slot 的写者都必须参加生命周期」「epilogue 循环中的正确 barrier 位置」和「交付前同步闭合检查」的要求，定位最早失败边界并给出修复边界，不要修改 GELU、Golden 或放宽误差。沙箱内没有对应的算子工程、测试数据或运行环境，不需要执行命令或运行测试。",
+      "expected_output": "1. 回复应把根因归到 UB staging slot 的写者/生命周期竞态：`ZeroUb` 或其他 VF store 也是该 slot 的真实写入者，不能与正在进行的 MTE2 写入并发。\n2. 回复应给出修复边界：按 slot 先等待旧 Vector 写者完成再发起 MTE2 写入（V→MTE2 回收反向依赖），MTE2 完成后再建立 V 读取前的正向交接，并为循环复用记录首轮预发、复用等待和尾轮 drain；`MTE3→V` 只能等待上一轮或 Init 已发出的 `SetFlag`，不能在首轮插入没有 producer 的同轮 wait。\n3. 回复应说明不能用 `PipeBarrier`、单次通过或数值 floor 掩盖该竞态，并应指出需保留同一设备上已确认的非零 scale、首个稳定失败边界与重复运行结果作为可核验证据。",
+      "expectations": [],
+      "files": []
+    },
+    {
+      "id": 7,
+      "title": "MIX AIV 索引必须按 task ratio 归一化",
+      "config": {
+        "max_tokens": 100000,
+        "timeout": 900,
+        "ascend_platforms": [
+          "A2"
+        ],
+        "eval_mode": "text"
+      },
+      "prompt": "请加载并使用 ascendc-blaze-best-practice 技能回答。假设场景：AIC 与 AIV 分开编译但由同一 MIX binding 启动；AIV 直接用 `GetBlockIdx()` 作为逻辑 AIC tile，导致它与 AIC 看到的 tile 不一致。请按该技能中 MIX 参与者行 ownership 与物理 index 语义冻结的要求，说明何时可用 `GetBlockIdx()/GetTaskRation()`，何时还需要 `GetSubBlockIdx()`，`GetBlockNum()` 的总量/分区语义应如何确认，以及应覆盖哪些验证组合。沙箱内没有对应的算子工程、测试数据或运行环境，不需要执行命令或运行测试。",
+      "expected_output": "1. 回复应说明只有在当前源码/编译 witness 证明 AIC 与 AIV 使用相同的物理任务排列时，AIV 才能用 `GetBlockIdx()/GetTaskRation()` 恢复与 AIC 相同的逻辑 tile 索引，且这只完成 AIC tile 的归一化、不代表 Vector rank 唯一。\n2. 回复应说明需要唯一 Vector rank 时要结合当前 entry 已证明的 `GetSubBlockIdx()` 语义，且 `GetBlockNum()` 的总量/分区语义必须由当前源码或最小 probe 证明并记录在 DESIGN/PLAN 中，不能按命名或历史实现猜测。\n3. 回复应给出验证要求，覆盖 AIC/AIV 对照、ratio 边界（含 R=1 等取值）与 sub-block 组合，并覆盖空任务或 inactive lane。",
+      "expectations": [],
+      "files": []
+    },
+    {
+      "id": 8,
+      "title": "CV1+V2 使用 Epilogue tuple 与全核交接",
+      "config": {
+        "max_tokens": 100000,
+        "ascend_platforms": [
+          "A2"
+        ],
+        "eval_mode": "text"
+      },
+      "prompt": "开发者为 GMM dequant+SwiGLU+per-token quant 新建了 `GroupMatmulKernelDequantSwiGluPertokenQuant`，把 V1、V2 追加为 `GemmUniversal` 新模板参数，并准备在所谓通用的 C+V1+V2 Kernel 内固化 GLU group traversal、双分支 view 和 `Q=N/2`。V1 后只执行 `PipeBarrier<PIPE_ALL>()`，各 AIV 再沿原 N tile 做 quant；Host 只保留一个 device entry，在 device 内按 UB 大小选择 single-pass/two-pass。请按当前 Skill 审查并给出正确组装，不执行工具。",
+      "expected_output": "必须拒绝算子专用 Kernel 类、旧的 `GroupMatmulKernelGluFused` 组装和新增/改排 `GemmUniversal` 模板参数。应把 V1/V2 绑定为既有 `BlockEpilogue_` 参数上的 `AscendC::Std::tuple<V1,V2>`，使用当前 `GemmUniversal<ProblemShape,BlockMmad,EpiloguePipeline,BlockScheduler>` specialization。通用组合层复用已经选定并完成 final drain 的 C+V1 Kernel，再由已证明的 AIV 参与者执行文件级 `{PIPE_ALL,PIPE_ALL}` `SyncAllConfig` 的 AIV-only `SyncAll`，按 `realM` 完整逻辑行重分配并调用 V2；它不得拥有 GLU group traversal、双分支 view 或 `Q=N/2`，这些属于具体 C+V1。原 C+V1 specialization 还必须排除 Epilogue tuple，避免与通用 tuple specialization 同时匹配。本核 `PipeBarrier<PIPE_ALL>` 不能替代跨核交接。Host selector 必须选择两个独立静态 tuple Kernel entry，不能在 device 隐藏资源分支；具体 entry、Host 调用和 Launcher 位于目标工程。",
+      "expectations": [],
+      "files": []
+    },
+    {
+      "id": 9,
+      "title": "Typed launcher 与 verifier 必须分别闭合",
+      "config": {
+        "max_tokens": 100000,
+        "ascend_platforms": [
+          "A2"
+        ],
+        "eval_mode": "text"
+      },
+      "prompt": "请加载并使用 ascendc-blaze-best-practice 技能回答。假设场景：直接按二进制名称查找 Kernel 成功，但设备运行随后出现指令异常；批处理脚本返回 0，却没有保存本 case 的 verifier 返回码。开发者想把符号查找和脚本返回码作为 PASS。请按该技能中「启动 ABI 的最小穿刺」与「Launch 与 verifier 的证据隔离」的要求，给出正确的 ABI 穿刺和交付证据。沙箱内没有对应的算子工程、测试数据或运行环境，不需要执行命令或运行测试。",
+      "expected_output": "1. 回复应指出符号 lookup 成功只能证明名称可查找，不能证明类型化 entry 的入口修饰符、GM 参数顺序、TilingData 按值/指针/引用传递、POD 布局或设备指令路径；批处理脚本的零返回码也不能作为 PASS 依据。\n2. 回复应给出 ABI 穿刺：用同一版本 ASC witness 编译最小 typed launch 并完成一次 device-visible 运行以闭合首个 ABI/设备边界，修复后 clean rebuild，并在 execution_record 保留实际 entry、命令、目标架构、CANN 版本和返回码。\n3. 回复应要求每个 case 独立保留 launch RC、verifier RC、输入、raw output、stdout/stderr 和超时/终止状态；没有 verifier 结果或 verifier 未执行时状态是 `incomplete` 而不是 PASS，批处理零返回码不能补旧目录输出或历史 verifier 证据。",
+      "expectations": [],
+      "files": []
+    },
+    {
+      "id": 10,
+      "title": "逻辑到物理 paired buffer 必须有独立 witness",
+      "config": {
+        "max_tokens": 100000,
+        "timeout": 1800,
+        "ascend_platforms": [
+          "A2"
+        ],
+        "eval_mode": "text"
+      },
+      "prompt": "用户合同暴露逻辑 [K,N] weight 和 scale，但 MX GLU 的设备输入需要 act/gate paired、对齐和 padding 的物理 buffer。开发者想让 gen_data.py 直接写一份 physical 文件，Launcher 只按文件名 H2D，并把逻辑 Golden 作为精度依据。请给出 Skill 级的 ABI、Golden 和启动门禁，不要执行工具。",
+      "expected_output": "1. 回复应保持逻辑 weight/scale 为外部 ABI，并在 `abi_crosswalk` 中记录逻辑到物理转换的 shape、byte span、offset/stride、padding 和首个设备消费者，不能把预生成的 physical 文件直接当作逻辑合同。\n2. 回复应由独立于 Launcher adapter 的 data path 生成 physical witness，并要求 Launcher 在启动 Kernel 前按冻结转换从本 case 逻辑输入重新生成待 H2D buffer、执行 shape/size 与逐字节一致性检查，不一致时在 Host ABI/I/O 边界阻断。\n3. 回复应说明 Golden 必须使用最终实际 H2D 的 physical bytes 解码，不能只使用逻辑或量化前输入（没有逻辑到物理转换时逻辑 bytes 本身就是事实源、不额外伪造 witness）；具体 pack 公式、tile、padding 值和 hash 保留在项目 DESIGN/PLAN。",
+      "expectations": [],
+      "files": []
+    },
+    {
+      "id": 11,
+      "title": "FP16 GMM Golden 必须逐组写回并遵守 cumsum",
+      "config": {
+        "max_tokens": 100000,
+        "ascend_platforms": [
+          "A2"
+        ],
+        "eval_mode": "text"
+      },
+      "prompt": "用户要求 FP16 GMM + SwiGLU，`group_list` 是长度为 E 的 cumsum 端点数组（`group_list[i]` 为第 i 组末端点），包含一个空 expert。Golden 在循环内覆盖 `mm = x[s:e] @ weight[g]`，循环结束后才 split/计算 SwiGLU；旧签名还带有没有参与公式的 `x_scale/weight_scale`。请给出修复后的 Golden 合同和审查结论，不要执行工具。",
+      "expected_output": "1. 回复应校验 `group_list` 的 cumsum 编码（长度 E 的端点数组，`group_list[i]` 为第 i 组末端点）：非递减、首值非负、末值等于 M，并用 `start_i = 0 if i == 0 else group_list[i-1]`、`end_i = group_list[i]` 取区间端点，说明相邻端点相等表示合法空 group（跳过该组、不创建 MM tile）。\n2. 回复应为每个非空 group 立即计算并写回 `y[start_i:end_i]`，不能只在循环内复用一个局部 `mm` 导致只保留最后一个 group，并按全局 N/2 切分 act/gate。\n3. 回复应给出 Golden 合同：`x[start_i:end_i]` 与 `weight[g]` 以 FP32 计算并返回 FP32 Tensor（如 `torch.matmul(x[s:e].float(), weight[g].float())`、输出 `dtype=torch.float32`）；签名中未进入冻结公式的 `x_scale/weight_scale` 不得隐式引入 dequant/quant；Golden 后端、累加 dtype、非有限值分类和公式顺序必须与 DESIGN/PLAN 的语义合同一致。",
+      "expectations": [],
+      "files": []
+    },
+    {
+      "id": 12,
+      "title": "生产 GMM 不得绕过 source-backed BlockMmad assembly",
+      "config": {
+        "max_tokens": 100000,
+        "timeout": 900,
+        "ascend_platforms": [
+          "A2"
+        ],
+        "eval_mode": "text"
+      },
+      "prompt": "一个手写的 MIX 入口只调用 BlockMmad，设备在 aclrtSynchronizeStream 挂起；同版本 Blaze 的 GemmUniversal、Scheduler 和 ownership wrapper 尚未接入。开发者想保留这个入口作为正式实现，并认为 BlockMmad 能编译就是 ABI 已闭合。请给出 Skill 级判断，不要执行工具。",
+      "expected_output": "1. 回复应判定「BlockMmad 能编译 = ABI 已闭合」不成立：编译只证明接口存在，不能证明运行期 ABI 与调用前提已闭合，`aclrtSynchronizeStream` 挂起即为 ABI 未闭合的运行期证据，单次 launch 返回也不能反推已闭合。\n2. 回复应把手写 BlockMmad 入口归为隔离诊断而不是生产路线：它绕过 source-backed dispatch、Scheduler、Block/Epilogue 生命周期和 AIC/AIV 参与者协议。\n3. 回复应说明正式实现必须恢复当前 Investigation 绑定的完整 assembly（`GemmUniversal`/Scheduler/ownership wrapper）；MIX 还要说明每个逻辑 tile/输出行的唯一 writer、物理 block/task-ratio/sub-block 映射和完成通知。",
+      "expectations": [],
+      "files": []
+    },
+    {
+      "id": 13,
+      "title": "按请求目的路由到对应流程（关键能力）",
+      "config": {
+        "max_tokens": 100000,
+        "ascend_platforms": [
+          "A2"
+        ],
+        "eval_mode": "text"
+      },
+      "prompt": "我要用 Blaze 在 Ascend 950 上开发一个 MatMul 算子。请分别说明：1) 明确要求从零完整开发算子时走哪几步；2) 只要求算子设计、方案分析并输出设计文档时走哪些步骤；3) 只做咨询/解释/评审/排障时如何执行。",
+      "expected_output": "应说明：明确要求开发算子时走 Step 1→2→3→4 完整流程；只要求设计时走 Step 2→3；咨询/解释/评审/排障时只读取相关 references。不得按调用者身份增加模式，也不得因发现已有 DESIGN/PLAN 而单独进入 Step 4。",
+      "expectations": [],
+      "files": []
+    },
+    {
+      "id": 14,
+      "title": "路线模型判定（关键能力）",
+      "config": {
+        "max_tokens": 100000,
+        "ascend_platforms": [
+          "A2"
+        ],
+        "eval_mode": "text"
+      },
+      "prompt": "Blaze 开发中如何决定实现路线选择 blaze_native、blaze_custom 还是 unsupported？各自的判定依据是什么？",
+      "expected_output": "应说明：官方 Blaze 覆盖全部 required partitions 时选 blaze_native 且不读取场景注册表；存在证据闭合的 native gap 且场景唯一命中时选 blaze_custom；证据充分但场景零命中或多命中时选 unsupported。并说明 native gap 不是 SIMT fallback 的授权。",
+      "expectations": [],
+      "files": []
+    },
+    {
+      "id": 15,
+      "title": "计算执行原则（关键能力）",
+      "config": {
+        "max_tokens": 100000,
+        "ascend_platforms": [
+          "A2"
+        ],
+        "eval_mode": "text"
+      },
+      "prompt": "我计划把 Blaze 算子里的部分计算步骤（如元素级处理）放到 Host 侧实现，Kernel 里只做 MatMul。这样是否允许？为什么？",
+      "expected_output": "应说明全部计算步骤必须在 device 侧单一 Kernel 中完成，Host 侧只负责数据准备、Tiling 计算、Kernel launch 和结果搬运；不得通过把非 matmul 计算步骤排除到 host 侧来缩小 native_gaps 的判定范围，该原则适用于 blaze_native 与 blaze_custom 全部路线。",
+      "expectations": [],
+      "files": []
+    }
+  ]
+}

package/assets/ops-direct-invoke/skills/ascendc-blaze-best-practice/references/blaze-investigation/assembly-recovery-method.md

@@ -0,0 +1,106 @@
+# Blaze 组装方案恢复方法
+
+本文只对“Blaze 源码调查”阶段已发现的 `candidate_evaluation` 恢复 concrete Blaze 组装方案。Blaze 组装方案是同一真实入口或 concrete 实例化证实的组件链，不是按组件名称拼接出的笛卡尔积。
+
+## 1. 输入与边界
+
+每次恢复必须绑定：
+
+```text
+candidate_evaluation_id
+candidate_id
+partition_id
+seed_or_expansion_source
+required_requirement_ids
+required_constraint_ids
+```
+
+本阶段只判断组装结构是否闭合。TilingData 全字段语义、Tensor API、物理数据和资源合同在 Dependency Trace 阶段闭合；不得因这些依赖尚未完成而把一个结构完整的 Blaze 组装方案改成 partial。
+
+## 2. Concrete Witness
+
+按以下优先级寻找 witness：
+
+1. example、UT 中完整 using/alias/实例化和调用；
+2. 真实 Kernel wrapper 中的 concrete 模板实例化；
+3. 同一 Kernel 入口内可完整还原的类型链、specialization 和调用顺序。
+
+孤立公开类定义、相似文件名、注释、不同入口中的片段或手工猜测模板参数都不是 concrete witness。没有 example/UT 并不自动阻塞，只要真实 wrapper/入口已经完整实例化。
+
+## 3. 恢复顺序
+
+沿同一 witness 的实际关系恢复：
+
+```text
+Kernel entry / wrapper
+  -> dispatch / specialization / Policy
+  -> BlockMmad
+  -> BlockScheduler
+  -> actual Epilogue, if present
+  -> TilingData / Params type binding
+```
+
+逐层记录：
+
+- 具体符号、namespace、头文件和定义位置；
+- concrete specialization、模板参数和 `ScheduleType`；
+- 架构/编译守卫和必要 include；
+- caller/callee、类型引用和实例化关系；
+- Kernel 入口修饰符、参数角色和调用顺序；
+- Policy、Block、Scheduler、Epilogue 与 TilingData/Params 的实际绑定；
+- 当前 role/partition 投影出的 topology、numeric、dtype、layout、transpose、shape 和功能约束。
+
+Witness 中实际不存在的层可以标记 `not_applicable`，但必须由入口和类型链直接证明。空白、搜索未命中或“通常不需要”不能代替 N/A 证据。
+
+## 4. Blaze 组装方案合同
+
+每个 evaluation 写入：
+
+```text
+assembly_witness
+  witness_id
+  witness_kind
+  entry_symbol
+  concrete_instantiation
+  source_refs
+
+assembly_members
+  member_role
+  concrete_symbol
+  specialization
+  source_ref
+  relationship_ids
+  status: resolved | not_applicable | unknown | conflict
+
+assembly_status: complete | partial
+structural_gaps
+```
+
+字段含义：`assembly_witness` 表示 Blaze 组装方案真实证据；`assembly_members` 表示该组装方案的具体成员；`assembly_status` 表示组装方案结构状态。字段名保持与报告和 DESIGN 兼容。
+
+`assembly_status=complete` 当且仅当：
+
+- candidate 和单一 partition 绑定明确；
+- 存在 concrete witness；
+- 该 witness 实际需要的每个成员及其关系均为 resolved/N/A；
+- concrete specialization、入口绑定和架构守卫无 unknown/conflict；
+- 没有跨 witness 拼接成员。
+
+其他情况均为 partial。`complete` 只表示结构链闭合，不等于 candidate ready，也不表示设备、精度或性能通过。
+
+## 5. 组合需求约束
+
+- Grouped Plain、Grouped Quantized、Grouped MX、Batch Quantized 等激活 partition 必须各自由匹配完整画像的 concrete witness 支撑。
+- 不同候选组装方案评估可以使用不同 witness；是否足以覆盖同一项目需求由 Step 3 根据精确合同判断。
+- 普通 MatMul candidate 内实际存在官方 AIV/Epilogue 只是一项 Blaze 源码事实，不推导项目路线。
+- 非组装方案证据对象不进入本方法。
+
+## 6. 产物与停止条件
+
+每条 evaluation 必须得到 `complete` 或 `partial`，并列出 evidence IDs、结构缺口和下一阶段输入：
+
+- complete：进入 [Dependency Trace](dependency-trace-method.md) 闭合直接依赖；
+- partial 且冻结扩展尚未使用、并满足 Blaze 源码调查 的扩展条件：执行唯一一次有限扩展；
+- partial 且无合法扩展：保留 partial/unknown，不按名称补齐。
+
+本阶段不得直接评定 `candidate_evaluation_readiness=ready`，不得选择项目候选，也不得创建 recommendation。

package/assets/ops-direct-invoke/skills/ascendc-blaze-best-practice/references/blaze-investigation/dependency-trace-method.md

@@ -0,0 +1,140 @@
+# 依赖追溯方法
+
+本文闭合已发现 Blaze 组装方案和语义证据对象的直接依赖。只沿实际调用、类型引用和已声明源码读取边界追踪；不重新发现候选、不建立 Tensor API 百科、不匹配场景、不选择项目实现。
+
+## 1. 追踪顺序
+
+对每个 candidate evaluation 或 evidence subject 按数据流执行：
+
+1. 从 Kernel/subject 入口识别真实输入、输出、TilingData、Params、workspace 和 dispatch。
+2. 沿 concrete 类型链找到 Scheduler、Policy、Block、实际 Epilogue 和 API 消费点。
+3. 闭合 TilingData 到各层 Params 的逐字段映射和 device 侧字段语义。
+4. 从实际 API 调用点追到唯一定义/specialization 与 Routing。
+5. 归一化逻辑对象、设备物理表示、地址单位、资源和生命周期。
+6. 仅在源码不能独立解释调用语义时读取对应官方 API 文档。
+7. 将观察值、限制、unknown 和 evidence IDs 写回对应需求项。
+
+直接依赖追踪不消耗候选扩展额度。无法确认的 required 原子问题保持 `unknown`；不得用默认值、Asset、旧 recipe 或相似算子填充。
+
+## 2. Kernel 与 Device ABI
+
+每个 candidate evaluation 记录：
+
+- Kernel 符号、入口修饰符、concrete specialization 和架构守卫；
+- GM 参数顺序、类型、方向、可选性和空值语义；
+- shape、batch/group、scale、mode、layout、transpose 和 dispatch 信息的位置；
+- TilingData 传递方式、字段类型、单位和 Params 映射；
+- grid/used core 的来源；
+- workspace 地址、大小单位、初始化、生命周期和归并关系；
+- 输出是 final/partial、目的地和完成时机。
+
+入口声明、host 传参和 device 消费必须逐项对应。只看到类型名或未实例化模板不能闭合 ABI。
+
+## 3. Scheduler Params 语义
+
+对 Scheduler、BlockMmad、Policy、Kernel 和实际 Epilogue 消费的字段记录：
+
+```text
+candidate_evaluation_id_or_subject_id
+partition_id
+field_path
+field_type
+unit
+consumer
+semantics
+applies_when
+legal_domain_or_predicate
+cross_field_constraints
+shape_and_core_dependencies
+tiling_data_mapping
+observed_default_or_example
+observed_value_scope
+evidence_ids
+evidence_status: source_observed | documented | example_assembled | conflict | unknown | unsupported
+```
+
+至少解释字段对 tile、tail、core、offset、workspace、final/partial 和输出路径的影响。实际未消费字段用直接证据标记 `not_applicable`；示例值仅记录观察范围，不能成为项目默认值。
+
+Blaze 源码没有可直接复用的 host Tiling 时，记录 `not_provided` 和已闭合的 device 语义。真正影响 Step 3 的是字段单位、适用条件、合法域、交叉约束或 TilingData 到 Params 映射未知。
+
+## 4. Tensor API 调用闭合
+
+每个实际调用点记录：
+
+| 字段 | 内容 |
+|---|---|
+| Caller | candidate/subject、组件、符号和调用位置 |
+| API | concrete 符号、参数、返回值和调用目的 |
+| Definition | 唯一定义或 specialization 位置 |
+| Routing | Pattern、location、layout、dtype、架构和 trait 条件 |
+| Units | shape、extent、offset、stride、alignment 的单位 |
+| Effects | Copy/Mmad/Fixpipe/Layout、同步、资源和输出影响 |
+| Status | `source_observed`、`documented`、`conflict`、`unknown`、`unsupported` |
+
+名称命中或公共说明不等于调用点解析。定义、specialization 或 Routing 不能唯一确定时保留 `unknown`，并绑定受影响 requirement IDs。
+
+## 5. 物理数据合同
+
+对每个输入、输出和 metadata Tensor 记录：
+
+| 类别 | 必填事实 |
+|---|---|
+| 数学对象 | 角色、逻辑 shape、逻辑 dtype、公式轴 |
+| 设备对象 | 存储 dtype、元素/打包字节、物理 shape、layout pattern |
+| 变换 | transpose、ND/NZ、padding、alignment、packing、broadcast |
+| 地址 | stride、pitch、slice、offset 及单位 |
+| 有效范围 | tail、padding 是否参与计算、final/partial 范围 |
+| 绑定 | candidate/API/Tiling/Params 字段和 evidence IDs |
+
+逻辑值与设备字节必须分开。Scale、zero-point、group metadata、packed FP4 等对象分别建立合同，不允许只记录一个笼统“支持量化/分组”字段。
+
+## 6. 额外 I/O 与输出数据流证据
+
+需求中有额外 operand、输出后逐元素处理或 broadcast 时，按已发现的真实候选追踪相关对象：
+
+```text
+subject_id
+related_requirement_ids
+producer_and_consumer
+logical_and_physical_shape
+layout_dtype_and_location
+index_stride_offset_units
+completion_and_lifecycle
+adapter_or_sync_binding_if_present
+source_refs
+evidence_status
+```
+
+这只记录 Blaze 源码事实。不得从需求名称推导 Block 输出、C+V、Epilogue adapter 或同步机制存在；也不得将这些对象打包成场景证据、选择 MemBase/RegBase 或判断 custom 路线。
+
+## 7. 源码关系账本
+
+只记录源码明确存在的关系：
+
+```text
+relationship_id
+relationship_kind: same_entry | caller_callee | type_reference |
+                   shared_params | shared_tiling_field | explicit_dispatch |
+                   explicit_prohibition
+left_object_id
+right_object_id
+source_refs
+observed_constraint
+```
+
+缺少显式 binding 不等于不兼容。Step 2 不枚举候选笛卡尔积，也不把接口适配判断写成 source relationship；这些设计选择留给 Step 3。
+
+## 8. 闭合门禁
+
+Dependency Trace 完成时必须能对每个已调查对象回答：
+
+```text
+TilingData -> Params -> consumers
+Scheduler field -> semantics/unit/legal domain
+API call -> unique definition/specialization/Routing
+logical tensor -> physical tensor -> address units
+Kernel entry -> GM ABI/grid/workspace/output lifecycle
+extra I/O/output dataflow -> observed facts or unknown
+```
+
+所有适用的 source questions 都必须有原子状态和证据。缺失 Blaze 源码 host Tiling 不构成事实缺口；缺失 device 语义、合法域、ABI 或 Routing 记录为 `partial` 或 `unknown`。完成后交给[调查合同审计方法](design-contract-method.md)核验，不在本阶段作候选推荐。

package/assets/ops-direct-invoke/skills/ascendc-blaze-best-practice/references/blaze-investigation/design-contract-method.md

@@ -0,0 +1,78 @@
+# Investigation 合同审计方法
+
+本文只审计前述阶段已经记录的 Blaze 源码事实。它不发现新候选、不补搜源码、不推荐方案、不匹配场景，也不产生项目路线或可执行性结论。
+
+## 1. 原子状态与边界
+
+```text
+coverage = out_of_scope | indexed | deep
+candidate_result = found | not_found | unknown
+subject_result = found | not_found | unknown
+evidence_basis = {source_observed, documented, example_assembled}
+evidence_status = source_observed | documented | example_assembled |
+                  not_applicable | conflict | unknown | unsupported
+assembly_status = complete | partial
+object_readiness = ready | partial | blocked | unknown
+```
+
+- `coverage` 只表达调查深度；`deep` 可与 `partial`、`unknown` 或 `blocked` 共存。
+- `evidence_basis` 是来源集合，`device_verified` 不属于 Step 2。
+- `not_applicable` 必须由 `applies_when=false` 和来源支持；不能用作跳过未调查事实的标记。
+- `unsupported` 只用于 Blaze 源码或官方约束明确拒绝准确对象；`not_found`、缺失目录、未调查和 `unknown` 均不是 `unsupported`。
+- `object_readiness` 只能描述一个候选或证据对象的本地闭合度，不能提升为需求级支持判断。
+
+对象本地聚合顺序：明确 conflict 或明确拒绝影响必需事实时为 `blocked`；身份、适用性、specialization、binding 或 Routing 无法判断时为 `unknown`；对象身份明确但结构或必需事实未闭合时为 `partial`；其余才为 `ready`。
+
+## 2. Blaze 组装方案审计
+
+每个 candidate evaluation 的记录必须能机械核验：
+
+1. 绑定单一 concrete candidate、真实入口和明确 partition；
+2. 有 concrete witness，且 `coverage=deep`、`assembly_status=complete`，或准确说明为何为 partial；
+3. Kernel/Policy/BlockMmad/BlockScheduler/可选 Epilogue/TilingData/Params 成员来自同一真实调用链；
+4. 适用的硬约束、TilingData/Params、Tensor API Routing、物理数据、device ABI、资源/workspace 和输出生命周期各有事实、明确限制或 unknown；
+5. 任何 conflict、unknown、明确拒绝都绑定 requirement IDs 和 source refs；
+6. 不使用跨 partition witness、Asset、历史项目或猜测模板参数补齐缺口。
+
+完整 candidate 是 Step 3 的输入材料，不是“官方完整支持”结论。不同 candidate 能否覆盖同一需求、能否组合或应选哪一个，只能由 Step 3 根据精确接口和约束判断。
+
+## 3. 依赖与物理数据审计
+
+每个已声明 source question 必须得到下列三种之一：
+
+1. 直接 Blaze 源码事实及其 source refs；
+2. 来源绑定的已观察限制或明确拒绝；
+3. `unknown`，包括已搜索边界、缺少的关系和受影响 requirement IDs。
+
+逐项检查：
+
+```text
+TilingData -> Params -> consumer
+Scheduler field -> semantics/unit/legal domain
+API call -> definition/specialization/Routing
+logical tensor -> physical representation -> address units
+Kernel entry -> GM ABI/grid/workspace/output lifecycle
+extra I/O/output dataflow -> producer/consumer/lifecycle facts
+```
+
+没有现成 host Tiling 只需如实记录；若 device 侧字段语义和合法域已闭合，它不是报告阻塞项。未知 Params/ABI/物理地址语义必须保留为 unknown，不能以示例观察值替代。
+
+## 4. 报告完整性审计
+
+关闭报告前确认：
+
+- 需求投影、demand partitions、hard constraints 和 source questions 可追溯到用户需求；
+- 每个 candidate/subject 的 ID、适用范围、状态和来源唯一且可回溯；
+- 已读取根、未读范围、候选扩展和停止位置已记录；
+- 明确限制与未闭合事实没有混用；
+- `out_of_scope` 只表示未调查，不表示不支持；
+- 不存在场景 ID、场景匹配、bundle、组合 option、官方支持状态、交接状态或项目路线结论；
+- 若有 `supplement_scope`，其 `attempt` 仅为 1，问题是语义化且不含场景信息。
+
+若报告中仍有影响 Step 3 判断的 unknown，保持其事实状态。报告仍可冻结；Step 3 决定是否需要该事实并发起唯一补充，不能由本审计方法把 unknown 改写成“不支持”。
+
+## 5. Step 3 消费规则
+
+Step 3 可以从报告读取：需求投影、候选组装方案、局部结构状态、依赖与物理/ABI事实、已观察限制、明确拒绝、未闭合事实、证据账本和读取边界。
+
+Step 3 不能把 `indexed`、`out_of_scope`、`not_found` 或 `unknown` 当作完整方案证据；也不能要求 Step 2 预先提供项目路线、候选组合、场景信息或支持结论。若现有事实不足以判断精确需求，Step 3 只能写入一次语义化 `supplement_scope` 并返回 Step 2。