@harmonyos-arkts/d2h 0.1.26 → 0.1.27

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

@@ -0,0 +1,378 @@
+"""Behavior checks for the dashboard selection boundary; no real project is touched."""
+
+import copy
+import contextlib
+import io
+import json
+import os
+from pathlib import Path
+import subprocess
+import sys
+import tempfile
+import unittest
+from unittest.mock import patch
+
+import architecture_plan as helper
+from architecture_plan import ContractError, apply_selection, read_selection, 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 = json.loads((SKILL_ROOT / "references" / "architecture-plan.example.json").read_text(encoding="utf-8"))
+        self.decision = {
+            "requestId": "request-1", "planId": self.plan["planId"],
+            "selectedProposalId": "android-mirror",
+            "action": "select-and-create", "source": "dashboard", "notes": "",
+        }
+
+    def test_example_has_three_independently_valid_trees_and_no_user_selection(self):
+        validate_plan(self.plan)
+        self.assertEqual({p["id"] for p in self.plan["proposals"]}, {"android-mirror", "harmony-practice", "hybrid"})
+        self.assertIsNone(self.plan["selectedProposalId"])
+
+    def test_minimal_content_needs_no_execution_paths_or_architecture_relationship_models(self):
+        self.plan["androidAnalysis"]["risks"] = []
+        validate_plan(self.plan)
+        self.assertEqual(set(self.plan["androidAnalysis"]), {"summary", "techStack", "risks"})
+        self.assertEqual(set(self.plan["project"]), {"name", "summary"})
+        for proposal in self.plan["proposals"]:
+            self.assertEqual(set(proposal), {"id", "name", "summary", "directoryTree"})
+        updated, result = apply_selection(self.plan, self.decision)
+        self.assertEqual(result["nextAction"], "create-directory-shell")
+        self.assertEqual(updated["androidAnalysis"], self.plan["androidAnalysis"])
+
+    def test_selecting_nonrecommended_scheme_does_not_change_recommendation_or_trees(self):
+        original = copy.deepcopy(self.plan)
+        updated, result = apply_selection(self.plan, self.decision)
+        self.assertEqual(self.plan, original)
+        self.assertEqual(updated["recommendedProposalId"], "hybrid")
+        self.assertEqual(updated["selectedProposalId"], "android-mirror")
+        self.assertEqual(updated["proposals"], original["proposals"])
+        self.assertNotIn("selection", updated)
+        proposal, confirmation = read_selection(updated, self.decision)
+        self.assertEqual(proposal, updated["proposals"][0])
+        self.assertEqual(confirmation["requestId"], self.decision["requestId"])
+        self.assertEqual(result["nextAction"], "create-directory-shell")
+        validate_plan(updated)
+
+    def test_select_only_does_not_instruct_creation(self):
+        self.decision["action"] = "select"
+        updated, result = apply_selection(self.plan, self.decision)
+        self.assertEqual(result["nextAction"], "selection-recorded")
+        self.assertEqual(updated["selectedProposalId"], "android-mirror")
+
+    def test_exact_retry_does_not_change_plan(self):
+        updated, _ = apply_selection(self.plan, self.decision)
+        retry, result = apply_selection(updated, self.decision, self.decision)
+        self.assertEqual(retry, updated)
+        self.assertEqual(result["status"], "already-applied")
+
+    def test_request_id_cannot_be_reused_with_changed_content(self):
+        updated, _ = apply_selection(self.plan, self.decision)
+        for key, value in (("selectedProposalId", "hybrid"), ("action", "select"), ("notes", "changed")):
+            changed = {**self.decision, key: value}
+            with self.subTest(key=key), self.assertRaisesRegex(ContractError, "requestId"):
+                apply_selection(updated, changed, self.decision)
+
+    def test_new_request_can_change_the_selected_scheme(self):
+        updated, _ = apply_selection(self.plan, self.decision)
+        changed = {**self.decision, "requestId": "request-2", "selectedProposalId": "harmony-practice"}
+        final, result = apply_selection(updated, changed, self.decision)
+        self.assertEqual(result["status"], "applied")
+        self.assertEqual(final["selectedProposalId"], "harmony-practice")
+        _, confirmation = read_selection(final, changed)
+        self.assertEqual(confirmation["selectedProposalId"], "harmony-practice")
+
+    def test_wrong_plan_scheme_action_and_extra_paths_are_rejected(self):
+        for key, value in (
+            ("planId", "another-project"), ("planId", True),
+            ("selectedProposalId", "unknown"), ("action", "run-command"),
+            ("targetRoot", "E:/other"), ("directoryTree", {}),
+        ):
+            with self.subTest(key=key), self.assertRaises(ContractError):
+                apply_selection(self.plan, {**self.decision, key: value})
+        self.assertIsNone(self.plan["selectedProposalId"])
+
+    def test_plan_and_callback_only_need_content_and_selection_metadata(self):
+        self.assertEqual(set(self.plan), {
+            "planId", "project", "androidAnalysis", "proposals", "recommendedProposalId",
+            "recommendationReason", "selectedProposalId",
+        })
+        self.assertEqual(set(self.decision), {
+            "requestId", "planId", "selectedProposalId", "action", "source", "notes",
+        })
+        validate_plan(self.plan)
+        updated, _ = apply_selection(self.plan, self.decision)
+        self.assertEqual(set(updated), set(self.plan))
+
+    def test_fixed_analysis_fields_and_concise_risk_cards_are_validated(self):
+        stack = self.plan["androidAnalysis"]["techStack"]
+        invalid = (
+            {"techStack": "Kotlin"}, {"techStack": [""]},
+            {"techStack": {key: value for key, value in stack.items() if key != "storage"}},
+            {"techStack": {**stack, "ui": ""}},
+            {"techStack": {**stack, "language": ["Kotlin", "Java"]}},
+            {"techStack": {**stack, "frameworks": "extra category"}},
+            {"risks": ["long unstructured risk"]},
+            {"risks": [{"title": "存储适配", "impact": ""}]},
+            {"risks": [{"title": "存储适配"}]},
+            {"risks": [{"title": "存储适配", "impact": "需核验", "answerRequired": True}]},
+            {"risks": [{"title": str(index), "impact": "影响"} for index in range(6)]},
+        )
+        for fields in invalid:
+            with self.subTest(fields=fields), self.assertRaises(ContractError):
+                validate_plan({**self.plan, "androidAnalysis": {**self.plan["androidAnalysis"], **fields}})
+
+    def test_removed_fields_are_not_reintroduced_into_compact_contract(self):
+        cases = (("project", "targetRoot"), ("project", "scope"), ("androidAnalysis", "regions"),
+                 ("androidAnalysis", "structure"), ("androidAnalysis", "openQuestions"),
+                 ("androidAnalysis", "dependencies"), ("proposal", "mappings"),
+                 ("proposal", "dependencies"), ("proposal", "sharedOwners"),
+                 ("proposal", "benefits"), ("proposal", "costs"), ("proposal", "risks"))
+        for section, field in cases:
+            broken = copy.deepcopy(self.plan)
+            value = broken["proposals"][0] if section == "proposal" else broken[section]
+            value[field] = []
+            with self.subTest(section=section, field=field), self.assertRaisesRegex(ContractError, "unknown fields"):
+                validate_plan(broken)
+
+    def test_invalid_paths_case_collisions_and_skipped_levels_are_rejected(self):
+        for path in ("../escape", "/absolute", "E:/absolute", "a\\b", "a//b", "a/./b", "a/../b", "NUL", "x.", "{pages,state}", "a/b"):
+            broken = copy.deepcopy(self.plan)
+            leaf = broken["proposals"][0]["directoryTree"]["children"][0]
+            leaf["path"] = path
+            leaf["name"] = path.split("/")[-1]
+            with self.subTest(path=path), self.assertRaises(ContractError):
+                validate_plan(broken)
+        root = self.plan["proposals"][0]["directoryTree"]
+        root["children"].append({"name": "ENTRY", "path": "ENTRY", "description": "collision", "kind": "directory", "children": []})
+        with self.assertRaisesRegex(ContractError, "case-conflicting"):
+            validate_plan(self.plan)
+
+    def test_nested_module_and_missing_child_array_are_rejected(self):
+        entry = self.plan["proposals"][0]["directoryTree"]["children"][1]
+        entry["children"][0]["kind"] = "HAR"
+        with self.assertRaisesRegex(ContractError, "nested module"):
+            validate_plan(self.plan)
+        entry["children"][0]["kind"] = "directory"
+        del entry["children"][0]["children"]
+        with self.assertRaises(ContractError):
+            validate_plan(self.plan)
+
+    def test_empty_tree_or_tree_without_application_module_is_rejected(self):
+        for mode in ("empty", "no-hap", "hap-without-source"):
+            broken = copy.deepcopy(self.plan)
+            tree = broken["proposals"][0]["directoryTree"]
+            if mode == "empty":
+                tree["children"] = []
+            elif mode == "no-hap":
+                tree["children"][1].pop("kind")
+            else:
+                tree["children"][1]["children"] = []
+            with self.subTest(mode=mode), self.assertRaises(ContractError):
+                validate_plan(broken)
+
+    def test_read_preserves_user_notes_for_implementation_review(self):
+        answer = {**self.decision, "notes": "保留现有目录，只补充风险说明。"}
+        selected, _ = apply_selection(self.plan, answer)
+        _, result = read_selection(selected, answer)
+        self.assertEqual(result["notes"], answer["notes"])
+
+    def test_new_submission_cannot_overwrite_the_confirmation_input_in_place(self):
+        with tempfile.TemporaryDirectory() as directory:
+            root = Path(directory)
+            plan_file, saved_file = root / "architecture-plan.json", root / "architecture-selection.json"
+            plan_file.write_text(json.dumps(self.plan), encoding="utf-8")
+            saved_file.write_text(json.dumps(self.decision), encoding="utf-8")
+            original = plan_file.read_bytes()
+            result = self.run_cli("apply-selection", plan_file, saved_file)
+            self.assertEqual(result.returncode, 1, result.stdout + result.stderr)
+            self.assertEqual(plan_file.read_bytes(), original)
+
+    def test_required_content_scheme_identity_and_selection_consistency_are_checked(self):
+        mutations = (
+            lambda p: p["project"].pop("summary"),
+            lambda p: p["androidAnalysis"].pop("risks"),
+            lambda p: p["androidAnalysis"].pop("techStack"),
+            lambda p: p["androidAnalysis"].update(risks="unknown"),
+            lambda p: p["proposals"][1].pop("directoryTree"),
+            lambda p: p["proposals"].pop(),
+            lambda p: p["proposals"][0].update(id="hybrid"),
+            lambda p: p.update(selectedProposalId="unknown"),
+            lambda p: p.update(selection=None),
+        )
+        for index, mutate in enumerate(mutations):
+            broken = copy.deepcopy(self.plan)
+            mutate(broken)
+            with self.subTest(index=index), self.assertRaises(ContractError):
+                validate_plan(broken)
+
+    def run_cli(self, *args):
+        return subprocess.run([sys.executable, str(HELPER), *map(str, args)],
+                              capture_output=True, text=True, encoding="utf-8", timeout=10)
+
+    def test_dashboard_and_question_use_the_same_durable_confirmation_and_read_step(self):
+        for source in ("dashboard", "question"):
+            with self.subTest(source=source), tempfile.TemporaryDirectory() as directory:
+                root = Path(directory)
+                plan_file, answer_file = root / "architecture-plan.json", root / "tool-answer.json"
+                saved_file = root / "architecture-selection.json"
+                plan_file.write_text(json.dumps(self.plan), encoding="utf-8")
+                answer = {**self.decision, "source": source}
+                answer_file.write_text(json.dumps(answer), encoding="utf-8")
+                applied = self.run_cli("apply-selection", plan_file, answer_file)
+                self.assertEqual(applied.returncode, 0, applied.stdout + applied.stderr)
+                self.assertEqual(json.loads(saved_file.read_text(encoding="utf-8")), answer)
+                saved_plan = json.loads(plan_file.read_text(encoding="utf-8"))
+                self.assertEqual(saved_plan["selectedProposalId"], answer["selectedProposalId"])
+                self.assertNotIn("selection", saved_plan)
+                resumed = self.run_cli("read-selection", plan_file)
+                self.assertEqual(resumed.returncode, 0, resumed.stdout + resumed.stderr)
+                output = json.loads(resumed.stdout)
+                self.assertEqual(output["source"], source)
+                self.assertEqual(output["nextAction"], "create-directory-shell")
+                self.assertEqual(output["selectedProposalId"], "android-mirror")
+                self.assertEqual({p.name for p in root.iterdir()}, {plan_file.name, answer_file.name, saved_file.name})
+
+    def test_read_rejects_unconfirmed_or_mismatched_selection(self):
+        with self.assertRaisesRegex(ContractError, "no confirmed"):
+            read_selection(self.plan, self.decision)
+        updated, _ = apply_selection(self.plan, self.decision)
+        for key, value in (("planId", "other-plan"), ("selectedProposalId", "hybrid")):
+            with self.subTest(key=key), self.assertRaisesRegex(ContractError, "does not match"):
+                read_selection(updated, {**self.decision, key: value})
+
+    def test_read_select_only_never_requests_creation(self):
+        answer = {**self.decision, "action": "select", "source": "question"}
+        updated, _ = apply_selection(self.plan, answer)
+        _, result = read_selection(updated, answer)
+        self.assertEqual(result["nextAction"], "selection-recorded")
+
+    def test_missing_confirmation_file_prevents_directory_implementation(self):
+        with tempfile.TemporaryDirectory() as directory:
+            plan_file = Path(directory) / "architecture-plan.json"
+            selected, _ = apply_selection(self.plan, self.decision)
+            plan_file.write_text(json.dumps(selected), encoding="utf-8")
+            result = self.run_cli("read-selection", plan_file)
+            self.assertEqual(result.returncode, 1, result.stdout + result.stderr)
+            self.assertEqual(json.loads(result.stdout)["status"], "error")
+
+    def test_recovery_applies_saved_question_answer_before_reading_implementation_input(self):
+        with tempfile.TemporaryDirectory() as directory:
+            root = Path(directory)
+            plan_file, saved_file = root / "architecture-plan.json", root / "architecture-selection.json"
+            plan_file.write_text(json.dumps(self.plan), encoding="utf-8")
+            answer = {**self.decision, "source": "question"}
+            saved_file.write_text(json.dumps(answer), encoding="utf-8")
+            pending = self.run_cli("read-selection", plan_file)
+            self.assertEqual(pending.returncode, 1)
+            recovered = self.run_cli("apply-selection", plan_file, saved_file, "--recover")
+            self.assertEqual(recovered.returncode, 0, recovered.stdout + recovered.stderr)
+            ready = self.run_cli("read-selection", plan_file)
+            self.assertEqual(ready.returncode, 0, ready.stdout + ready.stderr)
+            self.assertEqual(json.loads(ready.stdout)["source"], "question")
+
+    def test_cli_retries_without_writing_and_never_creates_target(self):
+        with tempfile.TemporaryDirectory() as directory:
+            root = Path(directory)
+            target = root / "not-created"
+            plan_file, decision_file = root / "architecture-plan.json", root / "incoming-selection.json"
+            plan_file.write_text(json.dumps(self.plan), encoding="utf-8")
+            decision_file.write_text(json.dumps(self.decision), encoding="utf-8-sig")
+            result = self.run_cli("apply-selection", plan_file, decision_file)
+            self.assertEqual(result.returncode, 0, result.stdout + result.stderr)
+            self.assertEqual(json.loads(result.stdout)["nextAction"], "create-directory-shell")
+            first_write = plan_file.stat().st_mtime_ns
+            retry = self.run_cli("apply-selection", plan_file, decision_file)
+            self.assertEqual(retry.returncode, 0, retry.stdout + retry.stderr)
+            self.assertEqual(json.loads(retry.stdout)["status"], "already-applied")
+            self.assertEqual(plan_file.stat().st_mtime_ns, first_write)
+            self.assertFalse(target.exists())
+            self.assertEqual({p.name for p in root.iterdir()}, {plan_file.name, decision_file.name, "architecture-selection.json"})
+
+    def test_changed_retry_is_rejected_without_replacing_confirmation(self):
+        with tempfile.TemporaryDirectory() as directory:
+            root = Path(directory)
+            plan_file, incoming = root / "architecture-plan.json", root / "incoming.json"
+            saved = root / "architecture-selection.json"
+            plan_file.write_text(json.dumps(self.plan), encoding="utf-8")
+            incoming.write_text(json.dumps(self.decision), encoding="utf-8")
+            self.assertEqual(self.run_cli("apply-selection", plan_file, incoming).returncode, 0)
+            plan_bytes, confirmed_bytes = plan_file.read_bytes(), saved.read_bytes()
+            incoming.write_text(json.dumps({**self.decision, "action": "select"}), encoding="utf-8")
+            rejected = self.run_cli("apply-selection", plan_file, incoming)
+            self.assertEqual(rejected.returncode, 1, rejected.stdout)
+            self.assertIn("requestId", json.loads(rejected.stdout)["error"])
+            self.assertEqual(plan_file.read_bytes(), plan_bytes)
+            self.assertEqual(saved.read_bytes(), confirmed_bytes)
+
+    def test_recovery_flag_requires_the_script_owned_confirmation(self):
+        with tempfile.TemporaryDirectory() as directory:
+            root = Path(directory)
+            plan_file, incoming = root / "architecture-plan.json", root / "incoming.json"
+            plan_file.write_text(json.dumps(self.plan), encoding="utf-8")
+            incoming.write_text(json.dumps(self.decision), encoding="utf-8")
+            rejected = self.run_cli("apply-selection", plan_file, incoming, "--recover")
+            self.assertEqual(rejected.returncode, 1)
+            self.assertFalse((root / "architecture-selection.json").exists())
+
+    def test_failed_plan_write_cannot_enter_implementation_and_can_recover(self):
+        with tempfile.TemporaryDirectory() as directory:
+            root = Path(directory)
+            plan_file, incoming = root / "architecture-plan.json", root / "incoming.json"
+            saved = root / "architecture-selection.json"
+            plan_file.write_text(json.dumps(self.plan), encoding="utf-8")
+            incoming.write_text(json.dumps(self.decision), encoding="utf-8")
+            original = plan_file.read_bytes()
+            save_json = helper.save_json
+
+            def fail_plan_write(path, value):
+                if path == plan_file:
+                    raise OSError("simulated plan write failure")
+                save_json(path, value)
+
+            arguments = [str(HELPER), "apply-selection", str(plan_file), str(incoming)]
+            with patch.object(sys, "argv", arguments), patch.object(helper, "save_json", side_effect=fail_plan_write):
+                with contextlib.redirect_stdout(io.StringIO()):
+                    self.assertEqual(helper.main(), 1)
+            self.assertEqual(plan_file.read_bytes(), original)
+            self.assertEqual(json.loads(saved.read_text(encoding="utf-8")), self.decision)
+            self.assertEqual(self.run_cli("read-selection", plan_file).returncode, 1)
+            recovered = self.run_cli("apply-selection", plan_file, saved, "--recover")
+            self.assertEqual(recovered.returncode, 0, recovered.stdout + recovered.stderr)
+            self.assertEqual(self.run_cli("read-selection", plan_file).returncode, 0)
+
+    def test_reloaded_notes_are_utf8_even_with_an_ascii_console(self):
+        with tempfile.TemporaryDirectory() as directory:
+            root = Path(directory)
+            plan_file, incoming = root / "architecture-plan.json", root / "incoming.json"
+            plan_file.write_text(json.dumps(self.plan), encoding="utf-8")
+            answer = {**self.decision, "notes": "保留目录，补充说明 📝"}
+            incoming.write_text(json.dumps(answer, ensure_ascii=False), encoding="utf-8")
+            self.assertEqual(self.run_cli("apply-selection", plan_file, incoming).returncode, 0)
+            result = subprocess.run([sys.executable, str(HELPER), "read-selection", str(plan_file)],
+                                    capture_output=True, timeout=10,
+                                    env={**os.environ, "PYTHONIOENCODING": "ascii"})
+            self.assertEqual(result.returncode, 0, result.stdout + result.stderr)
+            self.assertEqual(json.loads(result.stdout.decode("utf-8"))["notes"], answer["notes"])
+
+    def test_cli_error_leaves_plan_bytes_unchanged_and_returns_structured_error(self):
+        with tempfile.TemporaryDirectory() as directory:
+            root = Path(directory)
+            plan_file, decision_file = root / "plan.json", root / "decision.json"
+            plan_file.write_text(json.dumps(self.plan), encoding="utf-8")
+            original = plan_file.read_bytes()
+            for content in (json.dumps({**self.decision, "planId": "other-plan"}), '{"action":"select","action":"select-and-create"}', '[]', '{invalid'):
+                decision_file.write_text(content, encoding="utf-8")
+                result = self.run_cli("apply-selection", plan_file, decision_file)
+                self.assertEqual(result.returncode, 1, result.stdout + result.stderr)
+                self.assertEqual(json.loads(result.stdout)["status"], "error")
+                self.assertEqual(plan_file.read_bytes(), original)
+
+
+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,52 @@
 ---
-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.
 
 ## 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.
 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, selected task ID, dispatch baseline, device target, and evidence directory. Do not run page-workers in parallel. Wait for its result before the parent begins testing and fixes.
+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 page reaches `implemented/passed/passed`, evidence is current, and all page-owned changes are committed may the parent select the next page and dispatch a new worker.
 
 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>.
+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 +55,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 +65,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 +77,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 +103,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.