android2harmony 0.1.6 → 0.1.8

package/skills/a2h-spec-implement/references/harmony-pitfalls.md

@@ -0,0 +1,186 @@
+# HarmonyOS Boundary Decisions
+
+Match the requirement's action, state, or failure wording against a heading.
+Load every matching block; one scenario may cross several boundaries.
+
+## Scenario construction contract
+
+Reduce the behavior to:
+
+```text
+source/baseline → identity → command → owner write → public readback
+```
+
+At an external boundary, distinguish `payload → success/result → cancel/denial/unavailable → consumer`.
+
+Freeze `identity · source · unit/time rule · allowed outcomes · visible state` from the specification.
+Use project source to resolve any fact the specification leaves open.
+The blocks below supply reusable implementation and review decisions, not application-specific values.
+
+## Coder contract — 闭环实现
+
+For each delivered scenario, write a compact closure row before coding:
+
+```text
+baseline/input → identity → visible entry → eligibility → command → owner state
+→ public sentinel → fresh readback
+```
+
+Freeze the expected transition for normal, boundary, empty, cancel, and reopen/restart paths.
+A row is complete only when every step has a concrete source, owner, and observable result;
+an absent step is an implementation gap, not a reason to weaken the assertion.
+
+Keep external evidence separate from implementation decisions. Fixture setup, device availability,
+system UI, and acceptance scoring belong to the orchestrator. Coder consumes their reported state,
+preserves explicit `unavailable` / `error` branches, and records the dependency instead of
+fabricating data or bypassing the path.
+
+When a failure returns, classify it before editing: missing entry, action not delivered,
+state not committed, public result not rendered, or readback mismatch. Change the first
+broken edge and leave one falsifier for the next run.
+
+## Identity — 共享/删除/收藏/选择/重排
+
+Saving an array index or copying an entity into a child can write stale or wrong data after sorting or removal.
+
+Carry the business ID in every command. Keep one owner and writer; children return intent.
+Re-find the entity by ID at commit time.
+
+Review by reordering or deleting a neighbor, then performing the original action and rereading the same ID.
+
+## Gesture — 拖拽/滑动/长按/锁定
+
+A gesture can reach a container while the intended row stays unchanged.
+A visible handle can exist without a mutation path.
+
+Bind the gesture to a stable target and explicit eligibility. Locking or disabling gates both delivery and mutation.
+Commit reorder once in the owner.
+
+Review one target before and after the gesture; compare public order and state.
+
+## Commit — 输入/数字/焦点/选区/格式化/保存
+
+A command can read an old field or stale selection and update only a visual draft.
+
+Separate draft, selection, committed, and saved values.
+Bind a text transform to document ID, revision, and normalized range.
+Share one owner command for keyboard, toolbar, and button submission.
+
+Review after changing the selection and after valid, invalid, or boundary input; compare exact public content.
+
+## Surface — 弹窗/Picker/日期/确认/取消/返回
+
+Closing before the page owner receives a result loses confirmed data.
+Treating surface disappearance as success turns cancel, denial, and unavailable handlers into false success.
+
+Give each result an operation ID. Branch confirm, cancel, denial, and unavailable; commit before close or return.
+Cancel preserves prior owner state; discard is explicit.
+
+Review confirm and cancel, reopen the surface, and reread the caller owner.
+
+## Durable — 保存/重启/重开/恢复
+
+A default projection or the write-side object can be mistaken for persisted truth.
+
+Classify lifetime and schema. Register fields through one storage owner and hydrate before the first truthful consumer.
+Read back from a fresh source; keep independent settings in independent owner fields.
+
+Review reset → write → reload or fresh reader → compare durable source and UI.
+
+## Async — 加载/刷新/离开/重入/重试
+
+Old work can write a new owner, leave pending stuck, or duplicate an effect after a retry.
+
+Give each operation an owner and generation ID. Invalidate or cancel before leave.
+Accept only the current winner, clear pending on every terminal path, and clean up.
+
+Review leave/reentry during delayed work, then verify no stale write and that the next operation is accepted.
+
+## Query — 搜索/筛选/排序/空列表
+
+Sorting or filtering can mutate the source, use an unstable comparator, or retain rows when the result should be empty.
+
+Keep source and query projection separate. Freeze comparator and direction.
+Model empty, zero, and no-data explicitly; cancelling a chooser leaves source unchanged.
+
+Review apply, cancel, and repeat; reread source identity and visible order.
+
+## Derived — 统计/日期/数量/单位
+
+A plausible value can use the wrong source set, time window, or unit, especially at empty or boundary states.
+
+Compute from a named source snapshot with explicit temporal and unit rules.
+Define invalidation and distinguish empty, zero, and no-data before rendering.
+
+Review non-empty, empty, boundary-time, and conversion inputs, then reread result.
+
+## Playback — 播放/暂停/跳转/队列/进度/系统输出
+
+A callback or moving slider can look active while the track, queue, or system projection is stale.
+
+Let one session own media ID, queue, position, and play state. A new track or session invalidates old callbacks.
+Treat OS output as a separate consumer.
+
+Review switch, seek, and repeat; compare current ID and position for each consumer.
+
+## Source — Feed/文件/网络/系统处理器
+
+An unavailable source can be mistaken for empty business data or silently replaced with fabricated data.
+
+Keep unavailable, empty, and business error distinct.
+Resolve the source boundary before building the consumer projection.
+
+Review the unavailable branch first, then inspect the named consumer state.
+
+## Visual — 主题/深色/纯黑/颜色/资源
+
+A stored preference can change while the rendered surface or semantic tree remains unchanged.
+
+Make semantic theme/resource state drive each relevant projection. Keep independent options independent.
+
+Review each mode by comparing the intended surface or semantic tree, not storage.
+
+## Platform — 导入/声明/签名/回调
+
+An Android-shaped import or guessed callback may compile in the wrong context or outlive its owner.
+
+Resolve the local SDK declaration or an existing project call.
+Confirm type, result shape, and owner/lifecycle contract before choosing the API.
+
+Review with the smallest compile or runtime probe that can falsify the assumption.
+
+## Outcome — 控件/标签/状态/结果/完成
+
+A handler, callback, log, or closed surface proves transport only.
+The named result may still be absent from the consumer.
+
+Render the required semantic control or state from the authoritative owner and connect it to the committed result.
+
+Review by locating the result before the action and rereading it afterward.
+
+## Delivery self-check
+
+Before returning, check only the blocks matched by the scenario:
+
+- [ ] Identity/Gesture: commands carry a stable business ID.
+  The owner rereads the same entity and public order after the action.
+- [ ] Commit/Surface: draft, selection, commit, and save are distinct.
+  Every confirm/cancel/denial/unavailable path has an explicit result before close.
+- [ ] Durable/Async: hydration precedes the first truthful consumer.
+  Fresh readback and generation invalidation prevent default or stale writes.
+- [ ] Query/Derived/Playback/Source: source, projection, time/unit, and media ID are explicit.
+  Unavailable/empty/error branches are explicit and independently reread.
+- [ ] Visual/Platform/Outcome: the required surface/semantic state is driven by the authoritative result.
+  Imports, signatures, callbacks, and lifecycle are confirmed from the local SDK or project code.
+- [ ] Evidence: static/build checks are not reported as runtime or device proof.
+  An unchecked runtime edge is recorded as `runtime_debt` with one falsifier.
+- [ ] Coder closure: every delivered scenario has a baseline, stable identity, owner command,
+  committed state, public sentinel, and fresh readback; normal and negative paths are explicit.
+- [ ] Scope: fixture/device/acceptance failures are recorded as external dependencies;
+  no business code or assertion is changed to hide them.
+
+## Evidence boundary
+
+Static or build evidence does not prove consumer readback.
+Persistence, async, system-surface, visual, and device claims require the matching capable oracle.
+Otherwise keep the edge `unknown` or `runtime_debt` with one falsifier.

package/skills/a2h-spec-implement/references/l1-unit-test.md

@@ -0,0 +1,185 @@
+---
+name: l1-unit-test
+description: "Operational contract for the L1 unit-test layer. Covers derivation from the acceptance test set, authoring rules (path, suite prefix, level constant, registration, imports, APIs), the single-shot `aa test` invocation, failure handling for the development self-test and delivery-time gates, and the result records produced."
+---
+
+# L1 — Logic Unit Tests (Instrument JsUnit)
+
+## 1. Contract
+
+L1 is the fast, deterministic gate for UI-independent logic. It runs after build and the lint gate, and before any e2e execution.
+
+HarmonyOS host-only tests have no automatable CLI path, so L1 uses instrument JsUnit under `src/ohosTest`. Because `aa test` has about five seconds of fixed startup overhead, all L1 suites for one delivery unit run in one invocation.
+
+- **`coder`**: authors, builds and runs L1 within the development self-test (step3).
+- **Round orchestrator**: decides what derives to L1 and stops the round when L1 remains red.
+
+---
+
+## 2. Derivation
+
+The test-case generator produces only the e2e acceptance set. L1 is derived from that set during the code phase.
+
+- **What derives to L1**: deterministic, UI-independent logic behind a TP — computations, formatting, state transitions, filtering, ordering, deduplication and boundary rules in service/model classes.
+- **What stays e2e**: the TP itself and its user-visible UI behaviour.
+- **Boundary duty**: every computational L1 target gets at least one nominal and one relevant boundary test, such as zero duration, empty list, duplicate input, or first/last item.
+- **What never derives**: rendered UI, navigation, UI interaction, visual assertions or real device-service state.
+- **No duplicate assertions**: do not restate an e2e assertion as L1 unless it isolates a distinct logic contract.
+
+### 2.1 L1 → E2E dependency via plan.md
+
+The L1 → E2E dependency is declared inline in `OUTPUT/logic/plan.md` on each case as a `unit_dep` field (the unit suite whose failure should block the E2E case). This keeps the contract in the same place as the case definition rather than scattered across a separate per-round artifact.
+
+| Case | `unit_dep` |
+|------|------------|
+| `scenario_1_1` | `L1_ProgressRatio` |
+| `scenario_1_2` | `L1_ProgressRatio` |
+| every case in `media_sorter` feature | `L1_MediaSorter` (feature-wide) |
+
+When a case's `unit_dep` is unset, no L1 → E2E block applies. Step ⑤ § 6 reads `unit_dep` from `plan.md` to write the derived `class=fixture, failing_point=L2-BLOCK:<suite>` line; the prefix `L2-BLOCK` is preserved as the canonical slug for both L1 and E2E layers.
+
+---
+
+## 3. Authoring
+
+- **Path**: `entry/src/ohosTest/ets/test/<feature>/L1_<unit>.test.ets`
+- **Suite**: `L1_<unit>`
+- **Level**: `it(name, Level.LEVEL1, …)`
+- **Registration**: add the suite to `List.test.ets` per `test-core.md` § Suite packaging.
+- **Imports**: import production code directly from `../../../main/ets/…`.
+- **Test API**: plain JsUnit only — `describe`, `it`, `expect`.
+- **No UI APIs**: no `Driver`, `ON`, selectors, gestures or UI assertions. Those belong in `E2E_*`.
+- **Specification-derived assertions**: expected values come from the specification, not from the implementation being tested.
+- **Fixture isolation**: Test fixtures shall be provisioned through the designated initialization entry point using a test-scoped storage instance rather than by writing to production-named identifiers, and the provisioned instance shall be destroyed in `afterAll`.
+
+### 3.1 Suite and Test Identifiers
+
+```typescript
+describe('L1_ProgressRatio', () => {
+  it('nominal_1/2',                 Level.LEVEL1, () => { ... });
+  it('nominal_1/4',                 Level.LEVEL1, () => { ... });
+  it('boundary_duration_zero',      Level.LEVEL1, () => { ... });
+  it('boundary_duration_negative',  Level.LEVEL1, () => { ... });
+  it('clamp_above_one',             Level.LEVEL1, () => { ... });
+});
+```
+
+| Token | Rule | Example |
+|-------|------|---------|
+| Suite prefix | `L1_` (literal) | `L1_ProgressRatio` |
+| Unit name | PascalCase, semantic | `ProgressRatio`, `MediaSorter` |
+| Test name | snake_case, scenario-shaped | `nominal_1/2`, `boundary_empty_list` |
+| Level constant | `Level.LEVEL1` (canonical value) | — |
+
+### 3.2 Forbidden APIs
+
+| API | Reason |
+|-----|--------|
+| `Driver`, `ON`, `text(...)`, `id(...)` | UI-layer API; belongs to E2E |
+| `hdc shell ...`, `aa test ...` | Cross-device boundary; orchestrator concern |
+| `systemCapability.*` direct calls | Platform channel; not under unit-test jurisdiction |
+| Sleeps, timers, `setTimeout` (unless boundary-of-interest) | Determinism violation |
+
+---
+
+## 4. Gate
+
+Run L1 after build and the lint gate are green, before the unit's e2e, on the exclusively bound device.
+
+```bash
+hdc -t <device> shell 'pidof uitest && kill -9 $(pidof uitest) || true'
+
+hdc -t <device> shell aa test -b <bundle> -m entry_test \
+  -s unittest OpenHarmonyTestRunner \
+  -s class <L1 suites, comma-joined> \
+  -s breakOnError true \
+  -s timeout 15000 \
+  > <round-dev-dir>/l1/l1-report.log 2>&1
+```
+
+- **Single sweep**: comma-join all L1 suites for the delivery unit into one `aa test` run.
+- **Exclusive channel**: clear any residual `uitest` process before execution.
+- **Pinned output**: write stdout and stderr to `<round-dev-dir>/l1/l1-report.log`.
+
+---
+
+## 5. Failure Handling
+
+- **Any L1 red**: fix immediately within the development self-test budget, rebuild the test HAP and rerun.
+- **Still red at delivery**:
+  - record all failing `suite#it` assertions as a gap;
+  - skip the unit's e2e (Round Step ⑤ marks the affected E2E cases as `source=uitest, verdict=BLOCKED, class=fixture, failing_point=L2-BLOCK:<suite>`);
+  - carry the unresolved failure into the next round as `prior-attempts`;
+  - **append a `source=unit, verdict=FAIL, class=code` line per affected (scenario, suite) pair to the convergence ledger.** This is the round's record of the unit-layer failure and feeds `no_progress` detection and the run's defect counts. It is **not** an E2E acceptance verdict; the E2E verdict is the BLOCKED fixture line appended at Step ⑤.
+
+`prior-attempts` should include the failed test, expected and actual values, attempted fixes, relevant source/test/log paths, suspected cause and recommended next action.
+
+This contract is the authoritative reconciliation between `l1-unit-test.md` and `SKILL.md` Round Step ③ — both files MUST agree on it. The convergence ledger (not the E2E acceptance ledger) is the source of truth for unit-layer failures.
+
+---
+
+## 6. Result Records
+
+### 6.1 Round Notes
+
+Record L1 gate status in the round notes under the code section. Use the canonical tokens `<suite>#<it>` and `<assertion_name>` (matches `SKILL.md` Round Step ③):
+
+```text
+L1: PASS <passed>/<executed>
+```
+
+or:
+
+```text
+L1: FAIL <passed>/<executed> planned=<n> | <suite>#<it>:<assertion_name>
+```
+
+- `<passed>` — number of (scenario, suite) pairs that pass.
+- `<executed>` — number of (scenario, suite) pairs actually executed.
+- `<n>` — total number of L1 suites the slice planned to run (planned but not necessarily executed; a SKIPPED round still counts `<n>`).
+
+For multi-failure aggregation, see § 6.2.
+
+### 6.2 Multi-Failure Aggregation
+
+When a single (scenario, suite) pair produces multiple assertion failures, the round notes still show only one `<suite>#<it>:<assertion_name>` slug — the first failure in execution order. The ledger follows the same rule (`SKILL.md` Round Step ③ § 3). Subsequent failures in the same pair are not appended as separate ledger lines; they are recorded in the gap log (§ 6.3) for traceability.
+
+For counting only:
+
+- A suite with three executed (scenario, suite) pairs and one failure contributes `<passed>=2`, `<executed>=3`.
+- `planned=<n>` reflects the slice's planned L1 suites, not the executed count; a SKIPPED round uses `planned=<n>` and omits the `| <suite>#<it>:...` suffix.
+
+### 6.3 Gap Record
+
+Unresolved L1 failures at delivery are recorded as a gap entry:
+
+```json
+{
+  "type": "gap",
+  "suite": "L1_<unit>",
+  "test": "<it_name>",
+  "expected": "<expected_value>",
+  "actual": "<actual_value>",
+  "attempted_fixes": ["..."]
+}
+```
+
+### 6.4 Result Boundary
+
+The result boundary separates the unit-layer signal from the acceptance signal:
+
+```text
+L1 round notes / gap     → unit-layer signal (this file)
+L1 convergence ledger    → unit-layer signal (SKILL.md, source=unit)
+E2E ledger (Step ⑤/⑥)    → acceptance verdict
+```
+
+L1 green does not by itself create an acceptance `PASS`. L1 red does not create an acceptance `FAIL`; it prevents the e2e case from running and routes the scenario to Step ⑦ for code-layer repair.
+
+---
+
+## 7. Cross-References
+
+- Skill entry point: [`../SKILL.md`](../SKILL.md)
+- E2E layer: [`l3-e2e-uitest.md`](./l3-e2e-uitest.md)
+- Shared contract: [`test-core.md`](./test-core.md)

package/skills/a2h-spec-implement/references/l3-e2e-uitest.md

@@ -0,0 +1,167 @@
+---
+name: l3-e2e-uitest
+description: "Contract for the E2E device-side end-to-end UITest layer. Covers transcription of each TP into an `E2E_*` instrument suite, authoring rules, the development self-test run, the acceptance run, failure handling, and the pinned host command for the single-shot execution."
+---
+
+# E2E — Device-side Suites
+
+## 1. Contract
+
+E2E is the single executable carrier for device-side end-to-end acceptance cases.
+
+Each TP in the delivery unit is transcribed into an `E2E_*` instrument suite. The same suite is:
+
+- self-run by `coder` before delivery (step5);
+- acceptance-run by the round's test orchestrator to produce the case verdict.
+
+The suite is authored once. Development self-test and acceptance are separate executions of the same carrier.
+
+---
+
+## 2. Transcription
+
+- **Source**: transcribe directly from the TP in `test_case.md`.
+- **Coverage**: preserve the TP's preconditions, actions and user-visible assertions.
+- **Selectors**: take selectors from grounded UI records; never invent them.
+- **Independence from L1**: L1 may cover underlying logic, but E2E must still verify the complete UI-visible behaviour.
+- **Preconditions**: each suite establishes its own preconditions through `beforeAll` or `beforeEach`.
+- **Check before establish**: fixture hooks use a check-and-establish pair rather than assuming state.
+- **Untranscribable establish**: treat an establishable precondition that cannot be encoded as a suite defect, not as a case property.
+
+---
+
+## 3. Authoring
+
+- **Path**: `entry/src/ohosTest/ets/test/<feature>/E2E_<feature>_<caseId>.test.ets`
+- **Suite**: `E2E_<feature>_<caseId>`
+- **Registration**: `List.test.ets` (per `test-core.md` § Suite packaging).
+- **API**: Hypium plus the approved device UI-test APIs.
+- **Packaging**: share the feature's test HAP with its L1 suites.
+- **Fixtures**: follow `test-core.md` § Fixture isolation.
+- **Level**: `it(name, Level.LEVEL2, …)`.
+
+### 3.1 Suite and Test Identifiers
+
+Sanitize `-` → `_`: a feature `playbar-progress` and case `1-2` form the suite `E2E_playbar_progress_1_2`.
+
+```typescript
+describe('E2E_SortByDateFlow', () => {
+  it('opens_sort_dialog',       Level.LEVEL2, async () => { ... });
+  it('applies_date_descending', Level.LEVEL2, async () => { ... });
+});
+```
+
+| Token | Rule | Example |
+|-------|------|---------|
+| Suite prefix | `E2E_` (literal) | `E2E_playbar_progress_1_2` |
+| Feature | snake_case, spec-derived | `playbar_progress` |
+| Case identifier | stable per test case | `1_2`, `4_1`, `5_1` |
+| Level constant | `Level.LEVEL2` (canonical value) | — |
+
+---
+
+## 4. Development Self-Test
+
+`coder` runs every E2E suite it authored or changed; no sampling.
+
+Use the pinned `scripts/test/l2_run.mjs` command from this document. The runner resets the fixture before the batch, runs the selected suites and stores evidence under:
+
+```text
+<output-dir>/dev/e2e/<case-id>/
+```
+
+Green means every coded device assertion passed.
+
+A self-test run:
+
+- does not produce an acceptance verdict;
+- does not update the ledger;
+- only establishes that the delivery unit is ready for acceptance.
+
+---
+
+## 5. Acceptance Run
+
+The round's test orchestrator executes the delivered E2E suites under the acceptance workflow.
+
+Only this run may:
+
+- assign the TP verdict;
+- write the acceptance report;
+- append or update the ledger.
+
+The result boundary is:
+
+```text
+E2E development self-test → delivery readiness
+E2E acceptance run        → TP verdict and ledger
+```
+
+---
+
+## 6. Failure Handling
+
+- **Self-test red**: `coder` fixes and reruns within its budget.
+- **Still red at delivery**: record the failing case and assertion as a gap; the round orchestrator carries it into the next round as `prior-attempts`.
+- **Acceptance red**: preserve the verdict and evidence; repair routing belongs to the round orchestrator.
+- **L1 → E2E dependency block**: when an L1 suite fails at Round Step ③, the affected E2E cases are skipped and a derived `source=uitest, verdict=BLOCKED, class=fixture, failing_point=L2-BLOCK:<suite>` line is appended per the `unit_dep` field on `OUTPUT/logic/plan.md` (see `l1-unit-test.md` § 2.1 and `SKILL.md` Round Step ⑤ § 6).
+
+### 6.1 Failure-Class Taxonomy
+
+Failures from E2E route to the repair loop following the cheapest-first policy:
+
+| Failure Class | Repair Path | Cost |
+|---------------|-------------|------|
+| `selector_drift` | Inline edit of the offending `E2E_*.test.ets`; rebuild; rerun | Low |
+| `fixture`        | Resolve the blocking prerequisite scenario; rerun affected subset | Medium |
+| `code`           | Repair agent — white-box verification and code repair | High |
+| `environment`    | Resolve environment deficiency (excluded from quality-rate denominator) | — |
+
+The `class` field on the convergence ledger is what drives this routing. `source=uitest` is the carrier; `class` is the discriminator. PASS lines carry `failing_point=""` so their `failing_point|root_cause` signature is `|` and never matches a non-PASS signature for `no_progress`.
+
+---
+
+## 7. Pinned Commands
+
+### 7.1 Test HAP Build
+
+Per `test-core.md` § Device channel & install.
+
+### 7.2 Installation
+
+Per `test-core.md` § Device channel & installation.
+
+### 7.3 E2E Self-Run
+
+```bash
+# Execute suite(s) — ONE pinned invocation: fixture reset (force-stop + bm clean -d,
+# built into the script) → per case aa test (restart pairs via @pair) +
+# observation pull + obs assembly.
+# Raise --timeout for establish-bearing suites (an instrumented SAF picker
+# interaction ≈30s, measured).
+node <plugin-path>/scripts/test/l2_run.mjs --device <device> --bundle <bundle> \
+  --out-dir <round-dev-dir>/e2e --cases <suite[,suite…][@pair]> --timeout 300000
+
+# --cases takes FULL suite names (E2E_<feature>_<caseId>) — no derivation in the script:
+# one identifier keys the aa test class, the per-suite output dir, and the obs filenames.
+```
+
+---
+
+## 8. Process-Restart-Crossing Cases
+
+A case whose actions cross an app restart is transcribed as **two suites** (`<suite>_pre` / `<suite>_post`) with the restart between them as a pinned host step:
+
+```bash
+hdc -t <device> shell aa force-stop <bundle>
+```
+
+then run the `_post` suite (its `startAbility` is the relaunch). Both suites append to the same `obs_<suite>.json` (filesDir survives a force-stop), so `_post` can assert against `_pre`'s recorded values; `scripts/test/l2_run.mjs` assembles one result from both `aa-test.log`s (`<suite>@pair`).
+
+---
+
+## 9. Cross-References
+
+- Skill entry point: [`../SKILL.md`](../SKILL.md)
+- L1 layer: [`l1-unit-test.md`](./l1-unit-test.md)
+- Shared contract: [`test-core.md`](./test-core.md)

package/skills/a2h-spec-implement/references/test-core.md

@@ -0,0 +1,132 @@
+---
+name: test-core
+description: "Shared contract for the L1 unit-test and E2E device-side instrument suites. Covers suite packaging (path, prefix), suite registration via `List.test.ets`, the device channel and install procedure, and the fixture-isolation invariants that apply to every suite riding the `ohosTest` instrument HAP."
+---
+
+# Test Core — Shared Contract for Instrument Suites
+
+Shared infrastructure for L1 logic suites and E2E device-side suites lives here. Layer documents reference this file and do not restate it.
+
+Pinned host commands use POSIX shell syntax: `(cd … && …)`, `$(…)`, and single-quote discipline. On Windows, run them through Git Bash or another POSIX shell, never PowerShell or `cmd`.
+
+---
+
+## 1. Suite Packaging
+
+- All suites for one feature live under `entry/src/ohosTest/ets/test/<feature>/`.
+- L1 suites use `L1_*`; e2e suites use `E2E_*`.
+- Feature-local fixture and setup helpers live in the same feature directory.
+- Register every suite in `List.test.ets`, with imports grouped by feature.
+- Suite names are globally unique. Directories do not namespace Hypium registration or `aa test -s class`.
+- One `ohosTest` sourceset produces one test HAP for all L1 and E2E suites.
+
+### 1.1 Suite Registration Mechanism
+
+```typescript
+// entry/src/ohosTest/ets/test/List.test.ets
+import './<feature>/L1_ProgressRatio.test.ets';
+import './<feature>/L1_MediaSorter.test.ets';
+import './<feature>/E2E_playbar_progress_1_2.test.ets';
+import './<feature>/E2E_sort_by_date.test.ets';
+// ... additional suite imports
+```
+
+Each `*.test.ets` is imported **once**; the runtime registry is built by the JsUnit harness. Imports are listed in topological order (L1 suites before E2E suites that depend on their units).
+
+---
+
+## 2. Device Channel and Installation
+
+Install only changed artifacts:
+
+```bash
+# App HAP changed
+(cd <package-set-dir> && hdc -t <device> install -r <app.hap>)
+
+# L2/L3 suites changed
+(cd <ohosTest-out-dir> && hdc -t <device> install -r <entry-ohosTest-signed.hap | entry-ohosTest-unsigned.hap>)
+```
+
+App and test HAPs must come from the same project version.
+The test HAP follows the project's signing mode, exactly like the app HAP: a project configured for signing emits `entry-ohosTest-signed.hap`, one with empty `app.signingConfigs` emits `entry-ohosTest-unsigned.hap`. Install whichever the build actually produced — never assume the filename. A device that refuses an unsigned package is an environment result (`class=environment`), not a code defect.
+
+For downgrade error `9568263`, uninstall before reinstalling:
+
+```bash
+hdc -t <device> shell bm uninstall -n <bundle>
+```
+
+Do not reinstall the app HAP when only test suites changed. App reinstall may drop persisted URI grants.
+
+The device `uitest`/AAMS channel is exclusive. Before every `aa test`-based run:
+
+```bash
+hdc -t <device> shell 'pidof uitest && kill -9 $(pidof uitest) || true'
+```
+
+Use single quotes so command substitution runs on the device, not the host.
+
+---
+
+## 3. Fixture Isolation
+
+Applies to all L1 and E2E suites.
+
+- Never seed user-visible persistent data through production-named RDB stores, `Preferences`, `PersistentStorage`, or indexed files.
+- Establish preconditions through the application UI by default.
+- Programmatic seeding is allowed only through an initialization seam into a test-scoped store.
+- Bind the production singleton to the test store before the application ability launches.
+- Delete the test store in `afterAll`.
+- `bm clean` is runner preparation, not fixture cleanup; it may revoke external application bindings.
+- A minimal configurable store-name seam is allowed in production code. Test-only business behaviour is not.
+
+### 3.1 L1-Specific
+
+- No production-named storage writes; test fixtures write only to test-scoped storage via the initialisation seam.
+- The `afterAll` hook of each suite must delete its test-scoped storage; no suite leaves persistent state visible to subsequent suites.
+
+### 3.2 E2E-Specific
+
+- Each suite establishes its own preconditions through `beforeAll` or `beforeEach` (check-before-establish).
+- The pinned runner (`scripts/test/l2_run.mjs`) force-stops and `bm clean -d`s the bundle before every batch; green is earned only from an empty fixture.
+
+---
+
+## 4. Reporting
+
+| Layer | Output Path |
+|:-----:|-------------|
+| L1 | `<round-dev-dir>/l1/l1-report.log` |
+| E2E | `<round-dev-dir>/e2e/e2e-report.log` |
+
+The convergence ledger (`convergence.jsonl`) records one line per (round, case, source) tuple. The `source` field uses the canonical values defined in `SKILL.md` Round Step ⑧:
+
+| `source` | Layer | Cost |
+|:--------:|:-----:|------|
+| `unit`        | L1 Unit Tests    | fixed ~5 s |
+| `uitest`      | E2E UITest       | ~18 s / scenario |
+| `integration` | Step ⑥ AutoTest  | highest |
+| `review`      | Step ④ Code Review | mid |
+| `fixer`       | Step ⑦ Repair    | — |
+
+### 4.1 Ledger Constraint
+
+The convergence ledger is one unified log; layer rows are not segregated. The constraint is on **what counts as the acceptance verdict**, not on whether a line is written:
+
+| Layer State | Ledger Row? | Counts as acceptance verdict? |
+|-------------|:-----------:|:-----------------------------:|
+| L1 green    | Yes (`source=unit, verdict=PASS, failing_point=""`) | No (precondition) |
+| L1 red      | Yes (`source=unit, verdict=FAIL, class=code`) | No (routes to Step ⑦) |
+| E2E green   | Yes (`source=uitest, verdict=PASS, class=code`) | Yes |
+| E2E red     | Yes (`source=uitest, verdict=FAIL, class=code`) | Yes |
+| E2E blocked by L1 | Yes (`source=uitest, verdict=BLOCKED, class=fixture, failing_point=L2-BLOCK:<suite>`) | Yes (fixture) |
+
+PASS lines carry `failing_point=""` (empty string, never omitted) so the schema is uniform and the `no_progress` signature `failing_point|root_cause` collapses to `|` for PASS — a value that never matches a non-PASS signature. See `SKILL.md` Defect Tracking § Ledger line schema for the canonical schema and `l1-unit-test.md` § 6.4 for the result-boundary narrative.
+
+---
+
+## 5. Cross-References
+
+- Skill entry point: [`../SKILL.md`](../SKILL.md)
+- L1 contract: [`l1-unit-test.md`](./l1-unit-test.md)
+- E2E contract: [`l3-e2e-uitest.md`](./l3-e2e-uitest.md)