@harmonyos-arkts/d2h 0.0.0-stage → 0.1.0

package/skills/harmonyos-migration-playbook/references/arkts-compile.md

@@ -0,0 +1,24 @@
+# ArkTS compilation diagnosis
+
+Use the compiler error and the smallest failing construct. These are migration patterns, not permission to mechanically rewrite unrelated code.
+
+| Error/pattern | Check | Typical repair |
+|---|---|---|
+| `arkts-no-any-unknown` | untyped catch/callback value | introduce an explicit supported type and narrow safely |
+| `arkts-no-untyped-obj-literals` | object literal crosses a typed boundary | define a class/interface and construct the declared value |
+| `arkts-no-obj-literals-as-types` | inline object type | introduce a named type |
+| `arkts-no-indexed-signatures` | string-key object access | use `Map` or a typed wrapper API |
+| `arkts-no-structural-typing` | shape-compatible literal assigned to class | use the class constructor |
+| `arkts-no-destruct-params` | destructured callback parameter | accept one typed parameter, then read fields |
+| `arkts-no-misplaced-imports` | import emitted below declarations | move imports to the file header |
+| implicit return failure | branch result cannot be inferred | declare a concrete return type |
+
+Also check compiler/SDK support before applying these previously observed repairs:
+
+- Enum strings usually need an explicit parser rather than a blind cast.
+- Unsupported Unicode escape syntax can be replaced with a supported literal or four-digit escape.
+- A `Button` label constructor and child content must follow the active ArkUI API signature.
+- Complex inline component callbacks may need a data-driven component API.
+- Expressions rejected inside `build()` can move to a typed helper method.
+
+Verification: rerun the exact ArkTS compile command and a focused test for behavior affected by the rewrite. A different compiler error is not success.

package/skills/harmonyos-migration-playbook/references/harmony-runtime.md

@@ -0,0 +1,53 @@
+# HarmonyOS runtime diagnosis
+
+The following are Thunderbird migration observations. Confirm them against the active SDK and current call path.
+
+## TLS and networking
+
+- When TLS reports missing socket/bind state, instrument bind and connect separately. Some SDK paths require binding a local address before `connect` and explicit supported protocols.
+- Android STARTTLS flows do not automatically imply a one-to-one HarmonyOS socket upgrade API. Confirm current platform support; if behavior must change, preserve the user-visible security contract and document the adaptation.
+- A request that appears hung needs stage logs and a deterministic timeout path. Do not assume a timeout strategy works if the scheduling context itself is stalled.
+
+### Real-device TLSSocket receive failure (proven platform defect, Mate system build)
+
+Symptom chain on a physical phone against any TLS endpoint (incl. `www.qq.com:443`):
+`bind ok → TLS handshake ok → send ok → 'message' callback never delivers any byte`, while the
+system `@ohos.net.http` stack fetches HTTPS fine at the same moment and the identical
+TLSSocket code passes on the emulator.
+
+Bisection procedure (ship a probe page, launch via want param, e.g. `--ps tlsProbe 1`):
+
+1. control `http.request('https://...')` — if this also fails, the device network is the problem;
+2. TLSSocket to a well-known HTTPS host with an HTTP GET — if handshake succeeds but zero bytes
+   arrive, the TLSSocket receive path is broken on that system build;
+3. confirm on the emulator with the same code before blaming the app.
+
+Related real bugs to fix BEFORE attributing to the platform (each bit us once):
+
+- `TLSSocket.send`/`TCPSocket.send` on real devices rejected ArrayBuffer slices copied from
+  Uint8Array (`"data is not string"`); line protocols should send plain strings
+  (`tls.send(str)`, `tcp.send({ data: str })`).
+- Servers that reject credentials (163/QQ IMAP with a login password) may half-close without
+  firing `close`; treat `message` with 0 length as peer-closed to fail fast, and surface a
+  provider-specific hint (authorization code / 授权码) instead of a raw timeout.
+- IPv6-preferred networks can blackhole the AAAA path: resolve with
+  `connection.getAddressesByName` and prefer an A record; Coremail servers do not require SNI,
+  so IP-direct connect still passes certificate validation.
+
+## IME and asynchronous callbacks
+
+If work triggered from `TextInput.onSubmit` produces no logs or completion:
+
+1. prove the synchronous callback ran;
+2. log before and after the asynchronous boundary;
+3. compare with the same operation triggered by a normal button;
+4. keep IME handling synchronous if the current SDK reproduces the stall, and move business execution to a verified callback path.
+
+Do not universalize this behavior without a current reproduction.
+
+## Component state
+
+- If an externally changed value is not rendered, verify whether the ArkUI component is controlled by that state or only initialized from it.
+- If a static theme lookup does not redraw, establish a real observed state dependency and verify the rendered color after switching.
+
+Verification must include the actual runtime path, not only compilation or a matching function name.

package/skills/harmonyos-migration-playbook/references/lesson-lifecycle.md

@@ -0,0 +1,45 @@
+# Lesson lifecycle
+
+## Read before a task
+
+Read `.migration/experience/lessons.md` when it exists. Select lessons by task type, symptom, subsystem and applicability. Do not load or repeat unrelated lessons.
+
+## Record after validation and commit
+
+The orchestrator records a lesson only after the implementation is validated and committed through an explicit checkpoint. Before recording, confirm the repository state with `droid2hmos checkpoint status <android-project>`. Use this structure:
+
+```markdown
+## <short title>
+- Task/commit: `<task>` / `<sha>`
+- Evidence level: project-validated | reusable-pattern | platform-rule
+- Applies when: <specific conditions and versions>
+- Symptom: <observable failure>
+- Root cause: <proven cause>
+- Fix: <minimal effective change>
+- Verification: <commands, tests, device evidence>
+- Does not apply when: <known boundary>
+```
+
+Skip routine success, generic coding advice, speculative causes, duplicate lessons and details recoverable from the commit alone.
+
+If the project tracks `.migration/experience/lessons.md`, record the lesson there. The migration workspace `<android-project>-migration/` lives outside the Android Git repository, so `droid2hmos checkpoint create` (which commits inside the Android repo) can no longer include it; keep lessons as workspace-local run memory, or version the `<android-project>-migration/` directory independently if the project wants lesson history.
+
+In either case, use `droid2hmos checkpoint status <android-project>` to ensure the next migration unit does not inherit an unexplained dirty worktree. Do not use `--all` merely to capture the lesson.
+
+## Promote to the public playbook
+
+`.migration/experience/lessons.md` is the source-project evidence log, not the cross-project knowledge base. Review a lesson after it is committed. If it is non-obvious, reproducible, useful beyond one task, bounded by explicit applicability conditions, and backed by real verification evidence, add its generalized form to the relevant public Playbook reference immediately as `project-validated`.
+
+Public entries must contain:
+
+- evidence level;
+- symptom and proven root cause;
+- applicable SDK/tool versions and conditions;
+- recommended fix or workflow;
+- repeatable verification;
+- non-applicable cases;
+- source project and commits.
+
+Remove project-specific names and identifiers from the recommendation. Keep them only in source evidence. A public `project-validated` entry is discoverable by later projects but must be treated as a candidate solution there. After an independent project or environment reproduces it, upgrade it to `reusable-pattern` and add the new evidence. Upgrade to `platform-rule` only with active SDK/compiler evidence or a repeatable minimal reproduction.
+
+Do not promote routine success, generic advice, speculation, or a workaround whose root cause is unknown. Promotion is a reviewed change to the plugin Playbook; migration agents must not silently mutate an installed or cached plugin copy.

package/skills/harmonyos-migration-playbook/references/protocol-e2e.md

@@ -0,0 +1,23 @@
+# Protocol-level E2E
+
+For mail or other network protocols, use a deterministic local server when external infrastructure makes results unstable.
+
+Derive a version-1 protocol specification from Android source evidence. Every route must include non-empty `sourceEvidence` and the four scenarios `success`, `empty`, `business-failure`, and `boundary`; do not invent routes or payloads. Generate the server with:
+
+```text
+droid2hmos mock init <android-project> --spec <protocol-spec.json>
+```
+
+The generated `mock-server/scenarios.json` is the protocol fixture and `transcript.jsonl` is request evidence. Start the generated server through the managed service command shown in `mock-server/README.md`, then use `droid2hmos service status` and `droid2hmos service stop`; do not launch a detached Node process directly. Select scenarios with the `x-droid2hmos-scenario` header or `scenario` query parameter.
+
+## Evidence layers
+
+1. Protocol driver: real socket exchange and server transcript.
+2. Application behavior: parsed data, persistence and error handling.
+3. UI flow: real user action reaches the protocol path and renders the result.
+
+Keep each layer's evidence separate. A direct protocol driver does not prove the UI path is connected.
+
+For IMAP literals, preserve byte lengths and response framing exactly. Seed known messages and assert complete subjects/senders/content rather than only response success. A small host-side parser mimic can help isolate tokenizer differences, but the final assertion must run against the ArkTS implementation.
+
+Restart behavior must be deterministic when launch parameters are consumed only during application creation; verify the process lifecycle rather than assuming a foreground launch recreates it.

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

@@ -0,0 +1,52 @@
+# UI automation and visual verification
+
+Use device automation as evidence, not as a substitute for understanding the UI.
+
+## Reliable workflow
+
+1. Start from a known app state.
+2. Capture a screenshot and `dumpLayout` before interaction.
+3. Perform one interaction.
+4. Capture the resulting screenshot, UI tree and relevant log.
+5. Assert the expected visible, navigation or state result.
+
+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 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.
+
+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.
+
+## `dumpLayout` checks
+
+- control text/value and selected state;
+- element bounds and scroll viewport;
+- missing or zero-size controls;
+- duplicate windows or duplicated controls;
+- visibility and reachability of the intended action.
+
+## Visual comparison dimensions
+
+Inspect every user-visible element for content, position, size, spacing, alignment, color, typography, icon, border, state and enabled/clickable behavior. When no visual model or Android device is available, use Android source/resources plus the HarmonyOS UI tree and screenshot; state the evidence limitation.
+
+White/non-white screenshot heuristics only detect gross rendering failures. They cannot prove Android parity.
+
+## Prefer semantic Hypium UI tests over coordinate injection
+
+- **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.
+- **Root cause:** the command-line injection path was mistaken for the full UI-test capability. Empty IDs in a layout dump were also treated as proof that semantic selection was unavailable, without first checking whether the app had stable ArkUI `.id()` anchors or a test module.
+- **Required acceptance workflow:** development does not have to be test-first, but a runnable `entry_test` Hypium module must exist before the first interactive feature is accepted as complete. Add stable, unique semantic IDs to important interactive controls; locate them through `Driver` selectors such as `ON.id(...)`; execute only the affected class/case after an implementation change. Run the full suite only for broad shared-code changes, coherent batch acceptance and final regression. Dynamic-list IDs must derive from stable business identity, not the current visual position. A feature without a current successful Hypium result remains unverified.
+- **Verification:** rerun the same semantic test suite after layout movement or scrolling and assert the visible/navigation/state result, not merely a successful click. The source project ran five core flows twice: list rendering, detail navigation, timer start/stop, settings entry and editor entry.
+- **Does not apply when:** performing one-off exploratory probing or interacting with content proven to have no usable semantic node, such as Canvas or an external system surface. Coordinate injection may help explore these cases, but it is not acceptance evidence by itself; record why semantic selection is impossible and verify the resulting visible or business state through another repeatable assertion. An unconfirmed Hypium API or a test module not yet created is a setup problem to resolve, not a lasting exception.
+- **API investigation checks:** confirm the correct Hypium dependency/import, selector matching behavior, test delegator launch API, whether the clickable node is the text child or its parent, and ArkTS syntax accepted in the test module. Do not copy an API fix across SDK versions without compiling and running it.
+- **Source evidence:** Cofi migration; test assets commit `65472f1d`, lesson commit `09278323`; five device tests passed in two runs on emulator `127.0.0.1:5555`.
+
+Android `uiautomator` and HarmonyOS `dumpLayout` can expose different semantic trees. Missing Compose `AnimatedVisibility` text on the Android side is a comparison-tool limitation until corroborated by the visible app; do not report it directly as an application mismatch.

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

@@ -0,0 +1,38 @@
+# Windows environment checks
+
+Check actual paths rather than trusting environment variables:
+
+- Android SDK/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.
+- Commands preserve spaces and non-ASCII paths.
+
+Encoding is tool- and file-format-specific. Detect the existing encoding and the consuming compiler/schema requirements before changing it. Do not impose BOM rules globally, and do not rewrite source files merely to normalize encoding.
+
+For long tasks, emit progress and bounded diagnostics. Do not leave an unbounded process running when a smaller stage probe can identify the bottleneck.
+
+## Long-lived background services under OpenCode on Windows
+
+**Evidence level: reusable pattern.** `Start-Process` and Node `detached + unref` can both leave a Mock Server or development server inside the process tree tracked by the Windows command runner. The launcher may print a successful result while the tool call still waits forever for the descendant service.
+
+Use the plugin-owned launcher instead:
+
+```text
+droid2hmos service start mock-server <PROJECT> --health-url <URL> -- <command> [args...]
+```
+
+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.
+
+## DevEco CLI login callback server lifecycle
+
+**Evidence level: project-validated.** `devecocli auth login` starts a local OAuth callback server on a random `127.0.0.1` port, and that server lives only as long as the login process. If the process is killed, reaped by a tool-call timeout, or launched as a short-lived child of a CLI invocation, the browser keeps the Huawei login page; completing authorization then redirects to the dead port and the browser shows "localhost refused to connect". The failure does not heal on re-run.
+
+- Symptom: browser shows `localhost 拒绝了我们的连接请求` after finishing Huawei account authorization during a DevEco CLI login.
+- Root cause: the login callback server died with its process (orphaned browser tab pointing at a stale port, often left by an earlier automated or timed-out login attempt).
+- Fix workflow: use the managed login `droid2hmos auth login <android-project>` — it kills orphan `devecocli auth login` processes first, relaunches the login process outside the command runner's process tree with stdin held open (auto-sends Enter to trigger the browser), prints the login URL for manual access, and polls `devecocli auth status` with a bounded timeout. Treat a failed `devecocli-auth` preflight gate as `retry.kind: external`; do not retry it with short-lived processes and do not start a second concurrent login while one is pending.
+- Verification: preflight `devecocli-auth` gate passes after `droid2hmos auth login`; `.migration/services/devecocli-auth.pid` is cleaned up after the login process exits.
+- Does not apply when: the CLI was never installed (`toolchain` gate fails first), or the browser cannot reach `127.0.0.1` at all (proxy/VPN intercepting loopback — see the proxy checks above).
+- Source: Android2Harmony droid2hmos CLI, DevEco CLI login callback incident (2026-09).

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

@@ -0,0 +1,155 @@
+---
+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.
+---
+
+# Maintain the migration report
+
+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.
+
+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.
+
+## 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.
+- 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.
+
+## Initialize and select work
+
+Run once when no report exists:
+
+```text
+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.
+
+## Update one report item while the context is fresh
+
+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:
+
+- `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.
+
+Use the safe item update interface instead of editing a report shard directly:
+
+```text
+droid2hmos report update <android-project> --ref <ref> [--status <status>] [--harmony-file <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.
+
+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`.
+
+Example:
+
+```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
+}
+```
+
+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.
+
+## Record analyzer omissions
+
+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`.
+
+## Validate continuously
+
+After updating report shards, run:
+
+```text
+droid2hmos report validate <android-project>
+```
+
+Repair every structural, reference, mapping, or evidence error before continuing. `valid: true, complete: false` is acceptable during migration.
+
+Before claiming the entire migration complete, run:
+
+```text
+droid2hmos test harmony <android-project> --all --target <device-id> --ref <report-ref> [--ref <report-ref>...]
+```
+
+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:
+
+```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 模拟器上从真实应用入口验证"]
+}
+```
+
+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.
+
+```text
+droid2hmos complete <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:
+
+- `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.
+
+```json
+{
+  "summary": "主要功能已迁移并完成模拟器端到端验证。",
+  "incomplete": [],
+  "nextSteps": ["发布前在 DevEco Studio 配置正式签名。"],
+  "additionalSections": [
+    { "title": "平台差异", "content": "后台任务已改用 HarmonyOS 对应机制。" }
+  ]
+}
+```
+
+```text
+droid2hmos complete <android-project>
+droid2hmos report render <android-project>
+```
+
+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.