@harmonyos-arkts/d2h 0.1.11 → 0.1.13

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

@@ -1,24 +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.
+# 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

@@ -1,53 +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.
+# 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

@@ -1,45 +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 playbook returns a lesson candidate only after the root cause and fix are supported by current-project evidence. The caller decides whether validation and checkpoint requirements are satisfied and whether to persist or promote the candidate. 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`, the caller may persist an accepted candidate there. The migration workspace `<android-project>-migration/` lives outside the Android Git repository, so the lesson remains workspace-local run memory unless that workspace is versioned independently.
-
-This reference does not inspect, create, or time checkpoints and never recommends broad staging merely to capture a lesson.
-
-## Promote to the public playbook
-
-`.migration/experience/lessons.md` is the source-project evidence log, not the cross-project knowledge base. After the caller confirms acceptance, review whether a lesson is non-obvious, reproducible, useful beyond one task, bounded by explicit applicability conditions, and backed by real verification evidence. Only then may its generalized form enter the relevant public Playbook reference 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.
+# 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 playbook returns a lesson candidate only after the root cause and fix are supported by current-project evidence. The caller decides whether validation and checkpoint requirements are satisfied and whether to persist or promote the candidate. 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`, the caller may persist an accepted candidate there. The migration workspace `<android-project>-migration/` lives outside the Android Git repository, so the lesson remains workspace-local run memory unless that workspace is versioned independently.
+
+This reference does not inspect, create, or time checkpoints and never recommends broad staging merely to capture a lesson.
+
+## Promote to the public playbook
+
+`.migration/experience/lessons.md` is the source-project evidence log, not the cross-project knowledge base. After the caller confirms acceptance, review whether a lesson is non-obvious, reproducible, useful beyond one task, bounded by explicit applicability conditions, and backed by real verification evidence. Only then may its generalized form enter the relevant public Playbook reference 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

@@ -1,23 +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.
+# 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

@@ -1,53 +1,53 @@
-# 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 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 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.
-
-## `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
-
-> 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.
-- **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.
+# 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 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 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.
+
+## `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
+
+> 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.
+- **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

@@ -1,38 +1,38 @@
-# Windows environment checks
-
-Check actual paths rather than trusting environment variables:
-
-- 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, 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
-
-**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).
+# Windows environment checks
+
+Check actual paths rather than trusting environment variables:
+
+- 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, 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
+
+**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).