@harmonyos-arkts/d2h 0.1.26 → 0.1.28

package/skills/d2h-architecture-plan/scripts/test_architecture_plan.py

@@ -0,0 +1,241 @@
+"""Final-display contract checks. No source or HarmonyOS project is touched."""
+
+import copy
+import json
+import os
+from pathlib import Path
+import subprocess
+import sys
+import tempfile
+import unittest
+
+from architecture_plan import ContractError, directory_tree, load_json, validate_plan
+
+
+SKILL_ROOT = Path(__file__).resolve().parents[1]
+HELPER = SKILL_ROOT / "scripts" / "architecture_plan.py"
+
+
+class ArchitecturePlanTests(unittest.TestCase):
+    def setUp(self):
+        self.plan = load_json(SKILL_ROOT / "references" / "architecture-plan.example.json")
+
+    def nodes(self):
+        def visit(node):
+            yield node
+            for child in node["children"]:
+                yield from visit(child)
+        return list(visit(self.plan["directoryTree"]))
+
+    def node(self, path):
+        return next(node for node in self.nodes() if node["path"] == path)
+
+    def cli(self, *args, env=None):
+        return subprocess.run([sys.executable, "-X", "utf8", "-B", str(HELPER), *map(str, args)],
+                              capture_output=True, encoding="utf-8", env=env, check=False)
+
+    def test_example_is_one_final_tree_with_decision_notes(self):
+        before = copy.deepcopy(self.plan)
+        validate_plan(self.plan)
+        self.assertEqual(self.plan, before)
+        self.assertEqual(set(self.plan), {"projectName", "directoryTree", "decisions"})
+        paths = directory_tree(self.plan["directoryTree"])
+        self.assertIn("entry/src/main/ets/features/mail/messageview", paths)
+        self.assertNotIn("products/thunderbird", paths)
+        self.assertTrue(self.plan["decisions"])
+
+    def test_missing_extra_and_legacy_top_fields_are_rejected(self):
+        for key in self.plan:
+            changed = copy.deepcopy(self.plan)
+            del changed[key]
+            with self.subTest(missing=key), self.assertRaises(ContractError):
+                validate_plan(changed)
+        for key in ("project", "androidAnalysis", "proposals", "recommendedProposalId", "recommendationReason",
+                    "selectedProposalId", "selection", "planId", "revision", "schemaVersion", "targetRoot", "dependencies"):
+            with self.subTest(extra=key), self.assertRaises(ContractError):
+                validate_plan({**self.plan, key: None})
+
+    def test_project_name_and_decision_fields_must_be_nonempty_text(self):
+        for value in (None, True, 0, [], {}, "", " \n"):
+            with self.subTest(projectName=value), self.assertRaises(ContractError):
+                validate_plan({**self.plan, "projectName": value})
+            for key in ("title", "description"):
+                changed = copy.deepcopy(self.plan)
+                changed["decisions"][0][key] = value
+                with self.subTest(decision=key, value=value), self.assertRaises(ContractError):
+                    validate_plan(changed)
+
+    def test_decisions_require_a_nonempty_exactly_shaped_array(self):
+        for value in (None, {}, "decision", [], [{}], [{"title": "保留"}],
+                      [{"title": "保留", "description": "原包族", "confirmed": True}]):
+            with self.subTest(value=value), self.assertRaises(ContractError):
+                validate_plan({**self.plan, "decisions": value})
+
+    def test_old_dependency_array_and_embedded_relationship_fields_are_rejected(self):
+        for value in ([], [{"fromPath": "entry", "toPath": "AppScope", "description": "旧关系模型"}]):
+            with self.subTest(value=value), self.assertRaises(ContractError):
+                validate_plan({**self.plan, "dependencies": value})
+        for key, value in (("fromPath", "entry"), ("toPath", "AppScope"), ("dependencies", [])):
+            changed = copy.deepcopy(self.plan)
+            changed["decisions"][0][key] = value
+            with self.subTest(key=key), self.assertRaises(ContractError):
+                validate_plan(changed)
+
+    def test_nodes_require_description_children_and_known_fields(self):
+        for key in ("name", "path", "description", "children"):
+            changed = copy.deepcopy(self.plan)
+            del changed["directoryTree"][key]
+            with self.subTest(missing=key), self.assertRaises(ContractError):
+                validate_plan(changed)
+        for key, value in (("description", ""), ("children", {}), ("kind", "module"),
+                           ("kind", None), ("selected", True)):
+            changed = copy.deepcopy(self.plan)
+            changed["directoryTree"][key] = value
+            with self.subTest(key=key), self.assertRaises(ContractError):
+                validate_plan(changed)
+
+    def test_root_is_a_normal_directory_at_dot(self):
+        for key, value in (("path", "entry"), ("kind", "HAP")):
+            changed = copy.deepcopy(self.plan)
+            changed["directoryTree"][key] = value
+            with self.subTest(key=key), self.assertRaises(ContractError):
+                validate_plan(changed)
+
+    def test_names_and_direct_nesting_must_match_paths(self):
+        for path, name in (("entry/src/main", "main"), ("entry/src", "sources")):
+            changed = copy.deepcopy(self.plan)
+            node = changed["directoryTree"]["children"][1]["children"][0]
+            node.update(path=path, name=name)
+            with self.subTest(path=path, name=name), self.assertRaises(ContractError):
+                validate_plan(changed)
+
+    def test_unsafe_and_placeholder_paths_are_rejected(self):
+        for path in ("/absolute", "E:/target", "../source", "a/../b", "a//b", "./entry", "a\\b",
+                     "pages/*", "{pages,state}", "<产品>", "…", "CON", "NUL.txt", "aux", "COM¹", "lpt².log", "a.", "a ",
+                     "bad\x00path", "bad?path"):
+            changed = copy.deepcopy(self.plan)
+            changed["directoryTree"]["children"][0].update(path=path, name=path.split("/")[-1])
+            with self.subTest(path=path), self.assertRaises(ContractError):
+                validate_plan(changed)
+
+    def test_duplicate_and_case_conflicting_paths_are_rejected(self):
+        for name in ("AppScope", "appscope"):
+            changed = copy.deepcopy(self.plan)
+            duplicate = copy.deepcopy(changed["directoryTree"]["children"][0])
+            duplicate.update(name=name, path=name)
+            changed["directoryTree"]["children"].append(duplicate)
+            with self.subTest(name=name), self.assertRaisesRegex(ContractError, "duplicate/case-conflicting"):
+                validate_plan(changed)
+
+    def test_application_hap_and_expanded_production_root_are_required(self):
+        changed = copy.deepcopy(self.plan)
+        changed["directoryTree"]["children"] = []
+        with self.assertRaisesRegex(ContractError, "application HAP"):
+            validate_plan(changed)
+        self.node("entry")["kind"] = "HAR"
+        with self.assertRaisesRegex(ContractError, "application HAP"):
+            validate_plan(self.plan)
+        self.node("entry")["kind"] = "HAP"
+        self.node("entry")["children"] = []
+        with self.assertRaisesRegex(ContractError, "src/main"):
+            validate_plan(self.plan)
+
+    def test_empty_hap_production_root_is_rejected(self):
+        self.node("entry/src/main")["children"] = []
+        with self.assertRaisesRegex(ContractError, "src/main"):
+            validate_plan(self.plan)
+
+    def test_hap_tree_validation_is_not_tied_to_one_source_language(self):
+        for name in ("js", "cpp"):
+            changed = copy.deepcopy(self.plan)
+            source = next(node for node in self.nodes() if node["path"] == "entry/src/main/ets")
+            source = copy.deepcopy(source)
+            def rebase(node):
+                node["path"] = node["path"].replace("entry/src/main/ets", f"entry/src/main/{name}", 1)
+                for child in node["children"]:
+                    rebase(child)
+            rebase(source)
+            source["name"] = name
+            changed["directoryTree"]["children"][1]["children"][0]["children"][0]["children"][0] = source
+            with self.subTest(source=name):
+                validate_plan(changed)
+
+    def test_module_cannot_be_inside_another_modules_source_tree(self):
+        for kind in ("HAP", "HAR", "HSP"):
+            self.node("entry/src/main/ets/features")["kind"] = kind
+            with self.subTest(kind=kind), self.assertRaisesRegex(ContractError, "source tree"):
+                validate_plan(self.plan)
+
+    def test_module_grouping_outside_a_source_tree_is_not_rejected_as_nesting(self):
+        self.node("entry")["children"].append({
+            "name": "libraries", "path": "entry/libraries", "description": "库目录分组", "children": [{
+                "name": "mail", "path": "entry/libraries/mail", "kind": "HAR",
+                "description": "由独立构建配置注册的库模块", "children": [{
+                    "name": "src", "path": "entry/libraries/mail/src", "description": "库源码", "children": [{
+                        "name": "main", "path": "entry/libraries/mail/src/main", "description": "生产根", "children": [{
+                            "name": "ets", "path": "entry/libraries/mail/src/main/ets",
+                            "description": "库的 ArkTS 源码", "children": [],
+                        }],
+                    }],
+                }],
+            }],
+        })
+        validate_plan(self.plan)
+
+    def test_multiple_hap_modules_and_sibling_libraries_are_supported(self):
+        for kind in ("HAP", "HAR", "HSP"):
+            with self.subTest(kind=kind):
+                changed = copy.deepcopy(self.plan)
+                module = copy.deepcopy(changed["directoryTree"]["children"][1])
+                def rebase(node):
+                    node["path"] = "second" + node["path"][len("entry"):]
+                    for child in node["children"]:
+                        rebase(child)
+                rebase(module)
+                module.update(name="second", kind=kind)
+                changed["directoryTree"]["children"].append(module)
+                validate_plan(changed)
+
+    def test_invalid_json_duplicate_keys_and_nonstandard_numbers_are_rejected(self):
+        with tempfile.TemporaryDirectory() as temporary:
+            path = Path(temporary) / "plan.json"
+            for content in ('{"projectName": "a", "projectName": "b"}', '{"bad": NaN}',
+                            '{"bad": Infinity}', '{"bad": -Infinity}', '{broken', 'null'):
+                path.write_text(content, encoding="utf-8")
+                with self.subTest(content=content), self.assertRaises(ValueError):
+                    validate_plan(load_json(path))
+
+    def test_cli_validates_utf8_bom_and_makes_no_writes_or_confirmation_files(self):
+        with tempfile.TemporaryDirectory() as temporary:
+            path = Path(temporary) / "architecture-plan.json"
+            path.write_text(json.dumps(self.plan, ensure_ascii=False), encoding="utf-8-sig")
+            before = path.read_bytes()
+            result = self.cli("validate", path, env={**os.environ, "PYTHONIOENCODING": "ascii"})
+            self.assertEqual(result.returncode, 0, result.stdout + result.stderr)
+            self.assertEqual(json.loads(result.stdout), {"status": "valid", "projectName": "示例邮件客户端"})
+            self.assertEqual(path.read_bytes(), before)
+            self.assertEqual([p.name for p in path.parent.iterdir()], [path.name])
+
+    def test_cli_errors_do_not_rewrite_input_and_missing_file_is_reported(self):
+        with tempfile.TemporaryDirectory() as temporary:
+            path = Path(temporary) / "architecture-plan.json"
+            for content in ('{"proposals": []}', '{broken', '[]'):
+                path.write_text(content, encoding="utf-8")
+                result = self.cli("validate", path)
+                self.assertEqual(result.returncode, 1)
+                self.assertEqual(json.loads(result.stdout)["status"], "error")
+                self.assertEqual(path.read_text(encoding="utf-8"), content)
+            result = self.cli("validate", path.parent / "missing.json")
+            self.assertEqual(result.returncode, 1)
+            self.assertEqual(json.loads(result.stdout)["status"], "error")
+
+    def test_legacy_selection_commands_are_unavailable(self):
+        for command in ("apply-selection", "read-selection"):
+            result = self.cli(command, "architecture-plan.json")
+            with self.subTest(command=command):
+                self.assertNotEqual(result.returncode, 0)
+                self.assertIn("invalid choice", result.stderr)
+
+
+if __name__ == "__main__":
+    unittest.main()

package/skills/d2h-dashboard/SKILL.md

@@ -19,6 +19,7 @@ npx --yes d2h-dashboard@latest --dataDir <项目>/.migration [--port 8080] [--ho
 
 - `.migration/progress.json` 出现（`progress init` 后）或恢复会话已存在 → 自动启动看板并用默认浏览器打开 URL，不等用户请求；每轮会话执行一次，复用实例不重复启动、不重复打开。
 - 启动或打开失败只记录不阻塞迁移，下次阶段更新重试一次。
+- 确认 `$url` 后按「TUI 常驻横幅」一节更新横幅；端口漂移（重启落到新端口）同样触发更新。
 
 ## 后台启动与验证（必做）
 
@@ -53,7 +54,17 @@ do {
 
 **URL 告知规范**：URL 单独成行或用反引号包裹，其后不得紧跟任何文字（含中文括号说明）——否则 markdown 会把 URL+后缀渲染成单个失效链接，说明放下一行。
 
+## TUI 常驻横幅
+
+- 确认 `$url` 后（启动/复用/端口漂移）执行，10s 超时防卡死：
+  ```powershell
+  Start-Process cmd.exe -ArgumentList '/c opencode-tui-extension.cmd set "<url>"' -NoNewWindow -PassThru | Wait-Process -Timeout 10 -ErrorAction SilentlyContinue
+  ```
+  bash：`timeout 10 opencode-tui-extension set "<url>"`
+- 停止看板后同法执行 `clear`
+- 失败/超时/命令不存在：只记录不阻塞，降级为 URL 单独成行输出；安装注册由 `d2h install` 负责，本 skill 不做初始化
+
 ## 复用与停止
 
 - **复用**：启动前探测 8080–8090 `GET /api/data/manifest`（1s 超时），`root` == 目标 dataDir 且 `GET /` 返回 200 才复用该 URL；仅 root 匹配但 `GET /` 非 200 属损坏实例（资产被删/版本切换残留），按停止规则杀掉后重新启动。root 不匹配跳过（其他流程的服务器）。服务器常驻，会话结束不回收，残留进程属预期。
-- **停止**：仅用户显式要求（「关闭看板」「关闭 XX 项目看板」）才执行，且必须 root 归属校验通过：Windows `Get-NetTCPConnection -LocalPort <port> -State Listen | ForEach-Object { Stop-Process -Id $_.OwningProcess }`（杀 node 真实 PID，cmd 包装 PID 无效）；bash `kill <pid>`。未找到 → 报告未在运行；root 不匹配 → 跳过并说明属于其他流程。
+- **停止**：仅用户显式要求（「关闭看板」「关闭 XX 项目看板」）才执行，且必须 root 归属校验通过：Windows `Get-NetTCPConnection -LocalPort <port> -State Listen | ForEach-Object { Stop-Process -Id $_.OwningProcess }`（杀 node 真实 PID，cmd 包装 PID 无效）；bash `kill <pid>`。未找到 → 报告未在运行；root 不匹配 → 跳过并说明属于其他流程。停止成功后按「TUI 常驻横幅」执行 `clear`。

package/skills/d2h-spec-develop/SKILL.md

@@ -1,50 +1,53 @@
 ---
-name: d2h-page-develop
-description: Implement ordered Android-to-HarmonyOS page tasks from pages.json, batch_report.md, and page-scoped spec.md files. Use during page development when a dedicated page-worker must complete one page through ArkTS implementation, managed build, Python Hypium tests, scoped commits, migration-report evidence, and in-place ledger updates before the next page starts.
+name: d2h-spec-develop
+description: Implement ordered Android-to-HarmonyOS page tasks from pages.json, batch_report.json, and page-scoped spec.md files. Use during page development when a dedicated page-worker must complete one page's ArkTS implementation and managed build; the parent agent owns testing and fixes, rebuilding, evidence, commits, and final acceptance before the next page starts.
 ---
 
 # Page development loop
 
-Implement and verify one ordered page task at a time. The parent agent selects and reviews the task; a dedicated page-worker owns exactly one page's complete loop.
+Each page-worker implements only the selected page and brings its build to a pass. After development is complete, the parent agent takes over testing, defect fixes, and acceptance for the current task. A worker may be reused for a fixed ordered group of up to three related Specs. Implement one assigned task per handoff; the parent accepts it before authorizing the same worker to continue with the next member. Task identities, states, evidence and acceptance remain separate. Reuse is conditional on the host supporting child-session continuation and the parent confirming that the next task shares relevant context, the worker can use the refreshed baseline and interfaces, and no unresolved task or ownership conflict remains. Otherwise, explicitly revise the group and dispatch a fresh worker for the remaining scope.
 
 ## Inputs and boundaries
 
-- Use `.migration/page-specs/pages.json` as the immutable page order and `batch_report.md` as the mutable execution ledger.
+- Use `batch_report.json` for task identities, dependencies, planning and execution state. Read included tasks and execution order from its bound planning field; legacy ledgers without planning use tasks order only when no selected scope is supplied. Do not read plan.json for execution or recovery. Keep task IDs and page packages unchanged.
 - Use the selected page package's `spec.md` as the authority for page scope, behavior, acceptance sequences, Android evidence, and expected HarmonyOS files.
-- Read `.migration/utg/page.json` when the Spec references a UTG node or the arrival path needs clarification. Read cited Android source before implementing behavior.
-- Do not require or generate `ui-design.md`, copied screenshots, copied `view.xml`, or any other page-package artifact. Each `page_NNNN_<name>-<id>/` directory continues to contain only `spec.md`.
-- Do not regenerate `pages.json`, page Specs, or `batch_report.md` during ordinary development. Correct an owning artifact only when current source proves it wrong, record the reason, and preserve execution history.
+- When a development scope is supplied, require bound ledger planning and execute only its included tasks. Never select an excluded task because its Spec exists or its ledger state is pending. Return mixed selected/unselected behavior in one Spec as a scope conflict before implementation.
+- Read `.migration/utg/page.json` when the Spec references a UTG node or the arrival path needs clarification. Read cited Android source before implementing or fixing behavior.
+- Each `page_NNNN_<name>-<id>/` directory contains only `spec.md`. Do not add `ui-design.md`, copied screenshots, copied `view.xml`, or test/build evidence to page packages. Keep evidence in the resolved task evidence directory.
+- Do not regenerate `pages.json`, page Specs, or `batch_report.json` during ordinary development. Correct an owning artifact only when current source proves it wrong, record the reason, and preserve execution history.
 - Use `droid2hmos` managed build and test entry points. Do not use task-planning commands or static scripts to choose or execute page work.
-- Preserve unrelated user changes. Never reset, discard, or include them in a page commit.
+- Preserve unrelated user changes throughout implementation, parent fixes, and commits. Never reset, discard, or include them in a page commit.
 
 ## Parent-agent mode
 
-1. Read `pages.json` and `batch_report.md`; use AI judgment to verify their task IDs, order, links, counts, and current states agree.
-2. Select the earliest ordered page whose development/build/validation states are not `implemented/passed/passed` and whose declared dependencies are satisfied.
+1. Read `pages.json` and `batch_report.json`; verify task identities, Spec paths and dependencies against pages.json, and use ledger planning for development scope and execution order. Verify planning references, counts and states. Reject missing, stale or invalid planning instead of falling back to all tasks when a selected scope or planning is present.
+2. Select the earliest eligible task in planning milestone/wave order (or legacy ledger tasks order when allowed) whose development/build/validation states are not `implemented/passed/passed` and whose declared dependencies are satisfied. When bound planning is present, the parent may group it with adjacent unfinished tasks in the same wave that share page, module or component context, normally two or three tasks and never more than three. Fix the ordered task IDs before dispatch; keep complex or unclear work as a single task and verify dependencies again before each member starts.
 3. Resolve the page package, Android root, HarmonyOS root, repository root, current `HEAD`, Git status, device target, and task evidence directory.
-4. Dispatch exactly one page-worker with absolute paths, selected task ID, dispatch baseline, device target, and evidence directory. Do not run page-workers in parallel or give one worker multiple pages.
-5. Wait for the worker to complete the selected page. If it is incomplete or fails review, send the same page back for repair; do not select another page.
-6. Independently verify the resulting implementation, current managed build/test evidence, migration report, commits, batch ledger, and Git status.
-7. Only after the selected task is genuinely `implemented/passed/passed` may the parent select the next task.
-8. Only when the user explicitly requests it, enumerate every Python Hypium test list and run one managed batch regression. Append the batch evidence to `batch_report.md` and the migration report.
+4. Dispatch exactly one page-worker with absolute paths, the current task ID, ordered group task IDs when present, dispatch baseline, device target, and task evidence directory. Do not run page-workers in parallel. Wait for its result before the parent begins testing and fixes. Preserve the returned child-session identifier for possible continuation; use the host's actual resume parameter and confirm that the continuation returns the same session ID. A new child session is a fresh dispatch, not context reuse.
+5. After the worker returns, the parent takes ownership of the current page and executes testing and all fixes according to **Managed page tests and fixes** below until current build and required tests pass.
+6. Execute **Parent report and commits** below.
+7. Apply **Parent verification** below. Only after the current page reaches `implemented/passed/passed`, evidence is current, and all page-owned changes are committed may the parent authorize the same worker to implement the next group member. Refresh its task package, baseline, permitted paths, dependency evidence and evidence directory. If continuation is unsupported or reuse review fails, explicitly revise the group and dispatch a fresh worker for the next eligible task with these refreshed inputs; lack of reuse support must not block normal serial development. If a member is blocked or the group becomes invalid, return to the parent with remaining tasks unchanged; do not skip members or expand the group. Dispatch a worker for a new group only after the current group closes or is explicitly revised.
 
 Use this worker prompt contract:
 
 ```text
-Use $d2h-page-develop in page-worker mode. Complete exactly <TASK_ID>.
+Use $d2h-spec-develop in page-worker mode. Complete the initial implementation and managed build for exactly <TASK_ID>.
+Assigned task IDs: <fixed ordered group of 1–3 task IDs; implement only TASK_ID until parent acceptance and explicit continuation>
+Skill path: <absolute path to this SKILL.md>
 Migration root: <absolute path>
 Page package: <absolute path>
 Android root: <absolute path>
 HarmonyOS root: <absolute path>
 Repository root: <absolute path>
 Dispatch baseline: <HEAD and recorded Git status>
+Execution ledger: <absolute batch_report.json path; planning revision/hash, milestone ID, wave ID when present>
 Device target: <target>
 Evidence directory: <absolute task/run directory>
 
 Own the complete page loop: read spec.md, UTG evidence and cited Android source;
-implement the page; run managed build; load $d2h-hypium-forge and execute the
-page tests through the managed Python runner; update the migration report;
-create scoped commits; and update batch_report.md in place. Do not start another page.
+implement the page; run managed build; update the migration report and batch_report.json in place;
+create scoped commits;  Do not start another page.
+After handoff, the parent owns all testing, defect fixes, rebuilding, and acceptance.
 ```
 
 If independent page-worker execution is unavailable, return that the required mode cannot run. Do not silently implement multiple pages in the parent agent.
@@ -53,9 +56,9 @@ If independent page-worker execution is unavailable, return that the required mo
 
 ### 1. Claim and understand the page
 
-- Confirm the task is the earliest incomplete eligible row and no other task is `in_progress`.
+- Confirm the task is the earliest incomplete eligible task in ledger planning (or legacy task order when allowed) and no other page is being implemented or awaiting parent acceptance.
 - Compare the checkout with the dispatch baseline. Preserve and avoid unrelated dirty files; if ownership conflicts with a build-affecting file, return the exact conflict instead of overwriting it.
-- Mark only the selected task `in_progress` in the working copy of `batch_report.md`.
+- Mark only the selected task `in_progress` in `batch_report.json`.
 - Read the complete `spec.md`, the referenced `.migration/utg/page.json` node, every cited Fact, and every cited Android source file. Follow handlers, state transitions, repositories, navigation, persistence, error paths, and platform side effects far enough to establish the observable result.
 - Inspect the HarmonyOS architecture, routes, resources, shared components, tests, and current implementation. Load `arkts-mvvm-architecture` before planning or writing ArkTS.
 - Build a private checklist mapping every `F-xxx` to reachable code, a stable semantic locator, an executed test assertion, and an observable result. Do not create another planning file.
@@ -63,10 +66,11 @@ If independent page-worker execution is unavailable, return that the required mo
 
 ### 2. Implement
 
-- Implement all page-scoped UI, navigation, overlays, state transitions, persistence/data effects, error paths, resources, and required shared integration.
+- Implement all page-scoped UI and UI resources, navigation, overlays, state transitions, persistence/data effects, error paths, and required shared integration.
 - Use the Android source and observable behavior for functional truth. Use HarmonyOS-native architecture and components for the target implementation.
 - Give tested interactive elements stable, unique semantic locators. Do not add controls solely to make testing easier.
-- Load the applicable domain Skill for identity, i18n, drawable conversion, icon sizing, or third-party substitution when the page touches that domain. Before implementing platform capabilities or uncertain HarmonyOS APIs (`@kit.*` Kit imports or `@ohos.*` modules), and when build or test failures point to API signatures or behavior, load `d2h-cloud-knowledge`: check `.migration/knowledge/kb_cache.json` first, query only on cache miss, and record conclusions with doc `title`/`uri` back into the cache, the page spec evidence, and the migration report.
+- Load the applicable domain Skill for identity, i18n, drawable conversion, icon sizing, or third-party substitution.
+- Before implementing platform capabilities or uncertain HarmonyOS APIs (`@kit.*` Kit imports or `@ohos.*` modules), and when build or test failures point to API signatures or behavior, load `d2h-cloud-knowledge`.
 - Keep shared changes limited to capabilities this page actually needs and record downstream consumers.
 - Do not leave stubs, fixed success values, swallowed errors, unreachable pages, placeholder controls, or TODO implementations.
 
@@ -74,12 +78,20 @@ If independent page-worker execution is unavailable, return that the required mo
 
 - Run a fresh, non-interactive, bounded build through `droid2hmos build harmony <ANDROID_PROJECT>` using the resolved project configuration.
 - Save the exact command, exit status, timestamps, relevant log, produced HAP path, and HAP SHA-256 in the task evidence directory.
-- Treat compilation errors caused or exposed by the implementation as work to fix. Repeat edit/build until the managed build passes.
+- Fix compilation errors caused or exposed by the implementation within this worker until the build passes.
 - An older HAP, static analysis result, direct Hvigor run, or previous log is not current build evidence.
 
-### 4. Managed page tests
+### 4. Worker report and commits
 
-- Load `d2h-hypium-forge`. Add or update executable Python Hypium tests for every `F-xxx`, with paired `.py` and `.json` test-list assets and stable semantic locators.
+- Load `maintaining-migration-report` while evidence is fresh. Record real HarmonyOS files, Android source provenance, current managed evidence, differences, and source-proven discoveries; run report validation.
+- After a successful build, inspect Git status and diff and create a scoped initial implementation commit containing only this page's implementation, resources, required shared files, and source-proven Spec corrections. Do not commit unrelated changes.
+- Update the existing `batch_report.json` task object, summary, evidence, files, implementation commit, timestamps, blockers, and append-only history in place. Do not rerun `build_batch_report.py`. When planning is present, record planning_ref with revision, sha256, milestone_id and wave_id in this run's task history. Preserve planning and planning_history when updating task results.
+- Set `implemented/passed/not_run` only when all three states are supported by current evidence. Use AI inspection to confirm task/summary/history consistency and preserve all prior history.
+- Return the handoff and stop modifying this page. Do not generate or execute tests or select the next page.
+
+## Managed page tests and fixes
+
+- The parent agent loads `d2h-hypium-forge` to perform testing. Add or update executable Python Hypium tests for every `F-xxx`, with paired `.py` and `.json` test-list assets and stable semantic locators.
 - Cover navigation or overlay lifecycle, state changes, data effects, and error behavior required by the Spec. Assertions must prove the declared result, not merely that a page or button exists.
 - Run only the current page's test lists (the `pageNNNN_*` lists owned by this task) through the managed entry point. Do not append regression lists from other pages.
 
@@ -92,35 +104,33 @@ If independent page-worker execution is unavailable, return that the required mo
 
 - Save the exact command, result, native report/log, device target, timestamps, hashes, and returned `managedEvidence` in the task evidence directory.
 - A written-but-unexecuted test, screenshot-only check, coordinate-only replay, direct local runner, old log, or zero-test result is not a pass.
-- Fix implementation or test defects and repeat managed build/test until both pass. Only a persistent external environment, signing, or device failure may become `blocked`, after bounded retries with diagnostics recorded.
+- After application fixes, repeat managed build, installation, and managed tests until current build and required tests pass. Only persistent external environment, signing, or device failures may become `blocked` after bounded retries and recorded diagnostics.
 
-### 5. Report and commit
+## Parent report and commits
 
 - Load `maintaining-migration-report` while evidence is fresh. Record real HarmonyOS files, Android source provenance, current managed evidence, differences, and source-proven discoveries; run report validation.
-- Inspect Git status and diff. Stage only the selected page's implementation, resources, tests, necessary shared files, and a source-proven correction to this page's `spec.md` when required. Do not include unrelated changes.
-- Create a scoped implementation commit only after the managed build and page tests pass. Record its commit ID.
-- If build-affecting page changes remain after the commit, correct the commit and rerun build/test so the evidence proves the committed tree.
-- Update the existing `batch_report.md` queue row, detail section, counts, evidence, files, implementation commit, timestamp, blocker, and chronological notes in place. Do not rerun `build_batch_report.py`.
-- Set `implemented/passed/passed` only when all three states are supported by current evidence. Use AI inspection to confirm queue/detail/count consistency and preserve all prior history.
+- Inspect the final diff. After current build and tests pass, commit the parent's page fixes, test files, and necessary shared changes.
+- Update the existing `batch_report.json` task object, summary, evidence, files, implementation commit, timestamps, blockers, and append-only history in place. Do not rerun `build_batch_report.py`. When planning is present, record planning_ref with revision, sha256, milestone_id and wave_id in this run's task history. Preserve planning and planning_history when updating task results.
+- Set `implemented/passed/passed` only when all three states are supported by current evidence. Use AI inspection to confirm task/summary/history consistency and preserve all prior history.
 - Commit the ledger and immutable task evidence separately from the implementation commit. Do not create a self-referential commit field.
 
 ## Parent verification
 
-Before accepting the worker result, independently confirm:
+Before dispatching a worker for the next page, the parent confirms:
 
-- every `F-xxx` has reachable implementation, a stable locator, and an actually executed assertion;
+- every dispatched `F-xxx` has reachable implementation, a stable locator, and an actually executed assertion;
 - the page is reachable from the real app entry without a test-only route or replacement control;
-- build logs, HAP hash, test reports, managed evidence, and migration-report refs correspond to the implementation commit;
-- `batch_report.md` is internally consistent and the selected row is `implemented/passed/passed`;
-- both scoped commits exist and no uncommitted change owned by the page remains;
-- user changes and other pages were not reset or included;
+- final build logs, installed HAP hash, source snapshot, test reports, managed evidence, migration-report refs, and recorded implementation commit correspond to the final tested application;
+- `batch_report.json` is internally consistent and the selected task row is `implemented/passed/passed`;
+- all page-owned implementation, tests, report, ledger, and evidence changes are committed, while unrelated user changes remain untouched;
 - no implementation defect was reclassified as a platform difference or external blocker.
 
-Review failure returns the same task for repair. The worker never selects or starts the next task.
+If any check fails, the parent continues fixing the issues and repeats the necessary build/install/test and reporting steps.
 
 ## Batch regression
 
-Run the batch regression only when the user explicitly requests it. During ordinary page development, run only the current page's test lists (see Step 4).
+Run the batch regression only when the user explicitly requests it. During ordinary page development, run only the current page's test lists.
 
 ## Worker result
-Return the task ID and page, final states, implementation and test files, managed build command/HAP/evidence, managed test command/evidence, implementation and ledger commit IDs, unrelated Git changes left untouched, and any genuine blocker or unresolved item.
+
+Return the task ID and page, final states, implementation and test files, managed build command/HAP/evidence, implementation and ledger commit IDs, unrelated Git changes left untouched, and any genuine blocker or unresolved item.