@harmonyos-arkts/d2h 0.1.2 → 0.1.5

package/skills/harmonyos-migration-playbook/references/ui-automation.md

@@ -13,13 +13,12 @@ Use device automation as evidence, not as a substitute for understanding the UI.
 Use the managed evidence commands for collection and packaging:
 
 ```text
-droid2hmos evidence capture <android|harmony> <android-project> --name <name> [--target <id>]
-droid2hmos evidence flow android <android-project> --name <name> [--task <task>]
+droid2hmos evidence capture harmony <android-project> --name <name> [--target <id>]
 droid2hmos evidence flow harmony <android-project> --name <name> (--class <class> [--case <case>] | --all)
 droid2hmos evidence compare <android-project> --name <name> --android <android-evidence-dir> --harmony <harmony-evidence-dir>
 ```
 
-`capture` collects the screenshot, UI tree/`dumpLayout`, and device logs. `flow` creates before/after captures around a configured Android test or HarmonyOS Hypium test. `compare` creates a dual-platform evidence record; it supports human review but does not by itself prove semantic equivalence. Preserve command output paths as report evidence.
+`capture` collects the screenshot, UI tree/`dumpLayout`, and device logs. `flow` creates before/after captures around a HarmonyOS Hypium test (Android-side flow has been removed with the Android runtime dependency). `compare` creates a dual-platform evidence record from existing evidence directories; it supports human review but does not by itself prove semantic equivalence. Preserve command output paths as report evidence.
 
 For text input, verify focus and current value after each operation. A click can hit an input field or IME candidate and inject unintended text. Close the IME only with a method proven in the current environment.
 
@@ -39,6 +38,8 @@ White/non-white screenshot heuristics only detect gross rendering failures. They
 
 ## Prefer semantic Hypium UI tests over coordinate injection
 
+> Update (2026-10): migration-flow Hypium test case creation and execution are now standardized on the Python-based `d2h-hypium-forge` pipeline (`.hypium_forge/` assets; iteration via its `run_direct.py`, managed acceptance via `droid2hmos test harmony --runner python --test-list ...`). The ArkTS `entry_test` module workflow below remains valid only as a project-verified lesson for existing ArkTS assets; the principle "semantic location over coordinate injection" and the exception boundaries continue to apply.
+
 - **Evidence level:** project-validated
 - **Applies when:** HarmonyOS user flows need repeatable device-side verification and the relevant ArkUI controls can expose semantic nodes. Verified with DevEco SDK 6.0.2(22) and `@ohos/hypium` 1.0.25; recheck APIs on other versions.
 - **Symptom:** a migration relies on repeated coordinate-based device injection, requiring layout dumps and manual coordinate calculation at every step. Scrolling or layout changes cause misclicks, stale-frame dumps and evidence that cannot be replayed reliably.

package/skills/harmonyos-migration-playbook/references/windows-environment.md

@@ -2,7 +2,7 @@
 
 Check actual paths rather than trusting environment variables:
 
-- Android SDK/JDK/DevEco SDK directories exist and match the invoked tool.
+- JDK/DevEco SDK directories exist and match the invoked tool.
 - Included Gradle builds have the local configuration they require.
 - Proxy settings apply to Gradle/Node and do not unexpectedly intercept device or mail ports.
 - Node/npm pairs come from compatible installations.
@@ -24,7 +24,7 @@ droid2hmos service start mock-server <PROJECT> --health-url <URL> -- <command> [
 
 On Windows it asks `Win32_Process.Create` to create a short-lived host outside the command runner's process tree. The host starts the service with closed stdin and file-backed stdout/stderr, records the actual service PID, then exits. The outer launcher performs only a bounded health check and exits immediately after success.
 
-Do not substitute `Start-Process`, a foreground server command, or a project-local `spawn(..., { detached: true }).unref()` launcher. If the system-level creation mechanism is unavailable, stop and ask the user to start the service manually rather than risking a permanently blocked migration run.
+Do not substitute `Start-Process`, a foreground server command, or a project-local `spawn(..., { detached: true }).unref()` launcher. If the system-level creation mechanism is unavailable, return a blocking external-service item in `unresolved`, put the manual start instruction in `suggestedRemediation`, and let the caller handle user coordination rather than risking an unbounded migration run.
 
 ## DevEco CLI login callback server lifecycle
 

package/skills/maintaining-migration-report/SKILL.md

@@ -1,23 +1,37 @@
 ---
 name: maintaining-migration-report
-description: Maintain the lightweight fact-linked migration ledger while implementing or reviewing Android-to-HarmonyOS behavior, recording only implementation files, verification evidence, differences, and analyzer omissions.
+description: Maintain and validate the lightweight fact-linked Android-to-HarmonyOS migration ledger while implementation evidence is fresh. Record implementation files, Android source provenance, managed evidence, differences, discoveries, summary, and final-acceptance data without scheduling tests, regression, checkpoints, rendering, or completion.
 ---
 
-# Maintain the migration report
+# Maintain the migration ledger
 
-The migration report is the authoritative record of what Android behavior has actually been implemented and verified on HarmonyOS. Keep it synchronized with real code and tests throughout migration; do not reconstruct it only at the end.
+The migration report is a verifiable ledger linked to deterministic facts, Android source, HarmonyOS implementation files, and managed evidence. It is not the authority for application behavior: current Android source and observable behavior remain authoritative, and Kernel validation remains authoritative for machine gates.
 
-All `.migration/...` paths below live in the sibling migration workspace `<android-project>-migration/.migration/` in the Android project's parent directory (created by the CLI), not inside the Android project.
+All `.migration/...` paths below live in the sibling migration workspace `<android-project>-migration/.migration/` created by the CLI, never inside the Android project.
+
+## Scope and inputs
+
+This Skill owns only:
+
+- `report init`, `report update`, and `report validate`;
+- recording analyzer omissions in `discoveries.json`;
+- maintaining `summary.json`;
+- writing `final-acceptance.json` from test results and managed evidence supplied by the caller.
+
+For an update, accept the Android project root, report ref, requested status, real HarmonyOS implementation files, current Android source files, managed evidence paths, and any real difference or blocker. When the caller has a current Task/epoch, also accept its identifier and source closure so provenance can be reconciled with the exact implementation unit. Never replace these inputs with a prose summary.
+
+Read [references/source-provenance.md](references/source-provenance.md) whenever an item becomes `implemented` or `verified`. Read [references/final-acceptance.md](references/final-acceptance.md) when maintaining final acceptance.
 
 ## Invariants
 
-- Treat `.migration/spec/facts/` and `.migration/spec/index.json` as immutable analyzer output. Never edit them to make report validation pass.
-- The JSON files under `.migration/report/` are lightweight overlays. Scripts prefill stable refs, readable fact labels, and control-entry ownership; do not rewrite those fields.
+- Treat `.migration/spec/facts/` and `.migration/spec/index.json` as immutable analyzer output. Never edit them to make validation pass.
+- The JSON files under `.migration/report/` are lightweight overlays. Preserve stable refs, fact labels, and control-entry ownership generated by the CLI.
 - Do not edit `.migration/report/index.json` or `validation.json`; host scripts own indexes, hashes, counts, and validation output.
-- A report mapping names the concrete HarmonyOS file and symbol that performs the work. Imports, comments, ref strings, registries without executable wiring, generated hashes, stubs, and test-only symbols are not implementations.
-- Report only observed results. Compilation alone does not prove that a page, control, handler, navigation path, Dialog, or business function works.
-- Evidence for `verified` items and final acceptance must reference `managedEvidence` returned by a successful `droid2hmos test harmony ...` or HarmonyOS `evidence flow`. The CLI writes managed receipts under `.migration/evidence/managed/`, copies logs and HAP files into `.migration/evidence/blobs/` by SHA-256, and binds them to the current facts and HarmonyOS source fingerprint; never hand-write, copy, or modify receipts or archived artifacts.
-- A receipt supports a `verified` item only when `scope.coveredRefs` explicitly contains the item's `ref`, its structured Hypium result reports a non-zero execution count with zero failures, errors, and ignored cases, its target device matches, and every archived artifact has the expected size and SHA-256. A zero process exit code, a screenshot, a similar case name, or merely running a full suite cannot replace these requirements.
+- A mapping must name the concrete HarmonyOS file and symbol that performs the behavior. Imports, comments, ref strings, registries without executable wiring, generated hashes, stubs, and test-only symbols are not implementations.
+- Compilation alone does not prove that a page, control, handler, navigation path, Dialog, or business function works.
+- `implemented` and `verified` items require current Android `sourceProvenance`; a prose description or stale hash is insufficient.
+- `verified` and passed final-acceptance tests require fresh Kernel-managed evidence. Never hand-write, copy, or modify receipts or archived artifacts.
+- A receipt supports a ref only when `scope.coveredRefs` contains it, the structured result has a non-zero execution count with zero failures, errors, and ignored cases, the target matches, and archived artifacts pass integrity checks.
 
 ## Initialize and select work
 
@@ -27,129 +41,104 @@ Run once when no report exists:
 droid2hmos report init <android-project>
 ```
 
-Start from `.migration/report/index.json`. Select only the page or interaction shards relevant to the current implementation or review. Follow each shard's `factsFile` to obtain the Android fact and source evidence. Read additional Android source when the fact is ambiguous or when checking for analyzer omissions.
+Start from `.migration/report/index.json`. Select only the shards relevant to the caller's current implementation or review. Follow each shard's `factsFile`, then read the Android source named by the fact and current source closure. Read additional Android source when facts are ambiguous or may omit behavior.
 
-## Update one report item while the context is fresh
+## Update one item
 
-Update the relevant item immediately after implementing and testing it. Do not postpone report reconstruction until the end. Preserve `ref`, `kind`, `factLabel`, and `controlRef`; the initializer owns them. Fill only:
+Update while implementation and source context are fresh. Preserve `ref`, `kind`, `factLabel`, and `controlRef`. Maintain only:
 
-- `status`: `pending`, `implemented`, `verified`, or `blocked`.
-- `harmonyosFiles[]`: project-relative files that contain the real reachable implementation.
-- `testEvidence[]`: the `managedEvidence` path returned by the current managed HarmonyOS test; the receipt's `scope.coveredRefs` must contain the current item's `ref`. User-visible behavior requires end-to-end evidence from an emulator or physical device.
-- `difference`: normally `null`; write one concise sentence only for a real Android/HarmonyOS difference or blocker.
+- `status`: `pending`, `implemented`, `verified`, or `blocked`;
+- `harmonyosFiles[]`: project-relative files containing reachable implementation;
+- `sourceProvenance[]`: current Android files and CLI-computed hashes;
+- `testEvidence[]`: managed evidence whose `scope.coveredRefs` contains the ref;
+- `difference`: `null` unless a real behavior difference or blocker exists.
 
-Use the safe item update interface instead of editing a report shard directly:
+Use the safe update interface:
 
 ```text
-droid2hmos report update <android-project> --ref <ref> [--status <status>] [--harmony-file <path>...] [--evidence <path>...] [--difference <text>|--clear-difference]
+droid2hmos report update <android-project> --ref <ref> [--status <status>] [--harmony-file <path>...] [--android-source <path>...] [--evidence <path>...] [--difference <text>|--clear-difference]
 ```
 
-The command must resolve exactly one existing ref and may change only the four mutable fields above. It validates referenced project files before writing. `discoveries.json`, `summary.json`, and `final-acceptance.json` remain deliberate semantic records and may be edited directly according to their schemas; validate them immediately afterward.
+The command must resolve exactly one existing ref and validates project files and source membership before writing. Use `--android-source` for every Android file that informed the implementation. If a current Task/epoch source closure exists, reconcile it before update; a closure member that affects the behavior but is absent from `sourceProvenance` is unresolved, not silently ignored.
 
 Use statuses strictly:
 
-- `pending`: not implemented.
-- `implemented`: a real implementation file exists, but item-specific verification is incomplete.
-- `verified`: a real implementation exists and relevant test evidence has been recorded.
-- `blocked`: completion is impossible for the reason in `difference`.
+- `pending`: not implemented;
+- `implemented`: reachable implementation and source provenance exist, but item-specific runtime verification is incomplete;
+- `verified`: implementation, provenance, and relevant managed evidence all exist and validate;
+- `blocked`: implementation or verification is impossible for the concrete reason in `difference`.
 
-Example:
+If evidence is missing or invalid, keep the item at `implemented` (or `blocked` when appropriate) and return a verification request. Do not run a targeted test or full regression from this Skill.
 
-```json
-{
-  "ref": "interaction.open-settings",
-  "kind": "interaction",
-  "factLabel": "打开设置页",
-  "status": "verified",
-  "harmonyosFiles": ["ohos/entry/src/main/ets/pages/MainActivity.ets"],
-  "testEvidence": [".migration/evidence/managed/test-harmony-targeted-<fingerprint>.json"],
-  "difference": null
-}
-```
+## Record analyzer omissions
 
-The same HarmonyOS file may legitimately appear on several related facts. This small repetition is intentional traceability, not a request for prose. For an interaction, point to the file containing executable open/navigation/result wiring.
+When Android source proves that deterministic facts missed a page, control, entry, interaction, or business feature, append a semantic record to `.migration/report/discoveries.json`. Include a unique `discovered.*` ref, kind, concise label, Android source evidence, implementation files, status, test evidence, and optional difference. Do not inject it into immutable facts.
 
-## Record analyzer omissions
+Validate immediately after changing discoveries. A discovery is not automatically verified merely because its file exists.
 
-When Android source proves that deterministic facts missed a page, control, entry, interaction, or business feature, append it to `.migration/report/discoveries.json`. Include a unique `discovered.*` ref, kind, concise label, Android source evidence, implementation files, status, test evidence, and optional difference. Do not inject it into `spec/facts`.
+## Maintain final acceptance
 
-## Validate continuously
+Only write final-acceptance results supplied by the caller from a real managed test run. Follow [references/final-acceptance.md](references/final-acceptance.md). This Skill checks schema, stable refs, `coveredRefs`, receipt freshness and integrity, and consistency between test status and blockers.
 
-After updating report shards, run:
+It does not decide when application-wide regression should run, choose or expand its scope, execute the suite, or decide whether the workflow may advance.
 
-```text
-droid2hmos report validate <android-project>
-```
+## Maintain the user summary
 
-Repair every structural, reference, mapping, or evidence error before continuing. `valid: true, complete: false` is acceptable during migration.
+`summary.json` is the only free-form user summary. Keep it concise and limited to:
 
-Before claiming the entire migration complete, run:
+- `summary`: what has been migrated and what the validated evidence supports;
+- `incomplete`: remaining behavior, why it remains, and user impact;
+- `nextSteps`: concrete work still required;
+- optional `additionalSections` for meaningful platform differences, risks, or usage notes.
 
-```text
-droid2hmos test harmony <android-project> --all --target <device-id> --ref <report-ref> [--ref <report-ref>...]
-```
+Before updating the summary, run `report validate` and read `.migration/report/validation.json`. The prose must agree with that machine result:
 
-Run the real HAP on a Preflight-verified HarmonyOS emulator or physical device and execute application-wide end-to-end functional test cases from the real entry. List only report items and final-acceptance items actually asserted by the suite with `--ref`; never copy every ref merely to pass the gate. When multiple devices are available, specify `--target`; long cases may use `--case-timeout-ms`. If a precondition is unavailable, the case must fail or be explicitly marked ignored by Hypium—never return early and appear to pass. Diagnostic probes that catch exceptions must still assert required capabilities. The command succeeds only when the structured Hypium report has a non-zero execution count and no failures, errors, or ignored cases. Finish `final-acceptance.json` only after these tests pass:
+- if validation says the ledger is incomplete or final acceptance is not passed, describe it as partial/incomplete;
+- do not relabel pending or blocked behavior as harmless without a recorded decision;
+- do not duplicate calculated counts, mappings, test inventories, or blocker lists owned by the renderer;
+- do not add fields outside the current summary or final-acceptance schemas.
 
-```json
-{
-  "reportShardVersion": "1.2.0",
-  "kind": "final-acceptance",
-  "status": "passed",
-  "tests": [
-    {
-      "ref": "acceptance.create-note-from-launcher",
-      "name": "从启动页进入首页并完成新增笔记",
-      "status": "passed",
-      "evidence": [".migration/evidence/managed/test-harmony-all-<fingerprint>.json"]
-    }
-  ],
-  "blockers": [],
-  "notes": ["在 HarmonyOS 模拟器上从真实应用入口验证"]
-}
-```
+## Validate and return
 
-Every passed test needs a stable, unique `ref`, and the evidence receipt's `scope.coveredRefs` must contain that ref. `status: passed` is invalid when tests are empty, any test failed, evidence does not match the current source, facts, or device, an archive is damaged, or blockers remain.
+After every semantic update, run:
 
 ```text
-droid2hmos complete <android-project>
+droid2hmos report validate <android-project>
 ```
 
-This command re-derives all facts and enforces a non-bypassable completion gate. It requires a passing Preflight and HarmonyOS device, Android analysis evidence that still matches the current source and facts, a structurally and semantically complete report, a full-regression receipt whose structured result passes and matches the current HarmonyOS source, facts, and target device, and fresh, intact managed evidence that explicitly covers the ref of every `verified` claim, discovery, and final-acceptance test. When denied, read the returned `completion.unmet` unchanged, repair the stated cause, and run it again; do not rewrite the denial as a generic error. Do not claim completion unless it exits successfully. Independently inspect the application when acceptance requires human or visual judgment.
-
-## Generate the user-facing report
-
-The JSON shards are the machine-verifiable ledger, not the user deliverable. After validation, generate the Chinese HTML report entirely from the ledger and deterministic facts:
-
-Before final rendering, fill `.migration/report/summary.json`. This is the only free-form user summary. Keep it useful and concise; it has only three mandatory questions:
+Return the validation result without converting failure into success. `valid: true, complete: false` is acceptable during migration and does not authorize a completion claim.
 
-- `summary`: What was migrated and how usable is the result?
-- `incomplete`: What remains incomplete, why, and what is its user impact? Use an empty array only when nothing remains.
-- `nextSteps`: What must the user do next? Use an empty array when no action is needed.
-
-`additionalSections` is optional. Use it freely for meaningful information such as important platform differences, migration highlights, risks, or usage notes. Do not manually repeat counts, page lists, mappings, tests, or blockers that the renderer derives from the ledger.
-
-Before writing the summary, run `report validate` and read `.migration/report/validation.json`. The summary must agree with the machine result:
-
-- If `complete` is false or final acceptance is not `passed`, explicitly call the result partial/incomplete and never say “fully migrated”, “complete”, “all implemented”, or “zero remaining”.
-- Describe unresolved and blocked behavior as incomplete when it has observable user impact. Do not relabel pending analyzer findings as harmless without recording a decision in `unresolved.json`.
-- Do not copy calculated counts into prose. The renderer owns counts, percentages, completion state, and the technical incomplete inventory.
-- `final-acceptance.json` contains only the documented fields. Blockers and notes are concise strings; do not add run IDs, commit hashes, nested blocker objects, or alternative legacy fields.
+Return a structured result:
 
 ```json
 {
-  "summary": "主要功能已迁移并完成模拟器端到端验证。",
-  "incomplete": [],
-  "nextSteps": ["发布前在 DevEco Studio 配置正式签名。"],
-  "additionalSections": [
-    { "title": "平台差异", "content": "后台任务已改用 HarmonyOS 对应机制。" }
-  ]
+  "status": "completed | partial | failed",
+  "changedFiles": [],
+  "sourceFiles": [],
+  "evidence": [],
+  "domainChecks": [],
+  "unresolved": [],
+  "verificationRequests": [],
+  "suggestedRemediation": [],
+  "details": {
+    "updatedRefs": [],
+    "validation": {},
+    "taskId": null,
+    "epochId": null
+  }
 }
 ```
 
-```text
-droid2hmos complete <android-project>
-droid2hmos report render <android-project>
-```
+`status` describes ledger maintenance only. It does not mean regression passed or migration completed. Missing provenance, invalid receipts, closure mismatches, schema failures, and report gaps belong in `unresolved`; requested test or review work belongs in `verificationRequests`.
+
+## Boundaries
+
+This Skill never:
+
+- decides when targeted tests or full regression run;
+- calls `droid2hmos test`, `checkpoint create`, `complete`, or `report render`;
+- changes test scope or marks a failed, ignored, zero-execution, stale, or damaged result as passed;
+- decides an outer workflow state or announces migration completion;
+- uses report field completeness to override Android source, observable behavior, or Kernel denial.
 
-Render the final `.migration/report/report.html` only after `complete` succeeds. Before completion, `report render` may produce a stage/progress report, which must be labeled explicitly. Do not ask AI to rewrite the same content as a separate prose report. The user-facing body prioritizes result, incomplete behavior, next steps, tests, differences, and blockers. Page/control/entry/navigation mappings, refs, files, and other technical evidence are auxiliary proof and belong only in the collapsed technical trace appendix.
+The caller owns workflow transitions, test execution, checkpoint timing, completion gates, visual/business judgment, and final report delivery.

package/skills/maintaining-migration-report/references/final-acceptance.md

@@ -0,0 +1,48 @@
+# Final acceptance ledger contract
+
+`final-acceptance.json` records application-wide test results already produced by the caller. It does not schedule regression and does not decide that migration is complete.
+
+## Required shape
+
+```json
+{
+  "reportShardVersion": "1.2.0",
+  "kind": "final-acceptance",
+  "status": "pending | passed | failed",
+  "tests": [
+    {
+      "ref": "acceptance.create-note-from-launcher",
+      "name": "从启动页进入首页并完成新增笔记",
+      "status": "passed | failed",
+      "evidence": [".migration/evidence/managed/test-harmony-all-<fingerprint>.json"]
+    }
+  ],
+  "blockers": [],
+  "notes": []
+}
+```
+
+Only these fields are allowed by `schemas/final-acceptance.schema.json`. `blockers` and `notes` are concise strings; do not add run IDs, commit hashes, nested blocker objects, or legacy aliases.
+
+## Inputs from the caller
+
+The caller supplies:
+
+- the managed receipt from the application-wide suite it chose to run;
+- the exact stable refs actually asserted by that suite;
+- the structured execution totals and target device;
+- any failed scenarios or external blockers;
+- concise notes supported by observation.
+
+Do not add every report ref to make coverage appear complete. A receipt may support only refs in its actual `scope.coveredRefs`.
+
+## Recording rules
+
+- Each test has a stable, unique, non-empty `ref` and a user-readable `name`.
+- A `passed` test has at least one fresh managed receipt whose `scope.coveredRefs` contains that exact ref.
+- The structured result must report a non-zero execution count and zero failures, errors, and ignored cases.
+- The receipt must match current HarmonyOS source, facts and target device, and every archived artifact must pass size and SHA-256 checks.
+- `status: passed` is invalid when tests are empty, any test failed, evidence is stale or damaged, coverage is absent, or blockers remain.
+- When evidence is missing or invalid, record `pending` or `failed` according to observed results and return the gap; never synthesize a pass.
+
+After writing, run `droid2hmos report validate <android-project>` and return its result unchanged. The caller, not this Skill, decides workflow state, runs any additional regression, invokes completion gates, and renders or delivers the final report.

package/skills/maintaining-migration-report/references/source-provenance.md

@@ -0,0 +1,66 @@
+# Android source provenance
+
+Use this contract whenever a report item becomes `implemented` or `verified`. Provenance binds a claim to current Android source; it does not prove runtime behavior and does not by itself prove that source was read before target code was written.
+
+## Required inputs
+
+For each report ref collect:
+
+- the Android project root and exact report ref;
+- every Android source file that informed the behavior, including manifests, Kotlin/Java, XML and relevant resources;
+- the real HarmonyOS implementation files;
+- the current Task and epoch identifiers when the caller has them;
+- the current Task source closure, when available.
+
+A prose summary, fact label, earlier report, or generated plan can help locate source but cannot replace current files.
+
+## Safe update
+
+Use the CLI so it verifies source membership and computes hashes:
+
+```text
+droid2hmos report update <android-project> \
+  --ref <report-ref> \
+  --status implemented \
+  --harmony-file <harmony-file> \
+  --android-source <android-file> \
+  [--android-source <android-file>...]
+```
+
+`--android-source` records whole-file provenance. Prefer whole files when a symbol cannot be located deterministically. If the active host provides a schema-aware way to record precise ranges, every range must include `symbol`, `startLine`, and `endLine` and must satisfy `migration-report-item.schema.json`; do not bypass the safe update path with an ad hoc report edit.
+
+## Source-closure reconciliation
+
+When a current Task/epoch source closure exists:
+
+1. compare its members with the Android files actually read for the behavior;
+2. include every behavior-relevant member in `--android-source`;
+3. treat a newly discovered relevant file as a closure/epoch issue for the caller to resolve;
+4. do not silently add an unrelated file merely to satisfy a count;
+5. do not mark the item `implemented` or `verified` while a relevant closure member is missing from provenance.
+
+`report validate` generates `.migration/audit/android-source-manifest.json` and checks managed file membership and hashes. When a Task Plan is available it also reconciles report provenance with the plan's source closure.
+
+## Evidence levels
+
+- `declared-hash-validated`: the declared file is in the managed Android project and its SHA-256 matches the current file. This is the normal CLI guarantee.
+- `observed-order-audited`: available only when a trusted host/runner supplies ordered Read/Write events for the same session and epoch and D1 passes.
+- `enforced-prewrite`: not provided by the current CLI; ordinary writes are not intercepted before they occur.
+
+Project-created `.migration/audit/source-events.jsonl` is not a trusted event source and must not upgrade the evidence level.
+
+## D1 and D2 audits
+
+D1 writes `.migration/audit/source-order-audit.json`:
+
+- `passed`: trusted events show declared Android reads before the first target write in the same session/epoch;
+- `red-flag`: reads are missing, late, concurrent in an invalid action group, malformed, or inconsistent; report validation fails;
+- `unavailable`: no trusted event source exists; hash evidence remains usable, but read-before-write must not be claimed.
+
+D2 writes `.migration/audit/literal-drift-audit.json`. It deterministically samples up to five implemented/verified refs and compares selected strings, colors, values and simple conditions. D2 warnings require source and behavior review; they are not automatic failures because i18n, resource renaming, unit conversion, theming, and equivalent refactors can be valid.
+
+## Existing reports
+
+`report init` upgrades supported older reports by adding empty `sourceProvenance` arrays without fabricating history. Existing `implemented` or `verified` claims remain invalid until current Android sources are declared and validation passes.
+
+Return provenance or closure gaps to the caller as `unresolved`. This Skill does not create a checkpoint or invoke completion after provenance validation.

package/skills/managing-d2h-toolchain/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: managing-d2h-toolchain
+description: 安装、检查或升级 D2H 所依赖的 AppGraph 与 droid2hmos CLI 时使用。统一读取 D2H 包内的精确版本锁，保留本地 npm link，并把安装结果交还迁移主流程；其他 Skill 不执行工具安装。
+---
+
+# 管理 D2H 工具链
+
+本 Skill 是 AppGraph、droid2hmos 依赖声明、版本维护和安装的唯一流程入口。**依赖包、精确版本及命令能力只在本目录的 `toolchain.json` 声明**；`environment-requirements.json` 提供对应的主机检查边界。其他 Agent/Skill 不声明这些依赖或版本，也不执行 npm 安装或升级。`d2h` CLI 只解析本 Skill 的清单并实现确定性的探测、安装和校验；本 Skill 负责选择时机、目标 Agent 和失败分流。
+
+## 选择 D2H 版本
+
+- 已安装的 OpenCode/DevEco 定义读取配置根目录的 `.d2h-installation.json`；VS Code 定义读取扩展 `resources/opencode/plugin/d2h/.d2h-installation.json`。其中的 `packageVersion` 是本次调用 D2H CLI 的精确版本。
+- `d2h` 命令可用时先执行 `d2h --help`，确认支持 `install`、`upgrade`、`doctor`。需要通过 npx 调用时使用 `npx --yes @harmonyos-arkts/d2h@<packageVersion>`；Windows 使用 `npx.cmd`。不可用或记录缺失时，请调用方提供已批准的**精确 D2H 版本**完成首次安装，不猜测 `latest`。
+- 源码开发使用当前仓库构建出的 `node dist/bin/install-opencode.js`，不要把 npm 上同版本的旧包误当成本地源码。修改 D2H 依赖版本时只改包内 `skills/managing-d2h-toolchain/toolchain.json`，同时更新环境约束、兼容性测试和发布版本。
+
+## 检查与执行
+
+1. 确定目标 `--agent opencode|deveco|vscode`；VS Code 可通过 `--extension-dir` 指定扩展根目录。先运行 `d2h upgrade --check --agent <agent>` 只读预览，再运行 `d2h doctor --agent <agent>` 检查定义完整性、精确版本、命令能力与主机环境。
+2. 若缺少定义或受管 CLI，运行 `d2h install --agent <agent>`；已安装但需要应用当前锁定组合时运行 `d2h upgrade --agent <agent>`。开发者的 npm link 不被覆盖：遇到 link 冲突，返回具体路径并等待维护者显式处理。
+3. 安装后重新运行 `doctor`，核对 `.d2h-installation.json`、AppGraph/droid2hmos 的版本及能力，再把状态交给 `preparing-migration-workspace`。项目级 `droid2hmos preflight` 仍由准备 Skill 执行。
+4. 只想检查主机工具时使用 `d2h --check-env --output-dir <目录>`；读取生成的 JSON/Markdown 报告，不把 DevEco 登录、SDK 或设备缺失误判为需要升级 AppGraph/droid2hmos。
+
+安装失败时保留命令输出和失败阶段。包不可达、版本不匹配、能力不符分别报告；不得把失败掩盖成“使用已安装版本继续”。不允许在其他 Skill 中直接执行 `npm install -g`、`npm update` 或以浮动版本重新安装这两个 CLI。

package/skills/managing-d2h-toolchain/environment-requirements.json

@@ -0,0 +1,16 @@
+{
+  "schemaVersion": 1,
+  "tools": {
+    "node": { "minimum": "22.5.0", "maximumExclusive": "25.0.0" },
+    "python": { "minimum": "3.10.0" },
+    "git": null,
+    "npm": null,
+    "java": null,
+    "python-json5": null,
+    "appgraph": { "minimum": "0.0.10", "maximumExclusive": "0.0.11" },
+    "droid2hmos": { "minimum": "0.0.11", "maximumExclusive": "0.0.12" },
+    "hvigor": null,
+    "ohpm": null,
+    "devecocli": null
+  }
+}

package/skills/managing-d2h-toolchain/toolchain.json

@@ -0,0 +1,16 @@
+{
+  "schemaVersion": 1,
+  "node": { "minimum": "22.5.0", "maximumExclusive": "25.0.0" },
+  "tools": {
+    "appgraph": {
+      "package": "@harmonyos-arkts/appgraph",
+      "version": "0.0.10",
+      "capabilities": { "build-android": ["build", "--help"], "spec-analysis": ["spec-analysis", "--help"] }
+    },
+    "droid2hmos": {
+      "package": "@harmonyos-arkts/droid2hmos",
+      "version": "0.0.11",
+      "capabilities": { "analyze-android": ["--help"], "preflight": ["--help"], "status": ["--help"] }
+    }
+  }
+}