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

package/assets/ops-direct-invoke/skills/ascendc-blaze-best-practice/references/scenarios/cube-matmul-then-vector-glu/cube-matmul-then-vector-glu-design.md

@@ -0,0 +1,150 @@
+# Cube MatMul -> Vector GLU
+
+本 Scenario 描述 MM、BMM、GMM 或 MM_MX 的 Cube MatMul 后执行 GLU-family
+计算的完整路线：
+
+```text
+Cube MatMul (MM / BMM / GMM / MM_MX)
+    -> L0C2UB
+    -> Vector: specified GLU-family formula
+    -> y [R, Q]
+```
+
+本页在 [Scenario 索引](../index.md)唯一命中后读取
+[GLU / SwiGLU 组件开发指导](../../kernel-design/glu-development.md)，只描述
+不含后续 quant 的 GLU-only 路线及其联合合同，不作为其他 Scenario 的事实源。
+GMM 相对 MM 的 group 编码、完整 POD、Scheduler/Kernel 生命周期和地址规则统一
+遵循 [Grouped MatMul 项目侧差异](../../kernel-design/group-matmul-delta.md)。
+
+## 0. Step 3 输入与源码前提
+
+进入正文前必须具备 `requirements_contract`、`operator_interface_contract`、
+`native_gaps`、`matmul_base_analysis` 及其 source-backed `abi_bindings[]`，以及
+同次 Investigation 对基础 Assembly、双分支输出、L0C2UB、Kernel/Epilogue
+adapter、Tiling/Params 和 C/V 生命周期的事实。GMM/BMM/MM_MX 只在需求激活时
+追加对应 group/batch/MX 事实，不从本场景资产推导。
+
+缺少决定性事实时只允许向 Step 2 提出一次无场景名补充问题，记录受影响
+requirement IDs、待确认的物理接口/完成时机、有限源码前沿和阻塞原因；补充后
+仍缺失则停止，不生成 PLAN。使用普通 AscendC API 或 RegBase/VF 时，分别先
+加载对应依赖 Skill 根入口。
+
+DESIGN 必须区分 consumed/preserved/added contracts，并用
+`abi_crosswalk_delta` 只追加 paired operand、输出、Params、entry 和同步接线；
+每个 custom 文件都要有来源、首个修改点、保持不变量和验证门禁。
+
+## 1. 精确匹配条件
+
+### 1.1 设计主线
+
+`scenario_id`: `cube-matmul-then-vector-glu`。
+
+仅当需求同时满足以下条件时选择本 Scenario：
+
+- 基础计算是 MM、BMM、GMM 或 MM_MX；对应的 batch/group/MX scale、layout、
+  dtype 和地址合同已确认。
+- 用户明确给出 GLU-family 公式和两路分支语义，例如 GLU、Bilinear、ReGLU、
+  GEGLU 或 SwiGLU。
+- 将全部逻辑行轴展平为 `R` 后，GLU 输出逻辑 shape 为 `[R,Q]`。
+- 需求不包含后续独立的 per-token quant 或其他未命名 Vector 阶段。
+
+若 GLU 后还需要 per-token quant，返回 [Scenario 索引](../index.md)选择已登记
+的完整组合路线；不能把两个叶子自由拼装。
+
+### 1.2 成立条件/门禁
+
+- `act/gate` 分支、activation 精确公式、两路 weight/bias/scale 布局、逐操作
+  dtype 和输出 `Q` 必须由用户合同或 Golden 冻结。
+- 只有两路各宽 `Q` 且输入拼接宽度明确为 `2Q` 时，才能使用 `Q=N/2`。
+- `integration_mode`、唯一 Base Assembly owner 和目标版本绑定由 Investigation
+  证据确认。
+- 对 BMM，若同版本 Investigation 已绑定可复用 Base BMM/QBMM
+  Scheduler/Kernel，且缺口可精确写成双分支 Block、paired N metadata view、
+  L0C2UB/CV 生命周期和 Epilogue row adapter，则选择
+  `blaze_base_plus_custom_delta`，这些缺口为 `adaptation_required`。Scenario
+  不要求预先存在一个专用 BMM GLU Kernel 资产。
+- 基础组件缺失且本 Scenario 或公共组件指导没有登记精确 delta 时，记录
+  `extension_missing` 并阻塞。
+
+### 1.3 常见误用
+
+| 误用 | 原因 | 正确处理 |
+|---|---|---|
+| 根据 `SwiGLU` 类名默认分支顺序或近似公式 | 名称不能替代用户 Golden | 在 `DESIGN.md` 冻结公式、dtype 和分支 |
+| 从 GMM 参考资产推导普通 MM 缺少 Scheduler/Kernel | custom 资产不是上游能力表 | 从同版本 Investigation 绑定普通 MM 基础组件 |
+| 因资产目录没有 BMM GLU Kernel 就阻塞 | BMM Base 与局部 GLU 公式属于不同责任层 | 复用同版本 BMM Base，目标工程适配 paired view、MX Block、C/V 和 row base |
+| 将 GLU-only 叶子与 Quant 叶子组合 | 两阶段 workspace、同步和 ownership 未联合设计 | 选择已登记的 GLU+Quant Scenario |
+
+## 2. 不可拆分合同
+
+### 2.1 数学合同
+
+将两路投影记为 `act` 和 `gate`：
+
+```text
+act  = MatMul(A, B_act)
+gate = MatMul(A, B_gate)
+y    = activation(act) * gate
+```
+
+所有沿源 N 轴定义的输入和元数据必须使用相同 `qOffset/curQ` 成对切分。M 轴或
+K 轴输入不会仅因 GLU 自动复制。GLU 公式、双分支 view、BlockMmad、Epilogue
+和 dtype 适配的详细合同统一由
+[GLU / SwiGLU 组件开发指导](../../kernel-design/glu-development.md)定义。
+
+### 2.2 唯一正式架构
+
+本 Scenario 的正式架构只有 L0C2UB：
+
+```text
+Host/Tiling
+    -> selected Base Assembly and GLU delta
+Scheduler
+    -> problem/group/tile ownership
+Kernel
+    -> BlockMmad(A, B_act, B_gate)
+    -> L0C2UB
+    -> GLU Epilogue(act, gate)
+    -> y
+```
+
+L0C2GM 只用于 C-direct 诊断，不属于正式实现或 fallback。任一正式接口为
+`unsupported` 或 `unverified` 时阻塞，不得临时改成 Cube 写 GM workspace、
+第二个 Vector Kernel 执行 GLU。
+
+### 2.3 组件责任
+
+- Scheduler 只分配 problem/group/tile，不解释 `act/gate` 公式。
+- Kernel 构造 `B_act/B_gate` 和成对 N 轴 Tensor view，管理 C/V 生命周期。
+- BMM Kernel 继续拥有 batch loop/decode/offset；通用 Epilogue 只接收映射后的
+  batch-local tile 或展平 row base，不读取 batch Scheduler。
+- BlockMmad 复用 A tile 完成两路矩阵乘，只交付 final C。
+- GLU Epilogue 只消费 Kernel 已切出的局部 `act/gate` tile。
+- Host/Tiling 绑定完整 ABI、资源门禁和静态 `__mix__` entry。
+
+## 3. 资产适配
+
+本 Scenario 不复制公共资产表。GLU Block、Epilogue、Grouped delta、同步 Policy
+和 TilingData 的唯一登记位置是
+[GLU / SwiGLU 组件开发指导](../../kernel-design/glu-development.md)。
+
+目标工程只复制 `DESIGN.md` 选择的 custom delta 及必要直接依赖。连续 ND/DN
+weight 由当前 Grouped GLU Kernel 从 `BlockMmad::LayoutB` 派生；NZ/ZN、独立或
+交错 weight、双 bias、双 MX scale 以及非 SwiGLU 公式均按公共指导标记
+`adaptation_required`，并由目标工程完成对应接口、Golden、编译和设备验证。
+
+## 4. 验证
+
+至少覆盖：
+
+- `act/gate` 不对称 pattern 和用户指定的 GLU 公式；
+- base、M/N/K tail、odd/even M、multi-tile 和 slot reuse；
+- GMM 的空 group、prefix offset 和 group tail；
+- MM_MX 的 K/scale window、padding poison 和 Q alignment 边界；
+- 正式 L0C2UB 路线对应的 C-direct、C-through-L0C2UB、V-zero-C、V-known-C
+  和 Full；
+- 清理诊断代码后的 clean build、重复运行和正式输出路径。
+
+精度异常按
+[GLU 精度诊断](../../kernel-design/glu-precision-diagnosis.md)定位；通用同步、精度
+指标和交付门禁按 Scenario 通用规则导航的唯一事实源执行。

package/assets/ops-direct-invoke/skills/ascendc-blaze-best-practice/references/scenarios/cube-matmul-then-vector-glu/cube-matmul-then-vector-glu-development.md

@@ -0,0 +1,54 @@
+# Cube MatMul -> Vector GLU 开发指导
+
+本文只在同目录 design 已冻结、`implementation_route=blaze_custom` 且
+`selected_scenario=cube-matmul-then-vector-glu` 后用于编译项目 PLAN。Step 4
+只执行 PLAN，不重新选择 GLU 公式、Base Assembly、MemBase/RegBase 或资产。
+
+## 1. PLAN 输入和阅读
+
+PLAN 必须引用已闭合的 `matmul_base_analysis`、基础 ABI、GLU 公式与 paired-axis
+合同、L0C2UB 接口、C/V 生命周期、customization scope 和验证合同。按 DESIGN
+登记以下阅读：
+
+- [GLU 组件指导](../../kernel-design/glu-development.md)及其中实际激活的资产；
+- GMM 时读取 [Grouped MatMul delta](../../kernel-design/group-matmul-delta.md)；
+- 选用普通 AscendC API 或 RegBase/VF 时，分别先加载对应依赖 Skill 根入口；
+- 实际使用的同步、Tiling 和 Launcher 方法，以及 Investigation 绑定的源码位置。
+
+缺少 concrete Kernel/Block/Epilogue signature、Params 字段、物理 layout 或同步
+事实时回 Step 2/3，不让 Step 4 猜测。
+
+## 2. 有序动作
+
+1. 只读核对当前 Blaze witness 和基础 ABI。
+2. 复用 Base MM/BMM/GMM/MM_MX Scheduler/Kernel owner；仅复制 DESIGN 授权的
+   GLU delta 和直接依赖到项目 `blaze_custom`。
+3. 适配双分支 BlockMmad、paired N metadata、L0C2UB 和指定 GLU Epilogue；
+   Block 不实现激活，Epilogue 不读取全局 group/batch 状态。
+4. 在 concrete Kernel 中完成 Tensor view、C-ready/V-done、slot、inactive AIV
+   和 final drain；不得用单独 Vector launch 替代正式 `__mix__` 路线。
+5. 将 TilingData/Params/Wrapper/entry/Launcher 的新增或替换字段逐项映射到
+   `abi_crosswalk_delta`。
+6. 生成与冻结公式、dtype 和转换顺序一致的数据与 Golden。
+
+当 `paired N` 或其他 GLU 物理 view 需要由逻辑 weight/scale 物化时，必须额外
+生成独立 physical witness；Launcher 从逻辑输入重新执行同一份已冻结的 Host
+adapter，并在 H2D 前对 physical value、ScaleB、shape、字节数和 gate offset 做
+逐字节闭合检查。检查失败属于 Host ABI 边界失败，不得启动设备或用 Full 精度
+结果掩盖。Golden 读取该次实际 H2D 的 physical bytes；具体 paired 宽度和 padding
+仍由 DESIGN/PLAN 冻结。
+
+每个 action 必须写明目标文件、来源、前置、checkpoint 和 rollback。资产原文件
+与三个官方源码区始终只读。
+
+## 3. 验证和交付
+
+先构建真实类型链，再按 C-direct、C-through-L0C2UB、V-zero-C、V-known-C、
+Full 定位最早失败边界。覆盖分支不对称、M/N/K tail、multi-tile、slot reuse，
+以及需求激活的 batch/group/MX 边界。若逻辑 Q 小于 Cube 最小宽度或未对齐，
+必须验证 act/gate 两半独立 padding、physical gate offset、逻辑 mask/writeback
+和外部 ABI 未改变；合同允许任意正偶数 N 时必须上板最小 N，不能用实现约束
+缩窄合同。清理所有诊断 entry、known-C 和 Dump 后 clean build 并重跑 Full。
+
+交付记录必须列出最终 entry/symbol、复制并适配的资产、目标版本、支持边界、
+构建/设备验证状态。未上板的组合写 `unverified`，不得从资产存在推导支持。

package/assets/ops-direct-invoke/skills/ascendc-blaze-best-practice/references/scenarios/cube-matmul-then-vector-glu-then-vector-pertoken-quant/cube-matmul-then-vector-glu-then-vector-pertoken-quant-design.md

@@ -0,0 +1,189 @@
+# Cube MatMul -> Vector GLU -> Vector Per-token Quant
+
+本 Scenario 描述一条不可拆分的复杂扩展路线：
+
+```text
+Cube MatMul (MM / BMM / GMM / MM_MX)
+    -> optional bias / scale / dequant
+    -> Vector: specified GLU-family formula
+    -> FP workspace [R, Q]
+    -> Vector: per-token quant
+    -> y [R, Q] + yScale [R]
+```
+
+本页在 [Scenario 索引](../index.md)唯一命中后读取，只描述 Cube
+MatMul、GLU 和 per-token quant 不可拆分组合的场景 delta。
+GMM 相对 MM 的 group 编码、完整 POD、Scheduler/Kernel 生命周期和地址规则
+统一遵循
+[Grouped MatMul 项目侧差异](../../kernel-design/group-matmul-delta.md)。
+
+## 0. Step 3 输入与源码前提
+
+进入正文前必须具备 `requirements_contract`、`operator_interface_contract`、
+`native_gaps`、`matmul_base_analysis` 及其 source-backed `abi_bindings[]`，以及
+同次 Investigation 对基础 Assembly、双分支 L0C2UB、GLU producer、FP
+workspace、全局完成依赖、完整行 consumer、Tiling/Params 和静态 entry 的事实。
+
+缺少决定性事实时只允许向 Step 2 提出一次无场景名补充问题，记录受影响
+requirement IDs、待确认的 producer-completion-consumer 物理关系、有限源码
+前沿和阻塞原因；补充后仍缺失则停止，不生成 PLAN。普通 AscendC API 与
+RegBase/VF 的依赖 Skill 按实际实现路线加载根入口。
+
+DESIGN 必须分别冻结 MatMul/GLU、workspace 交接和 quant 的
+consumed/preserved/added contracts；`abi_crosswalk_delta` 只追加成对 operand、
+workspace、量化参数、entry、输出和同步接线，并为每个 custom 文件记录授权。
+
+## 1. 精确匹配条件
+
+### 1.1 设计主线
+
+`scenario_id`: `cube-matmul-then-vector-glu-then-vector-pertoken-quant`。
+
+仅当需求同时满足以下条件时选择本 Scenario：
+
+- 基础计算是 MM、BMM、GMM 或 MM_MX；对应的 batch/group/MX scale、layout、
+  dtype 和地址合同已确认。
+- 用户明确给出 GLU-family 公式，例如 GLU、Bilinear、ReGLU、GEGLU 或
+  SwiGLU。
+- 将全部逻辑行轴展平为 `R` 后，GLU 输出写入逻辑 `[R,Q]` 的 FP workspace；
+  MM/GMM 通常 `R=M`，BMM 通常 `R=B*M`。
+- per-token quant 对每个完整逻辑行 `[0, Q)` 生成唯一 scale。
+- bias、scale 和 dequant 仅在用户语义要求时存在，其计算顺序和 dtype 已确认。
+
+只包含 GLU，或 Cube MatMul 后直接执行 per-token quant 时，返回
+[Scenario 索引](../index.md)按完整需求选择唯一场景。
+
+### 1.2 成立条件/门禁
+
+- 基础计算变体语义、GLU 公式、workspace `Q` 和 per-token quant 域必须同时闭合。
+- bias、scale、dequant 的存在、顺序和 dtype 均以用户合同为准。
+- 基础组件、证据状态和 `integration_mode` 由当前 Investigation 的 concrete
+  witness 和本场景 DESIGN 绑定。
+
+### 1.3 常见误用
+
+| 误用 | 原因 | 正确处理 |
+|---|---|---|
+| 将简单 GLU 与 quant 两个叶子自由拼接 | 两阶段 workspace、同步和所有权切换尚未联合设计 | 选择本不可拆分 Scenario |
+| 从参考类名默认选择 SwiGLU | 用户公式可能是其他 GLU 变体 | 按 Golden 冻结 activation 和分支 |
+| GLU 后仍按原始拼接宽度 `N` 做 quant | quant 域没有跟随 GLU 输出 | 对完整逻辑输出 `[0,Q)` 生成 scale |
+
+## 2. 不可拆分契约
+
+### 2.1 设计主线：GLU 阶段
+
+两路投影记为 `act` 和 `gate`：
+
+```text
+workspace = activation(act) * gate
+```
+
+`activation`、两路命名、权重排布、bias/scale/dequant、计算 dtype 和输出
+`Q` 均来自用户契约。只有两路各宽 `Q` 且输入拼接宽度明确为 `2Q` 时，才能
+使用 `Q = N / 2`。
+
+GLU 的双分支 Block、公式、布局和组件 delta 见
+[GLU / SwiGLU 组件开发指导](../../kernel-design/glu-development.md)。
+
+### 2.2 接口与数据流：Workspace 交接
+
+GLU 生产者与 quant 消费者共享同一份合同：
+
+| 项 | 必须冻结 |
+|---|---|
+| 逻辑 Tensor | FP workspace `[R,Q]` |
+| 物理布局 | dtype、row pitch、alignment 和实际 GM 容量 |
+| 完成条件 | 所有 workspace 写入完成且本地 C/V 协议 final drain 完成 |
+| 阶段边界 | 单一 `__mix__` entry 内所有 producer/consumer 完成已选同步协议 |
+| 所有权切换 | 交接后由 Kernel 按完整逻辑行重新分配 AIV |
+
+Kernel 根据逻辑 AIV rank 切出连续行 Tensor slice；quant Epilogue 只处理传入
+slice。完整量化、Host selector 和边界合同见
+[Per-token Quant 组件开发指导](../../kernel-design/per-token-quant-development.md)。
+
+### 2.3 成立条件/门禁
+
+- GLU producer 写入的逻辑 shape、dtype、row pitch、alignment 和容量必须与
+  quant consumer 完全一致。
+- workspace 全部写入并完成本地 final drain 后，才能切换到完整行 ownership。
+- quant Epilogue 只消费 Kernel 切出的连续行 slice。
+- 两阶段的同步协议按通用规则导航的同步事实源设计和验证。
+
+### 2.4 常见误用
+
+| 误用 | 原因 | 正确处理 |
+|---|---|---|
+| quant 继承 GLU 的局部列 tile ownership | consumer 不能看到完整 `[0,Q)` | 交接后由 Kernel 按完整逻辑行重新分配 |
+| 使用 chunk-local absmax | 每行产生多个局部 scale | 对完整 workspace 行归约唯一 scale |
+| workspace 写完前开始行重分配 | producer/consumer 生命周期未闭合 | 先证明全部写入和 final drain |
+
+## 3. 参考资产与适配
+
+### 3.1 设计主线
+
+本组合 Scenario 不登记第二份 GLU 或 quant 资产表：
+
+### 3.2 接口与数据流
+
+- GLU Block、Epilogue、Grouped delta 和同步资产只从
+  [GLU / SwiGLU 组件开发指导](../../kernel-design/glu-development.md)选择。
+- quant Epilogue、UB 公式和 Host selector 只从
+  [Per-token Quant 组件开发指导](../../kernel-design/per-token-quant-development.md)选择。
+- 本叶子只拥有 GLU FP workspace→quant 的联合 shape、pitch、完成条件、
+  ownership 重分配和单一 `__mix__` 生命周期合同。
+
+目标工程只复制 `DESIGN.md` 选中的文件及必要直接依赖。
+
+### 3.3 成立条件/门禁
+
+- 目标 MM/BMM/GMM/MM_MX 基础 Assembly、Scheduler、Params 和 Cube→Vector
+  接口由同版本 Investigation 绑定；项目侧 Host TilingData 按关联证据或
+  `DESIGN.md` 单独绑定。
+- 对 BMM，保留 Investigation 绑定的 Base BMM/QBMM batch ownership、
+  Scheduler 和地址公式；GLU 阶段按公共 GLU 指导实现 paired view、双分支
+  Block、L0C2UB/CV 和 row adapter，quant 阶段只增加本叶子定义的完整行
+  ownership 交接。缺少预制 BMM GLU 或 BMM GLU+quant Kernel 资产本身不构成
+  `extension_missing`，上述精确缺口应标记 `adaptation_required`。
+- 正式路线只允许单一 `__mix__` entry，不得拆成独立 GLU producer 和 quant
+  consumer entry。
+- Grouped Block/Kernel/Tiling 资产仅在目标为 GMM 且 group 合同兼容时适配；
+  MM、BMM、MM_MX 不得引入无关的 Grouped delta。
+- 关键接口为 `unknown/conflict` 时阻塞；custom 资产必须有明确 delta 边界。
+- 非 SwiGLU 变体标记 `adaptation_required`，并冻结对应 Epilogue 公式、API、
+  mask/tail 和 Golden。
+
+### 3.4 常见误用
+
+| 误用 | 原因 | 正确处理 |
+|---|---|---|
+| 复制整个 custom 目录 | 未选资产和间接依赖会扩大事实源与符号面 | 只复制 DESIGN 选中的 delta 和直接依赖 |
+| 参考资产存在就判定其他 dtype 或版本支持 | 资产不等于目标 capability | 重新编译并验证目标实例与输出路径 |
+| 共用双分支 Block 就跳过非 SwiGLU Epilogue 适配 | Block 不拥有 activation 公式 | 实现变体 Epilogue 与 Golden |
+| 因没有 BMM GLU+quant 专用资产而改用 GMM Kernel 或直接阻塞 | Base BMM、局部 GLU 和完整行 quant 分属不同责任层 | 保留 BMM Base，并按本叶子联合合同实现精确 custom delta |
+
+## 4. 联合验证
+
+### 4.1 场景验证矩阵
+
+除两个阶段各自的验证外，至少覆盖：
+
+- 不对称 `act/gate` pattern 和用户指定的 GLU 公式；
+- GLU workspace 与最终 INT8/scale 的分阶段 Golden；
+- M/Q tail、multi-tile、single-pass 容量边界和 two-pass 大 Q；BMM 增加 batch
+  边界，GMM 增加 empty group，MM_MX 增加其 scale/block 合同边界；
+- final drain、阶段交接、inactive AIV 和交接后行重分配；
+- 相同输入重复运行，以及 Host 实际选择的静态 quant entry；
+- 清理诊断代码后的完整 Cube MatMul + GLU + quant 回归。
+
+### 4.2 成立条件/门禁
+
+- GLU workspace 和最终量化结果分别与分阶段 Golden 对比。
+- 设备证据覆盖正式输出路径、阶段交接、静态 selector 和 Full 回归。
+- 通用精度、同步和性能结论按通用规则导航的唯一事实源执行。
+
+### 4.3 常见误用
+
+| 误用 | 原因 | 正确处理 |
+|---|---|---|
+| 只比较最终 INT8 输出 | 无法区分 GLU producer 与 quant consumer 误差 | 同时比较 FP workspace、scale 和最终输出 |
+| 两个简单阶段各自 PASS 就宣称组合 PASS | 联合同步、row pitch 和 ownership 未覆盖 | 运行组合边界矩阵和清理后的 Full |

package/assets/ops-direct-invoke/skills/ascendc-blaze-best-practice/references/scenarios/cube-matmul-then-vector-glu-then-vector-pertoken-quant/cube-matmul-then-vector-glu-then-vector-pertoken-quant-development.md

@@ -0,0 +1,52 @@
+# Cube MatMul -> Vector GLU -> Vector Per-token Quant 开发指导
+
+本文只在同目录 design 已冻结、`implementation_route=blaze_custom` 且
+`selected_scenario=cube-matmul-then-vector-glu-then-vector-pertoken-quant`
+后用于编译项目 PLAN。两个简单场景的 PLAN 不得在 Step 4 临时拼接成本路线。
+
+## 1. PLAN 输入和阅读
+
+除基础 MatMul ABI 外，PLAN 必须闭合指定 GLU 公式、可选 bias/scale/dequant
+顺序、FP workspace `[R,Q]` 及 pitch、全部 producer 完成条件、行 ownership
+交接、完整行 quant 合同和 static selector。必读：
+
+- [GLU 组件指导](../../kernel-design/glu-development.md)；
+- [Per-token Quant 组件指导](../../kernel-design/per-token-quant-development.md)；
+- GMM 时读取 [Grouped MatMul delta](../../kernel-design/group-matmul-delta.md)；
+- DESIGN 激活的 API/RegBase Skill、同步、Tiling、Launcher 与 concrete source。
+
+## 2. 有序动作
+
+1. 核对 Base Assembly 和基础 ABI，仅复制 DESIGN 授权的 GLU/quant delta。
+2. 适配双分支 BlockMmad、paired view 和 GLU Epilogue。纯 SwiGLU 使用
+   `BlockEpilogueSwiGlu`；用户合同包含 dequant 时才使用并适配
+   `BlockEpilogueDequantSwiGlu`，二者都不执行 quant。
+3. GLU Epilogue 写唯一 FP workspace `[R,Q]`；冻结 dtype、pitch、alignment、
+   capacity 和逐操作顺序。
+4. GMM GLU custom 路线先适配
+   `group_matmul_kernel_glu_fused.h` 的 GLU C+V1，再由通用
+   `group_matmul_kernel_cv1_v2.h` 组合 V2：以
+   `AscendC::Std::tuple<GluEpilogue, QuantEpilogue>` 占用既有
+   `BlockEpilogue_` 参数，在同一 `__mix__` entry 内按 ops-transformer INT8
+   输入 GMM SwiGLU quant 的阶段骨架完成 C+V1、一次 final drain、AIV-only
+   `SyncAll<true, config>()` 和基于 `realM` 的完整行重分配。GLU group traversal、
+   双分支 view 和 `Q=N/2` 只属于前者，通用组合层不得复制。`+` 的文件级 config
+   显式指定 trigger/wait 均为 `PIPE_ALL`，不得替换成本核
+   `PipeBarrier<PIPE_ALL>`；不得用同 stream 的两个 entry 替代。
+5. 复制并适配 single-pass、two-pass 和共享 UB selector，为两个 quant V2
+   分别实例化静态 tuple Kernel；quant Epilogue 只读 Kernel 切出的 FP
+   workspace slice。
+6. 逐项接线 Params、TilingData、Wrapper、entry、Launcher 和输出 buffer，
+   追加 `abi_crosswalk_delta`。
+7. 生成 GLU workspace、scale、INT8 输出三层 Golden。
+
+## 3. 验证和交付
+
+先验证 C-direct、C-through-L0C2UB、V-zero/V-known 和 GLU workspace，再验证
+阶段交接、single/two-pass selector、yScale 和最终 y。覆盖 act/gate 不对称、
+M/Q/K tail、multi-tile、inactive AIV、empty group/batch/MX 激活边界，以及
+重复执行。只比较最终 INT8 不能作为通过证据。
+
+清理诊断代码后 clean build 并重跑 Full。交付必须枚举唯一正式 entry、实际
+selector 命中、workspace 合同和验证状态；未匹配基线时性能写
+`NOT_EVALUATED`。

package/assets/ops-direct-invoke/skills/ascendc-blaze-best-practice/references/scenarios/cube-matmul-then-vector-pertoken-quant/cube-matmul-then-vector-pertoken-quant-design.md

@@ -0,0 +1,138 @@
+# Cube MatMul -> Vector Per-token Quant
+
+本 Scenario 描述 MM、BMM、GMM 或 MM_MX 的 Cube MatMul 结果经过正式交接后，
+由 Vector 阶段执行 per-token quant 的完整路线：
+
+```text
+Cube MatMul (MM / BMM / GMM / MM_MX)
+    -> FP workspace [R, N]
+    -> Vector: per-token quant
+    -> y [R, N] + yScale [R]
+```
+
+本页在 [Scenario 索引](../index.md)唯一命中后，使用
+[Per-token Quant 组件开发指导](../../kernel-design/per-token-quant-development.md)实现
+完整行归约、single/two-pass、量化参数、阶段交接和精度诊断。本页只描述
+Cube MatMul 直接连接 per-token quant 时的场景边界和集成 delta。
+
+GMM 相对 MM 的 group 编码、完整 POD、Scheduler/Kernel 生命周期和地址规则
+统一遵循
+[Grouped MatMul 项目侧差异](../../kernel-design/group-matmul-delta.md)。
+
+## 0. Step 3 输入与源码前提
+
+进入正文前必须具备 `requirements_contract`、`operator_interface_contract`、
+`native_gaps`、`matmul_base_analysis` 及其 source-backed `abi_bindings[]`，以及
+同次 Investigation 对 MatMul final FP 输出、Fixpipe/GM workspace、Kernel
+参与者、完成依赖、Tiling/Params 和静态 entry 接线的事实。
+
+缺少决定性事实时只允许向 Step 2 提出一次无场景名补充问题，记录受影响
+requirement IDs、待确认的 workspace 物理合同/完成时机、有限源码前沿和阻塞
+原因；补充后仍缺失则停止，不生成 PLAN。quant 代码实际使用普通 AscendC API
+或 RegBase/VF 时，分别先加载对应依赖 Skill 根入口。
+
+DESIGN 必须区分 consumed/preserved/added contracts，并用
+`abi_crosswalk_delta` 只追加 workspace、量化参数、静态 entry、输出和同步接线；
+每个 custom 文件都要记录来源、首个修改点、保持不变量和验证门禁。
+
+## 1. 精确匹配条件
+
+### 1.1 设计主线
+
+`scenario_id`: `cube-matmul-then-vector-pertoken-quant`。
+
+仅当需求同时满足以下条件时选择本 Scenario：
+
+- 基础计算是 MM、BMM、GMM 或 MM_MX；对应的 batch/group/MX scale、layout、
+  dtype 和地址合同已确认。
+- Cube MatMul 的逻辑输出展平为 `[R,N]`；MM/GMM 通常 `R=M`，BMM 通常
+  `R=B*M`。
+- Cube MatMul 与 quant 之间没有 GLU、elementwise、独立 Vector dequant 或
+  其他未命名计算。量化 MatMul 在 Cube/Fixpipe 输出侧完成的 accumulator→FP
+  转换属于 MatMul 最终输出合同，不增加独立 Vector 阶段。
+- per-token quant 对每个完整逻辑行 `[0,N)` 生成唯一 scale。
+- scale、零行、舍入、clamp、饱和范围和 NaN/Inf 行为均已由用户合同或 Golden
+  冻结。
+
+若 MatMul 与 quant 之间还存在 GLU-family 或 shape-preserving elementwise，
+必须分别选择对应的完整组合 Scenario，不能把本 Scenario 与其他叶子自由拼装。
+
+### 1.2 成立条件/门禁
+
+- `integration_mode`、唯一 Base Assembly owner 和目标版本绑定必须由
+  Investigation 证据确认。
+- Cube 输出的 accumulation dtype、workspace dtype、逻辑 `[R,N]`、物理 row
+  pitch 和完成条件必须闭合。
+- quant 组件的输入必须是最终 MatMul 结果，不得是尚未归并的 SplitK/StreamK
+  部分和。
+- 参考资产只是适配起点，不证明目标版本或目标工程已经支持本 Scenario。
+
+### 1.3 常见误用
+
+| 误用 | 原因 | 正确处理 |
+|---|---|---|
+| 已有任意 FP workspace 就选择本 Scenario | 缺少本 Scenario 必需的 Cube MatMul producer | 纯 Vector 请求不属于本 Skill 的 Scenario |
+| MatMul 后还有 elementwise 仍选择本 Scenario | 名称没有表达实际中间阶段 | 选择对应的完整组合 Scenario |
+| 将 quant 组件文档登记为 Scenario | 组件事实源被误当成完整路由 | 注册表只登记从 Cube 开始的完整路线 |
+
+## 2. 接口与数据流
+
+### 2.1 Cube 输出
+
+Cube 阶段必须产生逻辑 `[R,N]` 的最终 FP 结果。若 Fixpipe 能直接写 GM
+workspace，优先使用正式直写路径；不得为了接入 quant 人为增加没有语义的
+identity Vector Epilogue。
+
+`DESIGN.md` 必须冻结：
+
+- MM/BMM/GMM/MM_MX 的基础变体及其输入、layout 和 scale 合同；
+- accumulator 到 FP workspace 的转换顺序和 dtype；
+- `R`、逻辑 `N`、物理 row pitch 和 workspace 容量；
+- 每条逻辑行的 Cube producer 集与 Vector consumer 集；
+- workspace 完成信号、final drain 和 quant 前的 ownership 重分配。
+
+### 2.2 Quant 组件
+
+quant 阶段的数学合同、Params、single/two-pass 静态选择、同步依赖、行切片和
+RNE 边界诊断统一由
+[Per-token Quant 组件开发指导](../../kernel-design/per-token-quant-development.md)定义。
+目标算子必须按 Golden 显式选择饱和范围，不得由 Skill 资产替用户决定。
+
+## 3. 组件与资产适配
+
+### 3.1 设计主线
+
+- Cube Block、Scheduler、Kernel 和 Tiling 以目标版本 Investigation 报告为
+  事实源。
+- quant Epilogue 和 Host selector 以组件开发指导登记的资产为适配起点。
+- Kernel 负责 producer→consumer 交接、workspace Tensor slice 和逻辑行 ownership；
+  quant Epilogue 只消费已切分的 slice。
+- DESIGN 必须冻结实际拓扑：可以是已证明 ownership 的单一 `__mix__` entry，也
+  可以是同一 ACL stream 上的独立 AIC producer 与 AIV consumer。MIX 的物理 block
+  index、task ratio 和参与者集合必须有源码或设备证据；没有证据时不得假设稠密
+  logical rank。候选方案先证明 workspace 依赖和完整行 ownership，再用同设备
+  性能数据选择，不能预先规定 MIX 或 split 永远最优。
+
+### 3.2 成立条件/门禁
+
+- 不得用 GMM 专用 Scheduler、POD 或 selector 证明 MM/BMM/MM_MX 已支持。
+- Host、Tiling、Kernel、Epilogue 和 Launcher 必须共同消费同一逻辑 `N`、pitch
+  和量化参数。
+- 选定拓扑的参与者集合、完成依赖、inactive AIV、final drain 和行重分配必须由
+  目标工程设备证据闭合；同 stream split 还必须证明 producer kernel 完成后
+  consumer kernel 才读取 workspace。
+
+## 4. 验证矩阵
+
+必须同时覆盖：
+
+- MM/BMM/GMM/MM_MX 中目标需求实际包含的基础变体边界；
+- base、M/N/K tail、multi-tile、空 group/零行及重复运行；
+- quant single-pass 容量边界和 two-pass 大 `N`/chunk tail；
+- 全零、tiny、大正负值、舍入半整数附近和 INT8 saturation；
+- Cube workspace、`yScale`、最终 `y` 的分阶段 Golden；
+- 宽范围随机端到端输入，以及只用于隔离 quant 的精确二进制小数输入；
+- 实际命中的静态 kernel entry 和同步方案性能证据。
+
+任何 RNE mismatch 必须按组件开发指导导出 workspace、scale 并分阶段归因；
+位级合同未闭合时不得通过缩窄输入分布声明通过。

package/assets/ops-direct-invoke/skills/ascendc-blaze-best-practice/references/scenarios/cube-matmul-then-vector-pertoken-quant/cube-matmul-then-vector-pertoken-quant-development.md

@@ -0,0 +1,45 @@
+# Cube MatMul -> Vector Per-token Quant 开发指导
+
+本文只在同目录 design 已冻结、`implementation_route=blaze_custom` 且
+`selected_scenario=cube-matmul-then-vector-pertoken-quant` 后用于编译项目 PLAN。
+Step 4 不重新决定量化公式、完整行宽度、UB 路线或同步协议。
+
+## 1. PLAN 输入和阅读
+
+PLAN 必须绑定最终 FP workspace `[R,N]`、物理 pitch、producer/consumer 集、
+完成依赖、完整行 scale 公式、RNE/clamp/saturation 合同、static entry selector
+和基础 MatMul ABI。必读：
+
+- [Per-token Quant 组件指导](../../kernel-design/per-token-quant-development.md)；
+- GMM 时读取 [Grouped MatMul delta](../../kernel-design/group-matmul-delta.md)；
+- Investigation 指定的 Base Kernel/Fixpipe、同步、Tiling 和 Launcher 来源；
+- quant 实现实际使用的 AscendC 或 RegBase 依赖 Skill 根入口及必要叶子。
+
+## 2. 有序动作
+
+1. 核对 Base MatMul final output；Fixpipe 可直接写 FP workspace 时不增加
+   identity Vector Epilogue。
+2. 按 DESIGN 冻结的依赖选择并实现 `__mix__` 或同一 ACL stream 上的
+   producer/consumer split；先闭合 producer 完成、final drain、消费者可见性和
+   完整逻辑行 ownership，再进行性能选择。
+3. 复制并适配 single-pass、two-pass 及共享 selector。`MakeUbLayout()` 是 UB
+   容量唯一事实源；Host 选择独立静态 entry，不修改现有序列化 Tiling ABI。
+4. Kernel 切出带真实 pitch 的 workspace/y/yScale Tensor slice；quant
+   Epilogue 只使用 slice-relative row。
+5. 把量化参数、workspace 字节、entry、拓扑参与者和 Launcher buffer 映射到
+   `abi_crosswalk_delta`；Host 和 device 消费同一合同。
+6. 生成同源 Golden 中间值和最终结果；half-tie 分类使用生成 Golden `y` 的
+   同一个内存 `normalized` tensor。
+
+## 3. 验证和交付
+
+覆盖 single-pass 容量边界前/等于/后、two-pass 大 N、多 chunk/tail、零行、
+tiny、饱和、RNE 和需求规定的非有限值行为；每个 case 记录实际 entry。RNE
+mismatch 必须依次比较 workspace、yScale 和 quant 重算结果。相同输入重复运行
+次数由 DESIGN 冻结；对 MIX 还要记录实际 physical-to-logical owner 映射，
+对 split 还要记录同 stream 顺序和 workspace 可见性；清理诊断后 clean build
+并重跑 Full。
+
+交付分别声明 single-pass 与 two-pass 的正确性和性能状态。没有 matched
+baseline 时性能写 `NOT_EVALUATED`；不得以 single-pass 优化删除任意宽度的
+two-pass 能力。