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

package/assets/ops-direct-invoke/skills/cannbot-dsl-test-generator/tests/test_skills.py

@@ -0,0 +1,547 @@
+#!/usr/bin/env python3
+# -*- coding: UTF-8 -*-
+# ----------------------------------------------------------------------------------------------------------
+# Copyright (c) 2026 Huawei Technologies Co., Ltd.
+# This program is free software, you can redistribute it and/or modify it under the terms and conditions of
+# CANN Open Software License Agreement Version 2.0 (the "License").
+# Please refer to the License for details. You may not use this file except in compliance with the License.
+# THIS SOFTWARE IS PROVIDED ON AN "AS IS" BASIS, WITHOUT WARRANTIES OF ANY KIND, EITHER EXPRESS OR IMPLIED,
+# INCLUDING BUT NOT LIMITED TO NON-INFRINGEMENT, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE.
+# See LICENSE in the root of the software repository for the full text of the License.
+# ----------------------------------------------------------------------------------------------------------
+
+import csv
+import json
+import os
+import shutil
+import subprocess
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+SCRIPTS = ROOT / "scripts"
+sys.path.insert(0, str(SCRIPTS))
+from prepare_golden import SUPPORT
+
+SPEC = """schema_version: 1
+op: {name: add, error_codes: [shape_mismatch]}
+inputs:
+  - {name: x, role: tensor, dtype_set: [float32], rank_range: [0, 8]}
+  - {name: y, role: tensor, dtype_set: [float32], rank_range: [0, 8]}
+attributes: []
+outputs:
+  - {name: z}
+dtype_policy:
+  supported_combinations:
+    - {inputs: {x: float32, y: float32}, outputs: {z: float32}}
+math_semantics: {formula: "z = x + y"}
+boundary_conditions:
+  - {case: aligned, machine_check: {kind: matches_oracle}}
+  - {case: incompatible, machine_check: {kind: raises_error, error_type: shape_mismatch}}
+extreme_inputs:
+  - {case: nan, machine_check: {kind: nan_propagates}}
+numerical_tolerance:
+  per_dtype:
+    float32: {rtol: 1.0e-6, atol: 1.0e-6, metric: max_relative}
+"""
+DESIGN = """# add
+Algorithm-Add: elementwise addition.
+Stage-Elementwise: add x and y.
+"""
+COLUMNS = (
+    "sheet",
+    "case_id",
+    "source",
+    "branch_ids",
+    "unit_id",
+    "inputs_json",
+    "output_json",
+    "seed",
+    "expected",
+    "assertions_json",
+    "obligation_ids",
+    "note",
+    "status",
+    "design_ref",
+    "condition",
+    "exclude_reason",
+)
+PAIR = {
+    "x": {"shape": [2, 8], "dtype": "float32"},
+    "y": {"shape": [2, 8], "dtype": "float32"},
+}
+
+
+def row(sheet, case_id, inputs=None, **fields):
+    value = {column: "" for column in COLUMNS}
+    value.update(
+        sheet=sheet,
+        source=sheet,
+        case_id=case_id,
+        status="active" if inputs is not None else "excluded",
+        inputs_json=json.dumps(inputs) if inputs is not None else "",
+        output_json="{}",
+        seed="42",
+        assertions_json="[]",
+    )
+    value.update(fields)
+    return value
+
+
+def write_rows(work, rows):
+    path = work / "operators/add/test/testcase.csv"
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with path.open("w", encoding="utf-8-sig", newline="") as handle:
+        writer = csv.DictWriter(handle, fieldnames=COLUMNS)
+        writer.writeheader()
+        writer.writerows(rows)
+    return path
+
+
+def fixture(work):
+    (work / "design/doc").mkdir(parents=True, exist_ok=True)
+    (work / "design/doc/spec.yaml").write_text(SPEC, encoding="utf-8")
+    (work / "design/doc/DESIGN.md").write_text(DESIGN, encoding="utf-8")
+    unit_dir = work / "design/units"
+    unit_dir.mkdir()
+    native = {
+        "unit": {
+            "unit_id": "U01",
+            "title": "add",
+            "kind": "minimal_operator",
+            "design_sources": [
+                {"file": "algorithm.md", "section": "Stage-Elementwise"}
+            ],
+            "depends_on": [],
+            "scope": {"source_files": ["src/add.py"]},
+            "verification_obligations": [
+                {
+                    "id": "VO-U01",
+                    "kind": "numerical",
+                    "design_sources": ["algorithm.md"],
+                }
+            ],
+        }
+    }
+    (unit_dir / "U01.yaml").write_text(json.dumps(native), encoding="utf-8")
+    golden = (
+        "import torch\n"
+        "OP_NAME = 'add'\n"
+        "INPUT_NAMES = ['x', 'y']\nOPTIONAL_INPUT_NAMES = []\nOUTPUT_NAMES = ['z']\n"
+        "ATTR_DEFAULTS = {}\nREQUIRED_ATTR_NAMES = []\n"
+        "TOLERANCE = {'float32': {'rtol': 1e-6, 'atol': 1e-6, 'metric': 'max_relative'}}\n"
+        "DESIGN_REFS = ('Algorithm-Add', 'Stage-Elementwise')\n"
+        "def add_golden(x, y):\n    return torch.add(x, y)\n"
+        "GOLDEN_FUNCTION = add_golden\n" + SUPPORT
+    )
+    (work / "operators/add/test/add_golden.py").parent.mkdir(
+        parents=True, exist_ok=True
+    )
+    (work / "operators/add/test/add_golden.py").write_text(golden, encoding="utf-8")
+    rows = [
+        row(
+            "blackbox",
+            "BB-core",
+            PAIR,
+            expected="match_golden",
+            note="aligned addition",
+            design_ref="math_semantics,dtype_policy.supported_combinations[0],boundary_conditions[0]",
+            condition="L0",
+        ),
+        row(
+            "blackbox",
+            "BB-nan",
+            {
+                "x": {"shape": [8], "dtype": "float32", "fill": "nan_one"},
+                "y": {"shape": [8], "dtype": "float32", "fill": "zeros"},
+            },
+            expected="match_golden_nan",
+            note="NaN propagation",
+            design_ref="extreme_inputs[0]",
+            condition="L1",
+        ),
+        row(
+            "blackbox",
+            "BB-bad-shape",
+            {
+                "x": {"shape": [2, 3], "dtype": "float32"},
+                "y": {"shape": [2, 4], "dtype": "float32"},
+            },
+            expected="raises_error:shape_mismatch",
+            note="invalid shapes",
+            design_ref="boundary_conditions[1]",
+            condition="L2",
+        ),
+        row(
+            "whitebox",
+            "WB-B0",
+            PAIR,
+            branch_ids="B0",
+            expected="match_golden",
+            note="return_value",
+            design_ref="Stage-Elementwise",
+            condition="tile path",
+        ),
+        row(
+            "whitebox",
+            "WB-B-excluded",
+            branch_ids="B-excluded",
+            design_ref="Stage-Elementwise",
+            condition="unreachable path",
+            exclude_reason="not exposed by public inputs",
+        ),
+        row(
+            "tdd",
+            "TD-u01-main",
+            PAIR,
+            unit_id="u01",
+            branch_ids="B0",
+            obligation_ids="VO-U01",
+            expected="match_golden",
+        ),
+    ]
+    path = write_rows(work, rows)
+    return path, rows
+
+
+def run_script(name, work, *extra):
+    args = [
+        "--spec",
+        str(work / "design/doc/spec.yaml"),
+        "--test-dir",
+        str(work / "operators/add/test"),
+    ]
+    if name != "build_blackbox_cases.py":
+        args += ["--design", str(work / "design/doc/DESIGN.md")]
+    if name == "build_tdd_cases.py":
+        args += ["--units-dir", str(work / "design/units")]
+    return subprocess.run(
+        [sys.executable, str(SCRIPTS / name), *args, *extra],
+        text=True,
+        capture_output=True,
+    )
+
+
+class ExplicitPathTests(unittest.TestCase):
+    def test_inputs_and_output_can_use_independent_directories(self):
+        with tempfile.TemporaryDirectory() as temp:
+            work = Path(temp)
+            fixture(work)
+            source = work / "design/doc"
+            spec = work / "inputs/operator.yaml"
+            design = work / "notes/algorithm.md"
+            units = work / "unit-cards"
+            target = work / "output/test-assets"
+            spec.parent.mkdir()
+            design.parent.mkdir()
+            shutil.move(source / "spec.yaml", spec)
+            shutil.move(source / "DESIGN.md", design)
+            shutil.move(work / "design/units", units)
+            target.parent.mkdir(parents=True)
+            shutil.move(work / "operators/add/test", target)
+            base = ["--spec", str(spec), "--test-dir", str(target)]
+            commands = [
+                ("build_blackbox_cases.py", base),
+                ("prepare_golden.py", base + ["--design", str(design)]),
+                ("build_whitebox_cases.py", base + ["--design", str(design)]),
+                (
+                    "build_tdd_cases.py",
+                    base + ["--design", str(design), "--units-dir", str(units)],
+                ),
+            ]
+            for name, args in commands:
+                result = subprocess.run(
+                    [sys.executable, str(SCRIPTS / name), *args],
+                    text=True,
+                    capture_output=True,
+                )
+                self.assertEqual(
+                    result.returncode, 0, f"{name}: {result.stderr} {result.stdout}"
+                )
+            # Execute from a custom directory, then relocate and rename the runner.
+            for directory in (target, work / "relocated/assets"):
+                if directory != target:
+                    shutil.copytree(target, directory)
+                    (directory / "test_add.py").rename(directory / "entry.py")
+                entry = directory / (
+                    "test_add.py" if directory == target else "entry.py"
+                )
+                (directory / "target_add.py").write_text(
+                    "def run(x, y):\n    return x + y\n"
+                )
+                env = dict(
+                    os.environ,
+                    CANNBOTDSL_OP_MODULE="target_add",
+                    CANNBOTDSL_OP_ENTRY="run",
+                )
+                for sheet, case_id in (
+                    ("blackbox", "BB-core"),
+                    ("whitebox", "WB-B0"),
+                    ("tdd", "TD-u01-main"),
+                ):
+                    result = subprocess.run(
+                        [
+                            sys.executable,
+                            str(entry),
+                            "--sheet",
+                            sheet,
+                            "--case-id",
+                            case_id,
+                            "--device",
+                            "cpu",
+                        ],
+                        cwd=work,
+                        env=env,
+                        text=True,
+                        capture_output=True,
+                    )
+                    self.assertEqual(
+                        result.returncode, 0, result.stderr + result.stdout
+                    )
+                    report = (
+                        directory
+                        / "testcase_output"
+                        / sheet
+                        / f"verify_result_{sheet}_{case_id}.csv"
+                    )
+                    with report.open() as handle:
+                        self.assertEqual(
+                            next(csv.DictReader(handle))["status"], "passed"
+                        )
+
+
+class DirectArtifactTests(unittest.TestCase):
+    def test_complete_validation_has_no_intermediate_directory(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            work = Path(tmp)
+            fixture(work)
+            for name in (
+                "build_blackbox_cases.py",
+                "prepare_golden.py",
+                "build_whitebox_cases.py",
+                "build_tdd_cases.py",
+            ):
+                result = run_script(name, work)
+                self.assertEqual(result.returncode, 0, f"{name}: {result.stderr}")
+            self.assertFalse((work / "operators/add/test/intermediate").exists())
+            test = work / "operators/add/test"
+            expected = (
+                (ROOT / "assets/test.py")
+                .read_text()
+                .replace('"__CANNBOTDSL_OP_NAME__"', repr("add"))
+            )
+            self.assertEqual((test / "test_add.py").read_text(), expected)
+            for sheet in ("blackbox", "whitebox", "tdd"):
+                self.assertTrue((test / "testcase_output" / sheet).is_dir())
+
+    def test_blackbox_coverage_and_exclusion_are_read_from_csv(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            work = Path(tmp)
+            path, rows = fixture(work)
+            rows = [row for row in rows if row["case_id"] != "BB-bad-shape"]
+            rows.append(
+                row(
+                    "blackbox",
+                    "BB-exclude-shape",
+                    design_ref="boundary_conditions[1]",
+                    exclude_reason="target API does not expose this shape",
+                )
+            )
+            write_rows(work, rows)
+            result = run_script("build_blackbox_cases.py", work, "--coverage")
+            self.assertEqual(result.returncode, 0, result.stderr)
+            report = json.loads(result.stdout)
+            self.assertEqual(
+                report["exclusions"]["boundary_conditions[1]"],
+                "target API does not expose this shape",
+            )
+            self.assertFalse((path.parent / "intermediate").exists())
+
+    def test_uncovered_spec_path_rejected(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            work = Path(tmp)
+            _, rows = fixture(work)
+            write_rows(work, [row for row in rows if row["case_id"] != "BB-bad-shape"])
+            result = run_script("build_blackbox_cases.py", work)
+            self.assertNotEqual(result.returncode, 0)
+            self.assertIn("uncovered blackbox spec paths", result.stderr)
+
+    def test_unknown_golden_design_reference_rejected(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            work = Path(tmp)
+            fixture(work)
+            golden = work / "operators/add/test/add_golden.py"
+            golden.write_text(
+                golden.read_text().replace("Stage-Elementwise", "Stage-Missing"),
+                encoding="utf-8",
+            )
+            result = run_script("prepare_golden.py", work)
+            self.assertNotEqual(result.returncode, 0)
+            self.assertIn("DESIGN_REFS", result.stderr)
+
+    def test_obligation_kind_requires_matching_evidence(self):
+        for kind in ("performance", "unknown", "semantic", "device"):
+            with self.subTest(kind=kind), tempfile.TemporaryDirectory() as tmp:
+                work = Path(tmp)
+                _, rows = fixture(work)
+                native_path = work / "design/units/U01.yaml"
+                native = json.loads(native_path.read_text())
+                native["unit"]["verification_obligations"][0]["kind"] = kind
+                native_path.write_text(json.dumps(native), encoding="utf-8")
+                rejected = run_script("build_tdd_cases.py", work)
+                self.assertNotEqual(rejected.returncode, 0, rejected.stdout)
+                if kind in ("performance", "unknown"):
+                    self.assertIn(
+                        "unsupported verification obligation kind", rejected.stderr
+                    )
+                    continue
+                tdd = next(row for row in rows if row["sheet"] == "tdd")
+                tdd["expected"] = "assertions"
+                assertion = (
+                    {"kind": "output_device"}
+                    if kind == "device"
+                    else {"kind": "output_shape", "shape": [2, 8]}
+                )
+                tdd["assertions_json"] = json.dumps([assertion])
+                write_rows(work, rows)
+                accepted = run_script("build_tdd_cases.py", work)
+                self.assertEqual(accepted.returncode, 0, accepted.stderr)
+
+    def test_missing_tdd_obligation_rejected(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            work = Path(tmp)
+            _, rows = fixture(work)
+            write_rows(work, [row for row in rows if row["sheet"] != "tdd"])
+            result = run_script("build_tdd_cases.py", work)
+            self.assertNotEqual(result.returncode, 0)
+
+    def test_fixed_runner_executes_direct_csv_case(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            work = Path(tmp)
+            fixture(work)
+            prepared = run_script("prepare_golden.py", work)
+            self.assertEqual(prepared.returncode, 0, prepared.stderr)
+            (work / "target_add.py").write_text(
+                "import torch\ndef run(x, y):\n    return torch.add(x, y)\n",
+                encoding="utf-8",
+            )
+
+            env = os.environ.copy()
+            env["PYTHONPATH"] = str(work)
+            env["CANNBOTDSL_OP_MODULE"] = "target_add"
+            result = subprocess.run(
+                [
+                    sys.executable,
+                    str(work / "operators/add/test/test_add.py"),
+                    "--sheet",
+                    "blackbox",
+                    "--case-id",
+                    "BB-core",
+                    "--device",
+                    "cpu",
+                ],
+                env=env,
+                text=True,
+                capture_output=True,
+            )
+            self.assertEqual(result.returncode, 0, result.stderr)
+            self.assertIn("total=1 failed=0", result.stdout)
+
+    def test_structural_unit_requires_real_probe_events(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            work = Path(tmp)
+            _, rows = fixture(work)
+            native_path = work / "design/units/U01.yaml"
+            native = json.loads(native_path.read_text())
+            native["unit"]["kind"] = "pipeline_framework"
+            native["unit"]["verification_obligations"][0]["kind"] = "structural"
+            native_path.write_text(json.dumps(native), encoding="utf-8")
+            tdd = next(row for row in rows if row["sheet"] == "tdd")
+            tdd["expected"] = "assertions"
+            tdd["assertions_json"] = json.dumps(
+                [{"kind": "output_shape", "shape": [2, 8]}]
+            )
+            write_rows(work, rows)
+            rejected = run_script("build_tdd_cases.py", work)
+            self.assertNotEqual(rejected.returncode, 0)
+            self.assertIn("probe_events", rejected.stderr)
+            tdd["assertions_json"] = json.dumps(
+                [{"kind": "probe_events", "events": ["stage-0"]}]
+            )
+            write_rows(work, rows)
+            accepted = run_script("build_tdd_cases.py", work)
+            self.assertEqual(accepted.returncode, 0, accepted.stderr)
+
+    def test_runner_loads_nested_probe_module(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            work = Path(tmp)
+            _, rows = fixture(work)
+            tdd = next(row for row in rows if row["sheet"] == "tdd")
+            tdd["expected"] = "assertions"
+            tdd["assertions_json"] = json.dumps(
+                [{"kind": "probe_events", "events": ["add"]}]
+            )
+            write_rows(work, rows)
+            self.assertEqual(run_script("prepare_golden.py", work).returncode, 0)
+            probe = work / "operators/add/probe"
+            probe.mkdir()
+            for package in (work / "operators", probe.parent, probe):
+                (package / "__init__.py").touch()
+            (probe / "add_probe.py").write_text(
+                "events = []\ndef reset(): events.clear()\ndef snapshot(): return list(events)\n"
+            )
+            (probe.parent / "add.py").write_text(
+                "from .probe import add_probe\ndef run(x, y):\n"
+                "    add_probe.events.append('add')\n    return x + y\n"
+            )
+
+            env = dict(
+                os.environ,
+                PYTHONPATH=str(work),
+                CANNBOTDSL_OP_MODULE="operators.add.add",
+                CANNBOTDSL_PROBE_MODULE="operators.add.probe.add_probe",
+            )
+            result = subprocess.run(
+                [
+                    sys.executable,
+                    str(work / "operators/add/test/test_add.py"),
+                    "--sheet",
+                    "tdd",
+                    "--device",
+                    "cpu",
+                ],
+                env=env,
+                capture_output=True,
+                text=True,
+            )
+            self.assertEqual(result.returncode, 0, result.stderr + result.stdout)
+
+    def test_excluded_whitebox_is_not_executed(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            work = Path(tmp)
+            fixture(work)
+            result = run_script("prepare_golden.py", work)
+            self.assertEqual(result.returncode, 0, result.stderr)
+            import ast
+
+            tree = ast.parse((ROOT / "assets/test.py").read_text(encoding="utf-8"))
+            function = next(
+                node
+                for node in tree.body
+                if isinstance(node, ast.FunctionDef) and node.name == "_rows"
+            )
+            context = {"CASEBOOK": work / "operators/add/test/testcase.csv", "csv": csv}
+            exec(
+                compile(
+                    ast.Module(body=[function], type_ignores=[]), "<runner>", "exec"
+                ),
+                context,
+            )
+            self.assertEqual(
+                [item["case_id"] for item in context["_rows"]("whitebox", None)],
+                ["WB-B0"],
+            )
+            with self.assertRaisesRegex(ValueError, "no cases selected"):
+                context["_rows"]("whitebox", "WB-B-excluded")

package/assets/ops-direct-invoke/skills/cannbot-dsl-test-generator/tests/test_synthesize_dtype.py

@@ -0,0 +1,85 @@
+#!/usr/bin/env python3
+# -*- coding: UTF-8 -*-
+# ----------------------------------------------------------------------------------------------------------
+# Copyright (c) 2026 Huawei Technologies Co., Ltd.
+# This program is free software, you can redistribute it and/or modify it under the terms and conditions of
+# CANN Open Software License Agreement Version 2.0 (the "License").
+# Please refer to the License for details. You may not use this file except in compliance with the License.
+# THIS SOFTWARE IS PROVIDED ON AN "AS IS" BASIS, WITHOUT WARRANTIES OF ANY KIND, EITHER EXPRESS OR IMPLIED,
+# INCLUDING BUT NOT LIMITED TO NON-INFRINGEMENT, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE.
+# See LICENSE in the root of the software repository for the full text of the License.
+# ----------------------------------------------------------------------------------------------------------
+
+"""Regression for scalar/mapped synthesis dtype and real CSV validation."""
+
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "scripts"))
+from build_blackbox_cases import validate_literal_synthesis
+from test_skills import fixture, run_script
+
+
+class SynthesisDtypeTests(unittest.TestCase):
+    def check(self, dtype, inputs):
+        validate_literal_synthesis(
+            "BB-dtype", "extreme_inputs[0]", {"synthesize": {"dtype": dtype}}, inputs
+        )
+
+    def test_scalar_applies_to_all_tensors_not_attributes(self):
+        values = {
+            "q": {"shape": [2], "dtype": "float16"},
+            "k": {"shape": [2], "dtype": "float16"},
+            "scale": 0.5,
+            "mask": None,
+        }
+        self.check("float16", values)
+        values["k"]["dtype"] = "float32"
+        with self.assertRaisesRegex(ValueError, "dtype for k"):
+            self.check("float16", values)
+
+    def test_mapping_allows_mixed_dtypes_and_partial_constraints(self):
+        values = {
+            "q": {"shape": [2], "dtype": "float16"},
+            "mask": {"shape": [2], "dtype": "float32"},
+        }
+        self.check({"q": "float16", "mask": "float32"}, values)
+        self.check({"q": "float16"}, values)
+        self.check(None, values)
+        self.check({}, values)
+        for dtype in ({"missing": "float16"}, {"mask": "float16"}):
+            with self.assertRaises(ValueError):
+                self.check(dtype, values)
+
+    def test_tensor_list_members(self):
+        values = {"xs": {"tensors": [{"shape": [1], "dtype": "float16"}]}}
+        self.check("float16", values)
+        self.check({"xs": "float16"}, values)
+        values["xs"]["tensors"].append({"shape": [1], "dtype": "float32"})
+        with self.assertRaises(ValueError):
+            self.check("float16", values)
+
+    def test_invalid_formats_report_contract_error(self):
+        for dtype in ([], ["float16"], 0, False, "", "unknown", {"x": 3}):
+            with (
+                self.subTest(dtype=dtype),
+                self.assertRaisesRegex(ValueError, "synthesize.dtype"),
+            ):
+                self.check(dtype, {"x": {"shape": [1], "dtype": "float16"}})
+
+    def test_real_blackbox_cli_accepts_scalar_and_mapping(self):
+        import yaml
+
+        for dtype in ("float32", {"x": "float32", "y": "float32"}):
+            with self.subTest(dtype=dtype), tempfile.TemporaryDirectory() as temp:
+                work = Path(temp)
+                fixture(work)
+                spec_path = work / "design/doc/spec.yaml"
+                spec = yaml.safe_load(spec_path.read_text())
+                spec["extreme_inputs"][0]["synthesize"] = {"dtype": dtype}
+                spec_path.write_text(yaml.safe_dump(spec))
+                result = run_script("build_blackbox_cases.py", work)
+                self.assertEqual(result.returncode, 0, result.stdout + result.stderr)
+                self.assertIn("validated", result.stdout)

package/assets/ops-direct-invoke/skills/cannbot-dsl-unit-planner/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: cannbot-dsl-unit-planner
+description: "根据 CANNBotDSL 算子的规格和调用方提供的设计资料，规划有依赖关系、可实现并独立验收的纵向实现 Unit，识别关键能力缺口和设计偏离风险，输出 U*.yaml。当用户要求拆分算子实现任务或编写 Unit 时使用。"
+---
+
+# CANNBotDSL 实现单元规划
+
+## 输入与输出
+
+- 算子规格：数学、接口和边界语义的来源。
+- 设计资料：调用方提供的单份文档或分文件目录。若有索引，按索引查阅执行路径、Host/Kernel 阶段、资源、同步、API 证据与验证方案。
+- 可选：已有实现代码、测试、补证记录和用户指定约束，用于判断已证实能力与改动范围。
+
+在调用方指定目录输出 `U01.yaml` 至 `U<n>.yaml`，每份只有一个 `unit` 对象，格式见 [Unit YAML 格式](references/unit-format.md)。Unit 数量由真实能力边界决定；每份交付能力必须在其声明的输入域内可实现、可判定、可被后继使用。本 Skill 规划实现与检验义务，不执行设备探针、不编写测试 Case 或修改上游设计。
+
+## 划分方法
+
+1. **提取约束与未决事实。** 从设计识别真实执行路径、最小合法输入、任务映射、资源、同步和验证要求。阅读 [可实现性与边界检查](references/decomposition-checks.md)，区分规格语义、设计承诺、可自由调整的实现细节；将影响调用契约、执行域、布局转换、同步、资源或规模的未决项归入首次使用它的 Unit。导入/签名或通用环境编译成功不代表组合数据通路已验证。
+2. **确定首个闭环。** 首个计算 Unit 在明确的合法输入子域内贯通入口、必要校验、真实计算与写回，以独立 Golden 验收。它不要求一次完成全输入域和最终并行调度；只保留该子域不可缺少的机制，后置机制写明归属和设计允许的演进方式。可先交付独立公开能力或真实流水协议；选择 `pipeline_framework` 时须能验证真实生产/消费及同步，而非占位阶段或不同断言类别。
+3. **让风险与能力共同交付。** 关键能力未验证时，在对应 Unit 的 `implementation.feasibility_checks` 写明前置补证、适用环境/形状、成功证据与失败返回点；补证失败就返回设计修订，后继不得消费其 `provides`。多个未决机制耦合时用一个最小真实数值闭环验证组合，避免先冻结假框架。若已知缺口导致无法给出保留设计承诺的实现路线，指出具体缺口并返回设计；仅在规划中写“实现期定选”不足以放行。
+4. **按纵向能力递增。** 最小数值闭环后，按有效多块状态、尾块安全、特殊值、跨任务并行、布局、可选输入和分支组合等真实故障面划分。搬入/Cube/Vector/写回等横向工序不是独立算子能力。设计规定的流水深度、执行域与数据通路属于实现义务，不能仅作为可选的性能优化；性能采样本身不列为实现 Unit。
+5. **核对依赖与保留面。** 每份 Unit 明确支持的输入域、前序可保留的行为与契约、可区分的验收点，以及为何不能合并。能力依赖与实际修改文件分别记录，不因共享文件虚构能力依赖。增量允许重构内部资源、ABI 或算子内部调度，但须保留已交付行为与设计承诺，并回归受影响的前序能力；前序尚未真正成立就要被重建时，调整边界或合并相关闭环。
+6. **分别验证语义与设计。** 数值义务检查 Golden；结构义务检查实际执行域、搬运链、生产/消费、代次与并行关系。阶段名称、槽号、静态配置和按预期拼装的事件不能证明真实结构。覆盖轴写会触发实现行为的量，例如去重/过滤后的有效列数跨块、槽复用、连续调用与状态存活期；参数大但有效工作小不算覆盖。
+
+已有设计 Case 仅作为线索，具体输入、Case ID、Golden 和命令由测试设计决定。最小输入域之外的合法能力应由后继 Unit 覆盖，临时不支持的路径不得以占位输出冒充已实现能力。
+
+`design_constraints` 和 `feasibility_checks` 必须落到验证义务或明确的源码/编译产物/设备证据检查；只增加描述字段不能提供门禁。无法由现有测试契约表达的义务记录具体证据缺口，交调用方处理，不能将 Case ID 关联或普通数值通过视为已验证。
+
+## 逐份产出与检查
+
+先读 spec、Unit 格式和设计索引，确定能力边界、关键风险归属与依赖轮廓；随后只展开当前 Unit 所需章节。聚合文档与分文件择一阅读相同内容，仅在引用缺失或事实冲突时补查。已有降级、缺口或验收争议时定向查阅对应实现、测试或补证记录。
+
+按依赖顺序生成 Unit，每份明确后写入正式目录，用 YAML 解析器检查单一 `unit` 对象、ID/文件名一致、必需字段与义务；再推进下一份。整体边界变化时同步修订受影响文件。未闭合事实应明确补证归属与失败阻断，不生成占位 Unit 冒充交付。
+
+全部写完后统一检查：ID/义务 ID 唯一；依赖存在且无环；requires 可由依赖闭包提供；每项依赖有原因；设计引用真实；首个数值闭环完整；各 Unit 的输入域与 out_of_scope/后继覆盖一致；关键未决项先验证后使用；设计约束/补证有 obligation_ids 或 review_evidence 关联、可物化触发条件写入义务；设计约束有可区分的证据；覆盖真实多块/复用行为。完成标准是以上检查均闭合或明确返回设计的具体缺口，部分文件落盘不等于完成。