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

package/assets/ops-direct-invoke/skills/ascendc-blaze-best-practice/references/scenarios/elementwise-broadcast-epilogue-fusion/elementwise-broadcast-epilogue-fusion-development.md

@@ -0,0 +1,202 @@
+# Elementwise/Broadcast Epilogue Fusion 开发指导
+
+本文是 Step 3 在场景 DESIGN 冻结后编译项目 `operators/<operator_name>/docs/PLAN.md` 的方法输入，不是 Step 4 的独立设计入口。本文不重新匹配场景、选择 MatMul Blaze 组装方案、选择 MemBase/RegBase、改变支持范围或补充 DESIGN；实施阶段按 `operators/<operator_name>/docs/DESIGN.md`/`operators/<operator_name>/docs/PLAN.md` 实现，并可在 `<project-root>/operators/<operator_name>/` 内为闭合设计补充修复步骤。
+
+## 目录
+
+1. PLAN 编译门禁
+2. 阅读与依赖清单
+3. 有序动作规则
+4. 接线和项目文件合同
+5. 验证、交付与清理
+6. 合规映射和回退
+
+## 1. PLAN 编译门禁
+
+Step 3 读取本文前必须确认：
+
+```text
+implementation_route: blaze_custom
+selected_scenario: elementwise-broadcast-epilogue-fusion
+matmul_base_analysis: present
+matmul_base_analysis.abi_bindings[]: source_backed_and_closed_for_consumed_partitions
+abi_crosswalk_delta: source_backed_and_closed
+design_plan_generation_phase: after_design_freeze
+```
+
+并且：
+
+- DESIGN 已冻结唯一首选、公式/broadcast、三层增量、Tiling/资源/同步、customization scope 和验证合同；`abi_crosswalk_delta` 只追加额外 operand、输出、Params、Wrapper 或同步接线，且每行具有 `delta_crosswalk_row_id` 并引用 `base_design_binding_ref` 和基础 MatMul `crosswalk_row_id`；
+- DESIGN 的 `dependency_skills` 与 `dependency_skill_evidence` 已冻结，覆盖当前首选路线的根入口、必要叶子及 API/路线证据；
+- 根 `ops-tensor` 和 Blaze skill Asset 原文件始终只读；项目内官方副本只允许执行 PLAN 登记的缺失目录 create-only 原样物化，物化后只读；
+- 无决定性 unknown、TBD、未选择分支、Grouped 基础分区缺口或要求 Step 4 决策的字段。
+
+失败时回 Step 3，不生成可执行 PLAN；不得把本文默认值或历史实现写入可执行 action。
+
+## 2. 阅读与依赖清单
+
+Step 3 根据首选 DESIGN 生成 PLAN `reading_manifest` 作为初始阅读基线。初始资料应绑定 `read_before_action_ids` 和 action `source_refs`；未激活资料写 N/A 或不登记，Step 4 可按实际实现和错误证据读取必要资料，但不能据此改变设计。
+
+| 设计合同 | PLAN 必读来源 | 条件 |
+|---|---|---|
+| Block层 delta | [Block层专题](block-l0c2ub-extension.md)、Investigation 指定的 concrete source locations | 使用/扩展 L0C2UB/GM 输出 |
+| Kernel层 delta | [Kernel层专题](fused-kernel-development.md)、实际 mixed Kernel/同步定义 | 存在 AIC/AIV、slot 或 event 协作 |
+| MemBase 首选 | DESIGN `dependency_skills` 记录的根入口和必要叶子、[MemBase 专题](epilogue-membase-design.md) | DESIGN 选择 MemBase |
+| RegBase 首选 | DESIGN `dependency_skills` 记录的根入口和必要叶子、[RegBase 专题](epilogue-regbase-design.md) 及 DESIGN 记录的真实参考实现 | DESIGN 选择 RegBase |
+| RegBase 使用普通 AscendC API | DESIGN `dependency_skills` 记录的普通 API 根入口和必要叶子 | 使用 DataCopyPad、HardEvent 等普通 API |
+| SplitM | [SplitM 专题](splitm-contract-and-debugging.md) | DESIGN 激活 SplitM |
+| 五模式/诊断 | [精度诊断专题](precision-diagnosis.md) | 所有本场景实现 |
+| Tiling/Launcher | [Tiling 方法](../../kernel-design/tiling-selection.md)、[Launcher 方法](../../launcher/launcher-development.md) | 按 DESIGN 选择所需章节 |
+| Event/pipe | [同步方法](../../fundamentals/blaze-sync-patterns.md) 和当前 CANN 实际头文件 | DESIGN 激活相关同步 |
+
+PLAN 先登记 DESIGN `dependency_skills` 中的根入口，再登记当前首选路线需要的叶子。`reading_manifest` 只登记当前首选路线的初始资料，不能把全目录一股脑列入；Step 4 可为诊断和实现读取必要资料，但不能将其变成新的路线或支持范围。
+
+## 3. 有序动作规则
+
+Step 3 将下列稳定动作类别实例化为 PLAN 的 `ordered_actions`。每个初始动作必须含 DESIGN refs、source refs、计划目标文件、前置、产物、checkpoint 和 failure rollback。
+
+### 3.1 来源与项目副本
+
+1. 核对 DESIGN/Investigation 与当前 Blaze 源码版本的抽象一致性。
+2. 对 DESIGN 选择的官方组件登记 read-only 来源；满足合同时直接引用，不创建 custom 副本。
+3. 只有 `customization_scope` 明确授权时，登记从具体来源复制到项目目标文件并适配的 action，记录首个修改点和必须保持的不变量。
+4. 只有 DESIGN 明确授权结构起点时，才可复制 [MemBase Asset](../../../assets/blaze_custom/epilogue/epilogue_fusion_membase.h) 或 [RegBase Asset](../../../assets/blaze_custom/epilogue/epilogue_fusion_regbase.h) 到项目文件；Asset 原文件只读，复制后必须按当前 ABI/公式/API 重写和验证。
+5. 不复制整个 Blaze，不通过 include 顺序覆盖官方 specialization，不创建项目根之外或 DESIGN forbidden scope 内的目录。
+
+### 3.2 Block层动作
+
+按 DESIGN 冻结的 Block delta 实例化：
+
+- L0C 源、UB/GM 目的、Copy API/trait、extent、row pitch 和 tail；
+- final/partial、归并和输出分支；
+- official/custom 类型链、namespace、Policy/Params 绑定；
+- 结构/ABI 静态检查及必要的单变量正负对照。
+
+未授权 custom Block 时只登记官方组件绑定和核对 action，不生成修改动作。
+
+### 3.3 Kernel层动作
+
+按 concrete witness 实例化：
+
+- mixed Kernel entry、AIC/AIV 角色和 ratio；
+- adapter 的参数、单位和地址语义；
+- flag/event/pipe、slot 初始化/轮转/覆盖前等待、empty task 和 final drain；
+- Block/Epilogue、Params/TilingData、Wrapper 的类型接线；
+- DESIGN 已证明必要的 local event bridge 及其负向对照。
+
+所有涉及新增 operand、输出、Params、Wrapper、Kernel entry 或同步的动作必须引用由 `base_design_binding_ref` 选定的 `matmul_base_analysis.abi_bindings[]` 中 `kernel_abi_contract`/`abi_crosswalk` 与对应 `abi_crosswalk_delta` 行；Wrapper、Kernel entry 或 Launcher 启动绑定还必须引用同一 binding 的 `source_backed_signature_skeleton`。不通过融合动作重新解释基础 MatMul GM 参数。
+
+不得从专题或历史实现补入固定 ratio、slot、bridge 或 adapter。实现发现调用点不一致时回 Step 2/3，不临时改 DESIGN。
+
+### 3.4 Epilogue层动作
+
+只实例化 DESIGN 的唯一首选路线：
+
+- 当前 formula DAG 和每个 broadcast operand 的索引/stride/offset；
+- C、operands/intermediates/output 的 dtype、alignment、有效列和转换；
+- slot-aware C/staging/output/guard 内存分区；
+- DataCopy/VF/LocalTensor API、mask/tail、event 和生命周期；
+- 输出写回、运行时拒绝和 host/Tiling 门禁。
+
+MemBase 和 RegBase 不形成两个可执行分支；备选只留在 DESIGN，PLAN 不自动切换。
+
+### 3.5 Tiling、Params、Wrapper 和 Launcher
+
+按以下单向接线形成 action：
+
+```text
+project host Tiling
+  -> TilingData
+  -> Scheduler/Block/Epilogue Params
+  -> concrete Kernel type and entry
+  -> Wrapper/build target
+  -> Launcher buffers and arguments
+```
+
+- 先逐字段验证复制后的 Blaze skill Tiling Engine 与当前 Scheduler Params 合同兼容；只有全部语义/单位/合法域一致才复用或最小适配。
+- 不能复用但 device 合同已闭合时，为对应 demand partition 实例化返回固定合法控制值的项目 Tiling action。
+- 需要重划 partition、新 specialization 或未知合法域时回 Step 2/3；不能让 Step 4 猜值。
+- Launcher 只执行设备 Kernel 和输出结果；逻辑输入、物理转换、CPU Golden 和比较由 PLAN 指定的 host/Python 产物负责。
+- 不预设固定工程树、脚本数量或文件名；PLAN 的 `target_file_manifest` 提供初始项目文件，实施阶段可在 `<project-root>/operators/<operator_name>/` 内补充实现文件，更新 PLAN 第 2 章并在第 11 章记录实际路径。
+- Tiling、Wrapper、Launcher 和 buffer action 必须把额外 operand/输出的物理字节、offset 单位、Params、workspace、grid/usedCore、entry 绑定和设备消费者映射回 `abi_crosswalk_delta`；任一项缺失时回 Step 3，不启动 Kernel。
+
+### 3.6 数据、诊断和验证入口
+
+实例化：
+
+1. 逻辑输入和 deterministic seed；
+2. 每个 Tensor 的逻辑到物理转换、padding/packing/broadcast 映射；
+3. 与 DESIGN 公式/dtype 顺序一致的 CPU Golden；
+4. C-direct-GM、C-through-fusion、V-zero-C、V-known-C、Full 五模式；
+5. SplitM、slot、broadcast 轴、alignment/tail 和重复运行的实际激活子集；
+6. row/column/known-C 等定位数据、单变量故障注入和记录格式；
+7. 诊断开关、额外输出和 Dump 的清理 action。
+
+## 4. 接线和项目文件合同
+
+PLAN 的 `target_file_manifest` 应逐文件记录初始目标的 `create/copy_and_adapt/modify/delete/read_only/forbidden`。至少覆盖当前项目预期需要的：
+
+- Kernel/Wrapper 和可选 custom Block/Kernel/Epilogue；
+- TilingData、host Tiling、Params 和构建接线；
+- Launcher 及其 ABI/Buffer 接线；
+- 逻辑数据、物理转换、Golden 和比较入口；
+- 模式分发、诊断、验证和交付产物。
+
+这些是角色，不是固定文件树。PLAN 初始文件必须属于 DESIGN `allowed_change_scope`，并记录为以 `operators/<operator_name>/` 开头的项目相对路径；实施阶段新增文件只能位于当前 `operator_root`，必须避开 DESIGN `forbidden_change_scope`，更新第 2 章并追加第 11 章。根 `ops-tensor`、Skill Asset 原文件、当前 `operator_root` 之外的路径、未注册 custom 层和无关用户文件必须列为 read_only/forbidden；项目内官方副本已存在时列为 `read_only`，缺失时先列为 `create`，完成原样物化和同源核对后转为 `read_only`。
+
+`implementation_wiring_contract` 必须能从最终 operator interface 一路追到每个文件和参数，并显式保留基础 ABI 与场景增量的边界：
+
+```text
+logical operand
+  -> physical buffer
+  -> Launcher argument
+  -> Wrapper argument
+  -> Kernel GM parameter
+  -> Params/Tiling field
+  -> Block/Kernel/Epilogue consumer
+  -> output buffer and Golden comparison
+```
+
+基础 MatMul 行必须引用与其 `design_binding_ref` 对应的 `matmul_base_analysis.abi_bindings[].abi_crosswalk` 和 `crosswalk_row_id`；只有本场景新增/替换的行写入 `abi_crosswalk_delta`，并写明 `delta_crosswalk_row_id`、`base_design_binding_ref` 和 `base_crosswalk_row_refs`。每行都要映射到 action、checkpoint 和 source ref，不能用泛化接线图替代。
+
+## 5. 验证、交付与清理
+
+PLAN checkpoints 至少包括：
+
+1. source/ABI/模板实例化静态核对，包括基础 ABI、场景 delta、物理字节/offset、TilingData、workspace、grid/usedCore、Wrapper/entry 和设备消费者；
+2. 分层构建和最小功能运行；
+3. 五模式按最早失败域定位；
+4. 每个声明支持的 elementwise/broadcast mapping、dtype、shape/alignment/tail；
+5. SplitM/slot/reuse/empty/final drain 的条件性用例；
+6. required 单变量负/正证据；
+7. 非有限值和 DESIGN 阈值门禁；
+8. 清理临时诊断后重新构建并执行 Full 回归；
+9. 最终 Asset/官方源码只读、交付件和支持边界审计。
+
+`deliverable_manifest` 只列当前项目必需产物。`cleanup_contract` 必须覆盖 known-C/zero/identity 注入、故障开关、额外 Kernel entry/Params、Dump、临时数据、日志和构建产物；清理后回归未通过时不得交付。
+
+## 6. 合规映射和回退
+
+PLAN 的 `scenario_guidance_compliance` 必须把本文每个激活要求映射到：
+
+```text
+DESIGN contract ID
+reading_manifest ID
+ordered_action ID
+checkpoint ID
+deliverable/cleanup ID
+or evidence-backed not_applicable
+```
+
+每个激活的 `abi_crosswalk_delta` 行都必须映射到基础 ABI ref、初始 action、checkpoint 和 source ref。未映射 required 设计要求、只写“参见场景指导”或留下待选分支时，PLAN 为 blocking；实现阶段新增的项目文件和修复步骤不要求回写这组映射。
+
+| 发现的问题 | 回退目标 |
+|---|---|
+| Blaze 源码版本不一致 | Step 1 |
+| Blaze 源码类型链、Params/API/物理事实被推翻或缺失 | Step 2，再重做 Step 3 |
+| DESIGN 首选、范围、场景合同或设计边界不完整 | Step 3 DESIGN |
+| 本文无法表达必要 PLAN 动作/门禁 | Blaze skill 场景维护；修订指导后重新编译 PLAN |
+| 实现或验证推翻设计前提 | Step 3；需要新 Blaze 源码事实时先 Step 2 |
+| 普通编码、构建或验证错误 | Step 4 在项目根内持续诊断、修复和重跑；只有推翻设计前提才回 Step 3 |
+
+Step 4 的规范性输入只有当前项目的 DESIGN 和 PLAN。它以 PLAN 登记资料为起点，也可以读取本文或其他相关资料诊断和实现，但不能据此重新匹配场景、生成新的设计路线、切换备选或扩大支持范围。

package/assets/ops-direct-invoke/skills/ascendc-blaze-best-practice/references/scenarios/elementwise-broadcast-epilogue-fusion/epilogue-membase-design.md

@@ -0,0 +1,82 @@
+# MemBase Epilogue层设计与实现
+
+本文是本场景 MemBase 路线专题。Step 3 用它比较当前公式的 MemBase 可行性，DESIGN 选定 MemBase 后由 Step 3 编译 PLAN；Step 4 只执行 PLAN。本文不把某个公式、adapter、dtype、tile 或 Asset 声明为通用能力。
+
+## 1. 入口与依赖
+
+必须先加载 [`/ascendc-api-best-practices/SKILL.md`](../../../../ascendc-api-best-practices/SKILL.md)，再按其路由读取当前公式实际需要的 DataCopy、Buffer、pipeline、arithmetic、mask/tail 和真实参考实现资料。直接阅读叶子不能替代根入口。当前 CANN 的实际头文件、目标 Kernel 调用点和 Investigation source refs 优先于旧专题示例。
+
+DESIGN 至少写出：
+
+```text
+membase_evidence_refs
+formula_dag
+operand_distribution_and_broadcast_mapping
+adapter_and_params_contract
+staging_and_slot_budget
+api_and_pipeline_contract
+dtype_alignment_mask_tail
+output_and_sync_contract
+support_boundary
+```
+
+## 2. 适用性审查
+
+按当前公式逐节点判断：
+
+1. 每个 operand 是否能以已确认的 LocalTensor/GM/UB 访问表达；
+2. broadcast 轴、stride、offset 和有效行列是否可由当前 API 闭合；
+3. 中间结果是否需要写回、重读或额外 staging；
+4. 每个 dtype 的 Copy/compute/store alignment 和转换是否有证据；
+5. tail、mask、空 tile、slot reuse 和 event 生命周期是否不超过资源合同；
+6. 公式操作顺序与 CPU Golden 是否一致。
+
+“操作数量少”只能作为比较线索。API、资源、同步或公式映射不闭合时，MemBase 为 blocking/淘汰，不能用历史单操作结果替代。
+
+## 3. Adapter 与地址合同
+
+如果当前 concrete Kernel 提供 `Init`、`GetTensor(slot)` 或 tile operator，逐项引用真实签名和单位；否则设计一个明确的场景 adapter 合同并记录其 ABI owner。禁止从 Asset 或相似 Kernel继承接口。
+
+每次调用必须明确：
+
+- 当前 slot 的 C 起点、元素/字节单位和独立容量；
+- 每路 operand 的逻辑到物理 broadcast 映射、GM row/column offset 和 stride；
+- `curM/curN`、stage rows、有效 bytes、padding 和 mask；
+- 输出目的地、final 时机、错误/拒绝条件和 Kernel release。
+
+不同 dtype 分别计算 alignment 和 row pitch。当前 AIV 若从本地 slot 起点读取 C，不得再次叠加 sub offset；GM full-tensor operands/output 是否增加 sub offset 必须由 DESIGN 证据明确。
+
+## 4. Staging 与流水
+
+DESIGN/PLAN 需要按 slot 预算列出 C、每路 operand、中间值和输出的 byte ranges，以及预取、覆盖前等待、compute、写回和 final drain。常见顺序仅作为待验证方法：
+
+```text
+producer ready
+-> GM/UB prefetch
+-> dependency wait
+-> MemBase arithmetic
+-> output writeback
+-> buffer release
+```
+
+每个 event/pipe 必须绑定当前 Kernel 首消费者和 source/device evidence。新增 bridge 必须有只移除 bridge 的负向版本和清理后正向 Full 回归；不能从另一个 Kernel 泛化。
+
+## 5. Asset 规则
+
+[MemBase 示例 Asset](../../../assets/blaze_custom/epilogue/epilogue_fusion_membase.h) 只是可选结构起点，保留原路径和原内容。它不提供正式 adapter、公式、dtype、slot、ratio、同步或支持边界。只有 DESIGN 授权时才由 PLAN 显式复制到项目目标文件；复制后按当前 API、公式、ABI 和验证合同重新适配。
+
+## 6. 输出与回退
+
+MemBase 评估输出为：
+
+```text
+route_evidence
+api_constraints
+formula_mapping
+resource_and_sync_budget
+known_tail_and_broadcast_limits
+selection_status: 首选 | 备选
+blocking_or_disposition
+```
+
+若与 RegBase 比较后不适用，记录独立处置，不让 Step 4自动切换。若实现或设备证据推翻本合同，回 Step 3；需要新的 Blaze 源码/API 事实先回 Step 2。

package/assets/ops-direct-invoke/skills/ascendc-blaze-best-practice/references/scenarios/elementwise-broadcast-epilogue-fusion/epilogue-regbase-design.md

@@ -0,0 +1,95 @@
+# RegBase Epilogue层设计与实现
+
+本文是本场景 RegBase 路线专题。Step 3 用它比较当前 elementwise/broadcast 公式的 RegBase 可行性，DESIGN 选定后由 Step 3 编译 PLAN；Step 4 只执行 PLAN。本文不固定公式、VF 宽度、guard、adapter、dtype、tile 或 slot。
+
+## 1. 入口与依赖
+
+必须先加载 [`/ascendc-regbase-best-practice/SKILL.md`](../../../../ascendc-regbase-best-practice/SKILL.md)，读取其 Reg API、限制、pitfalls 和真实 RegBase 参考实现。若实际使用 DataCopyPad、HardEvent 等普通 AscendC API，同时加载 [`/ascendc-api-best-practices/SKILL.md`](../../../../ascendc-api-best-practices/SKILL.md)。依赖 Skill 根入口不能由叶子链接替代。
+
+DESIGN 至少记录：
+
+```text
+regbase_evidence_refs
+formula_dag
+operand_distribution_and_broadcast_mapping
+vf_register_contract
+adapter_and_params_contract
+staging_and_slot_budget
+active_mask_and_tail_contract
+event_and_pipeline_contract
+output_and_support_boundary
+```
+
+## 2. 适用性审查
+
+逐节点验证：
+
+1. 每个 operand 的 GM/UB 物理映射和 Reg/VF load API；
+2. broadcast index、row/column pitch、有效列和尾部 mask；
+3. 注册器数量、临时值、stage rows 和 slot 容量；
+4. 整寄存器读取是否在 active mask 前发生，以及 guard 是否必要；
+5. dtype、cast、round、saturate 和 store 顺序；
+6. event、buffer reuse、首消费者和 final drain。
+
+Mask 只限制明确允许的 arithmetic/store。若 API 在 mask 前整向量读取，容量 guard、alignment 和合法地址必须单独证明，不能以 active mask 代替。
+
+## 3. Adapter、寄存器和地址
+
+当前 concrete Kernel 的 `Init`、`GetTensor(slot)`、tile operator、Params 字段和返回单位必须从 Investigation 调用点抄录；不同 Kernel 重新恢复，不得从示例 Asset推断。
+
+每个 slot 单独预算：
+
+```text
+C range
+operand staging ranges
+intermediate/register lifetime
+output range
+optional load guard
+slot reuse dependency
+```
+
+每路 operand 独立计算 dtype alignment、row pitch、GM offset、stage offset 和有效 `curM/curN`。若 SplitM 启用，UB C 的 sub 起点和 GM full-tensor 的全局 sub 行偏移分别记录；禁止对 UB C 重复增加 sub offset。
+
+## 4. VF 计算合同
+
+以当前公式为准建立伪代码/字段表，不固定某种操作链：
+
+```text
+for each valid local row:
+    load each operand according to its mapping
+    derive active mask from effective columns
+    execute formula DAG in DESIGN order
+    store only valid output elements
+```
+
+记录 VF API、数据类型、mask 更新、寄存器临时值、中间结果和输出写回证据。计算逻辑不能依赖 padding；所有加载和存储范围必须在当前 slot/GM 合同内。
+
+## 5. 本地流水与事件
+
+按当前 API 和 Kernel pipe 设计：
+
+1. 预发射每路 operand 的 GM->UB 或 Reg load 依赖；
+2. 等待对应 buffer/slot 可读或可覆盖；
+3. 执行 VF 公式；
+4. 释放输入、中间和输出依赖；
+5. 完成输出写回和 final drain。
+
+任何 MTE/V/Event bridge 必须引用当前控制流的 source/device evidence，并用“只移除该 bridge”的负向对照证明必要性；不得把其他路线的同步常量或性能判断带入。
+
+## 6. Asset 规则与输出
+
+[RegBase 示例 Asset](../../../assets/blaze_custom/epilogue/epilogue_fusion_regbase.h) 只提供结构骨架，不能声明公式、active mask、guard、adapter、dtype、slot、ratio 或 ABI。只有 DESIGN 授权时才在 PLAN 中复制到项目目标并重新适配。
+
+RegBase 评估输出为：
+
+```text
+route_evidence
+api_and_reference_implementation_constraints
+formula/vf/mask_mapping
+resource_and_event_budget
+known_broadcast_and_tail_limits
+selection_status: 首选 | 备选
+blocking_or_disposition
+```
+
+若资源、API 或同步不兼容，记录独立处置并回场景设计；Step 4不能自动切换 MemBase。设备结果推翻前提时回 Step 3，需要新事实先回 Step 2。

package/assets/ops-direct-invoke/skills/ascendc-blaze-best-practice/references/scenarios/elementwise-broadcast-epilogue-fusion/fused-kernel-development.md

@@ -0,0 +1,71 @@
+# Kernel层 Fused Kernel 设计与开发
+
+本文维护本场景的 Kernel层 CV 契约。Step 3 用它冻结 concrete Kernel 的编排增量，随后将所需动作编译进 PLAN；Step 4 只有在 PLAN action 绑定本文时才读取。本文不定义所有 Fused Kernel 的通用 ABI。
+
+## 1. Concrete 入口和 adapter
+
+以当前 Investigation 的真实 Kernel witness 为唯一来源，逐项记录：
+
+```text
+mix_entry / modifier / specialization
+aic_role / aiv_role / actual_ratio
+adapter_signature_and_parameter_units
+block_shape / gm_offset / split_or_sub_inputs
+params_and_tilingdata_fields
+```
+
+如果存在 `Init`、`GetTensor(slot)`、tile `operator` 或等价 adapter，必须从调用点抄录返回单位、地址推导和生命周期；不能从示例 Asset、相似 Kernel 或名称推测五参 ABI。单位必须明确是元素、字节、LocalTensor 还是逻辑索引。
+
+## 2. CV 生命周期
+
+DESIGN/PLAN 必须覆盖当前 concrete 控制流：
+
+1. AIC->AIV 的 producer/consumer、C-ready flag、pipe 和通知点；
+2. AIV->AIC 的 V-done、pipe、slot 和覆盖前等待；
+3. 首轮初始化、循环、slot reuse、empty task、partial/final drain；
+4. 每 tile 的 BlockShape、GM offset、split/sub 参数和 Epilogue 首消费者；
+5. cross-core wait 到本地 Vector/MTE/其他首消费者 pipe 的交接；
+6. localRows=0 或空 AIV 时的 release 行为。
+
+历史 `source_observed` 只说明源码控制流；`device_verified` 必须绑定同一 Investigation、目标 Blaze 组装方案、编译和验证记录。固定 ratio、slot 数、bridge 或 flag 不能升级为场景默认。
+
+## 3. Slot 与地址合同
+
+对每个 DESIGN 声明的 slot 方案写出：
+
+```text
+slot_count
+slot_index_lifecycle
+slot_base_unit
+GetTensor(slot) return unit
+slot_capacity
+C_range
+staging_ranges
+output_range
+reuse_wait
+```
+
+AIC 写入 C 和 AIV 读取 C 必须由同一 slot 起点和单位推导；staging 不能跨 slot。若 SplitM 激活，必须分别说明本地 UB C 是否已经按 sub 写入，以及 GM operand/output 是否需要全局 sub offset，避免二次偏移。
+
+## 4. 同步验证与扩展
+
+同步候选只有在以下证据齐全时才进入正式 DESIGN：
+
+- 源码中存在对应 wait/set/pipe 控制流；
+- 负向版本只移除该同步变量，能稳定复现同一责任域错误；
+- 正向版本恢复该变量并完成相关边界及 Full 重复回归；
+- 该结论绑定具体 Blaze 组装方案，而不是相似 Kernel。
+
+只在 DESIGN 明确授权时复制 Kernel 到项目 custom 目录，使用独立符号/namespace，并保持 Mmad、调度、Params、输出和未涉及的同步不变量。不能通过加 `__mix__`、增加 event 或复制相邻实现临时制造 Fused Kernel。
+
+## 5. PLAN action 清单
+
+场景 development guide 编译 PLAN 时，按 DESIGN 实例化：
+
+1. concrete Kernel/Wrapper 来源和只读范围；
+2. 官方复用或 custom 副本、首次修改点和类型接线；
+3. adapter/Params/TilingData/GM ABI 接线；
+4. AIC/AIV、slot、flag/pipe、bridge、empty/final/reuse action；
+5. 结构检查、构建、最早失败域诊断、单变量负向/正向和最终清理回归。
+
+每项初始 action 必须有 source refs、前置、预期输出、checkpoint 和 rollback。本文不补充 DESIGN 未冻结的参数或语义；Step 4 可在项目根内补充实现文件并记录实际变更。

package/assets/ops-direct-invoke/skills/ascendc-blaze-best-practice/references/scenarios/elementwise-broadcast-epilogue-fusion/precision-diagnosis.md

@@ -0,0 +1,86 @@
+# Elementwise/Broadcast Epilogue 精度诊断
+
+本文是本场景的验证方法专题。Step 3 用它设计验证合同并编译 PLAN；Step 4 以 PLAN 初始验证基线为起点，按实际失败证据读取本文并执行诊断。本文不选择路线、不维护 SplitM 公式，也不把固定 case 数写成通用支持矩阵。
+
+## 1. 基线合同
+
+每个项目在 DESIGN/PLAN 中冻结：
+
+```text
+logical_inputs_and_seed
+physical_conversion_and_packing
+formula_and_dtype_order
+shape/layout/broadcast/slot/split partitions
+actual blockShape and Tiling
+CPU golden
+atol/rtol/nonfinite gate
+required negative/positive comparisons
+repeat policy
+```
+
+阈值由需求和数值合同决定；必须全元素通过且拒绝非有限值。若当前 FP32 链额外要求零误差，写入该项目合同，不外推到其他 dtype/公式。构建、设备结果和 `device_verified` 只绑定当前 Investigation、目标 Blaze 组装方案和验证记录。
+
+### 1.1 公式的数值稳定性
+
+代数等价不等于设备 dtype 下的数值等价。诸如 tanh/GELU 的指数形式可能在
+大正值上先产生 `inf`，随后出现 `inf/inf -> NaN`；该 NaN 还可能让 absmax
+漏掉真正的最大值，最终同时污染 `yScale` 和 `y`。遇到此类首错时，先保留用户
+Golden 和验收公式，使用大正值、大负值、零附近及非有限值策略的定向输入比较
+`workspace -> yScale -> y`。只有在用户合同允许、dtype 顺序和特殊值行为已证明
+一致时，才能替换为数值稳定的等价实现；不能用设备 PASS 反向授权改写 Golden，
+也不能用放宽容差掩盖产生 NaN 的中间结果。稳定实现的阈值、常数和公式仍属于
+目标 DESIGN/PLAN，不写成通用 Skill 常量。
+
+## 2. 五种隔离模式
+
+所有模式使用同一逻辑输入、物理转换、Tiling 记录和 Golden，只改变 DESIGN 声明的隔离变量：
+
+| 模式 | 隔离目标 | 必须记录 |
+|---|---|---|
+| C-direct-GM | MatMul 主体与最终 GM 输出 | 真实 GM 分支/等价路径、C Golden、MatMul 证据 |
+| C-through-fusion | L0C2UB、slot、C-ready、identity writeback | adapter、slot、同步、C 输出 |
+| V-zero-C | 额外 operand、公式、mapping、mask/tail、写回 | 零 C 生成/注入方式、输入地址和 V Golden |
+| V-known-C | 非零 C、adapter、offset、同步 | known-C 产生方式、真实 wait/release、V Golden |
+| Full | 完整 MatMul + elementwise/broadcast Epilogue | 全公式、reuse、final drain、重复回归 |
+
+未激活的条件性模式必须在 DESIGN 说明 N/A 依据。C-direct 不证明 L0C2UB/Vector；单独通过模式不替代 Full。
+
+## 3. 最早失败域
+
+| 最早失败 | 责任域 | 优先核对 |
+|---|---|---|
+| C-direct-GM | MatMul 主体 | 输入/layout、Tiling、Mmad、归并、GM output |
+| C-direct 通过且 C-through 失败 | MatMul->Vector 交接 | L0C2UB、物理 pitch、slot、GetTensor 单位、C-ready pipe |
+| 前两项通过且 V-zero/V-known 失败 | Vector | operand mapping、mask、公式顺序、写回、dtype |
+| 隔离模式通过且 Full 失败 | 组合生命周期 | RAW、offset、slot reuse、同步、final drain |
+
+V-zero 通过而 V-known 失败时，优先比较非零 C 的物理 layout、formula order、mask 和原地依赖。结论必须附首错位置和对应 source/device evidence。
+
+## 4. 单变量负向/正向
+
+对每个候选根因建立：
+
+```text
+baseline_id
+changed_variable
+negative_reproduction
+positive_recovery
+affected_boundary_cases
+full_repeat_result
+```
+
+只移除一个 bridge、offset、trait、mask、slot wait 或 staging 变量；不能把多个改动一起作为根因。只有负向稳定失败、正向稳定恢复、相关边界和清理后 Full 都通过，才能将结论写成 `device_verified`；否则为 `unverified` 或保护性调整。
+
+## 5. 数据与 Dump
+
+优先使用 row-encoded、column-encoded、one-hot 或其他能区分 M/N/offset 的数据。全常量输入不能证明地址正确。V-known-C 可以由真实 MatMul 产生已知非零 C，也可以在 DESIGN 授权的诊断点注入，但必须保留真实 wait/release/final drain，不得跳过 Kernel 生命周期。
+
+Dump/诊断点只放在已确认 producer 完成之后，记录 tile、slot、sub、stage、row/column、元素单位和物理边界。Dump 可能改变时序；首错确认后必须移除 Dump 并复现，不能把 Dump 版本作为修复证据。
+
+CPU Golden 由 PLAN 指定的 host/Python 逻辑生成；C++ Launcher 只执行设备 Kernel、同步和写结果，不现场计算 Golden 或改变阈值。
+
+## 6. 清理与交付门禁
+
+交付前必须删除 PLAN 和 `execution_record` 中记录的 identity/zero/known-C 注入、故障开关、诊断 Params、Dump 和临时输出；清理后重新构建，并执行 DESIGN 声明范围内的五模式、边界、multi-tile、slot reuse、SplitM（如适用）和 Full 重复回归。
+
+最终记录：实际输入/shape/dtype/layout、Tiling/blockShape、slot/sub、错误统计、非有限值、source/device evidence、支持/未验证范围和清理状态。只有清理后 required checkpoints 全部通过，PLAN 才能标记交付完成。

package/assets/ops-direct-invoke/skills/ascendc-blaze-best-practice/references/scenarios/elementwise-broadcast-epilogue-fusion/splitm-contract-and-debugging.md

@@ -0,0 +1,86 @@
+# SplitM Elementwise/Broadcast Epilogue 契约与定位
+
+本文只在当前需求、MatMul 基础合同和选定 Kernel 明确启用 M 维分片时使用。它不规定所有 SplitM 的 ratio、trait、slot 或同步；每个公式和地址必须绑定当前 witness 与验证记录。
+
+## 1. 入口门禁
+
+DESIGN 进入本专题前必须已有：
+
+```text
+matmul_base_analysis: ready
+splitM_requested: true
+splitM_source_contract: resolved
+splitM_kernel_lifecycle: resolved
+```
+
+若未激活，写 `not_applicable`；若只发现名称线索或字段语义 unknown，保持 blocking/unknown，不推导行分配。
+
+## 2. 四层合同
+
+分别冻结：
+
+1. **Block层**：L0C/UB 逻辑和物理 shape、Copy extent、alignment、final/partial、sub 可见性；
+2. **Kernel层**：实际 AIC/AIV ratio、sub index、flag/pipe、slot、首轮、empty task、reuse 和 final drain；
+3. **Epilogue层**：localRows、UB C 起点、GM operand/output 全局 offset、stage pitch、stride/extent 单位和 mask/tail；
+4. **验证层**：实际 blockShape、odd/even M、N alignment、multi-tile、slot reuse、五模式和重复回归。
+
+每层都必须有 source evidence；device 规范还必须有同一 Blaze 组装方案的正向/负向精度证据。单 shape 通过、相似实现或最终版本单次通过不足以标记已验证。
+
+## 3. 行分配和地址规则
+
+先从当前 Kernel witness 恢复实际分配规则，再在 DESIGN 中写成符号合同。例如，若证据确实证明两个 sub 均分当前 tile，才可以使用：
+
+```text
+chunkRows = ceil_div(curM, ratio)
+subStart = sub * chunkRows
+localRows = min(chunkRows, max(curM - subStart, 0))
+```
+
+`ratio`、sub 范围和 odd-M 分配不能预先固定。对每个对象分别说明：
+
+| 对象 | 必须确认 |
+|---|---|
+| UB C | 当前 slot 是否已写入本 sub；是否允许再加 sub offset |
+| GM full-tensor operand | 是否按全局行增加 subStart；row pitch/offset 单位 |
+| GM output | 是否与 operand 使用同一全局行基准；non-overlap/final |
+| Empty sub | Epilogue 是否跳过访问；Kernel 如何释放/通知 |
+
+常见错误是对已经按 sub 写入本地 slot 的 UB C 再叠加 subStart；是否存在该风险必须由当前 Copy 和 adapter 证据决定。
+
+## 4. Slot、alignment 和容量
+
+对每个声明的 slot 方案写出：
+
+```text
+slot_count
+slot_base_unit
+slot_capacity
+C/staging/output ranges
+per-dtype alignment
+stage row pitch
+reuse wait and release
+```
+
+C、每路额外 input、中间值和 output 独立计算 alignment/row bytes；GM 有效 `curN`、Copy extent 和 UB pitch 不混用。所有 staging 必须落在当前 slot，整 VF load 的 guard 只有在目标 API 需要且已证明时才计入。
+
+## 5. 同步和根因定位
+
+先执行隔离路径，再按最早失败归因：
+
+1. C-direct-GM：确认 MatMul 主体；
+2. C-through-fusion：确认 L0C2UB、slot 和 C-ready；
+3. V-zero-C/V-known-C：确认 operand offset、mask、公式和 output；
+4. Full：确认真实 sub、reuse、RAW 和 final drain。
+
+若怀疑某个 trait、offset、ratio 或 bridge，必须有固定基线、只撤变量的负向、只恢复变量的正向、相关 boundary 和清理后 Full 回归。否则结论标记 `unverified`，不得写成根因。
+
+## 6. PLAN 输出
+
+Step 3 只有在 DESIGN 激活 SplitM 时，才在 PLAN 中实例化：
+
+- 真实 ratio/sub/slot/offset/row-pitch 字段；
+- odd-M、empty sub、alignment/tail 和复用动作；
+- row/column-encoded、known-C 和最早失败域诊断；
+- required 负/正对照、最终 Full 和清理回归。
+
+不激活的 SplitM action 必须显式记录 N/A 依据。任何新的 SplitN、ratio、dtype、Kernel 控制流或 shape 组合先回 Step 2/3，不由 Step 4扩展。

package/assets/ops-direct-invoke/skills/ascendc-blaze-best-practice/references/scenarios/index.md

@@ -0,0 +1,14 @@
+# 定制扩展场景索引
+
+- Step 3 仅在 Blaze 官方库方案已记录明确 `native_gaps` 时查询本表。
+- 只有唯一命中一个场景时，才读取该行的设计指导；具体前提由场景设计指导复核。
+
+| 场景 ID | 支持范围 | 准入条件（均满足） | 设计指导 | 开发指导 |
+|---|---|---|---|---|
+| `elementwise-broadcast-epilogue-fusion` | MatMul 类主计算的最终输出后接一个或多个 Vector 运算的 Epilogue。Vector DAG 仅由 elementwise 运算、具有静态明确映射的 broadcast 运算及其组合构成；同形输入按逐元素映射处理。不支持 reduce/reduction 或其他非 elementwise/broadcast 的 Vector 运算，包括 scan、softmax、跨轴 normalization、gather/scatter、改变元素归属的 transpose/reorder、窗口/邻域运算、额外 MatMul/Convolution、数据相关索引或有状态更新。满足前述条件的 quant/dequant 不因类别被排除，但具体 API、dtype 和精度可行性仍由设计阶段确认。 | 主数据流为 MatMul 类主计算产生最终输出后执行一个或多个 Vector 节点；Vector DAG 的每个节点均可归类为 elementwise 或具有明确映射规则的 broadcast；每个最终输出元素只依赖对应 MatMul 输出元素、映射到同一输出位置的输入及其 Vector 中间结果；所有参与输入和输出的 shape、dtype、layout、broadcast 轴及索引规则均可冻结。 | [设计指导](elementwise-broadcast-epilogue-fusion/elementwise-broadcast-epilogue-fusion-design.md) | [开发指导](elementwise-broadcast-epilogue-fusion/elementwise-broadcast-epilogue-fusion-development.md) |
+| `cube-matmul-then-vector-glu` | MM、BMM、GMM 或 MM_MX 产生两路投影，经 L0C2UB 执行一个已明确公式的 GLU-family 后处理并输出 FP `y[R,Q]`。不含后续 per-token quant、跨元素 reduction 或其他未命名 Vector 阶段。 | 基础 MatMul 变体及 layout/dtype 已确认；用户合同明确 act/gate、GLU-family 精确公式、两路 weight/bias/scale 布局和输出 `Q`；主数据流在 GLU 后结束。 | [设计指导](cube-matmul-then-vector-glu/cube-matmul-then-vector-glu-design.md) | [开发指导](cube-matmul-then-vector-glu/cube-matmul-then-vector-glu-development.md) |
+| `cube-matmul-then-vector-pertoken-quant` | MM、BMM、GMM 或 MM_MX 的最终 FP 输出经过完整行交接后执行 per-token quant，输出 `y[R,N]` 与每行唯一 `yScale[R]`。不含 GLU、shape-preserving elementwise 或其他独立 Vector 前处理。 | Cube/Fixpipe 产生最终 FP workspace `[R,N]`；每个 scale 的归约域是完整逻辑行 `[0,N)`；scale、零行、舍入、clamp、饱和和非有限值行为均可冻结；MatMul 与 quant 之间没有其他 Vector 计算。 | [设计指导](cube-matmul-then-vector-pertoken-quant/cube-matmul-then-vector-pertoken-quant-design.md) | [开发指导](cube-matmul-then-vector-pertoken-quant/cube-matmul-then-vector-pertoken-quant-development.md) |
+| `cube-matmul-then-vector-glu-then-vector-pertoken-quant` | MM、BMM、GMM 或 MM_MX 产生两路投影，按用户合同执行可选 bias/scale/dequant 与一个 GLU-family 公式，写 FP workspace `[R,Q]`，再按完整行执行 per-token quant。该路线是不可拆分场景，不由两个简单场景自由组合。 | 基础 MatMul 合同、act/gate 与 GLU 精确公式、可选 bias/scale/dequant 顺序、workspace `[R,Q]`/pitch、完整行 quant 公式及 producer-consumer 完成条件均可冻结。 | [设计指导](cube-matmul-then-vector-glu-then-vector-pertoken-quant/cube-matmul-then-vector-glu-then-vector-pertoken-quant-design.md) | [开发指导](cube-matmul-then-vector-glu-then-vector-pertoken-quant/cube-matmul-then-vector-glu-then-vector-pertoken-quant-development.md) |
+| `cube-matmul-then-vector-elementwise-then-vector-pertoken-quant` | MM、BMM、GMM 或 MM_MX 后执行一个 shape-preserving unary/pointwise/broadcast DAG，写 FP workspace `[R,N]`，再按完整行执行 per-token quant。明确排除 GLU-family、跨元素 reduction、shape 改变和纯 Vector 请求。 | elementwise 每个输出只依赖同位置主 Tensor 元素和已声明 scalar/row/column broadcast；公式、顺序、近似和 dtype 可冻结；输出保持 `[R,N]`；随后 per-token quant 对完整 `[0,N)` 生成唯一 scale。 | [设计指导](cube-matmul-then-vector-elementwise-then-vector-pertoken-quant/cube-matmul-then-vector-elementwise-then-vector-pertoken-quant-design.md) | [开发指导](cube-matmul-then-vector-elementwise-then-vector-pertoken-quant/cube-matmul-then-vector-elementwise-then-vector-pertoken-quant-development.md) |
+| `weight-dequant-prologue-fusion` | AIV 先将低比特量化权重（int8/fp8）反量化为 bf16/fp16 并写入 L1，AIC 随后从 L1 读取反量化后权重做 MMAD 的 V+C prologue 融合（C = A × dequant(B)）。反量化为 perchannel 模式（scale/offset 按 N 维广播）。本场景不属纯 Quantized MatMul（A8W8/MX 官方库原生 scale 路径）范畴，后者走 blaze_native。不支持 pergroup 量化、StreamK/Full-load 路径、Weight-Quant + Vector Epilogue 后融合，以及 C+V epilogue 融合（AIC 先 MMAD → AIV 后处理，数据流方向相反，属 elementwise-broadcast-epilogue-fusion 场景）。 | B 输入为低比特量化权重（int8/fp8），需在 device 侧反量化后参与 MMAD；反量化发生在 MMAD 之前（AIV 先执行反量化写入 L1，AIC 从 L1 读取 B_dequant 做 MMAD）；反量化参数为 perchannel（scale/offset 按 N 维广播）；所有参与输入和输出的 shape、dtype、layout、transpose 及索引规则均可冻结。 | [设计指导](weight-dequant-prologue-fusion/weight-dequant-prologue-fusion-design.md) | [开发指导](weight-dequant-prologue-fusion/weight-dequant-prologue-fusion-development.md) |
+| `cube-matmul-then-vector-softmax-reduce` | MM、BMM 或 GMM 的最终 FP 输出执行行级 online softmax（reduce-max → sub → exp → reduce-sum → div）或纯行级 reduce（如 reduce-max、reduce-sum、reduce-min 等），输出 `[R,N]`（softmax）或 `[R,1]`（reduce）。两阶段执行：V1 逐 N-tile 增量归约（per-tile reduce，AIC+AIV CV sync），V2 跨核归约 + 最终合并（仅 AIV）。softmax 额外含 exp/rescale 逻辑。不含 GLU、per-token quant、elementwise 或其他独立 Vector 阶段。 | 基础 MatMul 变体及 layout/dtype 已确认；归约域为完整逻辑行 `[0,N)`；两阶段公式、workspace 布局、splitM=1 和 L0C2UB 输出路径均可冻结；MatMul 与归约之间没有其他 Vector 计算。当前资产假设的 kernel 结构特征见 cv-sync §0，不匹配时需按适配方向调整。 | [设计指导](cube-matmul-then-vector-softmax-reduce/cube-matmul-then-vector-softmax-reduce-design.md) | [开发指导](cube-matmul-then-vector-softmax-reduce/cube-matmul-then-vector-softmax-reduce-development.md) |