android2harmony 0.1.6 → 0.1.8

package/skills/a2h-spec-implement/rules/arkts/ui/state-management.md

@@ -0,0 +1,152 @@
+---
+paths:
+  - "**/*.ets"
+  - "**/*.ts"
+---
+# ArkUI State Management — V1 / V2
+
+The single source of truth for choosing and using a state-management family. Decorator details are NOT restated here — they live in the official docs under `../official/mvvm-v1/` and `../official/mvvm-v2/` (referenced, not duplicated).
+
+## Family selection (decide first)
+
+Both **V1** and **V2** are valid. **Never mix V1 and V2 decorators within one project** — project-level policy; mixing inside one struct is additionally a build error (`../language/arkui-structure-rules.md` § 5). The official mixusage guide (`../official/mvvm-v2/状态管理V1和V2混用指导（API version 19及之后）.md`) documents platform capability for migration reference only — this no-mix policy overrides it.
+
+- **New / greenfield project** → use **V2**.
+- **Incremental development on an existing project** → match the family the project already uses. Detect from the existing `.ets`:
+  - `@ComponentV2` / `@Local` / `@Param` / `@ObservedV2` ⇒ the project is **V2**.
+  - `@Component` / `@State` / `@Link` / `@Observed` ⇒ the project is **V1**.
+
+## V2 family (cheat sheet)
+
+Full official docs: **`../official/mvvm-v2/`** (`@Local`/`@Param`/`@Once`/`@Event`/`@Provider`/`@Consumer`/`@Monitor`/`@Computed`/`@ObservedV2`/`@Trace`/`@Type`, AppStorageV2/PersistenceV2, makeObserved/getTarget, `!!` two-way binding, V1↔V2 mixusage, `MVVM模式（V2）.md`).
+
+| Decorator | Purpose |
+|-----------|---------|
+| `@ComponentV2` | Marks a struct as a V2 component |
+| `@Local` | Component-internal state |
+| `@Param` | External input from parent (read-only) |
+| `@Once` | Initialize from parent once, then decouple |
+| `@Event` | Output callback to parent |
+| `@Provider` / `@Consumer` | Cross-level two-way sync |
+| `@Monitor` | State-change listener (replaces V1 `@Watch`) |
+| `@Computed` | Derived/computed value |
+| `@ObservedV2` / `@Trace` | Observable class + observable property |
+| `@Type` | Mark a class-property type (for PersistenceV2) |
+
+Quick example (see `../official/mvvm-v2/` for the complete reference):
+
+```ets
+@ObservedV2
+class UserModel {
+  @Trace name: string = ''
+}
+
+@ComponentV2
+struct UserCard {
+  @Param user: UserModel = new UserModel()
+  @Event onDelete: () => void = () => {}
+
+  build() {
+    Column() {
+      Text(this.user.name)
+      Button($r('app.string.delete')).onClick(() => this.onDelete())
+    }
+  }
+}
+```
+
+## V1 family (cheat sheet)
+
+Full official docs: **`../official/mvvm-v1/`** (`@State`/`@Prop`/`@Link`/`@Provide`/`@Consume`/`@Observed`+`@ObjectLink`/`@Watch`/`@Track`, AppStorage/LocalStorage/PersistentStorage/Environment, `MVVM模式（V1）.md`). Use only when the project is already on V1.
+
+| Decorator | Purpose |
+|-----------|---------|
+| `@Component` | Marks a struct as a V1 component |
+| `@State` | Component-internal state |
+| `@Prop` | One-way input from parent (local copy) |
+| `@Link` | Two-way binding with parent (`$var`) |
+| `@Provide` / `@Consume` | Cross-level two-way sync |
+| `@Observed` / `@ObjectLink` | Observable class + nested-object binding |
+| `@Watch` | State-change listener |
+| `@Track` | Class property-level update granularity |
+
+Quick example (see `../official/mvvm-v1/` for the complete reference):
+
+```ets
+@Observed
+class UserModel {
+  name: string = ''
+}
+
+@Component
+struct UserCard {
+  @ObjectLink user: UserModel
+  onDelete: () => void = () => {}
+
+  build() {
+    Column() {
+      Text(this.user.name)
+      Button($r('app.string.delete')).onClick(() => this.onDelete())
+    }
+  }
+}
+```
+
+## MVVM layering (both families)
+
+```
+feature/
+  |-- model/      # data classes (V2: @ObservedV2/@Trace; V1: @Observed)
+  |-- viewmodel/  # business logic
+  |-- view/       # UI components (V2: @ComponentV2; V1: @Component)
+  |-- service/    # network / database / file I/O
+```
+
+- **View**: rendering only — no business logic in `build()`.
+- **ViewModel**: all business logic.
+- **Model**: pure data classes (observable per the chosen family).
+- **Service**: network requests, database, file I/O.
+
+## Async init vs synchronous reads (cold-start race)
+
+A fire-and-forget `async` initializer races a synchronous reader. Example: bootstrap calls `cache.refresh()` (async) **without** `await`, and a page's `aboutToAppear` reads the cache synchronously → on cold start the reader sees the empty pre-refresh state (blank page). Fix: keep a synchronous cache **and** expose a `whenReady(): Promise<void>` that resolves when `refresh()` completes; `await whenReady()` before relying on the data, and have a synchronous reader trigger one refresh if it read before ready. Never assume a non-awaited `async` init finished before the first read.
+
+## State written but never rendered
+
+State that is committed correctly but never reaches the screen. The write path passes review — the store holds the new value — and the screen keeps the old one. All four forms compile clean and pass codelinter; each fails on device as "value stored, screen never changes". Mechanical scan: `scripts/state_propagation_check.mjs` (L0 gate, check 3).
+
+**1. Value-passed `@Builder` parameter** (blocking). A `@Builder` receiving a primitive **by value** does not subscribe to the source state, so the builder body never re-renders.
+
+```ets
+// ✗ the row summary never updates, however correctly `choose()` persists the value
+@Builder row(title: string, summary: string, key: string) {
+  if (summary.length > 0) { Text(summary) }
+}
+this.row('Notebook', this.notebookLocation, 'pref_key__notebook_directory')
+
+// ✓ pass by reference
+this.row('Notebook', $$this.notebookLocation, 'pref_key__notebook_directory')
+// ✓ or read the state inside the builder, or split into @Component + @Prop/@Link
+```
+
+**2. keyGenerator omitting the rendered value** (suspect). `ForEach`'s third argument keyed only on index or a static id means an item is **not rebuilt** when the state it renders changes. Include the rendered value: `(item, i) => \`${item.id}_${item.value}\``.
+
+The state does **not** have to be read in the item body to count. It is routinely reached through a helper — `ForEach(this.library, (t) => { this.TagRow(t) }, (t) => t.id)`, where `TagRow` calls `isSelected()` which reads `this.selectedIds`. The key looks complete at the call site while the row still depends on changing state, so the scan follows `this.someMethod(...)` calls out of the item body and says "reached indirectly" when it found the state that way.
+
+This one stays **suspect, not blocking**, and the reason is worth knowing: the shape alone does not decide it. "Selection indicator keyed by id" appears verbatim on shipped code that scores 100% (a bottom-tab bar keyed by `tab.id` omitting `currentTab`; a swatch list keyed by `s.id` omitting `accent`) and on code that fails for exactly this reason (a checkmark row keyed by `${dayIndex}` omitting `todayValue`). What separates them is **how the value reaches the child**: passed in as a constructor argument to an `@Prop`, a reused node keeps the stale copy — that is the defect, and the fix is to hold it as `@State` in the child and update locally on the tap, or put it in the key. Read inline in the item body, it usually re-evaluates fine. Judge each finding on that, not on the key.
+
+**3. Framework callback overwriting a programmatic set** (blocking). Setting state next to a controller call while the matching `on*Change` writes the same member — the callback fires on the next frame and wins.
+
+```ets
+// ✗ caretOffset is reset to the document end before the next action reads it
+this.caretOffset = result.caret;
+this.editorController.caretPosition(result.caret);
+// …meanwhile:
+.onTextSelectionChange((start: number, end: number) => { this.caretOffset = end; })
+```
+
+Symptom shape worth memorizing: **the forward action passes and the inverse action fails** (apply bold ✓, un-bold ✗). Fix with a suppression flag around the programmatic write, or hold a semantic anchor (line index, item id) instead of a raw offset that drifts with text length.
+
+**4. Boolean control state gated only on an engine event** (suspect). `@State isPlaying` flipped solely by `player.on('stateChange', …)`: if the engine never reaches that state the control renders its initial value forever, and every test that must first drive this control dies at step 1. Keep a synchronous write path (optimistic update, roll back on failure) plus a timeout fallback state. A *data* field arriving from the engine (title, elapsed, list) is fine — a *control's* on/off state is not.
+
+**Rule of thumb.** For any preference / toggle / theme change, the assertion is the **rendered result**, not the stored value. If a change is only observable in the store, it is not implemented. Trace it end to end: state → token or derived value → the component that paints it.

package/skills/a2h-spec-implement/rules/arkts/ui/ui-quality.md

@@ -0,0 +1,67 @@
+# ArkUI UI Quality, Animation & Performance
+
+The checklist below runs before finalizing ArkUI UI changes (after the build passes — this is about whether the UI meets the requirement, not whether it compiles). Animation and performance practices follow at the end.
+
+## Requirement visibility
+
+- Required labels, button text, tab labels, card titles, and dialog text appear on the target screen.
+- Text is not hidden by overlays, zero-size containers, off-screen placement, or low contrast.
+- The first screen remains reachable from the app launch path.
+
+## Interaction
+
+- Required buttons use `Button` when the requirement asks for `Button`.
+- Click handlers update visible state, switch tabs, open dialogs, navigate, or show the requested response.
+- Cancel and close actions do not perform extra business actions.
+- Required click targets remain large enough and visually clear.
+
+## Layout quality
+
+- New UI follows nearby spacing, color, typography, density, and component style.
+- Layout nesting is only deep enough to express the UI.
+- Dynamic text, lists, and tab content have stable width/height constraints where needed.
+- New elements do not overlap existing banners, cards, bottom bars, or system safe areas.
+
+## State and rendering
+
+- UI-driving state uses the current component's decorator family.
+- Lists and grids render stable keys.
+- Conditional UI still leaves required content reachable.
+- Dialog, toast, and navigation code follows existing project patterns.
+- A preference / toggle / theme change is confirmed by its **rendered** difference, not by the stored value — a change observable only in the store is not implemented.
+- State reaching the screen is traced end to end: state → token or derived value → the component that paints it (see `state-management.md` § State written but never rendered).
+
+## Change scope
+
+- Only files required by the UI task are modified.
+- Existing business flow, page registration, resource naming, and navigation architecture are preserved.
+- No state-management migration, navigation rewrite, or broad refactor is introduced without an explicit request.
+
+## Animation practices
+
+- Drive animations with state variables (declarative), not imperative frame updates; use `animateTo` for explicit control.
+- Prefer `transform` (`translate` / `scale` / `rotate`) and `opacity` — they are cheap to animate.
+- **Never** animate `width` / `height` / `padding` / `margin` frequently — severe performance impact.
+- Set `renderGroup(true)` on complex sub-component animations to reduce render batches.
+- Prefer native HarmonyOS animation APIs and advanced templates.
+
+Example (state-driven):
+
+```ets
+@ComponentV2
+struct AnimatedCard {
+  @Local cardScale: number = 0.8
+  build() {
+    Column() { /* ... */ }
+      .scale({ x: this.cardScale, y: this.cardScale })
+      .animation({ duration: 300, curve: Curve.EaseInOut })
+      .onClick(() => { this.cardScale = this.cardScale === 1.0 ? 0.8 : 1.0 })
+  }
+}
+```
+
+## Performance practices
+
+- Large lists/grids use `LazyForEach` with a business-ID key generator (third arg, never the index) — verified form: `component-cookbook.md` § List, Grid, and ForEach.
+- Extract reusable UI into separate components; use `@Builder` for lightweight fragments.
+- Keep the component tree only as deep as the UI requires.

package/skills/a2h-spec-implement/rules/arkts/ui/ui-runtime-diagnosis.md

@@ -0,0 +1,32 @@
+# ArkUI Runtime UI Diagnosis (layout collapse & visual-diff attribution)
+
+Method for a **diagnosis round** on a UI-class failure (routed by the orchestrator when a failure signature enters its 2nd fix round): locate the culprit from runtime evidence, then fix once — never another blind rewrite. The two failure shapes below cover the measured field losses (7 rewrite rounds on one collapsed row; 2 rounds fixing gradient stops when the culprit was an overlying card).
+
+## Layout collapse (bounds collapse to 0 / children dropped)
+
+Symptom: an element renders blank or tiny; `observe --bound` shows its bound collapsed (or the child missing) while the code declares sizes.
+
+1. **Find the deciding boundary, bottom-up**: `observe --bound --raw` the subtree; walk up from the collapsed node to the first ancestor whose bound is sane. The collapse is decided at that parent↔child boundary — everything below it is downstream.
+2. **Read that boundary's constraint context**, not the collapsed node's own modifiers: a content-sized parent measured against a full-height sibling, `alignContent`/`offset`/`translate`/animation composites, `.clip` — the measure input is what shrank, the child merely obeyed.
+3. **Bisect in place**: toggle the boundary's suspects one at a time (drop the sibling, remove one modifier), rebuild the minimal pair, re-observe. One boundary, one variable per build — never a whole-page rewrite per round.
+
+Measured traps (extend as confirmed):
+
+- A full-height sibling inside `Stack({alignContent: Bottom})` composed with offset/margin collapses a content-sized sibling Row to its text height, silently dropping the Image (measured: 7 blind rounds; the row measured 14px).
+- `bindContentCover` shows a full-screen cover that intercepts touch: the host's `PanGesture` never receives events while the visuals look correct — a gesture defect invisible to source-level checks (measured: shipped dead press-drag).
+- A multiplicative opacity/color matrix keeps hue: a white icon ×0.6 over a white backdrop stays white — the spec clause is math-unreachable, fix the spec or the asset, not the matrix (measured).
+- `.scale` `centerY` must be a string percentage (`'100%'`); a number is vp, so a bottom-anchored scale pivots off-anchor (measured on a bottom-anchored card deck).
+
+## Visual-diff layer attribution (which layer paints the offending pixels)
+
+Symptom: captured page differs from the draft in a region; the tempting fix ("the property that looks closest") is usually the wrong layer.
+
+1. **List the z-stack over the diff region**: from `observe --bound` (+`--raw` when overlays hide layers), every element whose bound covers the region, ordered by z (tree order / `zIndex`).
+2. **Attribute by paint, top-down**: compare what the region actually renders (a screenshot region inspected by eye, or the element's resolved style read back from the component tree) against each layer's declared paint (bg color / gradient slice / image). The first layer whose declared paint matches the offending output is the culprit.
+3. **Confirm by minimal toggle**: change only the suspect (hide it, or adjust only its paint), re-capture — the diff must move with it before any real fix lands.
+
+Measured: a "gradient shows a hard cut" diff was fixed as gradient stops for 2 rounds with identical symptoms; the culprit was an opaque white rounded-card Rect covering the gradient — step 1's layer list names it immediately.
+
+## Deliverable of a diagnosis round
+
+Culprit boundary/layer + the minimal repro pair + evidence (targeted observe bounds, probe outputs, hilog at the failure moment) + a one-fix plan. No code delivery in the diagnosis round; the following fix round cites this evidence.

package/skills/a2h-spec-implement/rules/pipeline/build/package-set-collection.md

@@ -0,0 +1,43 @@
+# Package-set collection (entry HAP + in-app HSPs)
+
+Canonical shared procedure for harvesting the **full package set** — the entry HAP plus any in-app HSPs (and any feature HAP the build freshly produced) — so the installer applies them in one transaction (in-app HSPs cannot install standalone). Referenced by whichever stage performs the build — keep the rule here, not duplicated per stage.
+
+**Signing mode follows the project, not this procedure.** A project whose product references a `signingConfig` emits `*-signed.*`; one with `app.signingConfigs: []` emits `*-unsigned.*` and cannot be made to emit anything else without changing the project. Both are collected. Refusing the unsigned variant does not produce a signed package — it produces **no package set at all**, which silently disables every device layer downstream (L1 unit, L2 E2E, integration) and reports the cause as a missing artifact rather than as missing signing config.
+
+Two rules keep this safe:
+
+- **Signed wins within a directory.** When a module output dir holds both variants, take the signed one. Never prefer an unsigned package over a signed one — the unsigned file may be an older leftover.
+- **The set is uniform.** Every package in `DEST` must share one signing mode. A mixed set fails the single install transaction, so a mix is a collection failure (step 5), not a warning.
+
+Whether an unsigned package can actually be installed depends on the device and its developer-mode settings. Collection succeeds regardless; the installer reports the real outcome. Record the mode so a later install failure is read as "unsigned package rejected by device", not as a code defect.
+
+**Freshness gate.** The builder runs the pinned `devecocli build --build-mode <mode>` (default product = the `entry` module plus whatever hvigor transitively rebuilds on entry's dependency path), and copies only the entry HAP. Non-entry module output dirs keep whatever a *prior* build left, so a blind glob would pick up **stale** packages and install stale code. The mtime gate below is the only reliable discriminator.
+
+## Inputs
+
+- `BUILD_ROOT` — the project root the build compiled (= `harmonyos-project-path`).
+- `DEST` — a dedicated `package-set/` directory to populate; **must never be the directory the builder copied the entry HAP into** (step 1 clears `DEST`).
+- `BUILD_START` — a **transient** freshness marker captured **immediately before** the first build: an empty file in the system temp dir, **not** a round artifact under `build/`. Create it with whatever the session shell supports (the shell is PowerShell on Windows, so do not rely on `mktemp`). Used to tell freshly-rebuilt artifacts from stale ones. A touched marker + a newer-than comparison avoids clock-skew between the agent and the build host.
+- `AUTHORITATIVE_ENTRY` — the entry HAP the builder **copied** to the caller's output dir (the `*-signed.hap` or `*-unsigned.hap` it placed — list `entry/build/default/outputs/default/` to get the filename actually produced; do not infer it from a signing flag). Authoritative **by construction**, regardless of mtime.
+- `SIGNING_MODE` — derived from `AUTHORITATIVE_ENTRY`'s basename: `signed` for `*-signed.hap`, `unsigned` for `*-unsigned.hap`. It fixes the mode the rest of the set must match.
+
+## 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 the builder 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; the builder'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):
+   - **HSPs:** `*-<SIGNING_MODE>.hsp` (the fresh in-app HSPs).
+   - **Feature HAPs:** `*-<SIGNING_MODE>.hap` from non-entry modules the build freshly rebuilt; skip any whose basename equals `AUTHORITATIVE_ENTRY`'s.
+
+   Within one module output dir, a fresh `*-signed.*` always beats a fresh `*-unsigned.*` of the same module. If that contradicts `SIGNING_MODE` (a signed module package alongside an unsigned entry, or the reverse), it is a mixed set — see step 5.
+4. **Exclude test artifacts:** skip `*ohosTest*` and `*-test-signed.*` / `*-test-unsigned.*`.
+5. **Uniform-mode rule (all-or-nothing):** if any module dir has a **freshly-rebuilt** `.hsp`/`.hap` whose signing mode differs from `SIGNING_MODE`, or has a fresh package in neither mode's naming form, mark the collection **incomplete** → the caller falls back to the entry-only set and logs the mismatch as a build-config gap. (A *stale* package is ignored — it never passes the mtime gate.) Rationale: packages install in one transaction, so one package the device rejects fails the whole install; 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 installer 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 hsp(s), mode=<SIGNING_MODE> → DEST` (and `WARNING: K package(s) skipped — signing-mode mismatch, build-config gap` if any). When `SIGNING_MODE=unsigned`, add `NOTE: unsigned package set — install depends on device developer mode; an install rejection here is an environment result, not a code defect`.
+8. **Result:** `DEST` is the package set the caller installs from.
+
+> **Build-completeness constraint (HSP projects).** Whether a default `devecocli build` emits an `.hsp` at all, and *freshly*, depends on hvigor's transitive-build behavior — on the first run against an HSP project, confirm by capturing a temp marker, running a build (`build_project` — it emits signed artifacts whenever the project is configured for signing, unsigned ones otherwise), then listing artifacts newer than that marker under `*/build/default/outputs/default/` (`*.hsp` / `*.hap`). If nothing fresh is emitted, this procedure collects **entry-only** (safe — equivalent to a single-HAP install). Independent feature modules (not on entry's dependency path) are never rebuilt by the entry-targeted build; collecting their HAPs needs a build change (out of scope).

package/skills/a2h-spec-implement/scripts/_lib/common.mjs

@@ -0,0 +1,97 @@
+// Shared helpers for scripts (not an entry point).
+// Contents: emit single-line JSON output contract, the jsonl ledger trio, cross-process append lock.
+import fs from "node:fs";
+
+export function emit(obj) {
+  // Compact single-line JSON to stdout (script-to-agent output contract). Node defaults to UTF-8, no reconfigure needed.
+  process.stdout.write(JSON.stringify(obj) + "\n");
+}
+
+export function loadJsonl(pathStr) {
+  // Read jsonl as an ordered entry list (bad lines skipped; one dirty line must not kill the whole query).
+  if (!fs.existsSync(pathStr)) return [];
+  const out = [];
+  for (const raw of fs.readFileSync(pathStr, "utf8").split(/\r?\n/)) {
+    const line = raw.trim();
+    if (!line) continue;
+    try { out.push(JSON.parse(line)); } catch { /* skip bad line */ }
+  }
+  return out;
+}
+
+export function latestBy(entries, key) {
+  // Key value → latest entry (append-only ledger convention: last write wins on read). Entries missing the key are ignored.
+  const by = {};
+  for (const e of entries) { const k = e[key]; if (k) by[k] = e; }
+  return by;
+}
+
+export async function lockedAppend(pathStr, fn) {
+  // Cross-process mutually exclusive append. Under multi-device parallelism several writers append the same jsonl; unlocked writes can interleave and tear lines.
+  // Lock = sidecar `<file>.lock` created exclusively with O_EXCL (cross-platform, dep-free), spin-wait, 30s timeout.
+  const lockPath = pathStr + ".lock";
+  const deadline = Date.now() + 30000;
+  let fd = null;
+  for (;;) {
+    try { fd = fs.openSync(lockPath, "wx"); break; } // wx = O_CREAT|O_EXCL, throws if it already exists
+    catch (e) {
+      if (e.code !== "EEXIST") throw e;
+      // Stale-lock reclaim: a lock is held for ms — one older than 10s is a dead holder
+      // (killed process); remove it and retry (an unlink race with a live holder is benign:
+      // both writers still serialize on the fresh lock).
+      try {
+        if (Date.now() - fs.statSync(lockPath).mtimeMs > 10000) { fs.unlinkSync(lockPath); continue; }
+      } catch { /* lock vanished between stat/unlink — retry acquires normally */ }
+      if (Date.now() > deadline) throw new Error(`acquire ${lockPath} timed out (30s); stale locks self-reclaim after 10s — a live writer is holding it`);
+      await new Promise((r) => setTimeout(r, 50));
+    }
+  }
+  try {
+    return await fn((line) => fs.appendFileSync(pathStr, line, "utf8"));
+  } finally {
+    try { fs.closeSync(fd); } catch { /* ignore */ }
+    try { fs.unlinkSync(lockPath); } catch { /* ignore */ }
+  }
+}
+
+export function defaultDie(msg) {
+  // `<script>: error: <msg>` to stderr, exit 2 (shared CLI arg-parse failure path). Prog name = argv[1] basename.
+  const prog = (process.argv[1] || "script").split(/[/\\]/).pop();
+  process.stderr.write(`${prog}: error: ${msg}\n`);
+  process.exit(2);
+}
+
+export function parseFlags(argv, spec, die = defaultDie) {
+  // Parse `--flag value` / `--flag=value` into { specValue: value }. `spec` maps the written flag
+  // (dashed, no `--`) → its output key; an unrecognized flag or a missing value calls `die` (fail-fast).
+  const out = {};
+  for (let i = 0; i < argv.length; i++) {
+    let tok = argv[i];
+    if (!tok.startsWith("--")) die(`unexpected argument: ${tok}`);
+    let val;
+    const eq = tok.indexOf("=");
+    if (eq !== -1) { val = tok.slice(eq + 1); tok = tok.slice(0, eq); }
+    const name = tok.slice(2);
+    if (!(name in spec)) die(`unrecognized argument: --${name}`);
+    if (val === undefined) {
+      // next token missing, or itself a flag (else `--a --b` silently swallows --b as --a's value) → fail-fast
+      if (i + 1 >= argv.length || argv[i + 1].startsWith("--")) die(`argument --${name}: expected one argument`);
+      val = argv[++i];
+    }
+    out[spec[name]] = val;
+  }
+  return out;
+}
+
+export function requireFlags(vals, names, die = defaultDie) {
+  // Enforce required flags. `names` = [{ key, flag }] (key = output key, flag = written flag for the message).
+  for (const n of names) {
+    if (vals[n.key] === undefined) die(`the following arguments are required: --${n.flag}`);
+  }
+}
+
+// HarmonyOS system-UI denylist for view-tree capture: skip these node TYPES / system-app BUNDLES
+// (drop the node itself, keep walking its subtree). Single source consumed by device_ui_core.collectElements —
+// turns a raw dumpLayout tree into a clean app-only tree, stripping OS scaffolding + other-app surfaces.
+export const HMOS_SKIP_TYPES = new Set(["WindowScene", "__Common__", "EffectComponent", "metaballNode", "RootScene"]);
+export const HMOS_SKIP_BUNDLES = new Set(["com.huawei.systemui", "com.ohos.systemui", "com.huawei.android.launcher"]);

package/skills/a2h-spec-implement/scripts/_lib/config.mjs

@@ -0,0 +1,70 @@
+// Shared config reader for scripts (conf.yaml is its sole responsibility).
+// Single source of truth = repo-root conf.yaml (copied from conf.example.yaml). Locate the repo root
+// upward from this file, parse flat YAML, fall back to same-named OS env vars. On empty values the caller prompts the user.
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+
+export function repoRoot() {
+  // Walk up from this file to the directory containing conf.yaml or conf.example.yaml
+  for (let d = HERE; ; ) {
+    if (fs.existsSync(path.join(d, "conf.yaml")) || fs.existsSync(path.join(d, "conf.example.yaml"))) return d;
+    const up = path.dirname(d);
+    if (up === d) return null;
+    d = up;
+  }
+}
+
+export function parseFlatYaml(text) {
+  // Parse only flat `KEY: value` lines (this config has no nesting/lists). Comments and blank lines ignored.
+  const out = {};
+  for (const raw of text.split(/\r?\n/)) {
+    const line = raw.trim();
+    if (!line || line.startsWith("#") || !line.includes(":")) continue;
+    const i = line.indexOf(":");
+    const key = line.slice(0, i).trim();
+    let val = line.slice(i + 1).trim();
+    if (val.startsWith("'") || val.startsWith('"')) {
+      const q = val[0], end = val.indexOf(q, 1);
+      val = end !== -1 ? val.slice(1, end) : val.slice(1);
+    } else {
+      val = val.split("#", 1)[0].trim();
+    }
+    if (key) out[key] = val;
+  }
+  return out;
+}
+
+let _cache = null;
+let _warned = false;
+function load() {
+  if (_cache !== null) return _cache;
+  _cache = {};
+  const root = repoRoot();
+  const p = root && path.join(root, "conf.yaml");
+  try {
+    if (p && fs.existsSync(p)) _cache = parseFlatYaml(fs.readFileSync(p, "utf8"));
+  } catch (e) {
+    if (!_warned) { _warned = true; process.stderr.write(`警告: 读取 ${p} 失败(${e.message})——按空配置继续\n`); }
+  }
+  return _cache;
+}
+
+export function getKey(name, dflt = "") {
+  // conf.yaml → OS env var → default
+  return (load()[name] || "").trim() || (process.env[name] || "").trim() || dflt;
+}
+
+export function requireKey(name, purpose = "") {
+  // Fetch a required key; if empty, print a lazy hint and exit non-zero
+  const val = getKey(name, "");
+  if (!val) {
+    const hint = purpose ? `(${purpose})` : "";
+    const where = (repoRoot() && path.join(repoRoot(), "conf.yaml")) || "<repo>/conf.yaml(由 conf.example.yaml 复制)";
+    process.stderr.write(`错误: 配置项 ${name} 为空${hint}。请在 ${where} 填写后重试(或设置同名环境变量 ${name})。\n`);
+    process.exit(2);
+  }
+  return val;
+}

package/skills/a2h-spec-implement/scripts/_lib/lessons_cli.mjs

@@ -0,0 +1,48 @@
+// Generic keyed-lessons ledger CLI skeleton (not an entry point) — shared by build_lessons.mjs
+// and code_pattern_lessons.mjs, whose command surfaces are identical up to the key field and
+// field sets: append (validated fields, locked) / match (exact-key list, latest per key) / list.
+import fs from "node:fs";
+import path from "node:path";
+
+import { emit, loadJsonl, latestBy, lockedAppend, parseFlags, requireFlags, defaultDie as die } from "./common.mjs";
+
+// cfg: { key: ledger key field, matchFlag: match's list flag name,
+//        required: [[flag, field], …], optional: [[flag, field], …] }
+export async function runLessonsCli(argv, cfg) {
+  const cmd = argv[0];
+  const rest = argv.slice(1);
+  if (cmd === "append") await cmdAppend(rest, cfg);
+  else if (cmd === "match") cmdMatch(rest, cfg);
+  else if (cmd === "list") cmdList(rest, cfg);
+  else if (cmd === undefined) die("the following arguments are required: cmd");
+  else die(`argument cmd: invalid choice: '${cmd}' (choose from 'append', 'match', 'list')`);
+}
+
+const specOf = (pairs) => Object.fromEntries(pairs);
+
+async function cmdAppend(argv, cfg) {
+  const v = parseFlags(argv, { ledger: "ledger", ...specOf(cfg.required), ...specOf(cfg.optional) });
+  requireFlags(v, [{ key: "ledger", flag: "ledger" }, ...cfg.required.map(([flag, key]) => ({ key, flag }))]);
+  fs.mkdirSync(path.dirname(path.resolve(v.ledger)), { recursive: true });
+  const entry = {};
+  for (const [, key] of cfg.required) entry[key] = v[key];
+  for (const [, key] of cfg.optional) if (v[key]) entry[key] = v[key];
+  await lockedAppend(v.ledger, (append) => { append(JSON.stringify(entry) + "\n"); });
+  emit({ ok: true, appended: entry });
+}
+
+function cmdMatch(argv, cfg) {
+  const v = parseFlags(argv, { ledger: "ledger", [cfg.matchFlag]: "wants" });
+  requireFlags(v, [{ key: "ledger", flag: "ledger" }, { key: "wants", flag: cfg.matchFlag }]);
+  const byKey = latestBy(loadJsonl(v.ledger), cfg.key);
+  const want = v.wants.split(",").map((s) => s.trim()).filter((s) => s);
+  const hits = want.filter((s) => s in byKey).map((s) => byKey[s]);
+  emit({ matched: hits, count: hits.length });
+}
+
+function cmdList(argv, cfg) {
+  const v = parseFlags(argv, { ledger: "ledger" });
+  requireFlags(v, [{ key: "ledger", flag: "ledger" }]);
+  const lessons = Object.values(latestBy(loadJsonl(v.ledger), cfg.key));
+  emit({ lessons, count: lessons.length });
+}

package/skills/a2h-spec-implement/scripts/build_lessons.mjs

@@ -0,0 +1,24 @@
+// build-fix lessons ledger — build error → fix, reused across features, append-only jsonl.
+//
+// Ledger = <output-dir>/memory/build-lessons.jsonl, one line = root cause + fix for one class of build error, keyed by error_sig.
+// Before fixing, `match` known fixes and apply them first (build capability is inlined; whoever builds uses it); only after the
+// build **truly turns green**, `append` one entry per previously unseen error_sig (unverified guesses do not enter). Run `node build_lessons.mjs <cmd>`.
+//
+// error_sig = compiler error code + normalized message (strip file paths/line numbers/concrete identifiers, keep error class and symbol kind);
+// same error_sig = same class of error. Multiple entries per sig: the **latest** wins (append-only, last write wins on read).
+//
+// Commands:
+//     append --ledger P --error-sig SIG --root-cause C --fix F [--scope S] [--symptom Y] [--head H]
+//                 Append one build lesson.
+//     match  --ledger P --errors SIG1,SIG2,…
+//                 Return lessons hit by exact error_sig match, latest entry per sig.
+//     list   --ledger P
+//                 Emit all lessons (latest per error_sig).
+import { runLessonsCli } from "./_lib/lessons_cli.mjs";
+
+runLessonsCli(process.argv.slice(2), {
+  key: "error_sig",
+  matchFlag: "errors",
+  required: [["error-sig", "error_sig"], ["root-cause", "root_cause"], ["fix", "fix"]],
+  optional: [["scope", "scope"], ["symptom", "symptom"], ["head", "head"]],
+});

package/skills/a2h-spec-implement/scripts/code_pattern_lessons.mjs

@@ -0,0 +1,26 @@
+// code-pattern lessons ledger —— runtime pitfalls that compile clean but crash on-device / read empty,
+// distilled into avoidance rules, reused across features, append-only jsonl.
+//
+// Ledger = <output-dir>/memory/code-pattern-lessons.jsonl, one line = one class of code-pattern pitfall,
+// keyed by pattern (stable tag). logic-code reads the whole ledger as prior before coding (ledger is small,
+// relevance judged by the model); on a new on-device failure localized to a fresh pitfall, **after on-device
+// confirmation** append one entry (unverified guesses do not enter). Pure stdlib, run `node code_pattern_lessons.mjs <cmd>`.
+//
+// vs build-lessons: build-lessons records **compile-error→fix**, matched precisely by error_sig; this ledger
+// records **compiles-but-runtime** pitfalls, read whole by logic-code as prior. Generic ArkTS pitfalls belong
+// in rules/arkts/ (coding authority); this ledger only collects **project-learned** patterns.
+//
+// Fields: pattern (stable tag, same name keeps latest) / symptom / root_cause / rule / example (optional) / head (optional, calibrated git short hash).
+//
+// Commands:
+//   append --ledger P --pattern TAG --symptom Y --root-cause C --rule R [--example E] [--head H]
+//   list   --ledger P
+//   match  --ledger P --patterns TAG1,TAG2,…
+import { runLessonsCli } from "./_lib/lessons_cli.mjs";
+
+runLessonsCli(process.argv.slice(2), {
+  key: "pattern",
+  matchFlag: "patterns",
+  required: [["pattern", "pattern"], ["symptom", "symptom"], ["root-cause", "root_cause"], ["rule", "rule"]],
+  optional: [["example", "example"], ["head", "head"]],
+});