android2harmony 0.1.6 → 0.1.8

package/skills/a2h-code-review/SKILL.md

@@ -0,0 +1,379 @@
+---
+name: a2h-code-review
+description: "Reviews the code quality of a HarmonyOS app: performs code-change analysis through program analysis, outputs the affected code context, checks each scenario described in the SPEC document to determine whether it has been implemented, and fixes the scenarios that have not been implemented"
+---
+
+## Expected Input
+
+- `harmony_project_dir`: Path to the HarmonyOS project directory to review.
+- `spec_path`: Path to the requirement specification document, which declares all scenarios.
+- `scenarios`: The set of scenarios to verify this time, given either as an array of scenario ids or as a textual description of the scenarios; a subset of the scenarios declared in `spec_path`. If empty, all scenarios in `spec_path` are to be reviewed.
+- `commit_info`: Path to the file recording the code-change information, containing the commit hash.
+- `output_path`: Path where this skill's artifacts are stored.
+
+## Expected Output
+
+- Fixed source files in the HarmonyOS project
+- `code-review-report.md` in `output_path` (merged review + fix report; the commit id is recorded in its `## Commit Info` section, or `none`)
+
+---
+
+## Step 1 — Obtain Code-Change Information via git
+
+In `harmony_project_dir`:
+1. `git show --stat <commit_id>` — list the affected files.
+2. `git diff <commit_id>^..<commit_id>` — get the raw diff.
+Then classify and analyze the change:
+- If the affected file types are code files, e.g. ArkTS/TS/C/CPP/H/HPP, extract from the diff the **changed symbol names** (functions, methods, `struct`/`class`/component names) and the changed files, and continue with Step 2.
+- If the affected file types are non-code files, e.g. images (`.png`, `.jpg`), JSON/resource files (`.json`, `.json5`, resources under `entry/src/main/resources/`), or config files (`build-profile.json5`, `oh-package.json5`, `module.json5`, `.gitignore`, etc.), then **skip homegraph entirely**.
+Analyze the change content directly from the diff above; for binary/image assets, record the add/modify/delete and the size change. Treat this diff as the **code context** and go straight to Step 3.
+
+## Step 2 — Use homegraph to Expand the Code Context from the Raw Diff
+
+homegraph provides program-analysis capability by building an index of the target repository, and exposes two kinds of interfaces:
+
+- **Index management**.
+
+| Interface                 | Description                                       |
+|--------------------|------------------------------------------|
+| homegraph init -i [path]  | Initialize and index the project.    |
+| homegraph index [path]    | Full indexing (`--force` forces a rebuild).           |
+| homegraph sync [path]     | Incrementally sync changes.           |
+| homegraph status [path]   | Check index status. |
+
+- **Code queries**.
+
+| Interface              | Description                                       |
+|--------------------|------------------------------------------|
+| homegraph query <keyword> | Search for symbol locations.    |
+| homegraph explore <keyword> | Explore detailed information about the target.           |
+| homegraph node <symbol or file> | Get node information.           |
+| homegraph callers <symbol> | Who calls it. |
+| homegraph callees <symbol> | What it calls. |
+| homegraph impact <symbol> | The blast radius of modifying this symbol. |
+| homegraph files    | The tree of indexed files. |
+
+### Ensure the index homegraph uses, built from the target repository, is up to date
+
+1. Run `npx -y homegraph status <harmony_project_dir>` to check the index status.
+2. Decide based on the command output:
+   - **Not indexed** (no `.homegraph/`) → run `npx -y homegraph init -i <harmony_project_dir>`, wait for completion.
+   - **Stale index** (output does NOT contain `[OK] Index is up to date`) → run `npx -y homegraph sync <harmony_project_dir>` (incremental) or `npx -y homegraph index <harmony_project_dir> --force` (full rebuild).
+   - **Index up to date** → proceed to the next step.
+**Timeout (required).** Indexing a large project can run long — when invoking `init` / `sync` / `index` via the Bash tool, pass an explicit `timeout` of **600000** ms (10 minutes); do not rely on the tool's implicit default.
+If the command is killed for exceeding it, treat it as a failure and take the fallback.
+
+### Expand the changed symbols into the code context
+
+For the symbols and files collected in the previous step, using the changed line ranges from the diff as anchors:
+
+- Call `npx -y homegraph explore` with the concrete changed symbol / file basenames (**several names in one explore — one explore beats a chain of search → node → grep**).
+It returns the line-numbered source of those symbols plus the call paths between them.
+- Only when explore does not give enough information, supplement with the following commands:
+  - `npx -y homegraph callers` / `npx -y homegraph callees` — who invokes a changed function and what it invokes (which pages/components a change reaches).
+  - `npx -y homegraph impact` — the blast radius of a changed symbol, i.e. which other scenarios the commit may affect.
+  - `npx -y homegraph node` — one specific symbol body, or a bounded `offset`/`limit` read of one indexed file.
+- For non-code literals that live outside the graph (resource names in `string.json`, routes in `main_pages.json`, permissions in `module.json5`), use `Grep` on the exact literal.
+
+**Read only what the analysis points at — do not read whole files.** When you need extra surrounding context (an import, a type declaration a changed range depends on), read just that span with the Read tool's `offset`/`limit`.
+First determine whether **the project** involves multiple programming languages such as ArkTS and CPP (not just the diff). If it does, then while analyzing the changed code, use `Grep` and similar means to work out the ArkTS-CPP and CPP-ArkTS call traces. Once a cross-language hop is identified, keep going with homegraph on the symbols at the **other** end (e.g. `npx -y homegraph explore` on the ArkTS entry when the change is in CPP, and vice versa) to expand that side as well. Add both the call traces and the expanded other-side symbols to the code context.
+
+### Fallback
+
+If homegraph is unavailable (commands error out and cannot be resolved, or a command was killed for exceeding 600000 ms), fall back to analyzing the diff directly: based on the raw diff information, read the changed files directly from the project, assemble the code context by hand, and continue the review with this manually assembled context.
+
+---
+
+## Step 3 — Read the User Scenario Design Document
+
+- Extract every user scenario / user story / use case described in it
+- For each scenario, identify:
+  - **Scenario name**: A short descriptive title
+  - **Scenario description**: What the user does and expects
+  - **Involved pages/components**: Which UI pages or components participate
+  - **Involved data flows**: What data is read, written, or transmitted
+  - **Expected behavior**: The outcome the user should see
+  - **Related APIs/Kits**: Which HarmonyOS APIs or Kits are needed
+  If the scenario document uses a different structure (e.g. navigation flows, module descriptions, component hierarchies), derive the implicit user scenarios from it. Every navigable page, every data operation, and every user-facing feature implies at least one scenario.
+**Build a scenario checklist** — a numbered list of all extracted scenarios. This list drives the rest of the review.
+
+## Step 4 — Per-Scenario Validation
+
+For **each scenario** in the checklist from Step 3, perform a detailed review:
+
+### Trace the scenario through the code
+
+Walk through the code path that the scenario would exercise, focusing on the changes in the code context (you can use `npx -y homegraph explore` to analyze both endpoints — e.g. the page and the data API — and get the path between them in one call):
+- **Launch path (start here, not at the page under review)**: Resolve the app's *actual* launch page before tracing anything else — read `module.json5` `mainElement` → that ability's `srcEntry` → the page it loads (typically the first entry of `resources/base/profile/main_pages.json`). Then trace, hop by hop, how a user reaches the scenario's page **from that launch page**. For every hop, name the concrete control the user taps and confirm its handler actually navigates (`router.pushUrl` / `pushPath` / a `Navigation` destination). A page carrying `@Entry` is **not** evidence it is the launch page — `@Entry` only makes a page routable. Route registration in `main_pages.json` is **not** evidence the hop works; it only proves the target is addressable.
+  If any hop's control cannot be found, or its handler only logs (`hilog.*`) / is a TODO / is otherwise a no-op, the scenario is **FAIL** regardless of how complete the target page is — the user can never get there. Record the broken hop as the defect.
+- **Entry point**: Which page or ability handles this scenario? Does it exist? Was it modified in this commit?
+- **UI layer**: Are the required UI components implemented? Do they accept user input correctly?
+- **Logic layer**: Is the business logic implemented? Does it handle the scenario's data flow?
+- **Data layer**: Are data reads/writes/network calls present? Do they target the right sources?
+- **API usage**: Are the required HarmonyOS APIs imported and called correctly?
+- **Error handling**: Are failure paths handled (network errors, permission denials, empty data)?
+- **Commit relevance**: Does this commit's changes contribute to or break this scenario?
+
+### Determine the verdict
+
+Assign one of these verdicts to each scenario:
+
+| Verdict | Meaning |
+|---------|---------|
+| **PASS** | For **every** observable the scenario's steps assert, you can name the code that *produces* that observable, and the launch path to it is unbroken. |
+| **PARTIAL** | The code partially implements this scenario. Some parts are present but key pieces are missing or incomplete. |
+| **FAIL** | The code does not implement this scenario, or the implementation has critical errors that would prevent it from working. |
+| **UNABLE TO VERIFY** | The scenario's observable cannot be settled by reading code — it depends on framework runtime behavior, device state, or timing. Use this instead of PASS whenever you are reasoning about *what the framework will do*, not *what the code says*. |
+
+**UNABLE TO VERIFY vs. PARTIAL — judge by what's missing, not by what you call it.** These two get confused for a reason worth naming directly: a scenario can have every line of code correct and complete — the fetch, the parse, the persistence, the read-back — and still be unable to earn PASS, because the final observable (a real downloaded duration, a value surviving restart, a live network response) only exists once that code actually runs. That gap is UNABLE TO VERIFY, `class=environment` downstream — it is evidence debt, not a code defect, and a later round cannot close it by writing more code. PARTIAL means something different: the code itself is incomplete or wrong, and writing more code *would* close the gap. If you find yourself reaching for a description like "code path traced and correct, but the terminal value is a runtime/device observable" — that description **is** UNABLE TO VERIFY, however you phrase it in your own notes (e.g. "runtime debt"). Recording that situation as PARTIAL mislabels an evidence gap as a code defect, and a caller mapping verdicts to ledger `class` will file it under `class=code` instead of `class=environment` — which feeds it into defect counts and stuck-signature checks it was never meant to be part of, and a scenario that is actually done just gets stuck re-appearing as unfinished, round after round.
+
+**The PASS bar — "the code exists" is not the bar.** Each of the scenario's numbered steps names an observable (a literal string on screen, a control appearing or disappearing, a value changing, a visual change, state surviving restart). For each one, ask: *which line makes this observable happen, and does anything downstream actually consume it?* These do **not** earn PASS on their own:
+
+- A literal exists in the source, but you have not traced the branch that renders it.
+- A state field is assigned, but you have not traced the assignment through to a rendered difference.
+- A handler is wired, but the framework precondition that makes it fire is absent (see Step 5 item 4).
+- A value is persisted, but the read path that restores it was not traced.
+- The spec says a state "updates" / "applies" / "takes effect" *visually*, and the code only records the selection.
+
+When the scenario's own wording is too vague to name an observable (e.g. "the theme updates accordingly"), do not invent a strict one and do not wave it through. Derive the narrowest observable the wording can bear, state in the evidence which observable you settled on, and if the code cannot even produce that, the verdict is PARTIAL — with the ambiguity recorded as a gap against the spec.
+
+### Record findings for each scenario
+
+For each scenario, record:
+- **Scenario name and ID** (from the checklist)
+- **Verdict**: PASS / PARTIAL / FAIL / UNABLE TO VERIFY
+- **Evidence**: Specific files and line numbers that implement (or should implement) this scenario
+- **Gaps** (if PARTIAL or FAIL): What is missing or broken, with specific details — these become the **actionable defects** in Step 5.
+
+---
+
+## Step 5 — Cross-Cutting Checks
+
+After the per-scenario review, check these cross-cutting concerns that affect multiple scenarios:
+
+1. **Permission coverage**: Are all permissions required by the scenarios declared in `module.json5`?
+2. **Navigation completeness**: Resolve the real launch page once (`module.json5` `mainElement` → ability `srcEntry` → loaded page / `main_pages.json` first entry) and record it explicitly in the report. Then, for each scenario page, confirm an unbroken tap-by-tap path from that launch page, and that Back returns along it. State the launch page you resolved and each hop's control — a bare "all pages registered in `main_pages.json`" is not an acceptable finding for this item, because registration proves addressability, not reachability.
+3. **Stub traversal**: Scaffold projects ship placeholder handlers that are tappable but inert (body is only `hilog.*`, a TODO comment, or empty). Grep the handlers along every scenario's path for these, and flag any that the path must cross. A stub on the path fails the scenario even when the destination page is complete.
+4. **Framework precondition pairing**: Some ArkUI capabilities are inert unless a partner attribute or decorator is also present. Wiring the handler alone is not implementation. Check every such pair the scenarios rely on, for example:
+   - `List` `.onItemMove()` — fires only when the `List` also has `.editMode(true)`.
+   - `@ObjectLink` — inert unless the linked class is declared `@Observed`.
+   - `@Observed` class fields read in UI — may need `@Track` to trigger re-render.
+   - `@Prop` / `@Link` — need the parent to pass the binding in the matching form (`$var` for `@Link`).
+   - Persisted state — needs a read path invoked from a lifecycle hook (`aboutToAppear` / `onPageShow`), not just a write path.
+   For each pair the scenario depends on, name both halves in the evidence. If the partner half is missing, that is a defect and the scenario is FAIL, not PASS.
+5. **Precondition vs. seeded fixture conflict**: When a scenario asserts values for a stated starting condition (an empty list, no downloads, a fresh install), check the project's seed data (`resources/rawfile/*.json` and any in-code defaults) for entries that contradict it. A seeded row that survives a data reset will make the scenario's baseline assertions unreachable. Flag the conflict and say which fixture entry causes it.
+6. **State management correctness**: Is state shared correctly between the components involved in scenarios, using the project's own paradigm consistently? V1 project → `@State`/`@Prop`/`@Link`/`@Provide`/`@Consume` (plus `@Observed`/`@Track`); V2 project → `@Local`/`@Param`/`@Event`/`@Provider`/`@Consumer` (plus `@ObservedV2`/`@Trace`). Flag any V1/V2 decorator mixing within a component.
+   Additionally, for any scenario whose observable is *a re-render after a state change*, check the propagation path end to end: the mutation must reach the rendering expression. In V1, watch for a `ForEach` whose `keyGenerator` returns a key that does not change when the item's rendered content changes — the child may keep stale `@Prop` values. Name the mutation site, the propagation mechanism, and the rendering expression. If you cannot establish that the re-render follows from reading the code, the verdict is UNABLE TO VERIFY, not PASS.
+7. **API version compatibility**: Are all used APIs available in the project's target API version?
+8. **Resource completeness**: Are all UI strings, images, and other resources referenced by scenarios present?
+9. **Theming support (only when a scenario asserts a visual theme change)**: A scenario that requires a visible light/dark or color-scheme change needs a mechanism capable of producing it — a `dark` resource qualifier directory (`resources/dark/element/color.json`) or a runtime color-token indirection that every affected view reads from. Check whether that mechanism exists. If the affected pages hardcode literal hex colors and no `dark` qualifier set is present, recording the user's selection cannot produce the asserted visual change; report this as an architectural gap and say which of the two mechanisms is missing, rather than marking the scenario PASS because the selection persists.
+
+Each cross-cutting defect becomes an actionable fix item in Step 6.
+
+---
+
+## Step 6 — Fix the Defects
+
+You just found the defects yourself in Steps before, go straight to fixing.
+
+### Prioritize
+
+Sort all defects into this fix order:
+
+1. **Cross-cutting: Permissions** — blocking prerequisite for many features
+2. **Cross-cutting: Navigation and stub traversal** — an unreachable page makes every scenario on it fail, so a broken hop outranks any defect on the destination page
+3. **Cross-cutting: Framework precondition pairing** — a one-attribute fix that turns already-written code from inert to working; cheapest fix per scenario recovered
+4. **Cross-cutting: Resources** — UI depends on strings/images
+5. **Cross-cutting: Seeded fixture conflicts** — a baseline the scenario cannot reach invalidates its assertions
+6. **FAIL scenarios** — in report order (earlier scenarios are typically more fundamental)
+7. **PARTIAL scenarios** — in report order
+8. **Cross-cutting: State management** and other quality issues — lowest priority
+
+**Maximum 2 effective attempts** per defect (an effective attempt = code was modified AND compiles successfully; compile-fix retries inside `a2h-fix-build-errors` do NOT count as an attempt).
+
+### Fix strategies
+
+Apply the strategy that matches the defect category.
+
+#### Permission Fixes
+
+**When**: `module.json5` is missing a required permission.
+
+1. **Verify the permission name is valid** — first use `node -yes devecocli docs search` / `node -yes devecocli docs read` to confirm the permission exists in the HarmonyOS docs; fall back to WebSearch only if the local docs flow does not surface the needed reference.
+2. Read `module.json5` and locate the `requestPermissions` array (create it if absent).
+3. Add the missing permission entry:
+   ```json
+   { "name": "ohos.permission.XXX" }
+   ```
+4. If the feature requires **runtime permission** (e.g., camera, location, media), also add the runtime request code:
+    - Search the Android source (if available) to see how the permission is requested.
+    - Add `abilityAccessCtrl.createAtManager().requestPermissionsFromUser()` in the appropriate lifecycle (`onWindowStageCreate` or `aboutToAppear`).
+    - Prefer `node -yes devecocli docs search` / `node -yes devecocli docs read` for the HarmonyOS API reference, then fall back to WebSearch if the local docs are insufficient.
+
+#### Page/Component Creation
+
+**When**: A page or component referenced by a scenario does not exist.
+
+1. **Use `node -yes devecocli docs search` / `node -yes devecocli docs read` first** to look up the HarmonyOS equivalent UI components (e.g., `Grid` for `RecyclerView`, `List` for `ListView`). Fall back to WebSearch only when the local docs flow is insufficient.
+2. **Create the page file** under `entry/src/main/ets/pages/`:
+    - Implement a **minimal viable page**: basic UI structure + essential state variables + placeholder data.
+    - Do NOT attempt to implement all business logic — focus on making the scenario's happy path work.
+3. **Register the route** in `resources/base/profile/main_pages.json`.
+4. **Add navigation** from the calling page (if the scenario specifies a navigation flow).
+
+#### Broken Launch-Path Hop / Stub on the Path
+
+**When**: A hop from the launch page to the scenario's page has no control, or its handler only logs / is a TODO / is empty.
+
+1. Locate the control the user is meant to tap on the *source* page of the broken hop. If the scenario or the Android source names its label, match that label exactly.
+2. Replace the inert body with a real navigation call, following the project's existing navigation idiom — copy the form used by a hop that already works in this project (`router.pushUrl({ url: 'pages/XxxPage' })` or the project's `Navigation`/`NavPathStack` push), rather than introducing a second idiom.
+3. If the control does not exist at all, add it to the source page in the position the scenario describes, matching the labels and styling of its sibling controls.
+4. Verify the destination route is registered in `main_pages.json`, and that Back returns to the source page.
+5. **Do not** work around a broken hop by making the destination page the launch page, by adding `@Entry` to it, or by deep-linking past the hop — the user-visible path is what the scenario asserts.
+
+#### Framework Precondition Pairing
+
+**When**: A handler or decorator is present but its required partner is missing (the Step 5 item 4 list).
+
+1. Confirm the pairing requirement from the docs before editing — `npx -y devecocli docs search` / `npx -y devecocli docs read` on the component or decorator.
+2. Add the missing half at the site that already has the other half (e.g. add `.editMode(true)` to the `List` that already declares `.onItemMove()`; add `@Observed` to the class an `@ObjectLink` already points at).
+3. Prefer adding the partner attribute over rewriting the working half — the existing logic is usually correct and only inert.
+4. Check whether the added attribute changes unrelated behavior on the same component (e.g. `editMode` affecting item interaction), and adjust only if it breaks another scenario.
+
+#### Seeded Fixture Conflicts
+
+**When**: Seed data contradicts a starting condition a scenario asserts.
+
+1. Identify the exact fixture entry (file plus the entry's identifying field) that violates the stated starting condition.
+2. Prefer changing the seed data over changing the logic: remove or empty the offending entry so the declared starting condition is actually reachable. Aggregation/derivation logic that reads the fixture is usually correct and should be left alone.
+3. If other scenarios depend on that seeded entry, do not delete it — record the conflict as a residual gap naming both scenarios, since the two starting conditions cannot coexist in one fixture.
+4. Never hardcode the asserted value to satisfy the assertion; that removes the derivation the scenario is checking.
+
+#### API Import and Call Fixes
+
+**When**: A required HarmonyOS API is not imported or called.
+
+1. **Identify the correct API**:
+    - If Android source is available, find the corresponding Android API call and determine the HarmonyOS equivalent.
+    - Prefer `node -yes devecocli docs search` / `node -yes devecocli docs read` for HarmonyOS API documentation.
+    - Use WebSearch as fallback when the local docs flow does not provide enough detail.
+2. **Do NOT guess API signatures** — always verify import path, function name, parameter types, and return type from documentation.
+3. Add the import statement and the API call in the correct location.
+
+#### Event Handling / Business Logic Fixes
+
+**When**: A user interaction or data flow is missing.
+
+1. **Read the Android implementation** (if available):
+    - Find the event listener (e.g., `setOnClickListener`, `addTextChangedListener`).
+    - Trace what happens when the event fires: state changes, API calls, UI updates, navigation.
+2. **Translate to ArkTS**:
+    - Android `setOnClickListener` → ArkUI `.onClick(() => { ... })`
+    - Android `TextWatcher` → ArkUI `.onChange((value: string) => { ... })`
+    - Android `onItemClick` → ArkUI `.onClick()` on `ListItem` / `GridItem`
+    - Android `LongClickListener` → ArkUI `.gesture(LongPressGesture().onAction(() => { ... }))`
+3. **Implement the business logic**:
+    - Mirror the Android logic flow as closely as possible.
+    - Use appropriate HarmonyOS APIs for persistence (`preferences`), networking (`http`), file operations (`fileIo`).
+4. **Bind to UI**: Ensure the reactive state variables are updated so the UI reflects changes — `@State`/`@Link` etc. in a V1 project, `@Local`/`@Param` etc. in a V2 project (see State Management Fixes below for paradigm detection).
+
+#### Resource Fixes
+
+**When**: String resources, media files, or layout parameters are missing.
+
+1. **String resources**:
+    - Read `resources/base/element/string.json`.
+    - Add missing string entries with appropriate keys and values.
+    - If Android source is available, reference `res/values/strings.xml` for the original text.
+2. **Media resources (images/icons)**:
+    - If the original image exists in the Android project's `res/drawable*` or `res/mipmap*`, note it for manual copy (do not auto-copy binary files).
+    - For missing icons, record as "media resource needed" in the fix report — do not create placeholder images.
+3. **Layout parameters**:
+    - Add missing dimension/color values to `float.json` or `color.json` as needed.
+
+#### State Management Fixes
+
+**When**: Components have incorrect or missing state decorators.
+
+0. **Detect the project's state-management paradigm first** (project-level, decided once). ArkTS has two paradigms and they must NOT be mixed within a project/component:
+    - `@Component` + `@State`/`@Prop`/`@Link`/`@Provide`/`@Consume`/`@Observed`/`@ObjectLink`/`@Watch` → **V1**
+    - `@ComponentV2` + `@Local`/`@Param`/`@Once`/`@Event`/`@ObservedV2`/`@Trace`/`@Monitor`/`@Provider`/`@Consumer` → **V2**
+    - Empty project / no state decorators → default **V2**. When both exist, follow the majority and match the file's surrounding code. Fix decorators to fit the detected paradigm — never introduce the other one.
+1. **Analyze the component hierarchy** (use the matching paradigm's decorators):
+    - **V1**: Parent → Child: `@State` in parent + `@Prop` (one-way) or `@Link` (two-way) in child. Ancestor → deep descendant: `@Provide` + `@Consume`. Global: `AppStorage` / `LocalStorage`.
+    - **V2**: Component-internal: `@Local`. Parent → Child input: `@Param` (+ `@Once` if sync-once). Child → parent: `@Event` callback (with `!!` two-way binding when appropriate). Ancestor → descendant: `@Provider` / `@Consumer`. Global: `AppStorageV2` / `PersistenceV2`.
+2. **Check for common mistakes**:
+    - **V1**: `@State` on a non-primitive without `@Observed` on the class; `@Link` without a `$variable` binding from the parent; missing `@Watch` when a side-effect is needed on state change; `@Observed` class property used in UI but missing `@Track`.
+    - **V2**: `@ObservedV2` class property observed in UI but missing `@Trace` (both must be used together — either alone is inert); `@Param` mutated inside the child (it is input-only — emit changes via `@Event`); `@Local` expected to receive external input (use `@Param` instead).
+    - **Mixing**: V1 and V2 decorators in the same component (e.g. `@Local` inside `@Component`, or `@State` inside `@ComponentV2`) — align to the detected paradigm.
+3. Use `node -yes devecocli docs search` / `node -yes devecocli docs read` first to verify the correct decorator combination if unsure. Fall back to WebSearch only when the local docs are insufficient.
+
+After every single defect fix, invoke the `a2h-fix-build-errors` skill (if available in this edition) to compile and build the project, and try to fix any compile errors. If that skill is not available, stop and report it rather than guessing a build command — do not silently skip the compile gate, since every "effective attempt" is defined by a successful compile. If compilation fails and cannot be fixed, roll back this defect fix and record the fix result for this defect as "failed to fix — compilation error".
+
+After all defects have been fixed, if source files were ultimately modified, commit the changes and record the commit_id.
+```bash
+cd "<harmony_project_dir>"
+git add -A
+git commit -m "fix(review): code review defects Total defects: {total defects}, Fixed: {successfully fixed number}, Failed: {failed to fix number}"
+```
+
+---
+
+## Step 7 — Generate the Report `code-review-report.md`
+
+Write the merged review + fix report to `<output_path>/code-review-report.md` with the following structure:
+
+```markdown
+# Code Review Report
+
+## Overview
+- **Total Scenarios**: <N>
+- **Scenario Results**: <X> PASS | <Y> PARTIAL | <Z> FAIL | <W> UNABLE TO VERIFY
+- **Total Defects Found**: <T>  (FAIL + PARTIAL scenarios + cross-cutting defects)
+- **Successfully Fixed**: <A>
+- **Failed to Fix**: <B>
+
+## Launch Path
+
+- **Resolved launch page**: <page> (from `module.json5` mainElement=<ability> → srcEntry=<path> → <page>)
+- **Path to each scenario page**: <launch page> --tap "<control label>"--> <page> --tap "<control label>"--> <target>
+- **Hop status**: <OK / broken at hop N: control "<label>" handler is a no-op>
+
+## Scenario Coverage Summary
+
+| # | Scenario | Verdict | Observables checked (produced-by evidence) | Key Gaps | Fix Status |
+|---|----------|---------|--------------------------------------------|----------|-----------|
+| 1 | ...      | PASS    | "<asserted literal>" ← <file>:<line> <the builder/branch that renders it> | — | — |
+| 2 | ...      | PARTIAL | <asserted value change> ← <file>:<line>; re-render path not established | ... | ✅ Fixed |
+| 3 | ...      | FAIL    | — (unreachable: hop <N> inert) | ... | ⚠️ Partially Fixed |
+| ...| ...     | ...     | ...                                        | ...      | ...       |
+
+Every PASS row must cite, for each asserted observable, the file:line that produces it. A row that cites only "the literal exists" or "the field is assigned" does not qualify as PASS — downgrade it.
+
+## Residual Gaps (not closed by this pass)
+
+List anything you could not settle statically, each with the reason it could not be closed and what would settle it (device run, spec clarification, fixture change). Scenarios marked UNABLE TO VERIFY must appear here.
+
+## Commit Info
+
+commit_id: <commit_id>
+```
+---
+
+## Guidelines
+
+- **Scenario-first**: Every finding must be tied to a specific user scenario. Do not report generic code style issues unless they impact a scenario.
+- **Be specific**: Always include file paths and line numbers as evidence.
+- **Be fair, in both directions**: If the code genuinely produces every observable the scenario asserts, give it PASS — don't nitpick style in a scenario review. Equally, don't award PASS for code that merely looks complete: the presence of a literal, a field assignment, or a wired handler is not the observable. When you find yourself writing evidence of the form "X exists", stop and trace what consumes X.
+- **Distinguish "the code says" from "the framework will"**: Static review can settle the first and not always the second. Reserve PASS for observables you settled by reading code; when the outcome hinges on framework behavior you cannot confirm from the source (re-render timing, gesture recognition, focus and selection lifecycle, IME interaction), that is UNABLE TO VERIFY and belongs in Residual Gaps. Silent optimism here is what lets a scenario ship broken.
+- **Derive implicit scenarios**: If the scenario document describes architecture (pages, modules, data flows) rather than explicit user stories, derive the scenarios yourself.
+- **No re-verification**: You found the defects; do not run another verification pass before fixing. Trust your own findings. This is about not re-litigating a *defect you already confirmed* — it does not license awarding PASS without having traced the observable in the first place.
+- **Look up before you guess**: For HarmonyOS API usage, parameter types, and patterns, prefer `npx -y devecocli docs search` / `npx -y devecocli docs read`.
+- **Use device logs for runtime-only clues**: When a scenario failure appears device-specific or cannot be closed statically, first use `npx -y devecocli log --level E` and `npx -y devecocli log --crash --bundle-name <bundle>` to obtain the runtime information.
+- **Re-sync after fixing**: If later steps depend on graph queries after you have edited source, run `npx -y homegraph sync <harmony_project_dir>` first.
+- **Minimal changes**: Only fix identified defects. Do not refactor, add comments to unrelated code, or "improve" working code.
+- **Fix the root cause**: Address the underlying issue, not just the symptom.
+- **Compile before moving on**: After every defect fix, compilation must pass before the fix counts as truly complete.
+- **Don't introduce new issues**: Verify that fixes don't break other features by checking for shared state, shared components, or shared resources — running `npx -y homegraph impact` on the symbol you changed is the fastest way to see what else it reaches.
+- **Preserve intent**: Keep the original code's structure and patterns where possible. Match the existing naming conventions, file organization, and code style.
+- **Prioritize gaps**: In the final assessment, rank residual gaps by user impact — which gaps would users notice first?

package/skills/{hmos-integration-test → a2h-integration-test}/README.md

@@ -30,7 +30,7 @@
    - 首轮：解析 `test_case.md` → 写出 `output-path/testcases.json` 与 `app-metadata.json` → 连接真机或模拟器、安装 HAP、跑 AutoTest → 产出 `output-path/self-test-report.md`
    - 测试完成后，SKILL 把当轮的 `self-test-report.md`、`task/`、`_extracted.json`（若有）快照到 `output-path/round-{n}/`
    - Fix：白盒审查代码 → 修改源码 → 产出 `round-{n}/self-test-fix-report.md`
-   - Build：调用 `hmos-fix-build-errors` 重新编译 → 从构建输出重新收集包集合并更新下一轮使用的 HAP/HSP
+   - Build：编译项目并修复 → 从构建输出重新收集包集合并更新下一轮使用的 HAP/HSP
    - 后续轮：跳过解析阶段，直接读首轮已生成的 `testcases.json` + `app-metadata.json`，用新 HAP 跑测试 → 同样快照到对应轮 `round-{n}/`
 2. **HAP 镜像** — 循环结束后，最后一轮的 HAP 复制到 `output-path/entry-default.hap`，方便直接取用
 
@@ -124,7 +124,7 @@
 │            否(退出循环)    是(进入编译)                         │
 │                             │                                  │
 │  ┌── Build ────────────────────────────────────────────┐    │
-│  │ 调 `hmos-fix-build-errors` 重新编译 → 从构建输出重新收集 entry/HSP │    │
+│  │ 编译项目并修复 → 从构建输出重新收集 entry/HSP           │    │
 │  │ → 组装到 round-{n}/package-set/ 供下一轮安装           │    │
 │  └──────────────────────┬──────────────────────────────┘    │
 │                         │                                    │
@@ -193,7 +193,7 @@
 - **修复计划**：按依赖关系排序的修复列表
 - **修复详情**：每条修复的 Android 参考、根因、具体修改、有效尝试次数、结果
 - **误报说明**：为什么判定为误报，测试 agent 出了什么问题
-- **编译验证**：编译结果及 `hmos-fix-build-errors` 触发的编译修复情况（如有）
+- **编译验证**：编译结果及编译修复情况（如有）
 - **所有修改文件汇总**：文件路径、修改类型、关联 Scenario 的汇总表
 
 ### 编译阶段
@@ -204,9 +204,9 @@
 
 ## test_case.md 怎么写
 
-完整格式定义见 `hmos-test-case-generation/references/contract.md`（`hmos-test-case-generation` skill 产出的就是该完整格式）。集成测试的解析器只从中提取 `### Scenario` 的 `动作`/`预期结果`，其余字段（`- 前置条件：`、`## 编号映射表`、`- 测试点：` 等）会被忽略——所以你既可以手写完整格式，也可以手写下面的最小子集。
+完整格式定义见 `a2h-test-case-generation/references/contract.md`（`a2h-test-case-generation` skill 产出的就是该完整格式）。集成测试的解析器只从中提取 `### Scenario` 的 `动作`/`预期结果`，其余字段（`- 前置条件：`、`## 编号映射表`、`- 测试点：` 等）会被忽略——所以你既可以手写完整格式，也可以手写下面的最小子集。
 
-完整格式（`hmos-test-case-generation` 产出，contract.md 节选）：
+完整格式（`a2h-test-case-generation` 产出，contract.md 节选）：
 
 ```markdown
 # 测试套件名
@@ -338,4 +338,4 @@ A: 不必须。提供了 fixer 会参考 Android 实现来修 bug，质量更高
 
 **Q: 报 "Build did not produce a HAP"？**
 
-A: 通常是编译失败或构建配置有误。检查 `hmos-fix-build-errors` 的编译输出，确认项目能正常构建后继续循环。
+A: 通常是编译失败或构建配置有误。检查编译输出，确认项目能正常构建后继续循环。

package/skills/{hmos-integration-test → a2h-integration-test}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: hmos-integration-test
+name: a2h-integration-test
 description: "Run on-device self-test for a HarmonyOS app. Parse test_case.md, install the HAP, execute AutoTest, and produce a verification report. Optionally enters a test-and-fix loop. Triggers on phrases like '跑自测', '运行自测', '执行自测', '自动测试', '设备测试', '跑用例', '跑自动化测试', 'self test', 'run autotest'."
 allowed-tools:
   - Read
@@ -119,7 +119,7 @@ Substitute `<MAX_ROUNDS>` in the question text with the parsed value (default `3
 
 ### 2A — Test (per round)
 
-The helper scripts (`resolve-metadata-tool.mjs`, `testcases-tool.mjs`, `report-tool.mjs`) are bundled in this skill's own `scripts/` directory (NOT the legacy `$HOMETRANS_TOOL_PATH` copy). Before running any `node` command below, resolve `SKILL_SCRIPTS` to the absolute path of this skill's `scripts/` directory — for opencode that is `~/.config/opencode/skills/hmos-integration-test/scripts`. `self-test-runner.mjs` itself is spawned by the `a2h_self_test` / `a2h_self_test_status` tools (the plugin resolves its path internally), so you do **not** invoke it via `node` yourself. The scripts locate `@autotest/agent`'s `batch_runner.js` by walking up from their own location and falling back to the global npm root, so they run correctly whether invoked from the repo, the skill dir, or a project.
+The helper scripts (`resolve-metadata-tool.mjs`, `testcases-tool.mjs`, `report-tool.mjs`) are bundled in this skill's own `scripts/` directory (NOT the legacy `$HOMETRANS_TOOL_PATH` copy). Before running any `node` command below, resolve `SKILL_SCRIPTS` to the absolute path of this skill's `scripts/` directory — for opencode that is `~/.config/opencode/skills/a2h-integration-test/scripts`. `self-test-runner.mjs` itself is spawned by the `a2h_self_test` / `a2h_self_test_status` tools (the plugin resolves its path internally), so you do **not** invoke it via `node` yourself. The scripts locate `@autotest/agent`'s `batch_runner.js` by walking up from their own location and falling back to the global npm root, so they run correctly whether invoked from the repo, the skill dir, or a project.
 
 `self-test-runner.mjs` orchestrates HAP install/uninstall + batch execution; polling is driven by you via `a2h_self_test_status`. The agent mode (`single` vs `layered` Planner+Executor dual-agent) is set by the `mode` field of the `a2h_self_test` tool call — default `single`; pass `mode: "layered"` when the app is complex enough to benefit from a planning step. There is no `autotest.yaml` to edit on this path — the tool writes a temporary one (0o600) inside `task_subdir` from the stdin-injected key and deletes it on terminal state.
 
@@ -270,11 +270,11 @@ If `round_no_confirmed_defects`:
 
 If `confirmed > 0`:
 
-**Capture `BUILD_START`** immediately before invoking `hmos-fix-build-errors` — e.g. `touch "<ROUND_DIR>/.build_start_marker"` (or record a timestamp). This marks the moment the rebuild begins, so the re-collection step below can tell freshly-rebuilt module outputs from stale ones left by a prior build.
+**Capture `BUILD_START`** immediately before the rebuild — e.g. `touch "<ROUND_DIR>/.build_start_marker"` (or record a timestamp). This marks the moment the rebuild begins, so the re-collection step below can tell freshly-rebuilt module outputs from stale ones left by a prior build.
 
-**Determine signing mode**: Check `ORIGINAL_HAP_PATH` (the user's original input). If it contains `*-signed.hap` or `*-signed.hsp` entries → the original packages were signed (real device path) → pass `--signed` to assert signed output. If not (emulator path, unsigned packages) → omit `--signed` so the skill produces unsigned output. This prevents the rebuilt HAP from failing `hdc install -r` on a real device while allowing unsigned testing on emulators.
+**Determine signing mode**: Check `ORIGINAL_HAP_PATH` (the user's original input). If it contains `*-signed.hap` or `*-signed.hsp` entries → the original packages were signed (real device path) → produce signed output. If not (emulator path, unsigned packages) → produce unsigned output. This prevents the rebuilt HAP from failing `hdc install -r` on a real device while allowing unsigned testing on emulators.
 
-Then invoke the `hmos-fix-build-errors` skill with `<PROJECT_ROOT>` (and `--signed` if determined above) for a rebuild.
+Then build the project and fix errors at `<PROJECT_ROOT>` (producing signed output if determined above) for a rebuild.
 
 After completion, locate the authoritative entry directly from `<PROJECT_ROOT>/entry/build/default/outputs/default/`. Identify `ENTRY_HAP` in this priority order:
 
@@ -426,7 +426,7 @@ If failures remain (for `max_rounds_reached`), list them briefly (scenario names
 | `<output-path>/testcases.json` is empty (`total == 0` in 2A) | Report: "testcases.json contains 0 cases — nothing to run." Exit loop with `stop_reason = no_testcases`. Do NOT enter the fix loop. |
 | The skill writes a sentinel FAIL report (first line `status: FAIL`), or no `self-test-report.md` was written (skill failed before producing a report) | Capture the `reason:` line. Exit loop with `stop_reason = agent_early_exit` and surface the captured reason. Do NOT enter the fix loop — these failures (config / device / autotest-dir / crash / timeout / precondition failures / report not produced) are not application defects. |
 | Fixer returns `confirmed == 0` (all false positives) | Exit loop with `stop_reason = no_confirmed_defects`. Surface the fix report summary. |
-| hmos-fix-build-errors produces no HAP in build output | Report: "Build did not produce a HAP — cannot re-test." Exit loop with `stop_reason = no_hap`. |
+| The rebuild produces no HAP in build output | Report: "Build did not produce a HAP — cannot re-test." Exit loop with `stop_reason = no_hap`. |
 | Loop reaches `MAX_ROUNDS` (default 3) with failures remaining | Report `stop_reason = max_rounds_reached`. Surface final pass rate and remaining failures. |
 | `app-metadata.json` missing after round 1 (PROJECT_ROOT unknown) | Surface agent error; PROJECT_ROOT cannot be resolved. Do NOT enter 2B. |
 

package/skills/{hmos-integration-test → a2h-integration-test}/scripts/report-tool.mjs

@@ -12,7 +12,7 @@
  *       Exit 0 = PASSED, exit 1 = FAILED.
  *
  * The emitted markdown is a FROZEN contract parsed by the
- * hmos-integration-test skill and validateReport below — template strings are
+ * a2h-integration-test skill and validateReport below — template strings are
  * verbatim and must not drift.
  */
 import fs from 'node:fs';