android2harmony 0.1.6 → 0.1.8

package/skills/a2h-spec-implement/rules/arkts/arkts-standards.md

@@ -0,0 +1,184 @@
+---
+paths:
+  - "**/*.ets"
+  - "**/*.ts"
+---
+# ArkTS Grammar Standards
+
+> The ArkTS/ArkUI **authoring authority** for this repo — everything here constrains *the code you write*; anything constraining *what the pipeline does* lives in `rules/pipeline/` instead. This file is the overview + scenario router; each detail lives in exactly one sibling:
+> - **`language/`** — what compiles: `arkts-rules.md`, `arkui-structure-rules.md`, `ts-to-arkts-rewrites.md`
+> - **`ui/`** — building the UI: `component-cookbook.md`, `state-management.md`, `ui-quality.md`, `ui-runtime-diagnosis.md`
+> - **`conventions/`** — cross-cutting code conventions: `coding-style.md`, `security.md`
+> - **`official/`** — verbatim official-doc copies (read-only, never authored): `mvvm-v1/`, `mvvm-v2/`
+>
+> Read on demand via the routing table below.
+
+Review the core hard constraints below before writing `.ets` code; for specific errors, component APIs, or migration questions, use the scenario routing table to find the right reference.
+
+- Target version: **ArkTSLinter 1.1**
+- Verified SDK: OpenHarmony **API 23** (6.1.0.105) — `ui/component-cookbook.md` shapes are checked against this; for an older project target, confirm availability in the SDK `.d.ts`
+- Language rules are anchored to official rule tags (`arkts-*`), matching compiler/linter error messages one-to-one
+
+## API signature lookup (uncertain API / component / kit)
+
+Signature truth = the **local SDK interface files** — consult them before guessing; the cookbook stays first for the ArkUI shapes it covers:
+
+1. Resolve the SDK root once per run: `Grep` pattern `^DEVECO` on `<plugin-path>/conf.yaml` (content mode — the only sanctioned conf.yaml access; it holds secrets) → root = `DEVECO_SDK_HOME`, else `<DEVECO_PATH>/sdk`.
+2. `Grep` the symbol (e.g. `interface AVPlayer`, `linearGradient`) with an explicit `path` under `<root>/default/openharmony/ets/api|component|kits` (glob `*.d.ts`; HMS kits: `<root>/default/hms/ets`), then `Read` the hit **bounded** (offset ≈ hit − 30, limit ≈ 100) — the declaration + its JSDoc (params, `@since`) is the answer; never read a `.d.ts` whole (`component/common.d.ts` = 33k lines, measured).
+3. Usage/concept docs (not signatures): `devecocli docs search "<keyword>" --catalog harmonyos-guides --format json` → `devecocli docs read "<documentId>"` (offline full text; hits both English API names and Chinese concept terms — measured).
+
+This file remains the coding authority over both sources.
+
+## Avoid over-restriction first (common pitfalls)
+
+The most frequently mis-banned constructs — these are **legal** in ArkTS, do not avoid them out of TypeScript instinct:
+
+- Template literals `` `${value}` `` — fully supported, idiomatic in ArkUI
+- `value as T` — `as` is the ONLY supported assertion syntax (what's banned is `<T>value`)
+- `Record<K, V>` and its indexed access — the officially recommended replacement for index signatures
+
+Full whitelist (single source of truth): [`language/arkts-rules.md` § Explicitly allowed constructs](language/arkts-rules.md#explicitly-allowed-constructs).
+
+## Core hard constraints
+
+All rules below are ERROR severity (compile/linter failures) unless marked WARNING. Each entry is a one-line conclusion + rule tag — the tag is the anchor: search it in [`language/arkts-rules.md`](language/arkts-rules.md) for the full good/bad examples. Detail is not restated here.
+
+### Types
+- No `any` / `unknown`; use explicit types; when truly undetermined, use `Object` or a union type (`arkts-no-any-unknown`)
+- No structural typing: type compatibility requires explicit `extends`/`implements` (`arkts-no-structural-typing`)
+- Object literals need a type context in EVERY position — declaration, call argument, callback return — `const o: MyIface = {...}` or `Record`; an outer type does not propagate inward (`arkts-no-untyped-obj-literals`)
+- `Record`-typed literals additionally require quoted keys (`{ 'k': v }`, not `{ k: v }`) — same `arkts-no-untyped-obj-literals` error otherwise
+- An object literal assigned to a class type must list every field; class-body defaults do not make them optional — for seed data prefer a static factory (`arkts-no-untyped-obj-literals`; cookbook § Creating instances with data)
+- No inline object types `type T = {...}` / `f(p: {x: number})`; use a named `interface` (`arkts-no-obj-literals-as-types`)
+- No intersection types `A & B`; use interface inheritance (`arkts-no-intersection-types`)
+- No index signatures `[key: string]: T`; use `Record<K,V>` (`arkts-no-indexed-signatures`)
+- Utility types: only `Partial`/`Required`/`Readonly`/`Record` are supported (`arkts-no-utility-types`)
+- Generic call and function return type inference are limited; annotate explicitly (`arkts-no-inferred-generic-params`, `arkts-no-implicit-return-types`)
+
+### Null safety (strict-mode checks; no `arkts-*` tag, but the single largest source of check errors)
+- Any value that can be `undefined` — optional fields (`x?: T`), `Map.get(...)`, `Record` indexed access, `arr[i]`, optional callback params — must be narrowed before use: `?.`, `?? fallback`, or an explicit `if (x !== undefined)` check
+- `T | undefined` cannot be assigned to `T`; supply a fallback (`this.count = map.get(k) ?? 0`) instead of assigning directly
+- Declare component state that starts empty as `T | undefined` (or with a real initial value) — do not fake it with non-null assertions
+- Prefer `undefined` over `null`; convert external `null` with `?? undefined` (project convention)
+- Error messages this prevents: `Object is possibly 'undefined'.`, `Type 'X | undefined' is not assignable to type 'X'.`
+
+### Functions and classes
+- No function expressions `function(){}` as values; use arrow functions (`arkts-no-func-expressions`)
+- No nested function declarations; use arrow-function values inside functions, or promote to class methods (`arkts-no-nested-funcs`)
+- No `this` in standalone functions — and `static` methods count (reference statics via the class name); only instance methods may use `this` (`arkts-no-standalone-this`)
+- No constructor parameter properties `constructor(public x: number)`; declare fields in the class body (`arkts-no-ctor-prop-decls`)
+- No `#` private fields; use `private` (`arkts-no-private-identifiers`)
+- `implements` only accepts interfaces; interfaces cannot extend classes (`arkts-implements-only-iface`, `arkts-extends-only-class`)
+- No generators/`yield`, class expressions, or `Function.bind` (`arkts-no-generators`, `arkts-no-class-literals`, `arkts-no-func-bind`)
+
+### Statements and expressions
+- No destructuring of any kind: declarations, assignments, parameters (`arkts-no-destruct-decls/-assignment/-params`)
+- No `delete`, `in`, `for...in`, `with` (`arkts-no-delete`, `arkts-no-in`, `arkts-no-for-in`)
+- No indexed access `obj['k']` on non-Record objects; use dot access (`arkts-no-props-by-index`)
+- `throw` only accepts `Error` and subclasses; `catch (e)` cannot carry a type annotation (`arkts-limited-throw`, `arkts-no-types-in-catch`)
+- System API error callbacks (`windowStage.loadContent`, file/media/network kits) pass a `BusinessError`, not `Error` — `Error` has no `.code`. Type the param as `BusinessError` and import it: `import { BusinessError } from '@kit.BasicServicesKit'`; in `catch (e)` blocks, cast: `(e as BusinessError).code`
+- No `is` type guards; use `instanceof` + `as` (`arkts-no-is`)
+- Object spread is restricted (array spread is allowed) (`arkts-no-spread`)
+- No regex literals `/x/`; use `new RegExp()` (`arkts-no-regexp-literals`)
+- No `@ts-ignore` or other comment-based check suppression (`arkts-strict-typing-required`)
+
+### Standard library and modules
+- `eval`, `Object.assign/create/freeze/defineProperty`, `hasOwnProperty`, `Reflect`/`Proxy` metaprogramming, `Symbol()` (except `Symbol.iterator`), and `globalThis` are all banned (`arkts-limited-stdlib`, `arkts-no-globalthis`)
+- No `import type`, side-effect-only imports, `require`, or `export =`; `import` must precede all other statements (see [`language/arkts-rules.md` § 7. Module imports and exports](language/arkts-rules.md#7-module-imports-and-exports))
+- Namespaces cannot be passed as values, but calling their exported members directly is allowed (`arkts-no-ns-as-obj`)
+
+### ArkUI structure (build-stage failures; full rules in [`language/arkui-structure-rules.md`](language/arkui-structure-rules.md))
+- `@Component` + `struct` + a mandatory `build()`; `build()` (and `@Entry` pages especially) has **exactly one root node**, which must be a container component
+- Inside `build()` / `@Builder` bodies, only UI component syntax is allowed: component calls, `if/else`, `ForEach`/`LazyForEach` — no statements, local variables, or expressions
+- The inverse also holds: component syntax parses ONLY inside `build()`/`@Builder` — a plain closure passed to an ordinary method cannot contain `Row() {...}`; a reusable section is a `@Builder` method passed into a `@BuilderParam` (parse-error cascade + fix shape: [`language/arkui-structure-rules.md` § 6](language/arkui-structure-rules.md))
+- Struct member area holds only field declarations and methods; a stray brace or statement there cascades into `does not meet UI component syntax` errors
+- One decorator family per project, never mix V1/V2 (policy + correspondences: `ui/state-management.md`; struct-level mixing is also a build error: `language/arkui-structure-rules.md` § 5); pass `@Link` values from the parent with `$var`
+- Naming discipline — three collision classes, each observed repeatedly in production:
+  - **Member vs universal attribute**: no struct member named after a universal attribute/method (`opacity`, `scale`, `rotate`, `blur`, `translate`, `tabIndex`, …) — use a domain-specific name (`circleOpacity`, `currentTab`)
+  - **Struct vs import**: a struct name must not equal anything the same file imports — alias the import or name the page `XxxPage` (`arkts-unique-names`; full example: [`language/arkts-rules.md` § Rules 4/103](language/arkts-rules.md))
+  - **One declaration per type**: a type shared by multiple files lives in ONE model file, imported everywhere (`arkts-no-decl-merging`; full example: same § Rules 4/103, cookbook § Router params)
+- Only ArkUI decorators are allowed; custom decorators are flagged (`arkts-no-decorators-except-arkui`, WARNING severity — still fix it; full list in [`language/arkts-rules.md` § 9](language/arkts-rules.md#9-decorators-and-arkui-rule-148-arkts-no-decorators-except-arkui))
+- Before calling component constructors, modifiers, enums (e.g. `GradientDirection`, `BarPosition`), or callbacks you are not 100% sure of, check [`ui/component-cookbook.md`](ui/component-cookbook.md) — do not guess signatures or enum members
+- Global UI APIs (`router.pushUrl`, `promptAction.showToast`, `AlertDialog.show`, `animateTo`, `vp2px`) called bare are deprecated (WARNING) — call them through `this.getUIContext()` (`.getRouter()`, `.getPromptAction()`, `.showAlertDialog()`, `.animateTo()`, `.vp2px()`); same for `CustomDialogController` → `promptAction.openCustomDialog`
+- Every page listed in `main_pages.json` must contain exactly one `@Entry`-decorated struct — a missing `@Entry` fails the build with `10905402: A page configured in main_pages.json must have one and only one '@Entry' decorator`; conversely, embedded child components must NOT be listed in `main_pages.json`
+- `module.json5` `requestPermissions`: every `user_grant` permission (microphone, camera, location, …) requires BOTH `reason` (a `$string:` resource that must exist) and `usedScene` — omitting them fails the build with `00303218 Configuration Error: The reason and usedScene attributes are mandatory for user_grant permissions`
+
+### Concurrency
+- `@Sendable` classes have their own restriction set (explicit field types, sendable field types, no literal initialization, etc. — see [`language/arkts-rules.md` § 10. Sendable concurrency restrictions](language/arkts-rules.md#10-sendable-concurrency-restrictions))
+
+## Write workflow (self-consistency)
+
+`Cannot find name 'X'` is the single most frequent check error — it comes from referencing types/constants before creating them, not from ArkTS rules. When generating multi-file code:
+
+1. **Read [`ui/component-cookbook.md`](ui/component-cookbook.md) BEFORE writing the first page** — not after a check failure. Sessions that read it pre-write produce zero guessed-API errors; sessions that skip it guess enum members and constructor signatures wrong (e.g. `GradientDirection.BottomRight` does not exist), and one wrong guess copy-pasted across pages multiplies into many errors.
+2. Create shared model/constant/enum files FIRST, then the pages that import them
+3. Before referencing a type, enum member, or helper from another file, confirm it is actually declared and exported there (re-read or grep the file if it was generated earlier in the session)
+4. **Review per file, not per batch**: immediately after writing each `.ets` file, run the Per-file gate below and fix violations before starting the next file (observed: one unreviewed mistake copied into 3 pages = 9 errors and 3 fix rounds, vs 1 edit caught per-file). All violations must be fixed BEFORE building.
+
+## Write-time triggers (apply at the keystroke, not in review)
+
+Knowing these rules is not enough — they are most often violated mid-generation while attention is on business logic. Bind each trigger to its action the moment the trigger appears in the code you are emitting:
+
+| The moment you write... | ...do this before continuing |
+|---|---|
+| `{` starting an object literal — anywhere: variable init, **function/constructor argument** (router params, options objects), **callback return** | Stop. Name its type: `const x: MyIface = {...}` or declare the interface first. An outer declared type does NOT propagate into nested literals. If the type is `Record`, quote every key; if it is a class, list every field. |
+| `?:` in a class/interface field, or a read of `Map.get(...)`, `arr[i]`, `Record` access, optional param | Stop. Either give the field a real initial value (preferred — see cookbook § Data model template), or narrow at this read: `?.` / `?? fallback` / `if (x !== undefined)`. |
+| A modifier, enum member, constructor, `$r('sys.…')` resource name, or params-passing call you have not personally verified in the cookbook this session | Stop. Look it up. Copy the cookbook shape verbatim; do not improvise (§ Router params, § Enum members, § System resource names). |
+| A `@Builder` parameter typed `: string` / `: number` / `: boolean`, where the call site passes `this.<stateMember>` | Stop. A by-value `@Builder` parameter does **not** subscribe — the builder body never re-renders and the screen keeps the old value while the store holds the new one. Pass `$$this.x`, read `this.x` inside the builder, or split the fragment into `@Component` + `@Prop`/`@Link`. |
+| A `ForEach` / `LazyForEach` keyGenerator (3rd arg) | Stop. The key must include **the state value the item renders**, not just the index or a static id — otherwise a change to that value does not rebuild the item. |
+| `<x>Controller.<setter>()` (`caretPosition`, `scrollTo`, …) in a component whose `on<X>Change` writes the same state member | Stop. The callback fires after you and overwrites what you just set. Guard with a suppression flag, or hold a semantic anchor (line index / item id) instead of a raw offset. Symptom shape: the forward action passes, the inverse action fails. |
+| A `boolean` state member whose **only** writes sit inside an engine subscription (`.on('stateChange', …)`, `.then(…)`) | Stop. If that event never arrives the control renders its initial value forever, and every test that must first drive this control dies at step 1. Add a synchronous write (optimistic update + rollback) and a timeout fallback state. |
+
+These three categories account for nearly all recurring violations; keep them active while typing. The last four rows are **state-propagation** traps: they compile clean, pass codelinter, and fail only on device as "value stored, screen never changes" — see [`ui/state-management.md`](ui/state-management.md) § State written but never rendered, and the mechanical scan in `scripts/state_propagation_check.mjs`.
+
+## Per-file gate (run after EVERY .ets file, before the next one)
+
+Re-open the file you just wrote and run three scans — scan the actual content, do not answer from memory of what you intended to write:
+
+1. **Triggers** — the three write-time trigger patterns above: untyped `{` literals (including call arguments and callback returns; Record keys quoted; class literals listing every field), unnarrowed possibly-`undefined` reads (`?:`, `.get(`, `[i]`, Record access), and any enum member / modifier / constructor / resource name not verified in the cookbook this session
+2. **Imports** — every type, helper, and kit this file references is imported at the top, from the correct `@kit.*`
+3. **Names** — the struct name does not collide with any import; no member is named after a universal attribute (`opacity`, `scale`, `tabIndex`, `size`, `width`, …); any interface/type other files will also need lives in a shared model file, not redeclared here
+
+**Write the gate result down.** After each file, output one line in your response — e.g. `Index.ets: triggers✓ imports✓ names✓` — before starting the next file. A gate answered silently gets skipped under generation pressure; the written line is the evidence it ran. If a scan caught something, note the fix inline (`names✗→renamed opacity→circleOpacity`) and fix it now — caught here it costs one edit; caught after all files are written it costs a fix round across every file that copied it.
+
+**Sequencing rule: the write call for file N+1 is not allowed until the gate line for file N appears in your response.** Two write calls back-to-back mean the gate was skipped. Batch-writing all files and reviewing once at the end is NOT a substitute, and neither is asserting from memory that the files are clean — a session that did exactly that shipped a 16-error first check that its per-file scans would have caught at files 1 and 4.
+
+## Scenario routing table
+
+| Scenario | Read |
+|----------|------|
+| Error message contains an `arkts-xxx` rule tag | `language/arkts-rules.md` — search for the exact tag for details and good/bad examples |
+| `does not meet UI component syntax` / `Only UI component syntax can be written here` / `can have only one root node` / `UI component 'X' cannot be used in this place` | `language/arkui-structure-rules.md` |
+| Writing UI with Tabs, List/Grid + ForEach, forms, dialogs/toasts, DatePicker, gradients, or navigation | `ui/component-cookbook.md` — verified constructors, modifiers, enums, callbacks |
+| Passing params between pages (`router.pushUrl` + `getParams`) | `ui/component-cookbook.md` § Router params — exactly one shape passes the checker; do not improvise |
+| Designing a data model class / a detail page that looks up an item | `ui/component-cookbook.md` § Data model + detail page template — kills `possibly 'undefined'` at the design level |
+| Creating seed/mock data, or error `is missing the following properties from type` | `ui/component-cookbook.md` § Creating instances with data — class-body defaults do not make literal fields optional |
+| Before finalizing a UI change (visibility, interaction, layout quality) | `ui/ui-quality.md` |
+| Diagnosing a runtime UI failure that survived a fix round (collapsed bounds, wrong pixels, dead gesture) | `ui/ui-runtime-diagnosis.md` — measure-chain walk + layer attribution, evidence before the next fix |
+| Build/compile error WITHOUT an `arkts-*` tag and not UI-structural (hvigor, dependencies, signing) | `../pipeline/build/build.md` build-fix loop (match `build-lessons.jsonl` first; an uncertain official signature → § API signature lookup above) |
+| State management / MVVM (choose V1 or V2, never mix; new projects prefer V2) | `ui/state-management.md` — family selection policy + V1/V2 cheat sheets, pointing to the official docs `official/mvvm-v1/` and `official/mvvm-v2/` |
+| Porting plain TypeScript into ArkTS strict mode | `language/ts-to-arkts-rewrites.md` rewrite table |
+| Unsure whether a construct is allowed | Check "Avoid over-restriction" above first, then [`language/arkts-rules.md` § Explicitly allowed constructs](language/arkts-rules.md#explicitly-allowed-constructs) and the Rule Index |
+| Sendable / concurrency | [`language/arkts-rules.md` § 10. Sendable concurrency restrictions](language/arkts-rules.md#10-sendable-concurrency-restrictions) |
+| Project style conventions (naming / formatting / file org / comments / `$r()` resources) | `conventions/coding-style.md` |
+| Build / secure / test the project | build: `../pipeline/build/build.md` (pinned `devecocli build`); security: `conventions/security.md`; test: `../pipeline/testing/` (L0/L1/e2e contracts) |
+| Language-level project conventions (prefer-undefined, Map→Record) | [`language/arkts-rules.md` § Project conventions](language/arkts-rules.md#project-conventions-not-official-linter-rules) |
+
+Division of labor: this reference = language/linter rules + ArkUI structure and component APIs (everything needed to write `.ets` that compiles); build/test execution = `rules/pipeline/` (build-fix loop, testing layers); project-learned runtime pitfalls = `memory/code-pattern-lessons.jsonl` (per its ownership in `rules/pipeline/memory/memory-model.md`).
+
+## Source attribution
+
+- Anything with an `arkts-*` rule tag is a linter/language rule; violations are errors
+- ArkUI structural constraints (single root node, UI-syntax-only placement) are compiler rules without `arkts-*` tags; they surface at build time
+- The "Project conventions" section (prefer-undefined, Map-to-Record conversion, etc.) contains team conventions; when citing them, say they are project conventions — do not present them as ArkTS language restrictions. (Quoted keys in Record literals are NOT a convention — the checker enforces them as `arkts-no-untyped-obj-literals`.)
+
+## Change-set checks (once over the whole change set, after the per-file gates)
+
+Cross-file and config consistency the per-file gate cannot see — language-rule violations are already covered by the gate, do not re-audit them here:
+
+- [ ] Every page in `main_pages.json` has exactly one `@Entry` struct; embedded child components are NOT listed there
+- [ ] `user_grant` permissions in `module.json5` declare both `reason` (an existing `$string:` resource) and `usedScene`
+- [ ] Every shared interface/type is declared in exactly ONE model file and imported everywhere else
+- [ ] Every referenced type/enum/constant is actually declared and exported where it is imported from
+- [ ] `ForEach`/`LazyForEach` has a keyGenerator (third arg) using a business ID, not the index (verified form: `ui/component-cookbook.md` § List, Grid, and ForEach)
+- [ ] No bare global UI APIs (`router.*`, `promptAction.*`, `animateTo`, `vp2px`) — routed through `this.getUIContext()`; no bare global `getContext()` — use `this.getUIContext().getHostContext()`

package/skills/a2h-spec-implement/rules/arkts/conventions/coding-style.md

@@ -0,0 +1,96 @@
+---
+paths:
+  - "**/*.ets"
+  - "**/*.ts"
+---
+# HarmonyOS / ArkTS Coding Style
+
+> Project **style conventions** for the coding stage (and the UI skills). The ArkTS **language/linter rules** are NOT duplicated here — see the sibling files in this directory.
+
+## ArkTS Language Constraints
+
+The full ArkTS language/linter rule set (no `any`, no destructuring, no index signatures, object-literal type context, null safety, decorators, Sendable, etc.) lives in **`../language/arkts-rules.md`** (`arkts-*` tagged, with good/bad examples) and **`../language/arkui-structure-rules.md`** (build-stage structure). `../arkts-standards.md` is the overview + scenario router. This file covers only the project style conventions below.
+
+## Naming Conventions
+
+- Variables / functions: `camelCase` (e.g., `getUserInfo`, `goodsList`)
+- Classes / interfaces: `PascalCase` (e.g., `UserViewModel`, `IGoodsModel`)
+- Constants: `UPPER_SNAKE_CASE` (e.g., `MAX_PAGE_SIZE`, `COLOR_PRIMARY`)
+- File names: `PascalCase` for components (e.g., `HomePage.ets`), `camelCase` for utilities
+
+## Formatting
+
+- Prefer single quotes for strings (project convention; rule-set / official-doc examples may use double quotes — new project code follows this convention)
+- Semicolons at end of statements
+- Never use `var` - prefer `const`, then `let`
+- All methods, parameters, return values must have complete type annotations
+
+## File Organization
+
+- Component files (`.ets`): one component struct per file (`@ComponentV2` for V2 projects, `@Component` for V1)
+- ViewModel files: one ViewModel class per file
+- Model files: related data models may share a file
+- Keep files under 400 lines; extract helpers for files approaching 800 lines
+
+## Function Size & Nesting
+
+- Keep functions small — under ~50 lines and doing one thing; extract a helper once a function grows past that or mixes concerns.
+- Limit nesting to ~4 levels — prefer early returns / guard clauses / extracted helpers over deep `if`/`for` pyramids.
+
+## Comments
+
+- File header: `@file` (file purpose) + `@author` (developer), if the project already uses file headers
+- Public methods: JSDoc with `@param`, `@returns`; add `@example` for complex methods
+- Match the project's existing documentation language; use English unless the repository has already standardized on Chinese comments
+
+## Error Handling
+
+```ets
+// Use try/catch with proper error handling
+try {
+  const result = await riskyOperation()
+  return result
+} catch (error) {
+  hilog.error(0x0000, 'TAG', 'Operation failed: %{public}s', error)
+  throw new Error('User-friendly error message')
+}
+```
+
+Never silently swallow — an empty `catch {}` that drops the error is forbidden; log with context (`hilog`) or rethrow a user-facing error.
+
+## Immutability
+
+Scope: non-reactive data only (params, models passed across layers). Reactive state (`@Observed`/`@Trace`-tracked objects) is mutated in place **by design** — the framework observes property mutation (`../ui/state-management.md`); do not "fix" those mutations into copies.
+
+Follow the common immutability principles - create new objects instead of mutating:
+
+```ets
+// BAD: mutation
+function updateUser(user: UserModel, name: string): UserModel {
+  user.name = name  // direct mutation
+  return user
+}
+
+// GOOD: immutable - create new instance
+function updateUser(user: UserModel, name: string): UserModel {
+  const updated = new UserModel()
+  updated.id = user.id
+  updated.name = name
+  updated.email = user.email
+  return updated
+}
+```
+
+## Resource References
+
+Define UI constants as resources and reference via `$r()` — do not hardcode colors, sizes, or display strings. Scope: production UI code; cookbook / rules snippets hardcode literals to demonstrate API shape — copy the shape, not the literals:
+
+```ets
+// BAD: hardcoded values
+Text('Hello').fontSize(16).fontColor('#333333')
+
+// GOOD: resource references
+Text($r('app.string.greeting'))
+  .fontSize($r('app.float.font_size_body'))
+  .fontColor($r('app.color.text_primary'))
+```

package/skills/a2h-spec-implement/rules/arkts/conventions/security.md

@@ -0,0 +1,126 @@
+---
+paths:
+  - "**/*.ets"
+  - "**/*.ts"
+  - "**/module.json5"
+---
+# HarmonyOS / ArkTS Security
+
+> ArkTS security rules for the coding stage (and the UI skills).
+
+## Permission Management
+
+Declaring `requestPermissions` in `module.json5` — with the mandatory `reason` (an existing `$string:` resource) and `usedScene` for every `user_grant` permission — is a compile-time hard constraint owned by [`../arkts-standards.md`](../arkts-standards.md) § Core hard constraints; the build fails without them. This file covers the runtime security posture around permissions, not the declaration syntax.
+
+### Runtime permission checklist
+
+Before calling a permission-gated system API, verify:
+
+- [ ] Runtime permission request implemented for sensitive permissions (camera, location, etc.)
+- [ ] Permission check before the API call, with graceful fallback on denial
+
+### Runtime Permission Request
+
+```ets
+import { abilityAccessCtrl, bundleManager, common, Permissions } from '@kit.AbilityKit';
+
+// context: the caller's ability context — in a component, this.getUIContext().getHostContext()
+// (never the bare global getContext(), per the change-set checks in arkts-standards.md)
+async function checkAndRequestPermission(context: common.Context, permission: Permissions): Promise<boolean> {
+  const atManager = abilityAccessCtrl.createAtManager();
+  const bundleInfo = await bundleManager.getBundleInfoForSelf(
+    bundleManager.BundleFlag.GET_BUNDLE_INFO_WITH_APPLICATION
+  );
+  const tokenId = bundleInfo.appInfo.accessTokenId;
+  const grantStatus = await atManager.checkAccessToken(tokenId, permission);
+
+  if (grantStatus === abilityAccessCtrl.GrantStatus.PERMISSION_GRANTED) {
+    return true;
+  }
+
+  const result = await atManager.requestPermissionsFromUser(context, [permission]);
+  return result.authResults[0] === abilityAccessCtrl.GrantStatus.PERMISSION_GRANTED;
+}
+```
+
+## Secret Management
+
+- **NEVER** hardcode API keys, tokens, or passwords in `.ets`/`.ts` source files
+- Use HarmonyOS Preferences API for non-sensitive configuration
+- Use HarmonyOS Keystore for sensitive credentials
+- Environment-specific configs should be managed via build profiles
+
+```ets
+// BAD: hardcoded secret
+const API_KEY: string = 'sk-xxxxxxxxxxxx';
+
+// GOOD: from build profile config (non-sensitive)
+import { BuildProfile } from 'BuildProfile';
+const endpoint = BuildProfile.API_ENDPOINT;
+
+// GOOD: use HUKS to encrypt/decrypt data without exposing key material
+import { huks } from '@kit.UniversalKeystoreKit';
+async function decryptWithKeystore(alias: string, nonce: Uint8Array, aad: Uint8Array, cipherData: Uint8Array): Promise<Uint8Array> {
+  const options: huks.HuksOptions = {
+    properties: [
+      { tag: huks.HuksTag.HUKS_TAG_ALGORITHM, value: huks.HuksKeyAlg.HUKS_ALG_AES },
+      { tag: huks.HuksTag.HUKS_TAG_PURPOSE, value: huks.HuksKeyPurpose.HUKS_KEY_PURPOSE_DECRYPT },
+      { tag: huks.HuksTag.HUKS_TAG_BLOCK_MODE, value: huks.HuksCipherMode.HUKS_MODE_GCM },
+      { tag: huks.HuksTag.HUKS_TAG_PADDING, value: huks.HuksKeyPadding.HUKS_PADDING_NONE },
+      { tag: huks.HuksTag.HUKS_TAG_NONCE, value: nonce },
+      { tag: huks.HuksTag.HUKS_TAG_ASSOCIATED_DATA, value: aad }
+    ],
+    inData: cipherData
+  };
+  const handle = await huks.initSession(alias, options);
+  const result = await huks.finishSession(handle.handle, options);
+  return result.outData;
+}
+```
+
+## Input Validation
+
+- Validate all user input before processing
+- Sanitize data before displaying in UI to prevent injection
+- Validate deep link parameters before navigation
+
+```ets
+import { url } from '@kit.ArkTS';
+import { hilog } from '@kit.PerformanceAnalysisKit';
+
+// Validate before navigation. navPathStack: the page's own NavPathStack
+// (bound to its Navigation); no ArkTS `new URL` — parse via @kit.ArkTS url.
+function handleDeepLink(uri: string, navPathStack: NavPathStack): void {
+  const allowedPaths: string[] = ['detail', 'settings', 'profile'];
+  const parsed = url.URL.parseURL(uri);
+  const path = parsed.pathname.replace('/', '');
+
+  if (!allowedPaths.includes(path)) {
+    hilog.warn(0x0000, 'DeepLink', 'Invalid deep link path: %{public}s', path);
+    return;
+  }
+
+  navPathStack.pushPath({ name: path });
+}
+```
+
+## Network Security
+
+- Always use HTTPS for network requests
+- Validate server certificates
+- Implement request timeout and retry policies
+- Never log sensitive data (tokens, user credentials) in network request/response logs
+
+## Data Storage Security
+
+- Use encrypted preferences for sensitive local data
+- Clear sensitive data from memory when no longer needed
+- Implement proper data lifecycle management
+- Consider data classification (public, internal, confidential) when choosing storage mechanisms
+
+## Dependency Security
+
+- Only use dependencies from trusted sources (official ohpm registry)
+- Verify dependency versions in `oh-package.json5`
+- Regularly check for known vulnerabilities in third-party libraries
+- Pin dependency versions to avoid unexpected updates