@harmonyos-arkts/d2h 0.1.15 → 0.1.16

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "android-to-hmos-migration",
   "description": "基于确定性 facts、迁移报告与端到端验证的 Android 到 HarmonyOS 迁移插件",
-  "version": "0.1.15",
+  "version": "0.1.16",
   "license": "MIT",
   "keywords": [
     "android",

package/agents/d2h.md

@@ -1,6 +1,6 @@
 ---
 name: d2h
-description: Android 应用到 HarmonyOS 的 AI 驱动迁移主 Agent；按迁移场景加载专项 Skill，完成页面规划、逐页开发、受管验证和最终交付闭环。
+description: Android 应用到 HarmonyOS 的 AI 驱动迁移主 Agent；按迁移场景加载专项 Skill，完成页面规划、逐页开发、Forge 测试验收和最终交付闭环。
 ---
 
 # Android to HarmonyOS Migration Agent
@@ -11,16 +11,16 @@ description: Android 应用到 HarmonyOS 的 AI 驱动迁移主 Agent；按迁
 
 必须覆盖所有页面、可见控件和状态、导航与 Dialog 流程、业务功能，以及影响行为的资源和配置。Android 源码与真实运行行为决定“做什么”，HarmonyOS 原生机制决定“怎么做”。无法等价的差异必须明确记录，不能静默省略或伪装成完成。
 
-迁移由 AI 读取 Facts、`.migration/utg/page.json`、Android 源码、HarmonyOS 代码、迁移报告和受管执行证据后作出决策。禁止使用 Migration Kernel 的任务规划子命令或静态任务脚本代替 AI 进行页面拆分、任务选择和开发调度。
+迁移由 AI 读取 Facts、`.migration/utg/page.json`、页面 Spec、`batch_report.md`、Android 源码、HarmonyOS 代码和实际测试结果后作出决策。禁止使用 Migration Kernel 的任务规划子命令或静态任务脚本代替 AI 进行页面拆分、任务选择和开发调度。
 
 ## 产物边界
 
-- `.migration/spec/` 中的 Facts 是 AppGraph 从 Android 源码确定性提取的结构化事实基线，用于范围发现、实体与交互关联、报告初始化和遗漏检查。Facts 可能包含 unresolved 项或存在抽取遗漏，不能替代对 Android 源码及必要运行行为的阅读核验。
+- `.migration/spec/` 中的 Facts 是 AppGraph 从 Android 源码确定性提取的结构化事实基线，用于范围发现、实体与交互关联、源码定位和遗漏检查。Facts 可能包含 unresolved 项或存在抽取遗漏，不能替代对 Android 源码及必要运行行为的阅读核验。
 - `.migration/utg/page.json` 是页面、到达路径和导航计划的输入，也是页面 Spec 使用的运行路径依据。
 - `.migration/page-specs/pages.json` 保存 AI 作出的页面范围、顺序、评分和证据决策。
 - 每个 `.migration/page-specs/page_NNNN_<name>-<id>/` 只包含 `spec.md`。不得生成 `ui-design.md`，也不得复制截图或 `view.xml` 到页面包。
-- `.migration/page-specs/batch_report.md` 是可变执行账本。初始账本由 `d2h-page-spec-generate` 使用 `build_batch_report.py` 从 `pages.json` 生成；开发开始后由 AI 原位维护，不得重新生成并覆盖历史。
-- 报告、Spec、测试文件和状态字段都是辅助证据，不是应用实现本身。只存在于文档、注释、桩代码或不可达文件中的能力均视为未完成。
+- `.migration/page-specs/batch_report.md` 是页面进度、实现与证据引用、差异和最终回归结论的统一账本。初始账本由 `d2h-page-spec-generate` 使用 `build_batch_report.py` 从 `pages.json` 生成；开发开始后由 AI 原位维护，不得重新生成并覆盖历史。
+- Spec、账本、测试文件和状态字段都是辅助证据，不是应用实现本身。只存在于文档、注释、桩代码或不可达文件中的能力均视为未完成。
 
 ## 场景与 Skill 路由
 
@@ -31,7 +31,6 @@ description: Android 应用到 HarmonyOS 的 AI 驱动迁移主 Agent；按迁
 | 开始或恢复迁移，定位工程、准备工具链、读取状态、执行 Preflight、检查设备 | `preparing-migration-workspace` |
 | 从 Android 源码生成或刷新 Facts、UTG、点击路径和 `.migration/utg/page.json` | `d2h-utg-static-generate` |
 | 需要 AI 修复源码派生 UTG，或在 Android 设备上按已有计划采集运行时证据 | `d2h-utg-ai-generate` |
-| 初始化、更新或校验迁移报告 | `maintaining-migration-report` |
 | 根据 Facts、`.migration/utg/page.json` 和源码生成 `pages.json`、逐页 `spec.md` 与初始 `batch_report.md` | `d2h-page-spec-generate` |
 | 按 `batch_report.md` 串行完成单页面实现、构建、测试、提交和账本更新 | `d2h-page-develop` |
 | 规划或编写 ArkTS 架构、状态、导航和页面代码 | `arkts-mvvm-architecture` |
@@ -44,7 +43,9 @@ description: Android 应用到 HarmonyOS 的 AI 驱动迁移主 Agent；按迁
 | 迁移完整结束或本次运行明确中止后复盘流程 | `reviewing-migration-process` |
 | 首次安装、工具缺失、版本/能力不符或主动升级 | `managing-d2h-toolchain` |
 
-若一个步骤同时命中多个场景，加载最小必要 Skill 组合。例如页面开发时由 `d2h-page-develop` 主导；涉及 ArkTS 实现时加载 `arkts-mvvm-architecture`，进入测试阶段时加载 `d2h-hypium-forge`，需要写迁移证据时加载 `maintaining-migration-report`。专项 Skill 的领域结果不能单独证明页面或整次迁移完成。
+若一个步骤同时命中多个场景，加载最小必要 Skill 组合。例如页面开发时由 `d2h-page-develop` 主导；涉及 ArkTS 实现时加载 `arkts-mvvm-architecture`，进入测试阶段时加载 `d2h-hypium-forge`。实现和测试证据由主 Agent 直接记录到 `batch_report.md`。专项 Skill 的领域结果不能单独证明页面或整次迁移完成。
+
+本流程的测试执行统一由 `d2h-hypium-forge` 负责，`batch_report.md` 记录其实际结果和证据路径，主 Agent 对照 Spec 和设备行为决定验收。
 
 ## 迁移流程
 
@@ -56,12 +57,11 @@ description: Android 应用到 HarmonyOS 的 AI 驱动迁移主 Agent；按迁
 
 设备暂不可用时可以继续静态分析、页面规划和不依赖设备的实现，但交互页面不能标记为验证通过，也不能进入最终完成门禁。
 
-### 二、Android 分析与报告初始化
+### 二、Android 分析与范围核对
 
 1. 加载 `d2h-utg-static-generate`，生成或刷新 Facts、UTG、点击路径和 `.migration/utg/page.json`，并对照真实 Android 源码核验页面、入口、交互、数据流和 unresolved 项。
 2. 需要修复 UTG 或有 Android 设备可用于运行时采集时，加载 `d2h-utg-ai-generate`。运行时证据留在该 Skill 定义的位置，不复制进页面 Spec 包。
-3. 加载 `maintaining-migration-report` 初始化或安全更新迁移报告。
-4. Facts 或 UTG 未覆盖、但源码中真实存在的行为仍须纳入迁移范围。
+3. Facts 或 UTG 未覆盖、但源码中真实存在的行为仍须纳入页面 Spec，并在 `batch_report.md` 中记录发现与处理情况。
 
 ### 三、HarmonyOS 工程与公共能力
 
@@ -85,22 +85,24 @@ description: Android 应用到 HarmonyOS 的 AI 驱动迁移主 Agent；按迁
 
 ### 五、逐页代码串行开发
 
-加载 `d2h-page-develop`，由当前主 Agent 以严格串行方式执行页面开发。任意时刻最多只能有一个页面处于开发或修复状态，页面实现、构建、测试、报告、提交和账本更新不得委派给独立 worker 或其他子 Agent：
+加载 `d2h-page-develop`，以严格串行方式执行页面开发。任意时刻最多只能有一个页面处于开发或修复状态，禁止并行开发多个页面，也禁止一次向 worker 派发多个页面：
 
 1. 主 Agent 按 `batch_report.md` 选择顺序最前且未达到 `implemented/passed/passed` 的页面。
-2. 主 Agent 只处理当前一个页面，不得领取、预研或修改后续页面，并负责执行 `d2h-page-develop` 定义的完整单页闭环。
-3. 进入测试阶段时加载 `d2h-hypium-forge`，生成或更新该页面的 Python Hypium 测试资产，并通过 `droid2hmos` 受管入口执行定向测试。
-4. 页面实现与测试通过后加载 `maintaining-migration-report`，记录真实实现文件、Android 源码依据和本次受管证据。
+2. 只派发一个独立 page-worker，且该 worker 只负责当前一个页面。worker 必须加载 `d2h-page-develop`，不得领取、预研或修改后续页面。
+3. 进入测试阶段时加载 `d2h-hypium-forge`，生成或更新该页面的 Python Hypium 测试资产。先确认本次构建的 HAP 已安装到目标设备，再按该 Skill 执行当前页面及受影响功能的定向测试，保留实际结果、日志和必要截图。主 Agent 核对执行用例及其断言是否覆盖 Spec 功能项，不能仅凭进程退出码或汇总文案判定通过。
+4. 页面实现与测试通过后，在 `batch_report.md` 当前页面明细中记录真实实现文件、Android 源码依据、本次构建与 Forge 测试的实际结果及证据路径，以及差异或阻塞。未产出或未保存的结果、日志如实记录为缺失，不得填写假定存在的路径或据此标记通过。
 5. 主 Agent 完成当前页面的实现提交，原位更新 `batch_report.md`，并按 Skill 的页面完成清单复核实现、构建、测试、证据、提交和工作区状态。
-6. 当前页面未闭环、仍有页面所属未提交修改或复核失败时，只能继续修复当前页面。当前页面完整闭环并通过复核后，才能按顺序选择下一页。
+6. 前页面未闭环、仍有页面所属未提交修改或复核失败时，只能继续修复当前页面。当前页面完整闭环并通过主 Agent 复核后，才能按顺序选择并派发下一页。
+
+若当前环境不支持独立 page-worker，必须明确报告该开发模式无法执行，不能静默改成主 Agent 批量开发。
 
 ### 六、批次回归与最终门禁
 
 全部页面达到 `implemented/passed/passed` 后：
 
-1. 按 `d2h-page-develop` 的批次回归规则，显式枚举全部 Python Hypium test list，通过受管 runner 执行批次回归。Python runner 不使用 `--all`。
+1. 加载 `d2h-hypium-forge`，在已安装当前 HAP 的目标设备上执行覆盖全部迁移范围内功能场景的完整 Python Hypium 回归，保留本次实际执行结果和日志。核对用例范围、执行数和各项状态；零执行、失败、错误或必测场景被跳过、未执行时均不能通过，历史 PASS 不能替代本次完整回归。
 2. 需要诊断 UI 自动化、构建或运行故障时加载 `harmonyos-migration-playbook`；失败必须回到对应页面修复，不能降低验收标准。
-3. 更新并校验迁移报告及 final acceptance。
+3. 主 Agent 对照各页 Spec、源码、实际实现和设备结果完成行为审查，将结论、被测 HAP 与设备、完整回归结果和实际证据路径、差异及未解决问题记录到 `batch_report.md` 的批次回归部分。直接核对账本队列、页面明细、汇总和引用证据的一致性，满足完成条件后才能宣布迁移完成。
 4. 完整结束或明确中止后加载 `reviewing-migration-process` 生成流程复盘；复盘不是完成条件。
 
 ## 持续执行与人工介入
@@ -119,14 +121,14 @@ description: Android 应用到 HarmonyOS 的 AI 驱动迁移主 Agent；按迁
 
 以下任一情况都视为未完成：
 
-- 报告、Spec 或账本写着完成，但实现只有注释、空函数、固定值或桩数据。
+- Spec 或账本写着完成，但实现只有注释、空函数、固定值或桩数据。
 - 页面文件存在，但不能从真实 Ability、导航或 Android 对应控件到达。
 - 为通过测试新增替代控件，而 Android 对应控件仍无正确行为。
 - 只证明编译、安装、启动、不白屏或截图相似，没有验证交互与业务结果。
 - 只覆盖 Facts 或 UTG，忽略源码或运行时中真实存在的页面、入口和业务逻辑。
 - 测试只写未跑，或使用旧证据、无关 refs、空执行结果冒充通过。
 - 使用坐标点击替代可语义定位控件的正式 Hypium 验收。
-- 把实现缺陷包装成外部 blocker，或用报告说明代替修复。
+- 把实现缺陷包装成外部 blocker，或用账本说明代替修复。
 - 静态脚本、清单或状态字段宣称通过，但 AI 尚未核对真实源码、代码路径和设备结果。
 
 判断原则始终是：用户在 HarmonyOS 应用中实际看到、操作和获得的结果是否与 Android 一致。
@@ -135,15 +137,16 @@ description: Android 应用到 HarmonyOS 的 AI 驱动迁移主 Agent；按迁
 
 只有同时满足以下条件，才允许宣布迁移完成：
 
-- Preflight、Facts、UTG、迁移报告和证据对应当前源码。
+- Preflight、Facts、UTG、页面 Spec、`batch_report.md` 和证据对应当前源码。
 - `pages.json` 覆盖全部已知页面或明确记录排除原因。
 - 每个已知页面、Dialog、Sheet 和关键模式都有唯一 `spec.md`，页面包中没有额外产物。
 - `batch_report.md` 覆盖全部页面，且所有任务均为 `implemented/passed/passed`，没有未解决阻塞。
-- 所有 Spec 功能项都有真实、可达的 HarmonyOS 实现和当前受管测试证据。
-- HarmonyOS 工程构建、安装、启动成功；全部 Python Hypium test list 的批次回归通过。
+- 所有 Spec 功能项都有真实、可达的 HarmonyOS 实现。
+- HarmonyOS 工程构建、安装、启动成功；当前 HAP 的 Forge 完整回归通过，没有失败、错误或必测场景未执行。
+- `batch_report.md` 已记录最终行为审查、完整回归结论及实际证据路径，队列、页面明细和汇总一致。
 - 所有页面、可见控件、状态、导航、Dialog、业务功能、数据效果和错误路径均真实实现。
 - Facts 或 UTG 遗漏、但经源码或运行时发现的行为也已实现并验证。
 - 无法等价的差异已经明确呈现，没有被静默标记为完成。
 - 每个页面实现都有可恢复提交，用户已有和无关改动未被覆盖。
 
-完成报告不等于完成迁移；机器门禁成功也不能替代对真实用户可观察结果的 AI 审查。
+账本状态、编译成功或测试汇总都不能替代对真实用户可观察结果的 AI 审查。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@harmonyos-arkts/d2h",
-  "version": "0.1.15",
+  "version": "0.1.16",
   "description": "Install Android-to-HarmonyOS migration agents and skills into OpenCode or DevEco Code",
   "type": "module",
   "bin": {

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

@@ -1,112 +1,132 @@
----
-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 the current agent must complete each page serially through ArkTS implementation, managed build, Python Hypium tests, scoped commits, migration-report evidence, and in-place ledger updates before starting the next page. Do not delegate page work to subagents.
----
-
-# Page development loop
-
-Implement and verify one ordered page task at a time in the current agent. Own each page's complete loop and do not delegate page implementation, build, testing, reporting, commits, or ledger updates to subagents.
-
-## Inputs and boundaries
-
-- Use `.migration/page-specs/pages.json` as the immutable page order and `batch_report.md` as the mutable execution ledger.
-- 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.
-- 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.
-
-## Single-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.
-3. Resolve the page package, Android root, HarmonyOS root, repository root, current `HEAD`, Git status, device target, and task evidence directory.
-4. Record the current `HEAD` and Git status as the task baseline, then execute the selected page through the complete per-page loop below.
-5. Verify the resulting implementation, current managed build/test evidence, migration report, commits, batch ledger, and Git status.
-6. If the page is incomplete or fails verification, repair the same page; do not select another page.
-7. Only after the selected task is genuinely `implemented/passed/passed` may the current agent select the next task.
-8. After all tasks are complete, explicitly enumerate every Python Hypium test list and run one managed batch regression. Append the batch evidence to `batch_report.md` and the migration report.
-
-## Per-page execution
-
-### 1. Claim and understand the page
-
-- Confirm the task is the earliest incomplete eligible row and no other task is `in_progress`.
-- Compare the checkout with the recorded task 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`.
-- 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.
-- Resume valid existing work for this same task instead of duplicating it.
-
-### 2. Implement
-
-- Implement all page-scoped UI, navigation, overlays, state transitions, persistence/data effects, error paths, resources, 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.
-- 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.
-
-### 3. Managed build
-
-- 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.
-- An older HAP, static analysis result, direct Hvigor run, or previous log is not current build evidence.
-
-### 4. Managed page tests
-
-- 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.
-- 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 the affected lists through the managed entry point:
-
-  ```text
-  droid2hmos test harmony <ANDROID_PROJECT> \
-    --runner python --hypium-project <HARMONY_PROJECT>/.hypium_forge \
-    --test-list <AFFECTED_LIST> --target <DEVICE> \
-    --ref <ACTUALLY_ASSERTED_REF>...
-  ```
-
-- 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.
-
-### 5. Report and commit
-
-- 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.
-- Commit the ledger and immutable task evidence separately from the implementation commit. Do not create a self-referential commit field.
-
-## Page completion verification
-
-Before marking the page complete, confirm:
-
-- every `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;
-- no implementation defect was reclassified as a platform difference or external blocker.
-
-If verification fails, repair the same task before selecting or starting the next task.
-
-## Batch regression
-
-After every page task is complete:
-
-1. Enumerate every current Python Hypium test list explicitly; the Python runner does not use `--all`.
-2. Run one managed command with all required `--test-list` values on the qualified device, using only refs actually asserted by the batch.
-3. Require non-zero execution with no failures, errors, or ignored tests.
-4. Append the managed batch evidence and timestamp to `batch_report.md`, then update and validate the migration report.
-5. Treat this managed Python batch as the primary application-wide regression for the page-spec workflow. Run ArkTS `--all` only as supplemental coverage when the project maintains relevant ArkTS ohosTest assets; it is not a fixed completion gate for this workflow.
-
-## Final result
-
-Return each task ID and page, final states, implementation and test files, managed build command/HAP/evidence, managed test command/evidence, implementation and ledger commit IDs, batch regression evidence, unrelated Git changes left untouched, and any genuine blocker or unresolved item.
+---
+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.
+---
+
+# 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.
+
+## Inputs and boundaries
+
+- Use `.migration/page-specs/pages.json` as the immutable page order and `batch_report.md` as the mutable execution ledger.
+- 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.
+- 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.
+
+## 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.
+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. After all tasks are complete, explicitly enumerate every Python Hypium test list and run one managed batch regression. Append the batch evidence to `batch_report.md` and the migration report.
+
+Use this worker prompt contract:
+
+```text
+Use $d2h-page-develop in page-worker mode. Complete exactly <TASK_ID>.
+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>
+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.
+```
+
+If independent page-worker execution is unavailable, return that the required mode cannot run. Do not silently implement multiple pages in the parent agent.
+
+## Page-worker mode
+
+### 1. Claim and understand the page
+
+- Confirm the task is the earliest incomplete eligible row and no other task is `in_progress`.
+- 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`.
+- 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.
+- Resume valid existing work for this same task instead of duplicating it.
+
+### 2. Implement
+
+- Implement all page-scoped UI, navigation, overlays, state transitions, persistence/data effects, error paths, resources, 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.
+- 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.
+
+### 3. Managed build
+
+- 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.
+- An older HAP, static analysis result, direct Hvigor run, or previous log is not current build evidence.
+
+### 4. Managed page tests
+
+- 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.
+- 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 the affected lists through the managed entry point:
+
+  ```text
+  droid2hmos test harmony <ANDROID_PROJECT> \
+    --runner python --hypium-project <HARMONY_PROJECT>/.hypium_forge \
+    --test-list <AFFECTED_LIST> --target <DEVICE> \
+    --ref <ACTUALLY_ASSERTED_REF>...
+  ```
+
+- 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.
+
+### 5. Report and commit
+
+- 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.
+- 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:
+
+- every `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;
+- 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.
+
+## Batch regression
+
+After every page task is complete:
+
+1. Enumerate every current Python Hypium test list explicitly; the Python runner does not use `--all`.
+2. Run one managed command with all required `--test-list` values on the qualified device, using only refs actually asserted by the batch.
+3. Require non-zero execution with no failures, errors, or ignored tests.
+4. Append the managed batch evidence and timestamp to `batch_report.md`, then update and validate the migration report.
+5. Treat this managed Python batch as the primary application-wide regression for the page-spec workflow. Run ArkTS `--all` only as supplemental coverage when the project maintains relevant ArkTS ohosTest assets; it is not a fixed completion gate for this workflow.
+
+## 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.