android2harmony 0.1.0

package/skills/hmos-convert-pipeline/SKILL.md

@@ -0,0 +1,446 @@
+---
+name: hmos-convert-pipeline
+description: "Run the Android-to-HarmonyOS conversion pipeline — all agents in sequence with progress, duration, and defect tracking. Trigger phrases include 'full Android-to-HarmonyOS pipeline', 'run the conversion pipeline end-to-end', 'hmos-convert-pipeline', 'HarmonyOS conversion', or any request to convert an Android project to HarmonyOS with all stages (logic → build → review → fix → rebuild → self-test loop)."
+---
+
+# Full Conversion Pipeline
+
+Run all conversion agents in sequence, passing outputs between stages and recording cumulative progress after each step.
+
+**Raw arguments**: $ARGUMENTS
+
+---
+
+## Argument Parsing
+
+Parse `$ARGUMENTS` as positional tokens:
+
+- **Arg 1** (`android_project_dir`): Path to the Android source project (required)
+- **Arg 2** (`harmony_project_dir`): Path to the target HarmonyOS project directory (required)
+- **Arg 3** (`spec_file_path`): Path to the requirement spec document (required). This is the plan/spec that drives Stage 1 logic development and Stage 3 code review — both stages read it directly from this path.
+- **Arg 4** (`assets_output_path`): Directory to store all output/report files (optional). When omitted, default to `<harmony_project_dir>/.hometrans` — create the directory if it does not exist.
+- **Arg 5** (`test_case_path`): Path to the self-test case file driving the Stage 4 self-testing loop (optional). When omitted, default to `OUTPUT/test_case.md`. If the resolved file does not exist, the Stage 4 loop is skipped (see Loop Setup).
+- **Arg 6** (`pre_test_case_path`): Path to the pre-test case file (optional). When omitted, default to `OUTPUT/pre_test_case.md`. Only passed to the self-tester when the resolved file exists.
+- **Arg 7** (`max_rounds_review`): Maximum number of Stage 3→3a→3b code-review-fix rounds to run (optional, default `2`). Must be a positive integer `>= 1`.
+- **Arg 8** (`max_rounds_test`): Maximum number of Stage 4→4a→4b self-test rounds to run (optional, default `2`). Must be a positive integer `>= 1`.
+- **Arg 9** (`skip_test`): `true` or `false` (optional, default `false`). When `true`, skip Stage 4 / 4a / 4b (Self-Testing Loop) entirely. Use this when no real HarmonyOS device is available for on-device testing.
+
+Args are positional: to pass any optional arg, provide explicit values for all optional args before it (e.g., passing `test_case_path` requires an explicit `assets_output_path`; passing `skip_test` requires explicit Args 4–8).
+
+If any required argument is missing, ask the user before proceeding. If `spec_file_path` does not exist or is not a readable file, ask the user before proceeding. If `max_rounds_review` or `max_rounds_test` is provided but is not a positive integer, ask the user before proceeding. If `skip_test` is provided but is not `true` or `false`, ask the user before proceeding.
+
+Define shorthand variables for the instructions below:
+
+| Variable | Meaning |
+|----------|---------|
+| `ANDROID` | android_project_dir |
+| `HMOS` | harmony_project_dir |
+| `SPEC` | spec_file_path — requirement spec document, consumed directly by Stage 1 (`spec_file`) and Stage 3 (`test_case_path`) |
+| `OUTPUT` | assets_output_path; defaults to `HMOS/.hometrans` when not provided (created on demand) |
+| `SCRIPTS_PATH` | absolute path to `agents/scripts` in this repo |
+| `TEST_CASE` | test_case_path; defaults to `OUTPUT/test_case.md` when not provided |
+| `PRE_TEST_CASE` | pre_test_case_path; defaults to `OUTPUT/pre_test_case.md` when not provided |
+| `MAX_ROUNDS_REVIEW` | max_rounds_review — positive integer (default `2`). Controls Stage 3→3a→3b code-review-fix loop. |
+| `MAX_ROUNDS_TEST`   | max_rounds_test — positive integer (default `2`). Controls Stage 4→4a→4b self-test loop. |
+| `SKIP_TEST` | skip_test — `true` or `false` (default `false`). When `true`, skip Stage 4 / 4a / 4b entirely (no real device available). |
+
+---
+
+## Environment Variables Check (run before Stage 1)
+
+The pipeline's sub-agents resolve each setting along the standard chain — **OS environment variable first, then `~/.hometrans/config.json`, then ask the user**. Verify upfront so the long pipeline fails fast (read env vars with `echo "$VAR"` on macOS/Linux; `$env:VAR` in PowerShell on Windows):
+
+| Variable | config.json fallback | Needed for | Valid when |
+|---|---|---|---|
+| `DEVECO_HOME` *(or `DEVECO_SDK_HOME`)* | `env.DEVECO_HOME` / `env.DEVECO_SDK_HOME` | Stage 2 build + Stage 3b/4b rebuilds | resolves to a valid DevEco install |
+| `HOMETRANS_MODEL_API_KEY` *(legacy `TEST_API_KEY` still honored as a fallback)* | `autotest.unified_model.api_key` | Stage 4 self-test (only when `SKIP_TEST=false`) | non-empty / not the placeholder |
+| `HOMETRANS_TOOL_PATH` | `env.HOMETRANS_TOOL_PATH` (defaults to `~/.hometrans/tools`) | Stage 4 self-test AutoTest dir | path exists on disk |
+
+For each value, if the env var is unset, fall back to the listed `~/.hometrans/config.json` field. If neither yields a value: for the DevEco path / model api_key, **ask the user** (for the api_key they may instead pass `skip_test=true`). Suggest running `ht init` to persist these as machine environment variables.
+
+---
+
+## Progress Tracking
+
+Before any agent runs, create tasks for all pipeline stages listed below so the user sees the full plan immediately. Stages are sequential — each stage depends on the previous one completing first. For the Stage 3 and Stage 4 loops, create one umbrella task per sub-stage (3 / 3b and 4 / 4a / 4b) covering the full multi-round cycle rather than creating per-round tasks. If `SKIP_TEST == true`, still create Stage 4 / 4a / 4b tasks but mark them as completed immediately with a "Skipped" note.
+
+| # | subject | activeForm |
+|---|---------|------------|
+| 1 | Logic Development (Context Builder) | Building logic decision contract |
+| 1a | Logic Coding | Converting business logic to ArkTS |
+| 2 | Compilation and Build | Building HarmonyOS project |
+| 3 | Code Review + Fix | Reviewing and fixing HarmonyOS code |
+| 3b | Rebuild after Review Fix | Rebuilding after review fixes |
+| 4 | Self-Testing | Running on-device tests |
+| 4a | Self-Test Fix | Fixing self-test failures |
+| 4b | Rebuild after Self-Test Fix | Rebuilding after self-test fixes |
+
+For each stage: mark `in_progress` before launching the agent, then `completed` after it finishes (update description with actual output files and key stats). If a stage fails, still mark `completed` so the next stage unblocks — include the failure details in the description.
+
+### Stage Duration Tracking
+
+For every stage (including each Stage 3 / 3b review round and each Stage 4 / 4a / 4b test round), capture wall-clock duration:
+
+1. Just before marking a stage `in_progress`, record `stage_start_iso` using the current local time (e.g., run `date -Iseconds` via Bash, or capture a timestamp in ISO-8601 `YYYY-MM-DDTHH:MM:SS` form).
+2. Just after the stage's agent returns, record `stage_end_iso` the same way.
+3. Compute `duration_seconds = stage_end_iso - stage_start_iso` and format as `H:MM:SS` (hours, minutes, seconds).
+4. Record `start`, `end`, and `duration` in the manifest's **Duration Summary** table (see format below). For Stage 3 review loop rounds, record one row per execution using labels like `3 - Code Review + Fix (Round 1)`, etc. For Stage 4 test loop rounds, use labels like `4 - Self-Testing (Round 1)`, etc.
+
+For the Stage 3 review loop:
+- Mark Stage 3 `in_progress` when Round 1 starts, and keep it `in_progress` until the full review loop exits.
+- Mark Stage 3b `in_progress` when the first Stage 3b round starts.
+- Append brief per-round summaries into the Stage 3 / 3b task descriptions.
+- Only mark Stage 3 / 3b `completed` after the review loop finishes (either `all_passed`, `no_progress`, or `max_rounds_reached`).
+
+For the Stage 4 test loop:
+- Mark Stage 4 `in_progress` when Round 1 starts, and keep it `in_progress` until the full test loop exits.
+- Mark Stage 4a `in_progress` when the first Stage 4a round starts, and Stage 4b `in_progress` when the first Stage 4b round starts.
+- Append brief per-round summaries into the Stage 4 / 4a / 4b task descriptions.
+- Only mark Stage 4 / 4a / 4b `completed` after the test loop finishes (either `all_passed`, `no_confirmed_defects`, or `max_rounds_reached`).
+
+Also maintain a manifest file at **`OUTPUT/pipeline-manifest.md`** — update it after every stage with status, per-stage start/end timestamps, wall-clock duration, and a cumulative inventory of all output files (documents, generated code, build artifacts, reports).
+
+### Manifest duration format
+
+In `OUTPUT/pipeline-manifest.md`, include a **Duration Summary** table:
+
+```markdown
+## Duration Summary
+
+| Stage | Start | End | Duration (H:MM:SS) |
+|-------|-------|-----|--------------------|
+| 1 - Logic Development (Context Builder) | 2026-04-20T10:00:00 | 2026-04-20T10:05:12 | 0:05:12 |
+| 1a - Logic Coding | ... | ... | ... |
+| ... | ... | ... | ... |
+| **TOTAL** | first start | last end | **H:MM:SS** |
+```
+
+---
+
+## Defect Tracking
+
+After each **review**, **fix**, or **test** stage completes, read the corresponding report file from `OUTPUT` and extract defect statistics. Record these in the manifest's **Defect Summary** table.
+
+### Extraction rules per stage
+
+| Stage | Report File | What to Extract |
+|-------|-------------|-----------------|
+| **3 — Code Review** | `review-round-N/code-review-report.md` | From the **Overview** section, extract `Total Scenarios`, the verdict breakdown (`PASS`, `PARTIAL`, `FAIL`, `UNABLE TO VERIFY` counts), `Total Defects Found`, `Successfully Fixed`, `Failed to Fix`, `Fix Success Rate`, and **Overall Verdict** (`PASS` / `PASS WITH ISSUES` / `NEEDS REWORK`). **Defects found** = `Total Defects Found`. **Defects fixed** = `Successfully Fixed`. **Defects not fixed** = `Failed to Fix`. Record one row per review round. |
+| **4 — Self-Testing** | `round-N/self-test-report.md` | From the **测试概览** or **测试总结** section, extract: `总用例数` (total cases), `通过` (passed), `失败` (failed), `通过率` (pass rate). **Defects found** = `失败` count. Record one row per round. |
+| **4a — Self-Test Fix** | `round-N/self-test-fix-report.md` | From the **概览** section, extract: `报告中失败 scenario 总数` (total failed), `白盒确认问题存在` (confirmed), `白盒判定为误报` (false positives), `修复成功` (fixed), `修复失败` (failed to fix). **Defects fixed** = `修复成功`. **Defects not fixed** = `修复失败`. Use this to populate the same round row as Stage 4. |
+
+### How to extract
+
+After the agent completes and writes the report file, read the report and search for the key fields listed above. The values are typically in the first few sections of each report. If a field is missing or the report format is unexpected, record `N/A` for that field and add a note.
+
+### Manifest defect format
+
+In `OUTPUT/pipeline-manifest.md`, include a **Defect Summary** table after the Duration Summary:
+
+```markdown
+## Defect Summary
+
+| Stage | Report File | Defects Found | Defects Fixed | Not Fixed | Details |
+|-------|-------------|---------------|---------------|-----------|---------|
+| 3 Loop - Round 1 | review-round-1/code-review-report.md | X (Y FAIL + Z PARTIAL) | D fixed | E not fixed | Overall: PASS WITH ISSUES; rebuild=SUCCESS |
+| 3 Loop - Round 2 | review-round-2/code-review-report.md | X (Y FAIL + Z PARTIAL) | D fixed | E not fixed | Overall: PASS; stop=all_passed |
+| 3 Loop - Summary | review-round-*/... | Total found across rounds | Total fixed across rounds | Remaining in final round | Rounds executed: N / MAX_ROUNDS_REVIEW; stop reason: all_passed/no_progress/max_rounds_reached |
+| 4 Loop - Round 1 | round-1/self-test-report.md + round-1/self-test-fix-report.md | X failed / Y total | C | D | Pass rate: ZZ%; confirmed=B; false positives=F; rebuild=SUCCESS |
+| 4 Loop - Round 2 | round-2/self-test-report.md + round-2/self-test-fix-report.md | X failed / Y total | C | D | Pass rate: ZZ%; confirmed=B; false positives=F; rebuild=SUCCESS; stop=all_passed |
+| 4 Loop - Summary | round-*/... | Total found across rounds | Total fixed across rounds | Remaining in final round | Rounds executed: N / MAX_ROUNDS_TEST; stop reason: all_passed/max_rounds_reached |
+```
+
+For stages that are not review/fix/test (Stages 1–2), no row is needed in this table.
+For the Stage 3 loop, `code-reviewer` reviews and fixes in the same pass, so one row per round captures both.
+For the Stage 4 loop, combine test and fix results into one row per round plus one summary row.
+
+---
+
+## Pipeline Execution
+
+### Package-Set Collection (shared procedure)
+
+Several stages below need the **full signed package set** — the entry HAP plus any in-app HSPs (and any feature HAP the build freshly produced) — so the self-tester installs them in one `hdc install -r` transaction (in-app HSPs cannot install standalone). Those stages call this procedure.
+
+**Inputs:**
+- `BUILD_ROOT` — the project root build-fixer compiled (= `HMOS`).
+- `DEST` — a dedicated `package-set/` directory to populate; **must never be the directory build-fixer copied the entry HAP into** (step 1 clears `DEST`).
+- `BUILD_START` — a marker captured **immediately before** launching build-fixer, e.g. `touch "<DEST>/../.build_start_marker"` (or record a timestamp). Used to tell freshly-rebuilt artifacts from stale ones. A touched marker + `find -newer` avoids clock-skew between the agent and the build host.
+- `AUTHORITATIVE_ENTRY` — the entry HAP build-fixer **copied** to this stage's output dir (the `*-signed.hap` it placed). Authoritative **by construction**, regardless of mtime.
+
+**Procedure:**
+1. **Clear/create `DEST`** (remove prior contents, recreate) so stale packages never leak forward. `DEST` is a dedicated `package-set/` subdir, distinct from where build-fixer copied the entry.
+2. **Place the authoritative entry:** copy `AUTHORITATIVE_ENTRY` into `DEST`. Included **unconditionally — the mtime gate does NOT apply to the entry** (an incremental build may leave the build-tree entry UP-TO-DATE; build-fixer's copy still reflects the round's code).
+3. **Discover non-entry outputs** under depth-1 modules `BUILD_ROOT/*/build/default/outputs/default/`, admitting **only files with mtime ≥ `BUILD_START`** (freshly rebuilt this invocation; cross-platform: `find "<dir>" -newer "<marker>"` or compare `stat` mtimes). build-fixer runs **no clean**, so non-entry dirs still hold *prior*-build packages — the mtime gate is the only reliable way to reject those stale artifacts:
+   - **HSPs:** `*-signed.hsp` (the fresh in-app HSPs).
+   - **Feature HAPs:** `*-signed.hap` from non-entry modules the build freshly rebuilt; skip any whose basename equals `AUTHORITATIVE_ENTRY`'s.
+4. **Exclude test artifacts:** skip `*ohosTest*` and `*-test-signed.*`.
+5. **Unsigned-HSP rule (all-or-nothing):** if any module dir has a **freshly-rebuilt** `*.hsp` but **no** fresh `*-signed.hsp`, mark the collection **incomplete** → the caller falls back to the entry-only / legacy set and logs the unsigned HSP as a build-config gap. (A *stale* unsigned `.hsp` is ignored — it never passes the mtime gate.) Rationale: all packages install in one transaction; a single unsigned package fails the whole `hdc install -r`, so the entry would never install — strictly worse than today. A *partial* set is also unsafe.
+6. **Copy** the selected non-entry files into `DEST` (flat). (The entry is already there from step 2.)
+7. **Invariants:**
+   - **≥ 1 `.hap`** — guaranteed by step 2. If `AUTHORITATIVE_ENTRY` is missing, collection **fails** → caller fallback.
+   - **Exactly one `entry-*.hap`** (the authoritative one). If the fresh harvest still yields a second, differently-named `entry-*.hap`, **fail** the collection and log the conflict (the self-tester picks `entry-*` first and cannot disambiguate two entries). Non-`entry-*` feature HAPs may be many.
+   - On a same-basename collision in `DEST`, abort with a logged error listing sources.
+   - Manifest inventory line: `package-set: 1 entry hap + F feature hap(s) + M signed hsp(s) → DEST` (and `WARNING: K unsigned .hsp skipped — build-config gap` if any).
+8. **Result:** the caller sets `CURRENT_HAP = DEST`.
+
+> **Build-completeness caveat.** Whether `assembleHap -p module=entry` freshly emits a signed `.hsp` depends on hvigor's transitive-build behavior; if nothing fresh is emitted this procedure collects **entry-only** and equals today — never worse. Independent feature modules (off entry's dependency path) are never rebuilt by `-p module=entry`; harvesting their HAPs needs a build change (out of scope).
+
+### Stage 1 — Logic Development (Context Builder)
+
+Flags: `skip-plan-builder: true|false` (default `false`) — when `true`, skip this stage and reuse an existing `OUTPUT/logic/plan.md`.
+
+Prompt format (applies to both Stage 1 and Stage 1a): ONLY the key-value lines below. No natural language, step lists, or Markdown.
+
+1. Launch the logic context builder agent:
+   ```
+   Agent(
+     subagent_type="logic-context-builder",
+     prompt="harmony_project_dir: HMOS\nspec_file: SPEC\noutput_path: OUTPUT/logic\nscripts_path: SCRIPTS_PATH"
+   )
+   ```
+2. Verify `OUTPUT/logic/plan.md` exists.
+
+### Stage 1a — Logic Coding
+
+1. Launch the logic coding agent:
+   ```
+   Agent(
+     subagent_type="logic-coder",
+     prompt="harmony_project_dir: HMOS\nplan_file: OUTPUT/logic/plan.md\noutput_path: OUTPUT/logic\nscripts_path: SCRIPTS_PATH"
+   )
+   ```
+2. Copy `OUTPUT/logic/commit-info.md` → `OUTPUT/commit-info.md`.
+3. Read `OUTPUT/commit-info.md` and use it as the canonical handoff for the
+   following steps.
+
+### Stage 2 — Compilation and Build
+
+1. Launch the **build-fixer** agent with `--signed`.
+2. Input: `harmony_project_dir`: `HMOS`, `output_path`: `OUTPUT`.
+3. The agent runs the build-fix loop (up to 20 iterations), writes `build-fix-report.md` into `OUTPUT`.
+4. If the build succeeds, the signed `.hap` is copied to `OUTPUT`. Note its location in the manifest.
+5. **If the build succeeded**, run **Package-Set Collection** with `BUILD_ROOT = HMOS`, `DEST = OUTPUT/package-set/`, `AUTHORITATIVE_ENTRY =` the `*-signed.hap` build-fixer just copied to `OUTPUT/` (step 4), and `BUILD_START` captured just before launching build-fixer (step 1). Record the inventory in the manifest. (If the build failed there is no fresh entry to collect; collection's ≥1-`.hap` guard fails and Stage 4 Loop Setup's legacy fallback applies. The step-4 entry-HAP copy is retained for the manifest / back-compat.)
+6. After the agent completes, read `OUTPUT/build-fix-commit-info.md` and note the commit ID (may be a real hash or `none`). 
+
+### Stage 3 — Code Review Loop (Review-and-Fix → Rebuild)
+
+Treat Stage 3 → 3b as a loop that runs up to `MAX_ROUNDS_REVIEW` times. `code-reviewer` performs review and defect fixing in the same pass (no separate `review-fixer` agent).
+
+#### Review Loop Setup
+
+1. **Resolve the initial commit ID for code review** using the following priority:
+   - Read `OUTPUT/commit-info.md` (written by Stage 1a) and use its `commit_id` when available.
+   - IMPORTANT: Use `commit-info.md` from Stage 1a, NOT `build-fix-commit-info.md` from Stage 2.
+   - Store this as `REVIEW_COMMIT_ID`.
+2. Initialize loop state:
+   - `review_round = 1`
+   - `review_rounds_executed = 0`
+   - `review_stop_reason = none`
+   - `LAST_GOOD_REVIEW_SET = none` — the package-set dir from the **last review round whose 3b rebuild succeeded** (used at finalization; stays `none` if no review round ever rebuilt).
+3. Mark Stage 3 `in_progress` when Round 1 begins. Keep Stage 3 / 3b tasks open until the full loop exits.
+
+#### Per-Round Stage 3 / 3b Execution Order
+
+For each `review_round` from `1..MAX_ROUNDS_REVIEW`, set `REVIEW_ROUND_DIR = OUTPUT/review-round-{review_round}` and execute the following two steps in order:
+
+##### Review Round Step A — Stage 3 Code Review + Fix
+
+1. Launch the **code-reviewer** agent.
+2. Input:
+   - `harmony_project_dir`: `HMOS`
+   - `commit_id`: For Round 1, use `REVIEW_COMMIT_ID`. For Round 2+, review the project holistically (omit `commit_id` or pass `none`) since fixes have modified the codebase beyond the original commit scope.
+   - `output_path`: `REVIEW_ROUND_DIR`
+   - `test_case_path`: `SPEC`
+   - `android_project_dir`: `ANDROID` (enables reference-based fixing for missing pages / APIs / event handlers)
+3. If a valid `commit_id` is available, the agent will automatically run the **ArkAnalysis** extractor via `npx --yes arkanalysis@latest` to extract commit-scoped code context before reviewing. If it fails (e.g. the package is unpublished or unreachable), the agent falls back to direct git-diff analysis. If no `commit_id` is available, the agent reviews the project holistically without commit-scoped extraction.
+4. The agent reviews every user scenario, fixes every FAIL / PARTIAL / cross-cutting defect it finds, and writes `REVIEW_ROUND_DIR/code-review-report.md` (merged review + fix report) plus `REVIEW_ROUND_DIR/code-review-commit-info.md` (git commit id or `none`).
+5. **Extract defect stats**: Read `REVIEW_ROUND_DIR/code-review-report.md`, extract the verdict breakdown (PASS/PARTIAL/FAIL/UNABLE TO VERIFY counts), `Total Defects Found`, `Successfully Fixed`, `Failed to Fix`, `Fix Success Rate`, and Overall Verdict.
+6. Compute loop-control flags:
+   - `review_all_passed` = `true` if the overall verdict is `PASS` and there are zero `FAIL` or `PARTIAL` verdicts AND zero cross-cutting defects; else `false`.
+   - `review_no_progress` = `true` if `Total Defects Found > 0` AND `Successfully Fixed == 0` (nothing was fixed this round — a next round would repeat); else `false`.
+   If the report is missing or malformed, do **not** treat the round as passed.
+7. If `review_all_passed == true`, set `review_stop_reason = all_passed`, skip Stage 3b for this round, and exit the loop.
+8. If `review_no_progress == true`, set `review_stop_reason = no_progress`, still run Stage 3b (to leave the tree buildable), then exit the loop after 3b.
+9. Update the Stage 3 task description with a brief round summary (for example: `Round 1: 8 PASS, 2 PARTIAL, 1 FAIL; fixed=2, failed=1`).
+
+##### Review Round Step B — Stage 3b Rebuild after Review Fix
+
+1. Mark Stage 3b `in_progress` when the first Stage 3b round begins.
+2. Capture `BUILD_START` (touch a marker), then launch the **build-fixer** agent with `--signed`.
+3. Input: `harmony_project_dir`: `HMOS`, `output_path`: `REVIEW_ROUND_DIR`.
+4. The agent writes `REVIEW_ROUND_DIR/build-fix-report.md`.
+5. If the build succeeds, the signed `.hap` is copied to `REVIEW_ROUND_DIR`. Note its location in the manifest. **Then run Package-Set Collection** with `BUILD_ROOT = HMOS`, `DEST = REVIEW_ROUND_DIR/package-set/`, `AUTHORITATIVE_ENTRY =` the `*-signed.hap` build-fixer copied to `REVIEW_ROUND_DIR/`, and the captured `BUILD_START`; on success set `LAST_GOOD_REVIEW_SET = REVIEW_ROUND_DIR/package-set/`. **If the 3b build failed, do NOT run collection and keep the previous `LAST_GOOD_REVIEW_SET`** (a failed rebuild leaves stale sibling-module outputs on disk; the mtime gate already prevents harvesting them, and skipping collection avoids re-touching `LAST_GOOD_REVIEW_SET` with an entry-less set).
+6. Append one Defect Summary row for this round using the parsed Stage 3 stats, labeled `3 Loop - Round {review_round}`.
+7. Update the Stage 3b task description with a brief round summary (for example: `Round 1: build success`).
+8. Increment `review_rounds_executed`.
+9. **Loop stop decision** (after 3b completes):
+    - If `review_stop_reason` was already set to `no_progress` in Step A, exit the loop.
+    - Else if `review_round == MAX_ROUNDS_REVIEW`, set `review_stop_reason = max_rounds_reached` and exit the loop.
+    - Else continue to the next round.
+
+#### Review Loop Finalization
+
+After the review loop exits:
+
+1. Append one Defect Summary row labeled `3 Loop - Summary` with total defects found across rounds, total fixed across rounds, remaining defects in the final round, `review_rounds_executed`, and `review_stop_reason`.
+2. Add a short review loop summary in the manifest, including:
+   - `Configured max rounds: MAX_ROUNDS_REVIEW`
+   - `Rounds executed: review_rounds_executed`
+   - `Stop reason: review_stop_reason` — one of: `all_passed` (all scenarios PASS in code review), `no_progress` (defects found but none could be fixed this round), `max_rounds_reached` (hit the round limit with real defects remaining)
+   - `Final round: review-round-{review_rounds_executed}`
+3. Mirror the final review round outputs back to the root `OUTPUT` directory using the canonical filenames for backward compatibility:
+   - `OUTPUT/code-review-report.md`
+   - `OUTPUT/code-review-commit-info.md`
+   - `OUTPUT/build-fix-report.md` (overwrites Stage 2 report, if 3b ran in the final round)
+   - If the final round's build produced a signed `.hap`, copy it to `OUTPUT` (replaces Stage 2 `.hap` if present).
+   - **Mirror the package set:** if `LAST_GOOD_REVIEW_SET != none` (some review round rebuilt successfully), clear-then-copy `LAST_GOOD_REVIEW_SET` → `OUTPUT/package-set/`. **If `LAST_GOOD_REVIEW_SET == none`, leave `OUTPUT/package-set/` (the Stage-2 set) untouched — never clear it.** No self-copy guard is needed: `LAST_GOOD_REVIEW_SET` is always a `review-round-*/package-set/`, never `OUTPUT/package-set/`.
+4. Mark Stage 3 / 3b `completed` only after the full loop finishes.
+
+### Stage 3b — Rebuild after Review Fix
+
+Stage 3b is executed as **Review Round Step C** inside the Stage 3 loop above. Do not run Stage 3b outside that loop.
+
+### Stage 4 — Self-Testing Loop (On-Device Verification)
+
+**Skip check**: If `SKIP_TEST == true`, immediately mark Stage 4 / 4a / 4b as `completed` with description "Skipped — skip_test=true (no real device available)". Record a single Duration Summary row with `Duration = SKIPPED`. Add a note in the manifest: `Stage 4 loop skipped by user configuration (skip_test=true)`. Then proceed directly to the **Final Summary**.
+
+Treat Stage 4 → 4a → 4b as a loop that runs up to `MAX_ROUNDS_TEST` times.
+
+#### Loop Setup
+
+1. **Resolve the initial package set**: The self-tester needs the **complete signed package set** (entry HAP + any in-app HSPs) in one `hdc install -r` transaction (rationale in **Package-Set Collection** above).
+   - **Priority 1 — `OUTPUT/package-set/` directory**: If it exists and contains ≥ 1 `.hap` + any `.hsp`, set `CURRENT_HAP = OUTPUT/package-set/` (the set mirrored by Stage 2 or, if a review round rebuilt, by the review-loop finalization).
+   - **Priority 2 — Comma-separated assembly**: If `OUTPUT/package-set/` does not exist, find the entry HAP and any HSPs separately and assemble a comma-separated `CURRENT_HAP`:
+     - Entry HAP: `OUTPUT/entry-default-signed.hap` → first `*-signed.hap` in `OUTPUT/` → search `HMOS/entry/build/default/outputs/default/`.
+     - In-app HSPs: search `HMOS/*/build/default/outputs/default/` for `*-signed.hsp` (skip `*ohosTest*` / `*-test-signed*`). If found, copy them into `OUTPUT/hsp/` and include `OUTPUT/hsp/` in the comma-separated list.
+     - Example: `CURRENT_HAP = OUTPUT/entry-default-signed.hap,OUTPUT/hsp` (entry HAP file + HSP directory, comma-separated).
+   - **Priority 3 — Legacy single file**: If no HSPs are found anywhere (single-module project), set `CURRENT_HAP` to just the entry HAP file path.
+   - Log the resolved `CURRENT_HAP` in the manifest. If HSPs were found and included, note: "Package set includes N in-app HSP(s)". If HSPs were found but omitted (legacy fallback), log a **WARNING**: "In-app HSPs exist but were not included in CURRENT_HAP — app may not function on device".
+2. Store the resolved path (a **directory**, a **comma-separated list**, or a single file) as `CURRENT_HAP`.
+3. **`TEST_CASE` existence guard**: If `TEST_CASE` does not exist, mark Stage 4 / 4a / 4b as failed with note "No test case file available" and skip the loop entirely.
+4. Initialize loop state:
+   - `round = 1`
+   - `rounds_executed = 0`
+   - `stop_reason = none`
+5. Mark Stage 4 `in_progress` when Round 1 begins. Keep Stage 4 / 4a / 4b tasks open until the full loop exits.
+
+#### Per-Round Stage 4 / 4a / 4b Execution Order
+
+For each `round` from `1..MAX_ROUNDS_TEST`, set `ROUND_DIR = OUTPUT/round-{round}` and execute the following three steps in order:
+
+##### Round Step A — Stage 4 Self-Testing
+
+> ⚠️ **`CURRENT_HAP` must reflect the latest build**: If a previous round's Stage 4b produced a new signed package set, `CURRENT_HAP` should already point to it (a directory, e.g. `round-{N-1}/package-set/`; or, via the legacy fallback, a single file like `round-{N-1}/entry-default-signed.hap`). Do NOT reuse the original package from Stage 2/3b in subsequent rounds.
+
+1. If `CURRENT_HAP` is missing, do **not** launch the test. Record this round as Stage 4 failure with note "No HAP file available — build may have failed in Stage 2/3b or a previous 4b round".
+2. If `CURRENT_HAP` exists, launch the **self-tester**.
+3. Input (round 1):
+   - `hap_path`: `CURRENT_HAP`
+   - `output_path`: `OUTPUT` (the ROOT — the agent always writes here)
+   - `test_case_path`: `TEST_CASE`
+   - `pre_test_case_path`: `PRE_TEST_CASE` (only include this line when the file exists)
+   - `setup`: `true`
+4. Input (round 2+):
+   - `hap_path`: `CURRENT_HAP`
+   - `output_path`: `OUTPUT` (still the ROOT)
+   - `setup`: `false`
+5. The agent verifies device connectivity, invokes `ht autotest selftest run` to install the HAP and run test cases. **Pre-cases are folded into `OUTPUT/testcases.json` by the agent's S4/S5 step during round 1's `setup: true` invocation; they run first in the same batch — no separate pre-case file or parameter is needed downstream.** The agent writes `OUTPUT/self-test-report.md`, `OUTPUT/task/`, and (round 1 only) `OUTPUT/testcases.json` + `OUTPUT/app-metadata.json` + `OUTPUT/_extracted.json`.
+6. After round 1's agent returns, read `OUTPUT/app-metadata.json` and extract `project_root` → `PROJECT_ROOT`. For round 2+, re-read `OUTPUT/app-metadata.json` before invoking the agent; if the previous round's `OUTPUT/round-{round-1}/app-metadata.json` exists (build-fixer may have written one for a relocated project root), the round-dir copy overrides the root copy for this round.
+7. Snapshot per-round artifacts to `ROUND_DIR` after the agent returns: copy `OUTPUT/self-test-report.md` → `ROUND_DIR/self-test-report.md`, `OUTPUT/task/` → `ROUND_DIR/task/`, and (round 1 only) `OUTPUT/_extracted.json` → `ROUND_DIR/_extracted.json`. Skip any source that is missing.
+8. Read `ROUND_DIR/self-test-report.md` and extract total cases, passed, failed, and pass rate when the report exists.
+9. Compute `round_all_passed` only when the report can be parsed clearly and:
+   - `总用例数` is known
+   - `失败 == 0`
+   - `通过 == 总用例数`
+   If the report is missing or fields are malformed, do **not** treat the round as passed.
+10. Update the Stage 4 task description with a brief round summary (for example: `Round 1: 3/12 failed`).
+
+##### Round Step B — Stage 4a Self-Test Fix
+
+1. Mark Stage 4a `in_progress` when the first Stage 4a round begins.
+2. If `ROUND_DIR/self-test-report.md` exists, launch the **self-test-fixer** agent.
+3. Input:
+   - `self_test_report_path`: `ROUND_DIR/self-test-report.md`
+   - `harmony_project_dir`: `HMOS`
+   - `android_project_dir`: `ANDROID`
+   - `output_path`: `ROUND_DIR`
+4. The agent analyzes failed feature points from the self-test report, references Android source for correct behavior, fixes HarmonyOS code, and writes `ROUND_DIR/self-test-fix-report.md`.
+5. If `ROUND_DIR/self-test-report.md` is missing, do **not** launch the fixer. Record this round as `Skipped — missing self-test report`.
+6. Read `ROUND_DIR/self-test-fix-report.md` when it exists, extract total failed scenarios, confirmed, false positives, successfully fixed, and failed to fix.
+7. Compute `round_no_confirmed_defects`:
+   - `true` if the fix report exists AND `白盒确认问题存在 == 0` (all failures are false positives, or the report says "No failures to fix — all scenarios passed").
+   - `false` otherwise (at least one confirmed defect exists, or the fix report is missing/malformed).
+8. Update the Stage 4a task description with a brief round summary (for example: `Round 1: confirmed=3, fixed=2, failed=1`).
+
+##### Round Step C — Stage 4b Rebuild after Self-Test Fix
+
+1. Mark Stage 4b `in_progress` when the first Stage 4b round begins.
+2. Capture `BUILD_START` (touch a marker), then launch the **build-fixer** agent with `--signed`.
+3. Input: `harmony_project_dir`: `HMOS`, `output_path`: `ROUND_DIR`.
+4. The agent writes `ROUND_DIR/build-fix-report.md`.
+5. ⚠️ **CRITICAL — Update `CURRENT_HAP` for the next round**: If the build succeeds, the signed `.hap` is copied to `ROUND_DIR`. **Run Package-Set Collection** with `BUILD_ROOT = HMOS`, `DEST = ROUND_DIR/package-set/`, `AUTHORITATIVE_ENTRY =` the `*-signed.hap` build-fixer copied to `ROUND_DIR/` (`entry-default-signed.hap`, else first `ROUND_DIR/*-signed.hap`), and the captured `BUILD_START`; then set `CURRENT_HAP = ROUND_DIR/package-set/` so the next round's Stage 4 self-tester uses the freshly built set. If collection **fails** or yields zero HAPs (e.g. build-fixer placed no entry), **keep the previous `CURRENT_HAP`** (the prior round's full set — fresher than any legacy single-file resolution) and record that this round produced no fresh package set.
+6. Append one Defect Summary row for this round by combining the parsed Stage 4 and Stage 4a results into a single row labeled `4 Loop - Round {round}`.
+7. Update the Stage 4b task description with a brief round summary (for example: `Round 1: build success, hap=...`).
+8. Increment `rounds_executed`.
+9. **Loop stop decision** (after 4b completes):
+    - If `round_all_passed == true`, set `stop_reason = all_passed` and exit the loop.
+    - Else if `round_no_confirmed_defects == true`, set `stop_reason = no_confirmed_defects` and exit the loop. Rationale: all failures were judged as false positives (AutoTest limitations / environment issues) by white-box review, no code was changed, so repeating the test would yield identical results.
+    - Else if `round == MAX_ROUNDS_TEST`, set `stop_reason = max_rounds_reached` and exit the loop.
+    - Else continue to the next round.
+
+#### Loop Finalization
+
+After the loop exits:
+
+1. Append one Defect Summary row labeled `4 Loop - Summary` with total defects found across rounds, total fixed across rounds, remaining defects in the final round, `rounds_executed`, and `stop_reason`.
+2. Add a short Stage 4 loop summary in the manifest, including:
+   - `Configured max rounds: MAX_ROUNDS_TEST`
+   - `Rounds executed: rounds_executed`
+   - `Stop reason: stop_reason` — one of: `all_passed` (all tests green), `no_confirmed_defects` (failures exist but all judged as false positives by white-box review), `max_rounds_reached` (hit the round limit with real defects remaining)
+   - `Final round: round-{rounds_executed}`
+3. Mirror the final round's `OUTPUT/round-{rounds_executed}/` Fix/Build artifacts back to `OUTPUT/` root using the canonical filenames (the test report and `task/` are already at `OUTPUT/` root as the latest copies — they do NOT need mirroring):
+   - `OUTPUT/self-test-fix-report.md` ← `OUTPUT/round-{rounds_executed}/self-test-fix-report.md` (if present)
+   - `OUTPUT/build-fix-report.md` ← `OUTPUT/round-{rounds_executed}/build-fix-report.md` (if present)
+   - `OUTPUT/self-test-fix-commit-info.md` ← `OUTPUT/round-{rounds_executed}/self-test-fix-commit-info.md` (if present)
+   - `OUTPUT/build-fix-commit-info.md` ← `OUTPUT/round-{rounds_executed}/build-fix-commit-info.md` (if present)
+   - **Final package set** — branch on the type of `CURRENT_HAP`:
+     - **If `CURRENT_HAP` is a directory** (a `package-set/`): mirror `CURRENT_HAP/` → `OUTPUT/package-set/` (clear-then-copy), **but skip entirely when `CURRENT_HAP` already resolves to `OUTPUT/package-set/`** (source == dest — happens when every 4b build failed and `CURRENT_HAP` still holds the Loop-Setup value; a clear-then-copy onto itself would destroy the set). Then, best-effort, copy the single `entry-*.hap` out of the set to `OUTPUT/entry-default-signed.hap` for back-compat (skip if absent).
+     - **If `CURRENT_HAP` is a single file** (legacy fallback — no package set was ever produced): copy it to `OUTPUT/entry-default-signed.hap`, skipping when `CURRENT_HAP` is already that path. Do not attempt a directory mirror.
+   - `OUTPUT/screenshots/` when the final report still references `screenshots/...`
+4. When mirroring Fix/Build files back to `OUTPUT`, treat the final round directory as the source of truth and ensure the mirrored root-level reports still reference files that actually exist at the root level.
+5. Mark Stage 4 / 4a / 4b `completed` only after the full loop finishes.
+
+### Stage 4a — Self-Test Fix
+
+Stage 4a is executed as **Round Step B** inside the Stage 4 loop above. Do not run Stage 4a outside that loop.
+
+### Stage 4b — Rebuild after Self-Test Fix
+
+Stage 4b is executed as **Round Step C** inside the Stage 4 loop above. Do not run Stage 4b outside that loop.
+
+---
+
+## Error Handling
+
+- If a stage **fails**, log the error in the manifest and task, then **continue to the next stage** unless the loop logic says to continue to the next round.
+- Stage 3 uses a bounded Stage 3 → 3b review loop (up to `MAX_ROUNDS_REVIEW` rounds). `code-reviewer` reviews and fixes defects in the same pass; Stage 3b (Rebuild) then ensures the fixes still compile. The loop exits when all scenarios pass (`all_passed`), no defect could be fixed this round (`no_progress`), or `MAX_ROUNDS_REVIEW` is reached.
+- Stage 4 uses a bounded Stage 4 → 4a → 4b test loop (up to `MAX_ROUNDS_TEST` rounds). Stage 4a addresses failures found by Stage 4, followed by Stage 4b (Rebuild) to ensure compilation, then the pipeline either continues to the next round or exits the loop based on `all_passed` / `no_confirmed_defects` / `max_rounds_reached`.
+- If Stage 4a determines that all failures are false positives (`confirmed == 0`), the test loop exits after 4b with `stop_reason = no_confirmed_defects` — because no code was changed and repeating the test would yield identical results.
+- If a Stage 4 round fails before producing `round-N/self-test-report.md`, do not call Stage 4a with a missing report; record the round accordingly and continue to Stage 4b.
+- If a Stage 4 report is malformed or required fields are missing, do not treat the round as passed; continue until `MAX_ROUNDS_TEST` is reached or a later round clearly passes.
+- If a Stage 4 round passes but the same round's Stage 4b rebuild fails, stop the loop after that round if `round_all_passed == true`, but record clearly that the final rebuild failed and whether the previous `CURRENT_HAP` had to be retained.
+
+---
+
+## Final Summary
+
+After the Stage 4 loop completes (or is skipped), print a concise summary:
+
+1. Overall pipeline status (all green, or which stages had issues)
+2. Location of `OUTPUT/pipeline-manifest.md` for full details
+3. Stage 3 review loop summary: `MAX_ROUNDS_REVIEW`, `review_rounds_executed`, `review_stop_reason`, final review round directory
+4. Stage 4 test loop summary: If `SKIP_TEST == true`, print "Stage 4 skipped (skip_test=true, no real device)". Otherwise print `MAX_ROUNDS_TEST`, `rounds_executed`, `stop_reason`, final round directory.
+5. Key statistics: total files generated, self-test results (or "N/A — testing skipped" if `SKIP_TEST == true`)
+6. Defect summary: total defects found (code review + testing), total fixed, total remaining unfixed
+7. Recommended next steps (if testing was skipped, recommend running on-device tests when a real device becomes available)