@harmonyos-arkts/d2h 0.1.1 → 0.1.3

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/preparing-migration-workspace/SKILL.md

@@ -1,124 +1,129 @@
 ---
 name: preparing-migration-workspace
-description: 在 Android 转 HarmonyOS 迁移开始或恢复时，通过 droid2hmos 执行统一 Preflight，并依据 CLI 返回结果和报告决定是否进入事实扫描与实现。也用于配置、Git checkpoint、构建测试、AppGraph 分析和设备检查。
+description: 在 Android 转 HarmonyOS 迁移开始或恢复时，通过 droid2hmos 读取状态、执行 Preflight、初始化或校验配置，并采集设备与外部环境就绪度。只负责工作区准备和能力分流；不调度分析、实现、构建、测试、回归或 Git checkpoint。
 ---
 
 # 准备迁移工作区
 
-本 Skill 只编排 `droid2hmos` 和独立的 `appgraph` CLI，不直接调用 Node 脚本、Gradle、Hvigor、Hypium、ADB 或 HDC。不要在 `ohos/` 尚不存在时猜测 HarmonyOS 构建配置。
+本 Skill 只负责回答四个问题：项目和迁移工作区是否定位正确、非设备基线是否可用、设备是否可用、哪些外部条件仍阻塞特定能力。它不决定后续状态，也不把设备失败扩大为整个迁移停止。
 
-迁移产物（`.migration/`）统一位于安卓工程父目录下的 `<工程名>-migration/.migration/`，由 CLI 自动创建和维护，不写入安卓工程内部。创建 `.migration/` 时 CLI 会自动在工作区根目录生成 `.gitignore`（内容 `.migration/`），防止迁移产物被上层 Git 仓库提交到远端。下文所有 `.migration/...` 路径均相对该工作区根目录。
+只调用 `droid2hmos` 的 `status`、`preflight`、`config init/validate` 和按需的 `device check`。不要直接调用 Node 脚本、Gradle、Hvigor、Hypium、ADB、HDC 或 AppGraph 分析命令，也不要在 `ohos/` 尚不存在时猜测 HarmonyOS 构建配置。
 
-开始或恢复时先获取只读事实快照：
+迁移产物（`.migration/`）统一位于 Android 工程父目录下的 `<工程名>-migration/.migration/`，由 CLI 创建和维护，不写入 Android 工程内部。下文所有 `.migration/...` 路径均相对该迁移工作区根目录。
+
+## 输入与事实来源
+
+输入必须包含 Android Gradle 工程根目录。根目录应有 Gradle 标记，应用模块中应有 `AndroidManifest.xml`。
+
+开始或恢复时先获取只读快照：
 
 ```text
 droid2hmos status <ANDROID_PROJECT>
 ```
 
-使用 `completion.unmet` 识别缺口，使用 `allowedActions` 选择当前可安全调用的命令。`phase` 只解释当前现场，不是必须手工推进的状态；不得创建或编辑 `.migration/state.json`。
+以 CLI 返回的 `workspace`、`allowedActions`、`completion.unmet`、Preflight 检查项、`failedChecks` 和 `retry` 为机器事实。`phase` 只解释当前现场；不得创建或编辑 `.migration/state.json`。
 
-传入路径必须是 Android Gradle 工程根目录：根目录应有 Gradle 标记，并且应用模块中应有 `AndroidManifest.xml`。如果 `workspace.projectPresent=false` 且 `workspace.projectCandidates` 非空，说明传入的是包装目录；改用列出的明确候选工程，不得在包装目录初始化第二套 `.migration` 或 HarmonyOS 工程。
+如果 `workspace.projectPresent=false` 且 `workspace.projectCandidates` 非空，说明传入的是包装目录。改用列出的明确候选工程，不得在包装目录初始化第二套迁移工作区或 HarmonyOS 工程。
 
-## 首次执行
+## 首次准备
 
-运行统一门禁：
+运行统一预检：
 
 ```text
 droid2hmos preflight <ANDROID_PROJECT> [--sdk-path <PATH>] [--timeout-ms <MS>]
 ```
 
-`preflight` 负责选择检查项、判定检查项是否阻塞，并生成完整结果，包括：
+`preflight` 由 Kernel 选择并判定检查项，可能包含：
 
 - Android UI 技术栈支持性；
-- Git 仓库、分支、`HEAD` 和工作区干净状态；
-- Git、Node.js 20-24、npm、Python 3.10+、JDK、Android SDK 和 DevEco 工具链；
-- `appgraph --version` 及迁移分析能力健康检查；
+- Git 仓库、分支、`HEAD` 和用户已有改动；
+- Git、Node.js、npm、Python、JDK、Android SDK、DevEco 和 HarmonyOS SDK；
+- AppGraph 健康检查；
 - `.migration/config.json` 初始化和校验；
-- Android 基线状态及设备检查；
-- 已有 HarmonyOS 工程复用，或在目标为空时创建可编译工程壳；
-- HarmonyOS SDK 探测、应用 HAP 基线构建和必须通过的 HDC 设备检查；
+- Android 基线状态；
+- 已有 HarmonyOS 工程复用，或在空目标中创建工程壳；
+- Preflight 自身所需的基线构建和设备检查；
 - `.migration/preflight-report.json` 原子生成。
 
-已有 HarmonyOS 工程不得被覆盖。只想校验现有工程、不允许初始化工程壳时加 `--no-init-harmony`。命令失败后读取报告中的 `failedChecks`、`retry` 和对应日志；只有 `transient/bounded` 允许在给出的上限内原样重试，其余失败必须先改变输入或环境，不得绕过门禁继续事实扫描或实现。
-
-环境类门禁（`toolchain`、`devecocli-auth`、`appgraph`、`harmony-sdk`、`harmony-device`）只探测一次：它们依赖本机工具、华为账号授权或物理设备，原样重跑 `preflight` 不会自愈。这类失败会返回 `retry.kind=external` 且带 `remediation`；必须把 `remediation` 明确转述给用户、等待用户修改环境，不得在同一环境下连续重跑 `preflight`。其余（非环境类）失败在按 `retry` 指引改变输入后重跑。
-
-本 Skill 不单独定义或重算任何子检查门禁。命令成功且报告总体结果为 `passed` 时继续。
+这些是 Preflight 的内部门禁，不授权本 Skill 在预检后继续调度仓库级构建、测试或分析。已有 HarmonyOS 工程不得被覆盖；只校验现有工程且不允许初始化工程壳时使用 `--no-init-harmony`。
 
-## 语言资源基线清点
+命令失败时读取 `failedChecks`、`retry` 和对应日志：
 
-Preflight 通过后、进入事实扫描与批次规划前，对 Android 工程做一次只读语言清点（文件枚举，不涉及构建）：列出各应用模块 `src/*/res/` 下带语言/地区限定符的 `values-<locale>` 目录（如 `values-zh`、`values-en-rUS`、`values-b+es+419`；排除 `night`、`land`、`v<N>`、`sw<N>dp` 等非语言限定符），记录语言清单与数量。该清点结果是规划的强制输入：
+- `retry.kind=transient/bounded`：只在返回的上限内原样重试；
+- `retry.kind=external`：记录为外部阻塞项并返回具体 `remediation`，不要在环境未变化时连续重跑；
+- 其他失败：返回受影响能力和补救建议，不自行推断绕过方式。
 
-- 语言数 > 1：实现批次必须包含 i18n 资源迁移批次，该批次开始前加载 `arkts-i18n` skill，按其目录规范迁移全部语言；
-- 语言数 = 1：也须在写入首个字符串资源前加载 `arkts-i18n` 确认资源组织方式；
-- 任何情况下不得把用户可见文案硬编码进页面代码来替代字符串资源迁移。
+不要把 `preflight` 非零退出一概解释为“迁移不能继续”。例如 HarmonyOS 设备不可用只阻止设备测试、运行态验收和依赖设备的证据采集；当 `allowedActions` 仍允许时，源码阅读、静态分析和非设备实现可以继续。反之，工程定位、配置或必要工具链缺失可能使 `allowedNonDeviceWork=false`。最终分流必须忠实反映本次 CLI 快照。
 
-## 配置与测试
+## 配置
 
-需要显式提供项目特有的 Android 命令时，先运行：
+需要显式提供项目特有的 Android 命令或 HarmonyOS 工程路径时使用：
 
 ```text
 droid2hmos config init <ANDROID_PROJECT> [--harmony-project <PATH>] [--android-build <COMMAND>] [--android-test <COMMAND>]
 droid2hmos config validate <ANDROID_PROJECT>
 ```
 
-配置中只保存 Android 侧有限命令和能够确认的路径。不得保存或猜测 `harmonyBuild`、`harmonyTest`、module、product 或 target；HarmonyOS 参数由 CLI 从真实工程配置解析。
-
-`androidBuild` 默认为 null：迁移流程不编译 Android 工程，`analyze android` 是纯源码静态分析且不要求 APK。只有用户明确要求 Android/HarmonyOS 双端运行对照时，才通过 `--android-build` 显式配置构建命令；未配置时执行 `droid2hmos build android` 会返回引导提示而非自动探测。
-
-在首次 Preflight 之后需要针对性诊断或验证时使用：
-
-```text
-droid2hmos build <android|harmony|all> <ANDROID_PROJECT> [--timeout-ms <MS>]
-droid2hmos test android <ANDROID_PROJECT> [--task <TASK>] [--timeout-ms <MS>]
-droid2hmos test harmony <ANDROID_PROJECT> (--class <CLASS> [--case <CASE>] | --all) [--target <DEVICE>] [--case-timeout-ms <MS>] [--ref <REPORT_REF>...]
-```
-
-Android 测试只有在 `.migration/config.json` 已声明可执行的 `androidTest` 时运行。HarmonyOS 测试只有在已有 Hypium 测试资产时运行；没有测试资产时记录缺口，并在第一个可交互功能验收前建立。多个 HDC 目标可响应时必须显式传 `--target`，防止证据偶然落在另一台设备。`--case-timeout-ms` 控制单个 Hypium 用例超时，`--ref` 只声明该测试实际断言的报告项。CLI 会解析 Hypium 摘要：失败、错误、忽略、零执行或缺少摘要即使 HDC 退出码为零也视为失败。
-
-Hvigor 返回成功但没有刷新输出时，CLI 只复用不早于各自构建输入的既有应用/ohosTest HAP；应用源码变化只要求应用 HAP 更新，不会强制无关的 ohosTest HAP 重打。产物比对应源码或构建配置旧时必须失败并要求修复构建，而不是安装过期包。
-
-## 分析与设备诊断
+配置中只保存能够确认的路径和 Android 侧有限命令。不得保存或猜测 `harmonyBuild`、`harmonyTest`、module、product 或 target；HarmonyOS 参数由 CLI 从真实工程配置解析。
 
-Android 和 HarmonyOS 分析统一使用：
-
-```text
-droid2hmos analyze <android|harmony|all> <ANDROID_PROJECT>
-```
+`androidBuild` 默认为 `null`。只有用户明确要求 Android/HarmonyOS 双端运行对照时，才记录用户提供的 Android 构建命令；本 Skill 不执行该命令。
 
-CLI 负责调用 PATH 中的 `appgraph`，HarmonyOS 分析自动读取配置里的 SDK 路径。只有统一命令失败且需要定位工具缺陷时，才直接运行 `appgraph --version` 或查看其帮助；不得自行拼接内部分析参数作为正常工作流。
+## 设备状态采集
 
-需要单独复查设备时使用：
+当现有 Preflight 报告缺少当前设备状态，或调用方明确需要刷新设备状态时，可运行：
 
 ```text
 droid2hmos device check <android|harmony>
 ```
 
-Android 设备缺失是可记录的增强项；HarmonyOS 设备必须可被发现且 Shell 可响应，否则停止需要设备证据的流程。
+只记录设备发现、Shell 响应、目标歧义和返回的 remediation。多个目标、认证、签名或设备离线问题进入 `externalBlockers` 或 `capabilityBlockers`，由调用方决定何时处理。本 Skill 不因设备问题暂停并要求用户作流程选择。
 
-## 恢复执行与 Git checkpoint
+## 恢复
 
-恢复迁移时不得重新初始化已有 `ohos/`。先运行：
+恢复时不得重新初始化已有 `ohos/`。运行：
 
 ```text
 droid2hmos status <ANDROID_PROJECT>
-droid2hmos checkpoint status <ANDROID_PROJECT>
 droid2hmos config validate <ANDROID_PROJECT>
 ```
 
-然后只重跑快照显示为缺失或因源码指纹变化而失效的 `build`、`test`、`device check` 或 `analyze`。如果工具链、AppGraph、工程壳或基础环境可能变化，则重新运行完整 `preflight`。`.migration/` 运行态文件不会让重复 Preflight 自己判定工作区变脏；已有配置中尚未纳入 Git 的 HarmonyOS 目录可作为上次预检生成物忽略，但首次运行前就存在的未跟踪 `ohos/` 和该目录内已有的 tracked 变更仍然阻塞，不能借此隐藏用户改动。
-
-完成一个经验证的迁移单元后，只提交明确列出的文件：
-
-```text
-droid2hmos checkpoint create <ANDROID_PROJECT> --message <MESSAGE> --include <PATH> [--include <PATH>...]
+仅当工具链、配置、工程壳或设备环境可能变化，或 CLI 明确要求刷新 Preflight 时，重新运行 `preflight`。不要在这里检查或创建 checkpoint，也不要补跑 `analyze`、`build`、`test` 或全量回归；这些属于调用方根据当前工作单元和状态决定的后续动作。
+
+不得处理、覆盖、提交或删除用户已有改动。
+
+## 结构化结果
+
+始终返回同一就绪度结构：
+
+```json
+{
+  "baselineReady": true,
+  "deviceReady": false,
+  "externalBlockers": [],
+  "capabilityBlockers": [
+    {
+      "capability": "device-validation",
+      "check": "harmony-device",
+      "reason": "no responsive target",
+      "remediation": "connect or start one HarmonyOS target"
+    }
+  ],
+  "allowedNonDeviceWork": true,
+  "allowedActions": [],
+  "evidence": [".migration/preflight-report.json"],
+  "suggestedRemediation": []
+}
 ```
 
-仅在调用者明确要求纳入全部相关变更时使用 `--all`。即使使用 `--all`，`.migration/` 运行态和证据归档也不会进入提交。不得处理、覆盖或删除用户已有改动；生成的 AppGraph、命令日志和预检日志不进入检查点。显式路径暂存失败时命令会撤销本次新加入暂存区的文件，并保留调用前已经暂存的内容。
-
-## 继续条件
+字段语义：
 
-- `droid2hmos preflight` 成功退出；
-- `.migration/preflight-report.json` 已生成且总体结果为 `passed`。
+- `baselineReady`：工程定位、迁移配置和非设备基础能力是否足以支持 CLI 明确允许的后续工作；不能仅用 Preflight 总体退出码代替；
+- `deviceReady`：当前 HarmonyOS 目标是否满足设备类工作要求；
+- `externalBlockers`：需要用户、账号、签名、物理设备或外部环境变化的阻塞项；
+- `capabilityBlockers`：按能力说明阻塞范围，不能写成笼统的“迁移停止”；
+- `allowedNonDeviceWork`：当前是否仍可继续源码阅读、静态分析或非设备实现；
+- `allowedActions`：原样返回 CLI 快照中的允许动作；
+- `evidence`：本次读取或生成的状态、配置和 Preflight 报告；
+- `suggestedRemediation`：CLI 给出的可执行补救，不臆造成功结论。
 
-各检查项的 `required`、`status` 和最终阻塞关系以本次 CLI 输出及报告为唯一依据，Skill 不重复推导通过条件。
+本 Skill 不推进外部状态机、不更新迁移报告、不创建 checkpoint、不调用 `complete`，也不决定定向测试或全量回归。调用方根据上述结果决定下一步。

package/skills/preparing-migration-workspace/toolchain.json

@@ -4,34 +4,10 @@
     "preflight": ["preflight"],
     "requiredCapabilities": [
       "status",
-      "complete",
       "config init",
       "config validate",
-      "checkpoint status",
-      "checkpoint create",
-      "build android",
-      "build harmony",
-      "test android",
-      "test harmony",
       "device check android",
-      "device check harmony",
-      "analyze android",
-      "analyze harmony",
-      "evidence capture",
-      "evidence flow",
-      "evidence compare",
-      "report init",
-      "report update",
-      "report validate",
-      "report render",
-      "mock init",
-      "service start",
-      "service status",
-      "service stop",
-      "logs list",
-      "logs show",
-      "logs failures",
-      "logs stats"
+      "device check harmony"
     ]
   },
   "appgraph": {