deveco_hmigbot 0.21.5

package/manifest.json

@@ -0,0 +1,19 @@
+{
+  "name": "hmigbot",
+  "version": "0.21.5",
+  "engineVersion": "0.5.1-pure",
+  "skills": [
+    "migrate-core"
+  ],
+  "agents": [
+    "hmigbot-worker",
+    "hmigbot",
+    "workflow-subagent"
+  ],
+  "commands": [
+    "hmigbot"
+  ],
+  "tools": [
+    "workflow"
+  ]
+}

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "deveco_hmigbot",
+  "version": "0.21.5",
+  "description": "Android→HarmonyOS migration suite for DevEco Code: /hmigbot command, migrate-core skill, workflow engine, agents",
+  "type": "module",
+  "license": "MIT",
+  "main": "./dist/index.js",
+  "exports": {
+    ".": "./dist/index.js",
+    "./manifest.json": "./manifest.json",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "skills",
+    "agents",
+    "commands",
+    "manifest.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "dependencies": {},
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/skills/migrate-core/FILES.md

@@ -0,0 +1,26 @@
+# 宿主 skill 工具加载本技能时随内容附带的文件白名单（存在的才列出）；@note 行原样附带。
+@note 入口：流程正文在 SKILL.md；语料按 references/README.md 的加载索引按场景取件，不整目录搬运。
+@note SKILL.md 给出的脚本命令是完整可执行形态，直接跑；只在报错或需要未列出的参数时才 `node $HMIG/scripts/<路径>.mjs --help`。$HMIG = 本技能 Base directory。
+references/README.md
+references/host-capabilities.md
+references/flow/conventions-template.md
+references/flow/navigation-migration.md
+references/flow/unit-breakdown.md
+scripts/front.mjs
+scripts/feasibility/feasibility.mjs
+scripts/convert/convert-resources.mjs
+scripts/wire/wire-routes.mjs
+scripts/transpile/transpile-layout.mjs
+scripts/ledger/ledger.mjs
+scripts/ledger/parse-cards.mjs
+scripts/closure/closure-suite.mjs
+scripts/closure/check-anchors.mjs
+scripts/interface/interface.mjs
+scripts/vectors/setup-arkts-test.mjs
+scripts/vectors/run-arkts-vectors.mjs
+scripts/smoke/align-sdk.mjs
+scripts/smoke/ensure-sign.mjs
+scripts/smoke/smoke.mjs
+scripts/smoke/walk.mjs
+templates/mig_slices.js
+templates/acceptance.js

package/skills/migrate-core/SKILL.md

@@ -0,0 +1,484 @@
+---
+name: migrate-core
+description: |
+  Android 应用整体迁移到 HarmonyOS 的产线主流程（SDD 五相全自动：可行性→规格基线→开发→测试→发布），配合 workflow 工具与套件脚本执行。
+  触发场景：
+  (1) 用户要求迁移一个 Android 项目 / "开始迁移" / /hmigbot 命令
+  (2) 迁移中断后要求续跑（resumeFrom / only 复跑失败切片）
+  (3) 要求核对迁移台账或出迁移报告
+  单点问题（改一个页面、修一个报错）不用本技能。
+---
+
+# migrate-core
+
+## 流程速览（先看这个再看阶段）
+
+三句话：**①开工体检定档**（红黄绿，红=改道或尽力而为）→ **②程序能干的先干掉**（资源/路由/布局搬运+立台账+打地基，产出第一天就能编译的工程）→ **③模型自主实现（只挂确定性静态门）→ 末端判断性验收一遍 → 上机 → 报告**。
+
+**五阶段一览（SDD 五相）**（先扫这张表，再读各阶段）：
+
+| 阶段 | 含（原细步） | 干什么 | 产出 | 完成门 |
+|---|---|---|---|---|
+| **一·可行性** | 体检分诊 | 扫源码定红黄绿 | `$SPEC/feasibility.json` | 退出码 0 进／4 黄逐项处置／5 红改道或尽力而为 |
+| **二·规格基线** | 2a 静态前场 · 2b 语义装账 | 搬骨架+路由账 → 提断言/规划切片/定契约，冻结 | `$DST` 骨架 + `$LEDGER`(pages/features/slices) + `$SPEC/vectors/` + `conventions.md` | 构建绿 + 分母冻结 |
+| **三·开发** | 3a 地基波 · 3b 切片流水 | 打地基派生 manifest → 照 manifest 自主实现，只挂确定性门 | `$SPEC/interface-manifest.json` + 各片代码到 `checked` | 每片 构建+闭合绿 |
+| **四·测试** | 4a 末端验收 · 4b 运行时验证 | 判断性验收一遍+集成闭合 → 上机确认核心路径+on_device | 片 `accepted`、断言 `passed` | acceptance 绿 + 闭合 `final` 硬违规清零 + 核心路径过 |
+| **五·发布回流** | 收尾 | 出报告 + 坑回流语料 | `$SPEC/REPORT.md` | `ledger verify` 过 |
+
+数据流：`$SRC` →①判可行→②搬骨架+立账定契约→③打地基派生 manifest+照 manifest 实现→④判断验收+闭合+上机→⑤`REPORT.md`。每步吃上一步产物，冻结不回改。
+
+验证两类分置：**确定性验证**（构建/闭合/向量/接口一致性，退出码裁决）实现期连续挂；
+**判断性验证**（verify/对抗）只在阶段四末端跑一遍，禁逐片连续。
+
+**铁律**：
+- 计划冻结即不重规划——探索与切片规划完成后冻结，之后只 `only` 续跑失败片；禁重规划、禁改断言分母、禁挪 `$SPEC/` 路径。
+- 跨切片契约靠派生：接口从地基真实代码 extract（阶段三·地基波），下游照 manifest 实现，漂移由检查点确定性拦；契约要改走台账 `debts` → 改地基 → 重派生 → 定向复验。
+- 固定路径：`$SPEC/` 与 `$LEDGER` 一次定死全程不挪；禁 `ledger init` 重建。
+- 忠实源码，不无中生有：只搬源码可派生的内容。源有多 locale 就忠实搬那些语言，**源没有的不自造**（禁机翻凑语言、禁发明功能）；无等价的能力进 `degradations`，不假装实现。
+- **有 PRD 时的分工：范围看源码，契约看 PRD**。
+  ①迁移范围 = 源码全量：PRD 没提的、以及 PRD 写明"不要求/不验证/范围外"的源码能力**一律照迁**，不做禁用态占位、不省略；只有源码没有或平台无等价的才进 `degradations`。
+  ②PRD 明写的**可观察契约**（稳定 id、文案、格式、fixture、编号场景里的行为）必须按 PRD 落地；与源码不一致时**以 PRD 为准**，逐条记 `$SPEC/feedback.md`"PRD 与源码差异"（源码原样 + PRD 要求 + 落地方式）。
+  ③PRD 没写明的行为一律照源码：不推断额外前置条件/校验/复位，不把模拟实现升级成真硬件，PRD 里的技术选型描述不是行为。
+  PRD 覆盖表证明"PRD 要求的都验到了"，不证明"迁移做完了"。
+
+**阶段形态一次定（标准给默认值，模型可改判）**：体检按复合信号（源码 LOC、文件数、页面数、依赖广度）给
+`sizeClass` 与 `shape`（`explore: inline|workflow`、`foundation: inline|wave`、`adversary: false|derived`）建议值写入
+feasibility.json；模型结合调用深度改判（改判连理由写回同文件）。之后各阶段**只读 `shape.*` 决定形态，不再现场判断
+"要不要跑"**——小应用不跑空探索/空地基波/对抗，大应用不因此少任何门。
+
+**路径（一律工作区相对，禁绝对路径）**：`$SRC`=安卓源码相对目录（如 `MyApp`）；`$DST`=鸿蒙工程相对目录（如 `MyAppHM`）；`$HMIG`=本技能目录（skill 工具加载时返回的 Base directory 是 file URL：去掉 `file://` 前缀，Windows 上再去掉盘符前多出的那个 `/`（`file:///C:/x` → `C:/x`），`%20` 还原为空格，含空格时整段加双引号；按工程安装时是 `.deveco/skills/migrate-core`，宿主内置时是宿主技能目录下的 `migrate-core`（绝对路径，仅用于 `node $HMIG/scripts/…` 调用，不进任何产物）——以返回值为准，scripts/ 与 references/ 随技能封装）；`$SPEC`=`$DST/spec`（**迁移产物全在鸿蒙工程内**——多项目共用工作区互不干扰，工程交付自带全程审计）；`$LEDGER`=`$SPEC/ledger`。命令与所有落盘产物（args/台账/报告/manifest）中的路径**必须是工作区相对形式**；selfcheck 检测工作区搬运。
+只读写 `$SRC`、`$DST`（含 `$SPEC`）与 `.deveco/`，写进每次 workflow 的 goal。
+
+**纪律**：源码绝对真源；不降级不占位（做不到的进台账 degradations，且先记待裁决）；args>2KB 走 argsFile；
+检查一律 `$ 命令` 退出码；"验过"必带证据；台账只经 `ledger.mjs` 写；切片 ≤5 文件；
+阶段间自动推进，全程不问人（含红灯）。
+**套件模板只读**：`explore/implement/mig_slices/acceptance` 四份模板由套件发行并经回归门测试；引擎拒跑（如确定性约束）或模板运行报错
+= 套件缺陷，如实停在该步、把报错原文写进 `$SPEC/feedback.md` 与最终报告，**禁止**拷贝模板打补丁、改 `.deveco/skills` 下的模板文件、
+或用 `scriptPath` 跑改过的副本（引擎工具描述里"导出脚本可改后重跑"只适用于你自己写的工作流）。
+**跨平台（Windows 与 macOS 同一套写法）**：命令有两条执行路径——写进 args 的 `$ 命令` 由引擎经 cmd.exe/sh 执行，
+你自己用 bash 工具跑的命令在 Windows 上多半经 PowerShell。两边都安全的写法：只用双引号（禁单引号）、含空格的路径整段加双引号、
+不用 sleep/ls/grep/cat/rm/`sh -c`/`$(…)`/`2>/dev/null`、不写 `VAR=x 命令` 前缀（设备用 `--device` 参数）、
+需要逻辑一律 `node -e "…"`。**你自己跑命令时不写 `cd X && …`**（PowerShell 5 不认 `&&`），改用 bash 工具的 workdir 参数；
+args 里的 `$ cd $DST && …` 由引擎执行，两端都行。台账入账一律 `--file <JSON 文件>`（先用 Write 工具写文件），
+禁止命令行内嵌 JSON（PowerShell 会吞掉参数里的双引号）。`hvigorw` 用 2a 前场报告 `toolchain.buildCmd` 里解析好的命令
+（Windows 的 DevEco 默认不把 hvigor 放进 PATH，报告已按安装根找到）。套件脚本全是 Node，路径用 `/` 两端通用。
+
+## 阶段一 · 可行性（体检分诊）
+
+> **目的** 扫源码定红黄绿定档 ｜ **产出** `$SPEC/feasibility.json` ｜ **门** 退出码 0 进／4 黄逐项处置／5 红改道或尽力而为
+
+1. 按 `$HMIG/references/topics/env-doctor.md` 过环境。
+2. 盘点会话工具列表，对照 `$HMIG/references/host-capabilities.md` 填实测列；宿主有的后续直接用。
+3. **先建骨架工程定 `$DST`**（`$SPEC` 挂其下，一切产物有家）：
+   `$ devecocli create --project-path $DST --app-name <AppName> --bundle-name <源 applicationId>`
+   （宿主自带 devecocli，无头可跑、API 版本自探测、图标随 IDE 模板；AppName 须 `^[A-Za-z][A-Za-z0-9_]*$`；已存在非空目录会拒，不要覆盖）。
+   **不要单独跑 align-sdk / ensure-sign**——2a 的 front.mjs 内含这两步；它们的处置规则：
+   align-sdk exit 4=SDK 不匹配，按输出改 build-profile 再重跑该步；ensure-sign exit 4=需人工（登录/离线）：按输出提示用户
+   `devecocli auth login`，本轮走 unsigned+hdc uitest 降级链不阻塞，**提示置顶写入最终报告**。
+4. 可行性体检随 2a 一条命令跑（`front.mjs --feasibility`，见 2a；红=exit 5 会停在可行性一步）。结果 `$SPEC/feasibility.json` 按下列处置：
+   - **形态画像**（报告 `profile` 字段）供全程分派：`uiParadigm`（compose→布局走 fact-tree 旁路；xml→转译器）、
+     `navSources`（路由真源轨，wire-routes 自动全跑）、`archHints`（mvp/mvvm→语料加载，见
+     `$HMIG/references/flow/navigation-migration.md` 分派表）；
+   - **定档**：脚本按复合信号（LOC/文件数/页面数/依赖广度）出 `sizeClass` 建议值写入 feasibility.json，模型可改判（写理由）；
+   - 0（绿）→ front 继续往下跑；
+   - 4（黄）→ front 记录后继续；每个黄项按报告处置建议 `ledger add --type degradations`（2b 装账时做）；
+   - 5（红）→ front 停在可行性一步（exit 5）。默认尽力而为：墙内能力做显式禁用态（入口在、置灰、附说明），报告置顶红项，
+     决定后**不带 `--feasibility` 重跑 front.mjs** 继续前场；用户声明过快速失败的，产出可行性报告后结束。
+   - "待裁决依赖"：读用法+查 `$HMIG/references/topics/library-migration/`，结论写**工作区缓存**
+     `$SPEC/lib-adjudications.json`（`{entries:[{match,...}]}`，feasibility 自动合并读）——套件表不直改（回流走 feedback）。
+   - **标准库原语**（`java.*`/`kotlin.*`，非 gradle 依赖、扫描看不见、最易被实现期误判"缺失"而手造）：
+     grep 源码实际的 `java.*`/`kotlin.*` 标准库 import（**用什么查什么，不预设清单/不硬编码映射**），逐个走**原生查询定等价**——
+     `ls`/grep 本机 SDK `openharmony/ets/arkts`（`@arkts.*` 基础库全貌）+`ets/api`（`@ohos`/`@kit`）声明 ／ `devecocli docs search`；查得即映射、结论进运行期缓存。
+     **铁律：禁重造平台已提供的原语——重造前必须用查询证明无等价（MISS），否则一律映射**。查法见 `$HMIG/references/topics/library-migration/stdlib-mapping-table.md`。
+
+## 阶段二 · 规格基线（静态前场 + 台账装配）
+
+> **目的** 搬出可编译骨架 + 从源码提取断言/切片/契约并冻结 ｜ **产出** `$DST` 骨架 + `$LEDGER` + `$SPEC/vectors/` + `conventions.md` ｜ **门** 构建绿 + 分母冻结
+
+### 2a 静态前场（资源·路由·布局 → 骨架）
+
+工程已于阶段一建好。**体检与前场整段一条命令**：
+`$ node $HMIG/scripts/front.mjs --src $SRC --dst $DST --feasibility [--extra-res <AAR的res,..>]`
+——先跑可行性（红=exit 5 停下让你定改道/尽力而为），再按下列 1–5 的顺序把测试脚手架、资源转换、路由接线、布局转译、
+设备就绪与 SDK 对齐、签名、构建、闭合门、首屏冒烟串起来跑，每步退出码与摘要进 `$SPEC/front/front-report.json`
+（各步自己的报告仍在：feasibility / wiring-report / resource-manifest / transpile-report / closure-slice / smoke-2a）。
+退出码 0=前场绿进 2b；5=可行性红；10=构建红或闭合硬违规；2=冒烟立案；3=冒烟环境阻塞（如实记"未冒烟"）。
+定向修完只重跑涉事的单个脚本（每个都能独立跑，`--help` 看用法），不必整段重来。
+只处置报告里报出来的问题，修完**只重跑涉事那一步**（下列单命令），不整段重来。首页判不了时报告
+`launcherResolved:false`：核对源码后 `wire-routes … --launcher <路由名>` 校正重跑。下面是各步的单命令与要点：
+0. `$ node $HMIG/scripts/vectors/setup-arkts-test.mjs --project $DST` 装 ArkTS 测试脚手架（hypium + `entry/src/test/`，含离线兜底——算法域向量门依赖）。
+1. `$ node $HMIG/scripts/convert/convert-resources.mjs --src $SRC --dst $DST --out $SPEC/front [--extra-res <AAR的res,..>]`
+   依赖含 AAR 库时：`.aar` 即 zip，解包取其 `res/` 经 `--extra-res` 并入（应用侧同名优先）；
+   连 .aar 都拿不到的窄场景：装系统级 apktool（不随包）按 `$HMIG/references/topics/resources/aar-decompile.md` 反编合并。
+2. `$ node $HMIG/scripts/wire/wire-routes.mjs --src $SRC --out $DST/entry/src/main/ets --json $SPEC/front/wiring-report.json`
+   （三轨自动合并：manifest + res/navigation + Compose NavHost，单 Activity 壳自动让位；
+   产出 systemRouterMap `route_map.json`（**唯一注册真源**，Index 不再有 pageMap）+ module.json5 接线 +
+   EntryAbility `smokeRoute` 透传幂等补丁 + Index 壳（冷启入栈 + 直达钩子 + `hmigSmoke` 着陆日志）。
+   **路由基建=冻结件：禁自研动态注册表**（形态谱见 `$HMIG/references/flow/navigation-migration.md`）；
+   新页面一律走 2c 台账补漏重跑，禁手改 Router/Index/EntryAbility 透传；注册页文件 `pages/<Route>Page.ets`
+   就是该页的交付文件——实现写进它，不另起 screens/ 壳外目录）
+   把 `main_pages.json.generated` 并入工程 profile。
+3. `$ node $HMIG/scripts/transpile/transpile-layout.mjs --src $SRC --out $SPEC/front/layouts --json $SPEC/front/transpile-report.json [--extra-res 同上]`
+   转译骨架是**参考件**（结构/尺寸/文案引用已按源搬好，行为留 TODO 锚点），落 `$SPEC/front/layouts/`，**不进编译树**：
+   切片实现时按需把对应骨架的内容并进 `pages/<Route>Page.ets` 或组件文件，用不到的不搬。
+4. 门：构建必须绿——命令照 `$SPEC/front/front-report.json` 的 `toolchain.buildCmd`（前场已解析 hvigorw 路径；
+   本机在 PATH 时就是裸 `hvigorw assembleHap --no-daemon`），红了先修骨架。
+   随后 `$ node $HMIG/scripts/closure/closure-suite.mjs --project $DST --stage slice` 也必须绿——骨架页/资源账在本步清零，
+   悬空不许留给切片检查点。搬进页面的骨架片段若引用了没转到的资源（库资源走 `--extra-res`；转不了的改成 `TODO(res)` 注释），
+   在该片的检查点处理。终检（final）把工程里**任何未被 import/路由表/ability 入口引用的 .ets** 记 `dead_file` 硬违规——交付物不带死代码。
+5. **首屏冒烟**：`$ node $HMIG/scripts/smoke/smoke.mjs --project $DST --out $SPEC/smoke --json $SPEC/smoke/smoke-2a.json`
+   （无设备时经 align-sdk --device-only 自动拉起模拟器 + API 版本预检 + 装机输出校验 + 前台/着陆核对 + faultlog/页面子树/截图判定；
+   exit 3=环境阻塞（无设备/装机失败/hap 早于源码）不阻塞流程，但**报告须如实记"未冒烟"，不当通过**；
+   设备上残留上一轮不同签名的同包名旧包时脚本自动卸旧重装）
+   ——骨架壳+launcher 页可见即过（冷启落骨架页记 `scaffold`，属预期不算失败）；崩溃/纯白/着陆错当场修完再进 2b。
+   首屏跳转链（Index 冷启→splash→主页）此后为**冻结件**，切片实现不得改其转发目标；
+   转发目标语义：源 app 的 splash/launcher 转发到主 NavHost 首 destination 的等价页（禁转发到壳/骨架页）。
+
+### 2b 语义装账（台账装配）
+
+1. `$ node $HMIG/scripts/ledger/ledger.mjs init --dir $LEDGER --app <应用名> --src $SRC --dst $DST`
+   wiring-report 路由入账：写成 JSON 数组文件后 `add --type pages --file $SPEC/pages-batch.json`（不在命令行内嵌 JSON）。
+2. 语义提取：`shape.explore=inline`（默认 small 档）时**不起 workflow**，主会话亲读源码产卡（几百行的应用起并行探索是纯开销）；
+   `workflow` 时 args 写 `$SPEC/explore-args.json`，调用 workflow，顶层参数 `name='explore'`、`argsFile='$SPEC/explore-args.json'`、`runName='<应用名>/explore'`（按域并行，每探索者写自己的卡）。
+   **workflow 调用形态（全流程四处通用）**：`name`/`argsFile`/`runName` 是工具**顶层参数**、与 `args` 平级——**绝不嵌进 args**；本流程 args 一律写文件走 argsFile，调用里不出现 args 字段。`name` 必带。每域产物=**页面卡或域卡**，不写长文档：
+   - 页面卡=逐页功能断言；**域卡=无页面核心功能**（下载队列/播放会话/同步引擎/解析器等）
+     同规格断言——服务重于页面的应用，域卡应多于页面卡；断言标 `kind: ui|backend|on_device`：
+     **`on_device` 只给设备上可观察且静态证不了的契约**（真震/真弹通知/运行时授权/精确定时/冷重启后仍在/系统能力真调起）；
+     数据层方法契约（"提供 updateCart(cart)"）、纯逻辑、可读码判定的 UI 行为一律 `backend`/`ui`——4b 清单就是 on_device 全集，标错即撑大清单；
+   - **断言=每卡短验收单，宁短勿全**：只录"不达成即算失败"的行为（条数由模型按页面复杂度判断）；
+     视觉参数/尺寸/间距/动画细节**一律不入账**（保真由转译骨架+safearea 门+smoke 截图承载，REPORT 附录提示人工复核）；
+   - 断言纪律：原子可断言、带源锚点 `文件:行`、写**结果契约**（用户可见行为）不写实现步骤；
+   - **edge-to-edge 应用每页面卡固定一条「顶部内容避让状态栏」结果契约断言**（kind: ui），按页入账逐页核；
+   - **平台模型差异**（线程/后台/生命周期/权限，见 `$HMIG/references/flow/platform-model-gaps.md`）：
+     不可 1:1 的行为，断言抓**结果契约**（用户可见行为），标注鸿蒙 idiom + 差异点，实现重架构；
+     完全无等价的进台账 `degradations`；验收核结果契约不核是否照搬安卓机制；
+   - **断言行机读格式**（装账靠脚本解析，不靠模型转录）：每条一行
+     `- <ID> [kind] 断言文本。锚点：文件:行`，ID 用域前缀（DM-A01 式）；
+     断言引用的**稳定 id 与可见文本用反引号包住**（`id 为 X` 句式也识别）——解析器机械抽成字面锚点，
+     集成/收尾闭合核实产物里真有；严宽只看来源：锚点指向 PRD 或
+     `id 为 X` 句式的缺失立软案，锚点指向源码的只记 info（那是描述，反引号里常混调用签名/注解/源 API 名）；
+   - 跨切面备忘（状态机/线程/启动时序）合计一页内；平台风险点；
+   - **区体积上限**：单区源文件清单折算输入超 ~25K token（约 20 个中大文件）必须拆区
+     （大提示词高峰期首包超时挂死率高）；同一区挂死两次后不再派子代理，
+     改主会话亲读该区产卡（已建流不吃新建流首包问题）。
+   设置项/菜单/对话框先确定性清点（res/menu、PreferenceScreen、manifest），模型补语义；
+   **组件行为清单直接抄源码枚举行**（按钮/菜单项逐条对源），禁经探索摘要二次概括。
+   **装账走套件解析器，不现写脚本**：
+   `$ node $HMIG/scripts/ledger/parse-cards.mjs --cards $SPEC/cards --out $SPEC/features-batch.json --wiring $SPEC/front/wiring-report.json --project $DST [--prd <PRD 文件>]`
+   （固定格式机读；无锚点/重复 ID/零条会告警——按告警改卡片，不改解析器）→ `add --type features --file $SPEC/features-batch.json` 批量入账。
+   `--project` 让它同一轮顺带核字面量与 PRD 覆盖差集（报告 `$SPEC/anchors-precheck.json`），不用再单独跑闭合器。
+   **有 PRD 时（工作区 prd.md / 用户指定；可选输入，没有就不给 --prd）产卡顺序固定**：①先从源码逐页/逐域枚举产**全量卡**
+   （分母来自源码，PRD 不定范围）；②再拿 PRD 逐行对账**补验收断言**——每条需求行落到已有卡上（同一行为不重复开卡），
+   锚点写 `PRD.md:行`，PRD 明写的 id/文本原样反引号进断言；PRD 明写的契约与源码不一致的，**断言按 PRD 写**并记
+   `$SPEC/feedback.md`"PRD 与源码差异"；PRD 写明"不要求/范围外"的源码能力**照常产卡**（那只是不验，不是不迁）。
+   输出的"未覆盖 K 行"逐条处置——是需求行就补断言重跑本命令再入账，
+   是约束/说明行才留待闭合豁免（豁免票 type `prd_uncovered`，带理由）；这一步只记账不理解语义（行号 + 字面量对账），
+   语义转写仍是你的活。集成/收尾闭合会再核同一件事。
+   `--wiring` 把接线报告的 `appInit`（Application 及其父类各级 onCreate 的源码位点 / ContentProvider / androidx.startup 初始化器）
+   机械生成粗粒度 `INIT-A*` 断言（一个位点一条，锚点=文件:行）：应用级初始化横切所有页面，按页面/域产卡天然漏掉它，
+   漏接只在下游以别的错误露头。**逐项拆解由你读锚定的 onCreate 源码段完成**（每个初始化调用一条子断言写进
+   地基单元 expectation），脚本不替你判"哪些调用算初始化"。
+   任何单次模型输入 ≤25K。分母冻结。
+   算法/协议密集域：连同黄金测试向量一起提取，向量存 `$SPEC/vectors/*.json`（纯数据，从源单元测试提取）；
+   **逻辑一律 ArkTS `.ets`，禁 `.ts`**（`.ts` 不能 import `.ets`/@ohos、非原生）。配 **ArkTS Local Test 向量门**：
+   提取步产出 向量数据模块 `entry/src/test/<域>Vectors.ets` + 固定 data-driven harness `entry/src/test/<域>.test.ets`
+   （import 逻辑 + 逐向量 `assertEqual`，写法照 `$HMIG/references/flow/arkts-vector-gate.md`）并挂进 `entry/src/test/List.test.ets`；
+   此类域默认拆三小片（核心求值/格式化/函数表）。
+2c. **路由台账补漏**（页面账定型后立即做）：
+   `$ node $HMIG/scripts/wire/wire-routes.mjs --src $SRC --from-ledger $SPEC/ledger/ledger.json --out $DST/entry/src/main/ets --json $SPEC/front/wiring-report.json`
+   ——三轨没提到而页面账里有的页，补生成骨架并**仅经 route_map.json（systemRouterMap）注册**，
+   Routes 常量增量合并。报告 `appInit.ambiguous=true`（多产品仓多个 Application 候选）时，按阶段一选定的产品加
+   `--app-class <类名>` 重跑校正，再装账。
+3. 切片规划，写 `$SPEC/slices-batch.json` 后 `add --type slices --file`（一次入账，不逐条内嵌 JSON）：
+   - 纵切：**切片=特性内聚单元**（页面只是常见边界——小页可合并、复杂页沿松耦合边界拆，
+     内聚特性绝不强拆）；片数无定额，唯一硬约束：单片工单 ≤6K 且预计单轮可完成，超了=边界划错；
+     **后端域切片与页面切片同等公民**（下载/播放/同步各自成片，backend 断言归属之）；共享件划给地基波；
+     页面片填 `route`（注册路由名，wave-smoke 用）；
+   - **依赖方向铁律：页面是消费者不是宿主**——业务状态机/服务核心/引擎永远归
+     core/backend 片（如计时状态机独立成片，前台页与后台任务各自依赖它），
+     禁止 backend/platform 片依赖 page- 片；page 片可依赖任何层。模板启动会点名违规；
+   - **应用级初始化单元**：台账里有 `INIT-A*` 断言（接线报告 appInit 非空）时，规划必须有一个地基单元（建议 id `fnd-app-init`）
+     拥有 `entry/src/main/ets/entryability/EntryAbility.ets`（有 AbilityStage 也含）并归属全部 INIT-A* 断言；期望逐项写
+     "接入 EntryAbility.onCreate、首页前完成"或"无鸿蒙等价→记降级"（DI 框架类多属后者）；其余地基单元依赖它。
+     该单元只在 onCreate 里增加初始化调用，不动 smokeRoute 透传与 loadContent（冻结件其余部分）。
+     **源为 edge-to-edge**（`enableEdgeToEdge()` / `WindowCompat.setDecorFitsSystemWindows(false)` / 透明状态栏主题）时，
+     窗口层契约也归该单元：`onWindowStageCreate` 开 `setWindowLayoutFullScreen(true)`、按 `avoidAreaChange` 把状态栏/导航条高度写进
+     约定的 AppStorage 键，页面**只读不写**这些键；期望里写成一条 INIT 断言（锚点 = 源 enableEdgeToEdge 调用行）。
+     没人拥有它时页面全按缺省 0 避让、消费者门只能报 read_only。
+   - **页面片必须拥有其注册页文件**：`targetPath` 含 `entry/src/main/ets/pages/<Route>Page.ets`（可与实现目录并列为数组）；
+     模板启动按 route_map 逐路由校验归属，没人拥有的注册页拒跑；确不迁移的路由写 `unownedRoutes:[{route,reason}]`
+     并从 route_map 删注册；
+   - ≤5 文件；id 用可读名（`page-item-list`）；真依赖写 deps，紧耦合对合并；
+   - expectation 抄台账断言，并填 featureIds（该片覆盖的断言 id——验收过即同步过账）；
+     算法片与后端片必填 selfTest：算法用 **ArkTS Local Test 向量门**（见上），**后端用行为探针**（`$SPEC/probes/` 下
+     可执行脚本：喂输入→断言落库/文件/事件，退出码裁决——探针即后端的"截图"）；
+     **波门/检查点/自测命令必须当场可执行**（node/shell 或 ArkTS Local Test via hvigorw——主机侧、不依赖真机/签名/网络）；
+     设备级套件（装 HAP 上机跑 selfTest）另列、归阶段四·运行时验证（4b）；
+     实现提示写 instructions.md 的 SECTION（格式照 `$HMIG/references/flow/unit-breakdown.md`）。
+4. conventions.md：§A 以 `$HMIG/references/flow/conventions-template.md` §A 种子为基准；
+   `arkts-grammar-standards` 在场则一次性并入，缺失/失败即用种子、不重试。§A/§A2 按本工程 SDK 查证后保留；
+   `$HMIG/references/flow/ui-layout-semantics.md` 拷到 $SPEC/，UI 切片 SECTION 首行写"必读 + 过其 §5 自查门"。
+
+## 阶段三 · 开发（地基波 + 切片流水）
+
+> **目的** 先打地基派生跨片接口 → 照 manifest 自主实现各片，实现期只挂确定性门 ｜ **产出** `$SPEC/interface-manifest.json` + 各片代码到 `checked` ｜ **门** 每片 构建+闭合绿
+
+### 3a 地基波
+
+**`shape.foundation=inline`（默认 small 档）跳过本步**：地基单元（数据层/全局状态/主题）直接并入 3b 切片流水作 wave-0 依赖片，接口 manifest 在 wave-0 过门后派生。`wave` 照常：
+
+套件模板 `implement`（随技能 templates/ 分发，引擎不内置模板）：args 写 `$SPEC/fnd-args.json`，调用 workflow，顶层参数 `name='implement'`、`argsFile`、`runName='<应用名>/fnd_w0'`。3–6 单元一波（数据层/全局状态/主题接线/黄灯 shim），
+gate 写 `$ hvigorw` 增量构建（算法单元的 ArkTS Local Test 向量门经 `run-arkts-vectors.mjs` 一并入 gate；命令须静态可执行）。
+单元纪律：**按特性内聚拆分，内聚特性绝不强拆**——共享状态机/动画/手势或同一视觉单元的组件群、紧耦合同一数据契约的功能 = 一个单元；拆分只沿**松耦合边界**（页面间/层间/独立特性间）。**>20 断言或实现量大只是"找松耦合边界评估拆分"的信号，不是铁律**——找得到边界才拆，找不到就接受更长单轮；实现量大 = 确证无平台等价后需从零自研平台级原语（decimal/解析器/编解码）、源码 LOC 大、算法密集；拆成**可单轮完成**的子单元（如真需自研 decimal 拆 核心算术｜除法舍入｜开方pow阶乘）；共享文件的"桩"只许在真身
+**之前**落盘，真身单元覆写后桩方不得再写；一切"写入/恢复"类任务
+返回前用读文件工具确认目标文件已落盘（不靠 shell 列目录，跨平台）。波门全绿后立即过账：
+`ledger status --type slices --ids <全部地基片> --to accepted --evidence "地基波门+构建绿（波门验收）"`。
+
+波门绿后从地基真实代码派生跨切片接口 manifest：
+`$ node $HMIG/scripts/interface/interface.mjs extract --project $DST --dirs <地基各 targetPath,逗号分隔> --out $SPEC/interface-manifest.json`
+下游切片只准 import manifest 内符号；漂移由切片检查点确定性拦。
+地基接口变更：台账 `debts` 登记 → 改地基 → extract 重派生 → 受影响切片 `only` 定向复验。
+
+### 3b 切片实现流水（只做确定性验证，到 checked）
+
+实现期只挂
+**确定性静态门**（构建/selfTest/闭合——退出码裁决、重跑同答案、不靠真机、不 churn），
+判断性验证（verify/对抗）**不在此**，统一挪到阶段四末端跑一遍。故本阶段只把切片推进到
+ledger 的 `checked`（构建+闭合绿的确定性证据），**不过账 featureIds**（那是阶段四的判断性结论）。
+
+args 写 `$SPEC/slices-args.json`，调用 workflow，顶层参数 `name='mig_slices'`、`argsFile='$SPEC/slices-args.json'`、`runName='<应用名>/slices'`：
+**命令书写约定**（所有 `"$ …"` 命令）：在 `deveco run` 的启动目录（工作区根）执行；路径用 `$HMIG`/`$DST`/`$SPEC` 展开后的
+绝对或工作区相对路径；**不要 `bash -c '…'` 包裹**（模板会给 `smoke` 尾接 `--routes/--json`，包裹后尾接参数变成 bash 位置参数、
+引号错配，冒烟静默退化为仅冷启）；要切目录写 `$ cd <dir> && node …`。`build` 里的 `hvigorw` 不在 PATH 时（Windows 常见）
+换成前场报告 `toolchain.buildCmd` 的绝对路径命令。
+
+```json
+{
+  "goal": "<应用> 切片流水",
+  "dst": "$DST",
+  "build": "$ cd $DST && hvigorw assembleHap",
+  "closureSlice": "$ node $HMIG/scripts/closure/closure-suite.mjs --project $DST --stage slice --manifest $SPEC/interface-manifest.json",
+  "closureIntegration": "$ node $HMIG/scripts/closure/closure-suite.mjs --project $DST --stage integration --manifest $SPEC/interface-manifest.json",
+  "ledgerCmd": "node $HMIG/scripts/ledger/ledger.mjs --dir $LEDGER",
+  "instructionsFile": "$SPEC/instructions.md",
+  "conventionsFile": "$SPEC/conventions.md",
+  "smoke": "$ node $HMIG/scripts/smoke/smoke.mjs --project $DST --out $SPEC/smoke",
+  "unownedRoutes": [ { "route": "<确不迁移的注册路由>", "reason": "<实质理由；同时从 route_map 删注册>" } ],
+  "slices": [ { "id": "page-...", "targetPath": ["$DST/entry/src/main/ets/pages/<Route>Page.ets", "$DST/entry/src/main/ets/<实现目录>"], "deps": [], "route": "<注册路由名（页面片必填，归属校验+wave-smoke 用）>",
+                "expectation": "<台账断言>",
+                "card": "<该片自足工单：instructions.md 对应 SECTION 全文 + 涉及的接口签名/路由名>",
+                "featureIds": ["F1","F2"], "selfTest": "$ node $HMIG/scripts/vectors/run-arkts-vectors.mjs --project $DST --module entry --scope <域>Gate（算法片才配）" } ]
+}
+```
+
+**wave-smoke（模板机制，波门自动跑）**：每波 checked 的页面片装机冒烟，判定全可证（装机输出·前台 bundle·
+hilog 着陆页名==route·着陆页子树节点）——崩溃=修一轮不收敛即停轮；misland/nohook=接线问题修一轮；
+hollow=case 立案继续（登录墙/空态被立案属正常：模型裁决"需登录/空态合理"即 waive，登录后纵深归 4b）；
+环境阻塞（无设备/装机失败/hap 过期）exit 3 记 `summary.smoke[].status=blocked`，**不算通过，报告如实标"未冒烟"**。
+
+**blocked 清账（3b 收口必做）**：实现者按纪律不动壳/共享件、写进返回值 `blocked` 的项，模板落台账 `debts`（`blk-<片>`）并汇总
+`summary.blocked`——主会话逐条处置（壳/共享件改动自己改或派 fix agent，改完复跑 closure），**处置完才进阶段四**。
+**降级裁决（3b 收口必做，与清账同一轮）**：实现者报的 deviations 由模板登记为 `status: pending` 的降级（`{kind, note, probe}`），
+**待裁决的降级不豁免任何断言**。先跑 `$ node $HMIG/scripts/ledger/ledger.mjs verify --dir $LEDGER --sdk auto`（此时它必然
+红——每条 pending 都列为违规，这是裁决清单不是失败）：kind=no_equiv 的条目其 symbols 列出的 API 在 SDK d.ts 里有声明的会单独列出——这些直接 `status --type degradations --id X --to rejected --reason "SDK 有 <符号>"`
+并回涉事片实现（`only:[片]` 续跑或定向修）；其余逐条核 kind、symbols 与 probe 是否成立（approx 只许视觉/动画近似、policy 须指出平台策略、
+source_stub 须指出源码桩位置），成立的 `--to open`，不成立的 `--to rejected` 回片。裁决完 verify 无 pending 才进阶段四。
+
+**卡片机械切分（模板机制，装配零动作）**：模板启动自动读 instructionsFile/conventionsFile 各一次，
+按 `## SECTION: <id>` 切分后把「头部公共说明+规范全文+该片 SECTION」注入该片 prompt，agent 免读 $SPEC/ 文件；
+`card` 字段可显式覆盖；无对应 SECTION 的片回退文件指路。单片 SECTION 控制 ≤6K。
+**波序纪律（首屏先行）**：wave-0 = 首页垂直片（首页真实数据流+其直接依赖的核心片），
+构建+装机首屏可见真实数据后，其余切片再开闸；首页不通不铺面。
+
+**跨波依赖闭包与路由归属**：`slices[]` 是**整个计划的切片全集**（所有页面片含后续波的、已完成的地基片一并列进来，未执行的 `expectation` 标注"本轮不执行"），只用 `only:[<本波片>]` 限定执行集——模板视不在执行集的依赖为已满足外部依赖（extSat，只记日志不重跑）。两道校验都按 `slices[]` 全集：依赖闭包（否则报 `切片 X 依赖不存在的 <core-id>`）与路由归属（route_map 每个注册页都要落在某片 `targetPath` 内，否则报 `路由 X 的注册页 … 不在任何切片 targetPath 内`；只有确不迁移的路由才写 `unownedRoutes`）。每波只改 `only`，不重写 `slices[]`。
+
+检查点构建不带 `--no-daemon`；骨架门首构建与向量门 selfTest 保留 `--no-daemon`。consumers 撞名误报时建 `$SPEC/closure-idioms.json` 覆盖表，closure 命令加 `--idioms $SPEC/closure-idioms.json`。
+
+失败续跑：`resumeFrom` + `only:["<失败切片>"]`；绝不整波重来、绝不重验已 checked 的片。
+featureIds 此处可不填（末端验收按台账断言归属过账）。
+
+## 阶段四 · 测试（末端验收 + 运行时验证）
+
+> **目的** 判断性验收一遍 + 集成闭合 → 上机确认核心路径与 on_device 契约 ｜ **产出** 片 `accepted`、断言 `passed` ｜ **门** acceptance 绿 + 闭合 `final` 硬违规清零 + 核心路径过
+
+### 4a 末端综合验收（判断性验证唯一一遍）+ 集成闭合
+
+**验证分层：用最少的验证命中最重要的问题**。每条断言由**最便宜的够用层**验证，不均匀铺：
+- **确定性层（免费，覆盖大多数）**：build 绿 + 闭合绿（含 stubs/permissions/api-guards/safearea 静态门）+ 黄金向量探针。
+  一个片的断言若**全被确定性层覆盖**（纯逻辑有探针、UI 有闭合+静态门）→ 直接过账 accepted，**不进 acceptance、不花判断 agent**。
+- **判断层（贵，只留给确定性证不了的）**：断言是**行为/结果契约判断**、无探针无静态检查覆盖的片，才进 units。
+- **真机层（阶段四·运行时验证 4b，只留 on_device-only）**：见 4b。
+
+**判断性验证一次做完**（不逐片、不重验）。args 写 `$SPEC/accept-args.json`，units **只放判断-必需的片**
+（含 expectation + featureIds；确定性层已证的片不放），调用一次
+调用 workflow，顶层参数 `name='acceptance'`、`argsFile`、`runName='<应用名>/accept'`：
+
+```json
+{
+  "goal": "<应用> 末端验收",
+  "build": "$ cd $DST && hvigorw assembleHap",
+  "planFile": "$SPEC/instructions.md",
+  "conventionsFile": "$SPEC/conventions.md",
+  "ledgerCmd": "node $HMIG/scripts/ledger/ledger.mjs --dir $LEDGER",
+  "priorFile": "$SPEC/accept-prior.json",
+  "units": [ { "id": "page-...", "targetPath": "...", "expectation": "<台账断言>",
+              "featureIds": ["F1","F2"], "sliceIds": ["<单元id≠台账切片id时给映射，缺省=id>"], "risk": true } ]
+}
+```
+
+**复跑机制内置（不靠主会话转录）**：`priorFile` 让未过单元的判词跨 run 自动接力成限幅复验；台账已 `accepted` 且无待复验判词的
+单元自动跳过（`force:true` 强制全验）。复跑只需同一份 args 再调一次（可加 `only`），禁手工重写 units 从零重验。
+
+**`risk` 靠台账派生 + 最小化**：`shape.adversary=false`（默认 small 档）一律不置；`derived` 时置 `risk:true` **仅限**碰某 `degradations`
+（无鸿蒙等价）**且无法在运行时验证（4b）真机验证**的片（如纯后台逻辑/无 UI 触发路径）；其余不置。宁缺毋滥，通常全应用 0–2 片。
+
+acceptance 一遍：构建绿 → 逐单元 verify（判断性）→ 失败定向修+复验 → （极少数）对抗否证 →
+**过账**（slice→accepted、featureIds→passed，on_device 自动跳过；判词里的 `文件:行` 随过账写入证据）。不收敛的单元 only 续跑，不整体重来。
+过账证据须可回溯到代码位置：台账 `verify` 报"静态 passed 证据不可定位"条数、`render` 显示可定位比例——散文证据不算验过。
+**差异不许自我豁免**：与源不一致默认是缺陷，只有三种证据可豁免——用户明确豁免过／系统控制的 UI（引官方文档）／证实随机内容（两次采样不同）。
+**smoke 立案清账**：验收前过一遍 `$SPEC/smoke/*.json` 的 hollow/misland/nohook/not-foreground/expect-miss/crash 记录，逐条裁决
+（登录墙/空态合理=waive 带理由；真空壳=回涉事片修；misland/nohook=接线修）；`status=blocked` 的波=无运行时证据，报告如实标——冒烟立案不许悬着进报告。
+
+**集成闭合**（确定性全局判定，一次）：`$ node $HMIG/scripts/closure/closure-suite.mjs --project $DST --stage final --waivers $SPEC/closure-waivers.json --json $SPEC/closure/closure-final.json`
+（有 PRD 时加 `--prd <PRD 文件>`，字面锚点门按它对账；台账缺省取 `$DST/spec/ledger/ledger.json`，不在此处的加 `--ledger`）
+- 硬违规清零；软立案逐条回源码裁决：真问题 → 回相关切片修（only 复跑）；合法 → 豁免票写进
+  `$SPEC/closure-waivers.json`（`{"waivers":[{type, reason≥20字, name 精确 | match 正则 + sampled:[≥3 条逐条核过的实例]}]}`），
+  断言侧同步 `ledger status --type features --id <断言> --to waived --reason "<实质理由>"`；
+  **模式票 `match` 不得无界（能匹配任意文本的正则无效），`sampled` 须 ≥3 条本次报告里真实存在的立案（name 或 file:line），否则票无效**；
+  **`scaffold_page_residue`（注册页仍是骨架）在 final 是硬违规，不可豁免**——实现该页（only 续跑拥有它的片）或删注册+删骨架文件；
+  **`nav_registry_unparseable` 特例**：静态核对不算豁免依据——要么改回标准注册（route_map），
+  要么附**逐目的地真机跳转证据**；
+  **字面锚点三类**（`literal_missing` 断言引用的 id/文本产物里没有；`prd_uncovered` PRD 需求行无断言；`prd_anchor_stale` 锚点行号越界=PRD 变了）：
+  缺的 id/文本是 PRD/断言明写的就回涉事片补，不是需求（约束/说明/动态值）才豁免，别批量豁免；
+- 退出码 2（立案未裁决完）不许进下一阶段。
+- **记门（门历史必须反映实况）**：`$ node $HMIG/scripts/ledger/ledger.mjs gate --dir $LEDGER --name closure-final --stage final --ok <true|false> --evidence "硬违规X·软立案Y已裁决"`。
+
+### 4b 运行时验证（有界确认，不是猎 bug）
+
+**定位（决定时长的关键）**：会抛 API/权限声明/**转译桩**的死按钮已由**静态门**（api-guards/permissions/stubs）在集成闭合
+确定性拥有——**本步不再穷举重猎这些**；模型自写组件的点击死、缓存回调崩溃这类静态门看不见的只能靠本步走查
+（`tapsNoChange`、崩溃日志）暴露，出现即按第 5 条归因；布局避让门只出**软立案**（非确定性），A 级走查逐页截图时**顺检顶部重合兜底**。真机只做静态验不了的两件事：①**确认核心用户路径真能跑通**
+②**验 on_device-only 契约**（振动真震、通知真弹、权限运行时真授予、精确定时）。随静态覆盖变强，真机应越来越短。
+
+0. **走查清单不现场编**。无 PRD 时：`$ node $HMIG/scripts/ledger/ledger.mjs list --dir $LEDGER --kind on_device --status untested`
+   输出即待验全集，清单外只补"核心路径页序"这一项走查骨架。**有 PRD 时：清单 = 上述 on_device 全集 ∪ PRD 的编号场景全集**
+   （PRD 只加验收场景，不替换源码来的 on_device 契约）——按页面/数据状态把共通场景
+   合并成流（如队列的 8 条场景一条流串完、编辑页的 4 条一条流），每条场景必须落进某个流；禁止自选几段"核心路径"代替场景清单
+   **PRD 场景的计划步骤照 PRD 步骤逐条对应**：为走通而插入的导航步（如先点某标题打开面板）不是 PRD 步骤，须在该步写 `"extra": true`——
+   带 extra 步的场景只能记"走通但契约未满足"（PRD 要求该控件在当前界面上直接可点），不算通过。
+   **验证深度**：每个流必须走到**操作之后的可观察结果**（状态变化、文案变化、列表增减、重启后仍在），"页面可达 + 字面量出现"不算验证；
+   四类交互每类至少真做一遍：导航（含**从子页返回后再用底部导航/入口**）、列表操作（长按/滑动/多选/排序）、
+   编辑回写（改名/改描述/删条目后列表与详情同步）、持久化（改成非默认值后冷重启）。
+1. **走查驱动只用 `$HMIG/scripts/smoke/walk.mjs`（确定性·单飞·可证），禁止现场自写 python/node uitest 脚本**
+   `walk.mjs help` 看用法：逐步交互用
+   `start/dump/tap/type/expect/wait/back/swipe/scroll/shot/alive`；核心路径写成步骤数据 `$SPEC/4b/<路径名>.json` 后
+   `$ node $HMIG/scripts/smoke/walk.mjs run $SPEC/4b/<路径名>.json --out $SPEC/4b/<路径名>.report.json --shots $SPEC/screenshots`
+   ——报告即证据（逐步结果+截图+崩溃），过账 evidence 指向它。
+   位置类断言（顶部/底部/右下/悬浮按钮等）不读码裁决：对报告页面字典的 `geometry`（或 `walk.mjs dump` 的 `geometry` 行：
+   节点中心相对根节点的归一化坐标与 bounds，脚本只量不判）核对源/PRD 要求的位置，不符即缺陷。设备用 `--device <hdc key>`（与冒烟同一台；环境变量 `HMIG_HDC_TARGET` 也认，但不要写 `VAR=x 命令` 前缀）；
+   每个 `tap` 步记 `changed`（点后控件树是否变化），报告 `tapsNoChange` 计"命中却无变化"的点击数——复盘先看它：
+   连续出现即吞点击/接线断，按第 5 条归因；
+   **先跑机械计划**：`$ node $HMIG/scripts/smoke/walk.mjs plan --ledger $LEDGER/ledger.json --project $DST --out $SPEC/4b`
+   为每个带 route 的片生成"直达→存活→probe 该片断言字面量→截图"计划并打印 run 命令，逐份跑完即逐页可达性、崩溃与字面量出现率证据；
+   probe 只记见到/未见不判失败（断言含空态/校验提示/保存后提示/用户键入等状态相关文案，落地页不可能一次全显），
+   "未见"不是缺陷，是提示核心路径计划该在哪个状态下 expect 它。每份报告的 probe 步带**页面字典**（该页全部 text/id/可点击项），
+   写核心路径计划时照字典取 text/id，一次写准，不要再手工 dump 猜文案。
+   你只写跨页交互的流计划（有 PRD 时按第 0 条的场景分组，一流一份），不重复逐页枚举；**有 PRD 时每份流计划顶层写
+   `"scenarios": ["S12","S13"]`**（该流覆盖的 PRD 编号场景）——阶段五 `render --walks $SPEC/4b` 按它机械汇总"场景 N/M"，不手写。
+   **直达边界**：`start --route` 不经过首页，首页承载的状态恢复（读偏好/数据库）不会执行，看到的是种子/默认态。
+   **持久化类断言**（"重启后保留"）必须 `start` 正常冷启 + 应用内导航核；且先把状态改成**非默认值**再重启——用默认值验重启证明不了持久化
+   **首启/fixture/持久化类断言在干净态验**：`start` 步写 `"fresh": true`（清应用数据后冷启），评测用例每条都清数据。
+   **走查期间不并行跑任何 hdc/uitest 命令**（并发即空输出）。
+   verify_ui 不在阶梯里：它报"应用未安装"是其内部解析 bm dump 失败的误报（本机 64 次启动 11 次），与签名无关；
+   确要用只作补充证据，报未安装先 `walk.mjs alive` 核实再重试一次，不因此改走签名、不据此降级归因。
+   `start_app`/`devecocli run --skip-build`、`devecocli device list` 照用；`build_project` 网络不可达时以 `$ hvigorw assembleHap` 退出码为构建证据。
+   **滚动只用驱动的 `swipe`/`scrollUntil`**（步骤 `{"op":"scrollUntil","match":"<目标>","dir":"up","within":"type:^List$"}`；
+   `within` 缺省整屏、横滑区给容器匹配加 `--nth`），在命中容器的边界内 70%→30% 滑，折叠线下的项、触底加载、横滑条都能走到；
+   禁止自算坐标注入 swipe/fling。折叠线外内容不再靠"直达路由或 Back+重进"绕过——那验不到列表操作。
+2. **A 级=按清单单遍确认（硬时间盒，自装 HAP 起计，只计走查本身）**：无 PRD 时 small 档 15 分钟、standard 档 30 分钟；
+   **有 PRD 时按场景数给：每 10 条场景 10 分钟，上限 90 分钟**。走查中发现的缺陷按第 5 条定向修+只复验涉事流，**修复与复验计入时间盒**；
+   到点没走到的场景转 untested **逐条写进报告 PRD 栏**，不是丢弃、更不许记"全过"。
+   **有登录/账号的应用，登录流排清单第一位**（有凭据或验证码通道就真登录，没有则把依赖登录的场景记 blocked，不绕过）——
+   未登录时大半页面停在错误/空态，Success 态代码没有真正执行，走查"通过"不成立。
+   装 HAP → 按清单走（无 PRD 时是应用主价值链：列表→详情→核心操作→设置），
+   逐页截图存 `$SPEC/screenshots/`。只补测静态门覆盖不到的**功能交互**（长按改数据/编辑保存/退后台回前台的状态对齐）；
+   **别再逐个枚举猎崩溃/层序**（静态门已拦）。**超时间盒的边角一律转 untested，不深挖、不 fix-loop**。
+   写"无法到达"前必须差分：同一路径源端走一遍——源能到目标不能到=页面缺失（缺陷），两端都到不了才写不可达。
+3. B 级：体检标记的 crypto/扫码/网络/媒体/振动/通知授权断言必须真机；模拟器不算验证。
+   **权限弹窗照常弹**：未签名调试包上系统授权弹窗一样弹出，
+   `walk.mjs dump` 取弹窗按钮文案后 `tap` 允许即可；**不得以"未签名/模拟器抑制弹窗"为由跳过录音/相机等硬件 happy path**——
+   模拟器上至少走到授权后的首个状态并截图，硬件真值留真机。要清权限重验用卸载重装，不改签名。
+4. 逐断言过账，**一律带 `--layer device`**：`ledger status --type features --id X --to passed --layer device --evidence "<走查报告>.report.json#<步号>"`
+   （证据必须指到报告里 ok 的那一步，台账会核；骨架计划的 alive/shot 步不是行为证据）；
+   走查证实坏了的断言先 `--to failed --layer device`（不是只落债），修好复验后再 `--to passed --layer device`；验不到留 untested 或 waived（带理由）。
+   真机结论（device）不会被静态判断改写；报告按"真机/静态"分列 passed 与 failed。
+5. **发现问题 → 先读报告的失败类型再动手**：每个失败步带 `kind`——`target_missing`（附页面字典，照它改计划）、`target_ambiguous`
+   （用 `--nth`/`within`）、`expect_missing`（附页面字典）、`process_died`（附 `crashDetail`：Reason/Error message/首个应用源码帧，
+   直接定位到 `entry/….ets:行`，不用再去设备上读 faultlog 二分）；`tap` 步带 `occludedBy` 时点在弹层/对话框遮罩上，
+   目标在弹层内用 `"within": "type:^SheetPage$"` 之类限定容器。**只有 kind 指向应用缺陷时才改代码**。
+   → **目标化修**（限涉事片）→ **只复验涉事片一次**（`only:[涉事片]` 或重跑该份走查计划）→ 过账。
+   **同一缺陷只允许一次定向修 + 一次复验**：复验仍失败即 `--to failed --layer device` 记账 + 立案交阶段五，**不再改代码**；
+   报告 `failStreak ≥ 2` 就是停手信号。**铁律：禁重跑整轮 acceptance/对抗；修一片验一片，不牵动全局。**
+   **把崩溃/冻结/点击丢失/渲染异常归因为"平台级缺陷"或某个 idiom 之前必须走归因三步，缺一步不得写成约定、不得据此降级契约、
+   改写全局组件或"如实立案不深挖"**：
+   ① 复现：同一构建 ≥2 次同结果（崩溃看 faultlog 首帧+寄存器特征一致；冻结/点击死看同步骤同现象）；② 反转：对每个嫌疑条件单独撤掉→绿、装回→再现，各 ≥2 次，
+   一次只变一个变量（换 URL 同时换了格式和数量不算对照）——写法/idiom 类规则靠这一步就能坐实；③ 隔离：**只有**要下"平台级缺陷"结论时
+   才必须把嫌疑结构放进 `devecocli create` 的空工程（`$SPEC/probe/`）复现——空工程不复现 = 不是平台问题，回到 ② 找本工程条件。
+   ①② 齐才可写 §J 规则或 A3 待验条目；未齐的只能在涉事片记"实测缓解（机制未证）"+ 台账 debts，不进 conventions、不进语料回流。
+   **归因有时间盒：单个崩溃/冻结/点击死 30 分钟**，到点未坐实就按
+   "实测缓解 + debts（附已排除的条件清单）"收口，别继续猎；已坐实的规则连同反转数据写进 §J，下一轮免重猎。
+6. **收口记门**：`$ node $HMIG/scripts/ledger/ledger.mjs gate --dir $LEDGER --name runtime-4b --stage integration --ok <true|false> --evidence "<证据>"`；
+   evidence 无 PRD 时写"核心路径X页·on_device 过账N/转untested M"，**有 PRD 时必须写"场景 N/M 已走·失败 K 已修 J·未走：<场景号>"**；
+   `--ok true` 只在核心路径计划报告 `ok:true` 且 `tapsNoChange` 为 0 时给，否则 `--ok false`——门红不阻断收尾（阶段五照走、报告如实），
+   但不许把"部分完成"记成 true。
+
+## 阶段五 · 发布回流（收尾）
+
+1. `$ node $HMIG/scripts/ledger/ledger.mjs verify --dir $LEDGER --sdk auto --require-gates closure-final,runtime-4b` 必须过
+   （证据纪律 + 无待裁决降级 + 阻塞债已清 + 两道门有记录；门的 ok 值不在此核，门红照常收尾但报告如实）。
+2. 报告投影，**PRD 覆盖对照表与场景走查表都由脚本出，不手写**：
+   `$ node $HMIG/scripts/closure/check-anchors.mjs --project $DST [--prd <PRD 文件>] --json $SPEC/closure/anchors.json`
+   `$ node $HMIG/scripts/ledger/ledger.mjs render --dir $LEDGER --anchors $SPEC/closure/anchors.json --walks $SPEC/4b --out $SPEC/REPORT.md`
+   （无 PRD 时省略 check-anchors 与 `--anchors`；`--walks` 始终给，它同时汇总核心路径计划的结果）。有 PRD 时报告**两栏分列**：
+   源码全量还原（页面/能力逐项四态，passed/failed 按真机/静态分列）与 PRD 场景验证（`--walks` 出的逐条场景 通过/未过/未走，
+   和 4b 门的 N/M 对得上）——PRD 覆盖率不当完成度报。
+3. 回流（**只产候选，不改套件**）：本轮新坑逐条写 `$SPEC/feedback.md`（现象+证据+建议落点：数据表/conventions/门），
+   连同 `$SPEC/lib-adjudications.json` 一起交维护者——语料/数据表只由维护者按"两次原则+真机验证"裁决入库，流程不直改。
+4. 汇报：报告路径 + 断言四态数字 + 降级全量清单 + 遗留债务；"验过"与"没验到"分列。
+
+## 语料分配（自有知识为准、自足；官方/宿主技能仅可选增强）
+
+**官方语料已吸收进自有知识，迁移不引用/不依赖官方技能。** 官方/宿主技能仅在场时可用作一次性增补，
+**缺失或加载失败即走自有知识、不重试、不依赖**。
+
+| 用在哪 | 自有知识（为准，恒可用，自足） | 可选增强（在场才用·一次不重试·缺失跳过） |
+|---|---|---|
+| conventions §A | `$HMIG/references/flow/conventions-template.md` §A 种子 | arkts-grammar-standards |
+| 构建/运行期修错 | `references/flow/build-error-patterns.md` + `platform-api-guards.md` + 构建输出错误清单 | arkts-error-fixes / arkts-runtime-fix |
+| 工程创建 | `$ devecocli create --project-path $DST --app-name … --bundle-name …`（宿主自带，无头可跑） | deveco-create-project 技能（同一脚本的会话式封装） |
+| UI 切片 | `$HMIG/references/topics/ui-alignment/README.md` + `flow/ui-layout-semantics.md` | hmos-arkui-develop-skill |
+| 状态管理切片 | conventions §A2 状态条目 | hmos-arkui-statemgt-migration |
+| 沉浸式/安全区 | `scripts/closure/check-safearea.mjs` 门 + conventions §E | hmos-multidevice-avoid-areas |
+| 平台行为查证 | grep 本机 SDK `.d.ts` 声明为最准证据，结论进 conventions 标出处 | — |
+| 崩溃分析 | hdc 拉 faultlogger + 按栈回源码 + `platform-api-guards.md` | hmos-jscrash-analysis |
+| 多语言（源含多 locale values-*） | `$HMIG/references/topics/i18n/README.md`（references/ 按需） | — |
+| 应用名称/图标规格 | `$HMIG/references/topics/app-identity.md`、`$HMIG/references/topics/icon-sizing.md` | — |
+| 域知识（媒体/登录/支付等） | `$HMIG/references/topics/system-capabilities/*` + `topics/library-migration/*`（按加载索引取） | — |
+
+表未覆盖的场景按 `$HMIG/references/README.md` 的**加载索引**按需取件（目录页，不整目录搬运）。
+
+技能装载集按**有效性证据**治理（不按"用过"）：实现/修复 agent 须报一句所传技能是否产生决定性证据；阶段五汇总这些票据，裁决下一单默认装载集与吸收/裁撤对象。
+波级 skills 最多 1–2 个，切片特有放 slices[i].skills；名字先核对会话技能列表，不存在不传、走兜底列。
+
+## 脚本 × 模型协同（谁立案，谁裁决）
+
+脚本立案（确定性扫描/三态输出/退出码），模型裁决（violation 修复；case 回源码裁决——修或台账豁免带理由；unresolved 补人读判断）。修复纪律随卡片注入（conventions §A2/§E：会抛 API try/catch 降级、权限声明进 module.json5、避让走 `avoidAreaChange`、`TODO(attrs)` 的 `onClick` 必须接线）。
+
+## 中断恢复
+
+读 `$LEDGER/ledger.json` 与 `.deveco/workflows/` run 报告；workflow 用 `resumeFrom`，
+部分失败用 `only`；台账在，不重做已完成阶段。
+
+## 退出码
+
+0 通过 · 2 未裁决立案/用法错 · 3 环境错 · 4 黄灯 · 5 红灯 · 10 硬违规