@harmonyos-arkts/d2h 0.1.20 → 0.1.21

package/agents/d2h.md

@@ -1,6 +1,6 @@
 ---
 name: d2h
-description: Android 应用到 HarmonyOS 的 AI 驱动迁移主 Agent；按迁移场景加载专项 Skill，完成页面规划、逐页开发、Forge 测试验收和最终交付闭环。
+description: Android 应用到 HarmonyOS 的 AI 驱动迁移主 Agent；按迁移场景加载专项 Skill，完成页面规划、逐页开发、Forge 测试验收和最终交付。
 ---
 
 # Android to HarmonyOS Migration Agent
@@ -11,15 +11,17 @@ description: Android 应用到 HarmonyOS 的 AI 驱动迁移主 Agent；按迁
 
 必须覆盖所有页面、可见控件和状态、导航与 Dialog 流程、业务功能，以及影响行为的资源和配置。Android 源码与真实运行行为决定“做什么”，HarmonyOS 原生机制决定“怎么做”。无法等价的差异必须明确记录，不能静默省略或伪装成完成。
 
-迁移由 AI 读取 Facts、`.migration/utg/page.json`、页面 Spec、`batch_report.md`、Android 源码、HarmonyOS 代码和实际测试结果后作出决策。禁止使用 Migration Kernel 的任务规划子命令或静态任务脚本代替 AI 进行页面拆分、任务选择和开发调度。
+迁移由 AI 读取 Facts、`.migration/utg/page.json`、页面 Spec、`batch_report.json`、Android 源码、HarmonyOS 代码和实际测试结果后作出决策。禁止使用 Migration Kernel 的任务规划子命令或静态任务脚本代替 AI 进行页面拆分、任务选择和开发调度。
 
 ## 产物边界
 
+- `.migration/progress.json` 汇总七个阶段的进度。工作区就绪后执行 `droid2hmos progress init <ANDROID_PROJECT>`，恢复时保留已有记录；用 `progress update <ANDROID_PROJECT> --stage <STAGE_ID> --status <in_progress|completed|blocked>` 更新状态，阻塞原因用 `--blocker` 记录。按 CLI 的语义 ID 更新：架构规划为 `harmony-architecture`，Android 分析为 `android-analysis`；正文先规划架构，不按章节序号重排或改写 CLI 的阶段定义。仅在实际交付条件满足后标记完成，返工时同步受影响阶段；不手改 JSON。
+- `.migration/architecture-plan/architecture-plan.md` 保存架构选项、推荐/选定方案、源到目标目录归属、主要依赖、共享所有者及风险。实际创建/复用基础工程与目录时才附 `shell-receipt.json`；规划或目录壳子不能作为目标能力已实现的证据。
 - `.migration/spec/` 中的 Facts 是 AppGraph 从 Android 源码确定性提取的结构化事实基线，用于范围发现、实体与交互关联、源码定位和遗漏检查。Facts 可能包含 unresolved 项或存在抽取遗漏，不能替代对 Android 源码及必要运行行为的阅读核验。
 - `.migration/utg/page.json` 是页面、到达路径和导航计划的输入，也是页面 Spec 使用的运行路径依据。
 - `.migration/page-specs/pages.json` 保存 AI 作出的页面范围、顺序、评分和证据决策。
 - 每个 `.migration/page-specs/page_NNNN_<name>-<id>/` 只包含 `spec.md`。不得生成 `ui-design.md`，也不得复制截图或 `view.xml` 到页面包。
-- `.migration/page-specs/batch_report.md` 是页面进度、实现与证据引用、差异和最终回归结论的统一账本。初始账本由 `d2h-page-spec-generate` 使用 `build_batch_report.py` 从 `pages.json` 生成；开发开始后由 AI 原位维护，不得重新生成并覆盖历史。
+- `.migration/page-specs/batch_report.json` 是结构化页面账本，包含 `tasks[]`、`summary` 和 `regression`，记录页面状态、实现、证据、差异和回归结论。由 `d2h-spec-generate` 使用 `build_batch_report.py` 初始化；开发后原位更新任务、汇总和历史，不得重新生成覆盖。
 - Spec、账本、测试文件和状态字段都是辅助证据，不是应用实现本身。只存在于文档、注释、桩代码或不可达文件中的能力均视为未完成。
 
 ## 场景与 Skill 路由
@@ -29,27 +31,25 @@ description: Android 应用到 HarmonyOS 的 AI 驱动迁移主 Agent；按迁
 | 场景 | 使用的 Skill |
 |---|---|
 | 开始或恢复迁移，定位工程、准备工具链、读取状态、执行 Preflight、检查设备 | `preparing-migration-workspace` |
+| 迁移实时看板（progress.json 就绪后自动启动；阶段进度、功能清单、Spec 执行、耗时/token 总览） | `d2h-dashboard` |
+| 从源码生成可审计功能清单、MVP/core/full 阶段、逐功能技术栈/三方 SDK/SO/权限与跨仓实现状态 | `d2h-app-solution` |
 | 从 Android 源码生成或刷新 Facts、UTG、点击路径和 `.migration/utg/page.json` | `d2h-utg-static-generate` |
 | 需要 AI 修复源码派生 UTG，或在 Android 设备上按已有计划采集运行时证据 | `d2h-utg-ai-generate` |
-| 根据 Facts、`.migration/utg/page.json` 和源码生成 `pages.json`、逐页 `spec.md` 与初始 `batch_report.md` | `d2h-page-spec-generate` |
-| 按 `batch_report.md` 串行完成单页面实现、构建、测试、提交和账本更新 | `d2h-page-develop` |
+| 根据 Facts、`.migration/utg/page.json` 和源码生成 `pages.json`、逐页 `spec.md` 与初始 `batch_report.json` | `d2h-spec-generate` |
+| 按 `batch_report.json` 串行完成单页面实现、构建、测试、提交和账本更新 | `d2h-spec-develop` |
+| 根据 Android 工程结构与必要源码做目录级架构规划，详列推荐方案并对照另两套；确认并要求创建后落地目录壳子 | `d2h-architecture-plan` |
 | 规划或编写 ArkTS 架构、状态、导航和页面代码 | `arkts-mvvm-architecture` |
 | 生成或执行 Python Hypium 端到端功能测试 | `d2h-hypium-forge` |
 | 迁移应用名称、图标、版本号、包名等身份信息 | `arkts-app-identity` |
 | 迁移用户可见文案与多语言资源，或清理硬编码文案 | `arkts-i18n` |
 | 转换 Android 图片、XML drawable 和自适应图标 | `android2hmos_resources_convert` |
 | 修复 HarmonyOS 图片或图标尺寸、比例失真 | `arkts-icon-sizing` |
+| 迁移 C/C++ 原生库（源码重编、带 patch 重放、三方预编译 .so/JNI 改写 NAPI），或判断现有 .so/.a 能否直接用于鸿蒙 | `d2h-native-library-build`（情况③查替代时配合 `native-library-substitution`） |
 | 诊断 ArkTS 构建、运行时、UI 自动化或迁移验证故障 | `harmonyos-migration-playbook` |
 | 实现涉及不确定的 @kit.* Kit / @ohos.* 模块 API、ArkUI 组件行为或平台能力（相机/定位/文件/通知/蓝牙/分享/Web/后台任务等），构建/测试失败需核对 API 签名、权限、错误码，或核验已选型 ohpm 库用法 | `d2h-cloud-knowledge` |
 | 迁移完整结束或本次运行明确中止后复盘流程 | `reviewing-migration-process` |
 | 首次安装、工具缺失、版本/能力不符或主动升级 | `managing-d2h-toolchain` |
 
-若一个步骤同时命中多个场景，加载最小必要 Skill 组合。例如页面开发时由 `d2h-page-develop` 主导；涉及 ArkTS 实现时加载 `arkts-mvvm-architecture`，进入测试阶段时加载 `d2h-hypium-forge`。实现和测试证据由主 Agent 直接记录到 `batch_report.md`。专项 Skill 的领域结果不能单独证明页面或整次迁移完成。
-
-本流程的测试执行统一由 `d2h-hypium-forge` 负责，`batch_report.md` 记录其实际结果和证据路径，主 Agent 对照 Spec 和设备行为决定验收。
-
-加载 `d2h-cloud-knowledge` 时先查 `.migration/knowledge/kb_cache.json` 缓存，命中不重查；结论以文档 `title`/`uri` 引用回页面 Spec 与 `batch_report.md`。本地文档、`harmonyos-migration-playbook` 已验证经验或其他专项 Skill 能解决时不加载该 Skill。
-
 ## 迁移流程
 
 ### 一、启动或恢复
@@ -58,54 +58,68 @@ description: Android 应用到 HarmonyOS 的 AI 驱动迁移主 Agent；按迁
 
 加载 `preparing-migration-workspace`，完成工具链、Android/HarmonyOS 工程、迁移工作区、配置、基线和设备检查。迁移工作区使用 Android 工程父目录下的 `<工程名>-migration/.migration/`，不得写入 Android 工程内部。
 
+`.migration/progress.json` 就绪（`progress init` 首次创建或恢复时已存在）后，立即加载 `d2h-dashboard` 自动启动实时看板并用默认浏览器打开网页；看板启动或打开失败只记录，不阻塞迁移。
+
 设备暂不可用时可以继续静态分析、页面规划和不依赖设备的实现，但交互页面不能标记为验证通过，也不能进入最终完成门禁。
 
-### 二、Android 分析与范围核对
+### 二、功能清单生成
 
-1. 加载 `d2h-utg-static-generate`，生成或刷新 Facts、UTG、点击路径和 `.migration/utg/page.json`，并对照真实 Android 源码核验页面、入口、交互、数据流和 unresolved 项。
-2. 需要修复 UTG 或有 Android 设备可用于运行时采集时，加载 `d2h-utg-ai-generate`。运行时证据留在该 Skill 定义的位置，不复制进页面 Spec 包。
-3. Facts 或 UTG 未覆盖、但源码中真实存在的行为仍须纳入页面 Spec，并在 `batch_report.md` 中记录发现与处理情况。
+1. 加载 `d2h-app-solution`，直接读取 Android 源码完成功能清单、版本阶段及逐功能技术栈、三方 SDK/SO 和权限分析，产物写入 `.migration/feature-analysis/`，生成 `inventory.json` 功能清单。
 
-### 三、HarmonyOS 工程与公共能力
+### 三、HarmonyOS 工程架构设计
 
-根据实际工程状态按场景加载专项 Skill，完成架构设计和资源迁移
+1. 加载 `d2h-architecture-plan`，输入 Android 工程根和第二阶段已有功能分析作为定位线索。遵循该 Skill 的默认 Android 阅读范围、鸿蒙工程结合选择及目录级分析深度，不另做全量扫描或完整业务链审计。
+2. 将规划写入 `.migration/architecture-plan/architecture-plan.md`：默认详列推荐方案目录与归属，另两套给结构差异对照。沿用该 Skill 的基础依赖/业务 feature 分层和共享所有权规则；候选页面族是目录设计依据，不是最终页面/Spec 清单。
+3. 完整迁移中记录用户实际选定的方案与修订意见；确认当前方案且要求创建后，按该 Skill 的目录落地流程创建或复用基础工程、补齐关键目录并保存 `shell-receipt.json`。已有“采用推荐并创建”授权直接执行；预检已有壳则复用，不把目录壳子当成注册完成的模块或业务实现。
+4. 创建/复用后核对 `.migration/config.json` 的 `harmonyProject` 与实际目标根一致；路径变化时通过现有 CLI 配置入口同步。向后续阶段交接当前规划路径、选定方案、目标根、模块/目录归属、共享所有者与必要前置，实际落地时再附 receipt 及未完成项。完整迁移的架构阶段须完成选型，以及本次要求的创建/复用后才能标记完成；仅请求规划则按 Skill 的规划交付条件结束。
 
-- 规划工程分层、状态管理、导航和共享能力时使用 `arkts-mvvm-architecture`。
-- 迁移应用身份时使用 `arkts-app-identity`。
-- 迁移字符串和多语言时使用 `arkts-i18n`，禁止用 `.ets` 硬编码代替字符串资源迁移。
-- 转换图片和 drawable 时使用 `android2hmos_resources_convert`；发现尺寸或比例问题时使用 `arkts-icon-sizing`。
+选型尚未明确时，可以继续下一阶段不依赖目标结构的 Android 分析；确认前不据候选方案创建业务目录或固定 Spec 的目标归属。只影响实现的 SDK/Native 未知保留为相关能力前置；仍影响模块/目录的未知明确待决范围，不伪称结构已经确定。
 
-### 四、页面任务设计
+### 四、Android 工程分析
 
-加载 `d2h-page-spec-generate`，由 AI 基于当前 Facts、`.migration/utg/page.json`、Android 源码和 HarmonyOS 现状完成：
+1. 加载 `d2h-utg-static-generate`，生成或刷新 Facts、UTG、点击路径和 `.migration/utg/page.json`，并对照真实 Android 源码核验页面、入口、交互、数据流和 unresolved 项。
+2. 需要修复 UTG 或有 Android 设备可用于运行时采集时，加载 `d2h-utg-ai-generate`。运行时证据留在该 Skill 定义的位置，不复制进页面 Spec 包。
+3. Facts 或 UTG 未覆盖、但源码中真实存在的行为仍须纳入页面 Spec，并在 `batch_report.json` 中记录发现与处理情况。
+4. 发现架构规划遗漏的职责、共享状态或依赖冲突时，返回架构阶段局部修订受影响归属，保留已有用户选择；涉及重要取舍时展示变更，不重做全部架构分析，也不由页面候选静默裁剪真实业务。
+
+### 五、spec 设计与生成
+加载 `d2h-spec-generate`，由 AI 基于当前 Facts、`.migration/feature-analysis/` 的功能清单、`.migration/utg/page.json`、Android 源码、已选定架构和实际 HarmonyOS 工程状态完成：
 
 1. 识别所有页面、Dialog、Sheet 和具有独立行为的页面模式。
 2. 决定页面依赖、开发顺序、评分与证据账本，写入 `.migration/page-specs/pages.json`。
 3. 为每个 `page_NNNN_<name>-<id>` 生成且只生成一个 `spec.md`。
-4. 使用该 Skill 自带的 `build_batch_report.py` 生成初始 `batch_report.md`。
+4. 使用该 Skill 自带的 `build_batch_report.py` 生成初始 `batch_report.json`。
+
+`d2h-spec-generate` 是页面范围、顺序和 Spec 格式的规则真源；在已选目录/共享边界内细化页面与实现范围，不能直接把架构候选当最终页面身份，也不重新选一套目录。新证据需要改变边界时返回最小修订。主 Agent 不在本文重复实现页面拆分算法，也不使用其他静态脚本生成、选择或执行任务。
+
+### 六、代码转换
 
-`d2h-page-spec-generate` 是页面范围、顺序和 Spec 格式的规则真源。主 Agent 不在本文重复实现页面拆分算法，也不使用其他静态脚本生成、选择或执行任务。
+1. 根据实际工程状态按场景加载专项完成代码规范和资源迁移
+
+- 规划工程分层、状态管理、导航和共享能力时使用 `arkts-mvvm-architecture`。
+- 迁移应用身份时使用 `arkts-app-identity`。
+- 迁移字符串和多语言时使用 `arkts-i18n`，禁止用 `.ets` 硬编码代替字符串资源迁移。
+- 转换图片和 drawable 时使用 `android2hmos_resources_convert`；发现尺寸或比例问题时使用 `arkts-icon-sizing`。
 
-### 五、逐页代码串行开发
 
-加载 `d2h-page-develop`，以严格串行方式执行页面开发。任意时刻最多只能有一个页面处于开发或修复状态，禁止并行开发多个页面，也禁止一次向 worker 派发多个页面：
+2. 加载 `d2h-spec-develop`，以严格串行方式执行 spec 开发。每次最多在一个 worker 中派发 3 个 spec 完成任务：
 
-1. 主 Agent 按 `batch_report.md` 选择顺序最前且未达到 `implemented/passed/passed` 的页面。
-2. 只派发一个独立 page-worker，且该 worker 只负责当前一个页面。worker 必须加载 `d2h-page-develop`，不得领取、预研或修改后续页面。
-3. 进入测试阶段时加载 `d2h-hypium-forge`，生成或更新该页面的 Python Hypium 测试资产。先确认本次构建的 HAP 已安装到目标设备，再按该 Skill 执行当前页面的定向测试（仅本页面的 `pageNNNN_*` 用例，不回归其他页面），保留实际结果、日志和必要截图。主 Agent 核对执行用例及其断言是否覆盖 Spec 功能项，不能仅凭进程退出码或汇总文案判定通过。
-4. 页面实现与测试通过后，在 `batch_report.md` 当前页面明细中记录真实实现文件、Android 源码依据、本次构建与 Forge 测试的实际结果及证据路径，以及差异或阻塞。未产出或未保存的结果、日志如实记录为缺失，不得填写假定存在的路径或据此标记通过。
-5. 主 Agent 完成当前页面的实现提交，原位更新 `batch_report.md`，并按 Skill 的页面完成清单复核实现、构建、测试、证据、提交和工作区状态。
-6. 前页面未闭环、仍有页面所属未提交修改或复核失败时，只能继续修复当前页面。当前页面完整闭环并通过主 Agent 复核后，才能按顺序选择并派发下一页。
+a. 主 Agent 按 `batch_report.json` 选择顺序最前且未达到 `implemented/passed/passed` 的页面。
+b. 只派发一个独立 page-worker，且该 worker 只负责当前一个页面。worker 必须加载 `d2h-spec-develop`，不得领取、预研或修改后续页面。
+c. 进入测试阶段时加载 `d2h-hypium-forge`，生成或更新该页面的 Python Hypium 测试资产。先确认本次构建的 HAP 已安装到目标设备，再按该 Skill 执行当前页面及受影响功能的定向测试，保留实际结果、日志和必要截图。主 Agent 核对执行用例及其断言是否覆盖 Spec 功能项，不能仅凭进程退出码或汇总文案判定通过。
+d. 页面实现与测试通过后，在 `batch_report.json` 当前页面明细中记录真实实现文件、Android 源码依据、本次构建与 Forge 测试的实际结果及证据路径，以及差异或阻塞。未产出或未保存的结果、日志如实记录为缺失，不得填写假定存在的路径或据此标记通过。
+e. 主 Agent 完成当前页面的实现提交，原位更新 `batch_report.json`，并按 Skill 的页面完成清单复核实现、构建、测试、证据、提交和工作区状态。
+f. 前页面未闭环、仍有页面所属未提交修改或复核失败时，只能继续修复当前页面。当前页面完整闭环并通过主 Agent 复核后，才能按顺序选择并派发下一页。
 
 若当前环境不支持独立 page-worker，必须明确报告该开发模式无法执行，不能静默改成主 Agent 批量开发。
 
-### 六、批次回归与最终门禁
+### 七、测试与交付
 
 全部页面达到 `implemented/passed/passed` 后：
 
 1. 加载 `d2h-hypium-forge`，在已安装当前 HAP 的目标设备上执行覆盖全部迁移范围内功能场景的完整 Python Hypium 回归，保留本次实际执行结果和日志。核对用例范围、执行数和各项状态；零执行、失败、错误或必测场景被跳过、未执行时均不能通过，历史 PASS 不能替代本次完整回归。
 2. 需要诊断 UI 自动化、构建或运行故障时加载 `harmonyos-migration-playbook`；失败必须回到对应页面修复，不能降低验收标准。
-3. 主 Agent 对照各页 Spec、源码、实际实现和设备结果完成行为审查，将结论、被测 HAP 与设备、完整回归结果和实际证据路径、差异及未解决问题记录到 `batch_report.md` 的批次回归部分。直接核对账本队列、页面明细、汇总和引用证据的一致性，满足完成条件后才能宣布迁移完成。
+3. 主 Agent 对照各页 Spec、源码、实际实现和设备结果完成行为审查，将结论、被测 HAP 与设备、完整回归结果和实际证据路径、差异及未解决问题记录到 `batch_report.json` 的批次回归部分。直接核对账本队列、页面明细、汇总和引用证据的一致性，满足完成条件后才能宣布迁移完成。
 4. 完整结束或明确中止后加载 `reviewing-migration-process` 生成流程复盘；复盘不是完成条件。
 
 ## 持续执行与人工介入
@@ -114,6 +128,7 @@ description: Android 应用到 HarmonyOS 的 AI 驱动迁移主 Agent；按迁
 
 - 禁止依据模型自行估算的“剩余 token”“上下文百分比”“本轮剩余容量”等决定停止、收尾、汇报后等待或要求用户开启新会话。此类估算不可信。
 - 用户主动中断、修改需求或发出新指令。
+- 架构选型或重要修订需要用户决定时，只等待依赖该选择的目标目录落地/Spec 分配；独立的 Android 分析可继续。仅请求架构规划则交付即可，不强求立即选型；已有“采用推荐并创建”明确授权时记录后继续，不重复询问。
 - 真机签名、开发者账号、权限或凭据必须由用户完成，且没有可用替代方案。
 - 设备、CLI、构建环境或外部服务持续不可用，完成自诊和有限重试后仍确认是外部问题。
 - 完成目标需要超出原迁移范围的产品决策或新的授权。
@@ -140,13 +155,13 @@ description: Android 应用到 HarmonyOS 的 AI 驱动迁移主 Agent；按迁
 
 只有同时满足以下条件，才允许宣布迁移完成：
 
-- Preflight、Facts、UTG、页面 Spec、`batch_report.md` 和证据对应当前源码。
+- Preflight、Facts、UTG、页面 Spec、`batch_report.json` 和证据对应当前源码。
 - `pages.json` 覆盖全部已知页面或明确记录排除原因。
 - 每个已知页面、Dialog、Sheet 和关键模式都有唯一 `spec.md`，页面包中没有额外产物。
-- `batch_report.md` 覆盖全部页面，且所有任务均为 `implemented/passed/passed`，没有未解决阻塞。
+- `batch_report.json` 覆盖全部页面，且所有任务均为 `implemented/passed/passed`，没有未解决阻塞。
 - 所有 Spec 功能项都有真实、可达的 HarmonyOS 实现。
 - HarmonyOS 工程构建、安装、启动成功；当前 HAP 的 Forge 完整回归通过，没有失败、错误或必测场景未执行。
-- `batch_report.md` 已记录最终行为审查、完整回归结论及实际证据路径，队列、页面明细和汇总一致。
+- `batch_report.json` 已记录最终行为审查、完整回归结论及实际证据路径，队列、页面明细和汇总一致。
 - 所有页面、可见控件、状态、导航、Dialog、业务功能、数据效果和错误路径均真实实现。
 - Facts 或 UTG 遗漏、但经源码或运行时发现的行为也已实现并验证。
 - 无法等价的差异已经明确呈现，没有被静默标记为完成。

package/contracts/workflow/artifacts.md

@@ -0,0 +1,22 @@
+# 产物与所有权
+
+生产者可替换；消费方校验契约与来源，不加载生产者 Skill。
+
+| 产物 | 维护者 | 消费条件 / 失效条件 |
+|---|---|---|
+| inventory.json | 分析能力或外部输入方 | 结构、来源与实际范围可解释；源码/分析来源变化时复核，不当作用户选择或迁移验收 |
+| features.json | 调用方记录用户选择；d2h 在完整流程中协调 | 稳定 feature_id/scope_id、revision、来源与授权；变化时产生范围差异并递增版本 |
+| 架构上下文 / 目标工程 | 用户或架构能力 | 模块/目录、共享边界和风险有效；归属变化时修订受影响计划，不强制某个生产 Skill |
+| Facts / UTG page.json | 分析/采集工具 | 只读事实和节点到达/采集依据，不能逐节点当作业务页面或任务 |
+| pages.json v2 | 规划能力或外部输入方 | 版本化范围、轻量 Spec、依赖/波次/批次与验收概要；选定版本后交生成 |
+| 页面 spec.md / generation.json | 生成能力或外部输入方 | 只展开所选成员；逐成员输入及内容绑定有效才可派发，详见 [生成契约](generation.md) |
+| execution.json | d2h 通过公共 workflow 工具 | 事件序号、候选与证据身份；不由 Skill 手改，不因产物缺失重置历史 |
+| batch_report.json / batch_report.md | 公共工具从执行账本派生 | 每次 init/event/reconcile 同步；Markdown 供人阅读，不成为另一份状态真源 |
+| dashboard.html / 进度快照 | 公共工具按需派生 | 引用同一计划、范围和当前证据，离线展示不等于实时执行 |
+| progress.json | d2h 通过已有 progress CLI | 阶段聚合；不能替代 Spec 执行事件或当前候选验收 |
+
+公共操作入口是 `d2h workflow`，随 D2H 包分发，不依赖任何 Skill 目录。仅复制 Skill 也不会复制或假造工具；缺失工具时返回 requiredTools，由调用方准备。
+
+旧 v1 页面计划/账本保留兼容。必须按 schema 显式选择流程；旧批次报告的 tasks[] 与增量报告的 tasks 映射不能混写到同一路径。旧 Markdown 有历史时，显式迁移后才能建立新投影，不能用 init 覆盖。
+
+产物检查不证明真实行为正确。语义、源码、用户授权、实际接口、HAP、设备、执行断言及原始证据仍需调用方独立核对。

package/contracts/workflow/delivery.md

@@ -0,0 +1,54 @@
+# 交付目标、看板与功能 Review
+
+按分层目标规划、响应看板草稿、查看当前进度或进行交付功能评审时读取。来源字段见 [范围契约](scope.md)，执行事件及 reconcile 见 [执行契约](execution.md)。
+
+## 用户选择与规划
+
+MVP 是先交付项目实际需要的最小可用路径，核心在其基础上加入核心能力，全量包含全部未排除范围。三层是互斥新增集合，累计为 M、M∪C、M∪C∪F；不依赖名称、页面顺序、优先级或 round.kind 猜测。AI 结合源码提出逐范围划分。优先按用户明确选中的范围交付，恢复时保留仍有效的既有用户选择；无明确选择时默认交付核心功能。默认核心由 d2h 根据分析产物与真实路径建立，写入 delivery.target=core、具体 scope_items 与必要依赖、阶段及默认原因；spec-plan 和看板不凭配置缺失推断选用范围。已有明确全量或局部选择不被默认核心覆盖。
+
+同一功能可以跨层。scope_items 唯一保存 included/deferred/excluded/unresolved 与 milestone，delivery.scope_layers 只补最低交付层；delivery.target/customized 描述选用预设及是否局部调整。未选范围延期并写原因，不删除或计作完成。新项目按用户选择或默认核心生成配置；旧项目缺少配置保持只读兼容，执行前由上游确认仍有效的用户选择，无明确选择才按默认核心显式修订并 reconcile，不改在途窗口。
+
+Spec 只认领已授权且已分配阶段的范围。必要前置跨出选用范围时返回上游最小能力建议，不整页勾选。一个 Spec 负责多个范围时仍须可共同交付；未授权范围不能夹带。MVP/核心/全量不替代业务 milestones，baseline/incremental/completion 是里程碑内部执行轮次；跨层完善沿用基础 Spec 与页面身份，新增后续增量。
+
+全量目标不改变各项的最低交付层：禁止因“全量盘点／全量交付”将全部条目置为 full。导出前核对三个累计预设的条数、代表功能和依赖闭环；MVP 需包含真实最小用户路径，核心应保留 MVP 并按产品范围增强，不能用技术优先级机械换算。小范围应用允许两个累计集合相同；依据不足时标明未完成分层，不制造空预设。
+
+按钮预览不得把无配置或空集合当作有效范围变更。遇到空预设时保留当前草稿并说明需要修订 delivery.scope_layers；仍允许手动调整和重载。修复分层须经过上游版本修订和下游 reconcile，不直接更改执行账本或启动实现。
+
+## 看板读模型
+
+```bash
+d2h workflow dashboard \
+  --plan <pages.json> --features <features.json> --execution <execution.json> \
+  --baseline-features <archived-baseline-features.json> \
+  --output <same-plan-directory/dashboard.html>
+```
+
+stdout 为 `d2h-dashboard/v1` JSON，--output 可选，只允许计划目录 dashboard.html。baseline 可省略，此时 Review 明确显示原始基线缺失，不假装做过比较。命令只读执行账本，按当前文件与证据重新 derive；不 init、reconcile、启动 worker 或执行测试。HTML 内嵌同次快照，可直接打开，也可导入新的同 schema JSON；导出不是持续联网。
+
+若 CLI 提供同源快照端点，可在 HTML URL 指定 `?snapshot=/api/spec-plan/snapshot`，看板每约 3 秒读取 `d2h-dashboard/v1`。该接口需由 CLI 实现并调用同一派生逻辑；此技能不新增 HTTP 服务或跨仓库执行入口。断线保留最后成功数据并标明过期；不从宿主 idle 推导任务完成。查询参数不能指定跨源数据地址。
+
+`derive.delivery_progress` 提供 selected/full 与各层 increment/cumulative 的 accepted/total/percent/unplanned。分子只采用当前有效 scope accepted；excluded 不计入分母，deferred/unresolved/unassigned 保留在 full。零分母为 null。未配置层级时仍显示选用范围与全量，v1 无逐项追踪时两个指标为 null，不能从 Spec 数猜。
+
+页面保持六个视图：总览、分析、功能、规格、Spec 执行、交付 Review。总览的当前执行目标来自 relevant_specs，与跨里程碑选用目标分开；实际任务来自 running/active_batch，建议来自 ready_batches。工作包、真实接口、即时门禁、验证债务和阶段回归保留独立状态。
+
+项目摘要和分析通知通过可选 `--overview`、`--analysis-progress` 接入；代码统计、SDK/SO 处置、工具检查来源及活动动画约定见 [总览契约](overview.md)。
+
+## 草稿处理
+
+看板导出的 `d2h-scope-change-request/v1` 仅是用户修改建议，绑定 feature_hash、plan_hash、event_sequence、candidate；包含 target、scope_refs、user_priorities 与 reason。主 Agent 先核对身份，过期草稿重新合并，不覆盖最新版本。AI 可提出依赖/成本影响，不把 UI 本地预览当语义校验。
+
+上游更新 F 并用 --previous 校验，主 Agent 重新规划必要 Spec；完成或暂停在途任务、释放窗口、归档旧 F/P/spec.md 后 reconcile，再导出视图。三文件发布和 CLI 命令回执尚需适配，不能用一个浏览器按钮直接覆写多文件。只变优先级也需保留 revision/changes，但不伪造代码变化。
+
+## 交付功能 Review
+
+初始 F 定稿后由主 Agent 归档 baseline-features.json，不覆盖；当前 F 中改名保持 ID，拆分/合并保留 derived_from，旧项显式 excluded。snapshot 对相同复合 ID 比较 description/acceptance，输出 added/changed/unchanged/missing-from-current；名称相似不是自动合并依据。缺少 baseline 或 v1 范围时如实显示不可比较。
+
+自动差异、实现声明、当前有效证据、人工判断分别保存。生成的 review.items.manual_review=pending 不表示已评审。主 Agent 在 `.migration/page-specs/delivery-review.md` 记录：原始/当前 feature revision 与 hash、plan revision/hash、candidate、event sequence、逐项差异与处置、行为证据引用、评审者和时间。Review 是评审记录，不是第二执行账本；测试与 accept/round_accept/regression 仍通过 runtime。
+
+结果至少包括按约实现、部分实现、缺失、新增待确认、变更待确认、明确延期、明确排除、未评估。拆分合并逐项解释来源关系，不能把新增行为自动计作授权范围。对未通过项提出修复或上游范围修订；不得仅改评审文字、scope_complete、排除项或分母来消除实现缺口。人工接受偏差不补造设备证据。
+
+当前目标按用户选中范围、无明确选择时按已记录的默认核心范围判断。目标范围及必要依赖全部通过后，再核对相关轮次和最终当前 HAP 上覆盖整个目标的完整回归，宣布对应目标交付。跨里程碑目标须覆盖全部相关阶段，不能仅用最后阶段的回归代替。范围外延期/未排期项继续列入报告，不要求 scope_coverage_accepted=true、整页完整或全清单验收才能完成 MVP/核心/局部交付。
+
+全迁移完成另要求 scope_tracking=true、scope_coverage_accepted=true、全部约定功能与相关页面完整、最终 HAP 全应用回归及差异处置。范围或候选变化后重新核验，历史评审仍保留但不自动当作当前结论；当前目标 100% 不表示全迁移完成。
+
+启用预设（含默认核心）前由主 Agent 调用 公共工具 `d2h workflow validate-scope <features.json> --require-delivery`；普通校验继续兼容未配置或历史全 full 的计划，供查看、修订和 reconcile 使用。该选项只验证可选集合非空与结构，不生成分层或推断用户授权。

package/contracts/workflow/dispatch.md

@@ -0,0 +1,26 @@
+# 固定派发与实现结果契约
+
+输入可由任意调用方提供，计划无须来自特定 Skill。完整迁移时 d2h 负责确认就绪、固定版本和窗口、记录 start/start_batch，再将快照与以下参数交给实施能力。
+
+## 必需输入
+
+- 任务或固定 batch_id/spec_ids；同页也不得自行增加成员。
+- pages.json/页面 spec.md 定位、计划及范围版本；若已有 workflow 快照则保留 plan_hash/feature_hash/candidate/event_sequence 便于核对。
+- 完整行为、异常、checks、scope_refs、requires/provides 和当前所需前置能力/实际接口证据。
+- Android/HarmonyOS/仓库绝对路径、Git 基线与现状、允许文件、共享修改负责人。
+- 当前模块/目录、共享状态及生命周期、必要资源/平台结论和风险；它们可以来自用户、已有工程或任意已确认方案。
+- 即时/合批检查、已授权 CLI 与测试资产、预算、设备和证据目录。缺失信息明确为未决，不默认等于无需检查。
+
+`d2h workflow context --plan ... --features ... --execution ... --batch-id ...` 可提供裁剪的 d2h-dispatch-context/v1。快照不等于领取或开工许可；d2h 补齐当前基线、允许文件、实际接口和设备等参数。
+
+## 返回结果
+
+- status：implemented / needs-input / blocked；不包含调用方验收通过声明。
+- artifacts：实际实现、资源、测试或接口文件；每个 Spec 对应可达代码与行为。
+- evidence：逐 check 的实际命令、结果、原始日志/报告、时间、候选/HAP/设备身份及 managedEvidence；未执行项和原因分列。
+- commits：可恢复的作用域提交及本任务剩余修改，用户无关改动保留情况。
+- unresolved / requests：知识、领域处置、验证、计划修订或缺失输入。每项说明问题、当前依据、期望结论、消费者和阻塞范围，不指定下一项 Skill。
+
+d2h 接收后选择所需领域/测试/报告能力。能力提供者的真实接口经复核且即时检查通过后，消费者才可启动。证据与当前候选不符时保留历史并按事件失效，不能让 worker 改账本来消除缺口。
+
+启用 spec_generation_policy=required-v1 的计划，所选成员还须有当前有效的详细正文绑定；生成缺口属于 readiness_gaps，不能派发。规划校验通过不代表已生成。

package/contracts/workflow/execution.md

@@ -0,0 +1,125 @@
+# 执行、证据与版本修订协议
+
+主 Agent 派发、写执行账本、录入受管证据或修订运行中计划时读取；仅起草 Spec 时无需加载。
+
+计划字段与轮次/批次结构见 [计划契约](plan.md)。语义拆分、评分和归拢方法见 计划生产者的方法说明。本参考维护执行事件和证据格式，避免在各角色流程重复定义。
+
+程序：`d2h workflow`，Python 3 标准库。它校验 AI 显式计划和证据身份，不推断源码、不派发 worker，也不能替代主 Agent 的真实行为复核。
+
+按需要定位：命令、事件、证据格式、修订与历史；只更新状态不重读整份计划方法。
+
+## 命令
+
+```bash
+d2h workflow init --plan <pages.json> --features <features.json> --execution <execution.json>
+d2h workflow derive --plan <pages.json> --features <features.json> --execution <execution.json>
+d2h workflow event --plan <pages.json> --features <features.json> --execution <execution.json> --event <event.json> --expected-sequence <current-event-count>
+d2h workflow render --plan <pages.json> --features <features.json> --execution <execution.json> --output <same-plan-directory/batch_report.json>
+d2h workflow dashboard --plan <pages.json> --features <features.json> --execution <execution.json> --output <same-plan-directory/dashboard.html>
+```
+
+init 拒绝覆盖；写操作使用独占锁和序号检查，失败不覆盖已有状态；输出以临时文件原子替换。进程崩溃留下锁时，先确认无写进程再清理，不能自动抢锁。报告可重复生成；不能把报告写到输入或 Spec 文件。
+
+`batch_report.json` 使用 `schema_version: d2h-spec-batch-report/v1`，包含输入版本/哈希 `source`、当前候选、里程碑、完整派生 `state`、按 spec_id 索引的 `tasks`（计划、执行记录、当前有效证据与用户优先级）、回归证据及历史。`execution.json` 仍是执行真源，报告不手改；看板直接读取结构化字段。整页旧流程的 `d2h-page-batch-report/v1` 使用 `tasks[]`，消费者须按 schema_version 区分。
+
+dashboard 只生成派生 JSON/HTML，不改账本；可选 --baseline-features 支持原始功能范围对照。分层指标、看板草稿与交付 Review 见 [交付投影](delivery.md)。导出快照不表示在线连接，CLI 可消费同一 stdout 作为快照接口。
+
+## 事件
+
+每个事件追加序号、时间和计划版本。event.json 可为单对象或对象数组；数组整体校验成功后才写盘，适用于同一候选批次的多 Spec 证据映射。
+
+| type | 字段 | 约束 |
+|---|---|---|
+| start_batch | batch_id, spec_ids, worker, baseline, reason | ready_batches 中的批次；spec_ids 必须匹配 dispatchable_spec_ids；固定成员和独占 worker |
+| start | spec_id, baseline, reason | ready 中的任务；页面模式要求属于 active_batch；每次仅一个成员 in_progress |
+| implemented | spec_id, commit | 只由 in_progress 转入，暂未表示验证通过 |
+| finish_batch | batch_id, reason | 窗口内无在途成员，全部领取成员实现且即时门禁通过；其余测试可 pending，不表示整个页面完成 |
+| pause_batch | batch_id, reason | 先 pause/block 在途成员；释放窗口并保留逐项状态和实际成员记录 |
+| round_accept | round_id, reviewer, review, evidence | 前轮已交付，所有本轮成员 individually accepted，goal_checks 的当前真实路径通过；先释放活动批次 |
+| candidate | candidate | 当前集成提交或可恢复快照；先完成或暂停在途任务；默认旧证据全部 stale |
+| evidence | spec_id, evidence | 已实现后，当前候选、原始文件及哈希有效 |
+| accept | spec_id, reviewer, review | 当前构建、全部检查及依赖通过；主 Agent 实际行为复核 |
+| regression | evidence | 当前阶段及必要前置 Spec 已 accept；页面模式各相关轮次 current_accepted；证据覆盖全部当前阶段 checks，HAP 与各 Spec 当前构建一致 |
+| block | spec_id, reasons | 非空外部原因；在途工作退回 planned，保留派发记录 |
+| unblock | spec_id, reason | 记录恢复依据 |
+| failed / invalidate | spec_id, reason | 失败或证据失效，清空可用证据；历史仍在 events |
+| repair | spec_id | 已实现但 failed/stale，单 worker 空闲；不因积压阻止修复 |
+| pause | spec_id, reason | 明确处置在途工作，保留历史 |
+| metrics | spec_id, metrics | 投入分类、等待、返工、elapsed_hours、first_pass、conflicts；未知为 null |
+
+candidate 变化采用保守的全量证据失效。可以在同一候选中合并构建、安装和测试；本版本不自动推断不受影响代码，也不将旧 HAP 测试重新标成新候选通过。遗留旧代码能力通过同样的当前候选证据流程登记，不因代码已存在就默认 ready。
+
+metrics 支持 implementation_hours、test_hours、coordination_hours、waiting_hours、rework_hours、elapsed_hours、first_pass（bool）、conflicts。时间分类需约定互斥口径，共享批次准备投入按批次分摊一次；脚本不从日志虚构活跃工时。derive 根据已记录数据输出 actual_worker_hours、effort_ratio、coordination_share、rework_share、waiting_share；缺少必要分类时为 null。总活跃投入是实现、测试、协调、返工的互斥分类之和，不把等待再加一次。
+
+page_dispatch_metrics 根据窗口日志记录已结束/暂停窗口数、页面切换次数和平均每窗口 Spec 数。这些是执行组织指标，不是完成率，也不证明实际节省了多少时间。
+
+## 证据格式
+
+```json
+{
+  "kind": "test", "candidate": "<integration-commit-or-snapshot>",
+  "command": ["droid2hmos", "test", "harmony", "/abs/android", "--runner", "python", "--test-list", "/abs/test-list.json"],
+  "exit_code": 0, "timestamp": "2026-10-21T08:00:00+00:00",
+  "artifact": {"path": "/abs/original-result.json", "sha256": "<file-sha256>"},
+  "hap": {"path": "/abs/app.hap", "sha256": "<file-sha256>"},
+  "device": "<actual-device>", "checks": ["login-basic/AUTH-01", "login-basic/AUTH-02"],
+  "counts": {"executed": 2, "passed": 2, "failed": 0, "errors": 0, "skipped": 0},
+  "managed_evidence": ["<actual-managedEvidence-ref>"]
+}
+```
+
+build 使用 kind=build、command 前缀 droid2hmos/build/harmony，保留 candidate、exit_code、timestamp、artifact、hap。test 必须匹配已录入的当前构建/HAP。artifact 和 hap 记录实际文件字节哈希；相对路径以计划目录解析，保存后转为绝对路径。文件变动/缺失时 derive 不再视为有效证据。
+
+计数/checks/managed_evidence 是主 Agent 从实际结果读取并核验的交接映射，校验器不会替代 Forge 原生报告解析或证明真实执行；禁止手填预测结果。相同批次可引用同一 artifact，checks 按每个 Spec 实际断言子集映射。regression 使用全阶段 checks；历史证据永久保存或归档，不覆盖原文件。
+
+## 修订与历史
+
+先保存旧 pages.json、features.json 和受影响 spec.md。新计划 revision 恰好加一；不变的上游沿用原版本，上游变化必须通过其 `--previous` 校验。运行中任务先明确 pause 或完成，再 pause_batch/finish_batch 释放活动窗口，禁止静默改范围或成员。
+
+```bash
+d2h workflow reconcile --plan <new-pages.json> --features <new-features.json> --execution <execution.json> --previous-plan <archived-pages.json> --previous-features <archived-features.json> --reason <reason> --expected-sequence <current-event-count>
+```
+
+历史保存旧计划、功能版本及任务状态。保留现存 spec_id；废弃旧增量在新计划 retired_specs 中显式登记 `{spec_id, reason}`，原状态归档，不能无说明删除。改变范围/断言/证据依据的任务重回 planned；依赖或上游语义改变时消费者的有效状态重新计算。优先级等纯偏好变化不会伪造代码变更或覆盖旧证据，但仍需要版本事件。
+
+v1 计划不能直接传给 init/derive；先由 AI 保存旧计划、账本及证据，核验范围并编写 v2。旧评分没有新评分含义，旧 PASS 不自动导入。新 init 只用于没有 execution.json 的新基线。
+
+
+## 裁剪派发上下文与分析成本
+
+```bash
+d2h workflow context --plan <pages.json> --features <features.json> --execution <execution.json> --batch-id <batch_id>
+```
+
+只读 stdout 输出 d2h-dispatch-context/v1，不写状态或派发任务。无活动窗口时仅允许 ready_batches；有活动窗口时仅输出该窗口固定成员。包含版本/内容哈希、candidate、事件序号、context_hash、页面 spec.md 定位、当前成员与所需能力状态；省略无关后续 Spec。领取仍须 start_batch 和 expected-sequence，执行前按实时门禁核对。上下文身份变化用于检查差异，不作为测试证据或影响范围复用证明。
+
+metrics 新增可选 context_hours 和 repeated_analysis_hours，满足 repeated_analysis_hours ≤ context_hours ≤ implementation_hours（双方已知时校验）。两者均是既有实现工时的子集，不再加到 actual_worker_hours；相应占比用互斥总活跃工时作分母，缺失为 null。摘要提取及差异判断仍由 AI 完成，程序不自动读取源码生成可信语义摘要。
+
+## 实际接口交接
+
+启用 work_packet_policy=required-v1 后，提供者实现并形成当前候选，主 Agent 核对实际代码再追加事件：
+
+```json
+{
+  "type": "interface",
+  "spec_id": "login-basic",
+  "capability": "session.basic",
+  "candidate": "<current-candidate>",
+  "symbols": ["SessionStore.establish(token: string): Promise<void>"],
+  "summary": "已读真实代码；持久化后发布会话，失败不进入首页",
+  "reviewer": "main",
+  "code_files": [{"path": "/abs/harmony/SessionStore.ets", "sha256": "<actual-file-hash>"}]
+}
+```
+
+spec_id 必须已 implemented，capability 属于其 provides，candidate 匹配当前；代码文件必须存在且哈希相符。程序不解析 symbols 真实性或证明文件属于调用链，主 Agent 必须复核。接口不能替代构建或即时测试；消费者须全部门禁满足才启动。事件仍通过 event 命令并携带 --expected-sequence。
+
+derive 输出 readiness_gaps/work_packet_ready（规划开工就绪）与 missing_interfaces（提供者接口缺口）。context.members[].work_packet 含裁剪目标、源引用、目标路径、实施说明、验证层级、共享契约及有效接口；required_capabilities[].interface 只输出当前有效回执。候选变化、失效、失败、修复或相关语义修订后需重新确认，旧回执保留在事件历史。
+
+验证分层目前只作为计划；test evidence 的 layer 省略视为 device，显式非 device 拒绝，不能将本地检查升级为设备 PASS。引入向量或 host 证据须先适配 CLI 原始报告与受管回执。旧计划未启用策略时兼容原行为，不能声称已有工作包门禁。
+
+总览摘要与 AppGraph 通知可分别用 `dashboard --overview <overview.json> --analysis-progress <analysis.jsonl>` 读取；协议与来源检查见 [总览契约](overview.md)。两者不写 F/P/E，不替代当前验收。
+
+## 人工阅读投影
+
+公共工具 init/event/reconcile 在成功保存执行状态后同步派生 batch_report.json 与 batch_report.md；render 可重建两种视图。Markdown 标明自动生成，不能手改状态。工具拒绝覆盖旧页面账本 schema、未经迁移的历史 Markdown 或符号链接报告。执行事件是权威记录；若投影写入因 I/O 失败，可在保留账本后重试 render，不重放已写入事件。

package/contracts/workflow/generation.md

@@ -0,0 +1,40 @@
+# 波次计划到详细 Spec 的交接
+
+计划维护者写 pages.json v2；生成方只读计划与功能范围，写指定页面 spec.md 和 generation.json。双方只依赖产物，不要求或调用对方 Skill。旧 d2h-page-plan/v1 / tasks[] 页面账本保持原模式，不与本模式混写。
+
+## 先计划，再按选定版本生成
+
+1. 规划输入是功能范围、功能到行为/页面/非页面入口的来源映射、仍有效的架构、旧计划和当前执行摘要。保留 scope_id/spec_id、页面目录、历史及用户优先级，输出依赖、波次、批次、估算与验收概要。新计划显式设置 spec_generation_policy=required-v1，不写详细 spec.md。
+2. 用 `d2h workflow validate --planning-only --plan <pages.json> --features <features.json>` 检查计划，输出 plan_sha256。该参数只允许 validate，不要求 Spec 文件存在，也不代表可派发。用户可以调整波次，由计划维护者修订 revision。选定版本可以来自当次明确选择或既有授权；不强制每次重复确认。
+3. 调用方向生成方交付计划和 features 的绝对路径及 revision/hash、明确 spec_ids（可由 round_id/batch_id 解析）、源码/目标工程和架构上下文。只选真实存在于该版本的成员，不从阶段名称猜 scope，不自动包含整页或整轮之外的功能。跨页 Spec 保留唯一主页面与其他页面引用。
+4. 生成方按原有源码核验和完整内容要求写所选成员。它不重排计划、不改用户范围、不写 execution.json、不初始化旧 batch_report.json。缺少前置、工作包或接口信息时返回 needs-input/needs-revision、unresolved、requests 和 proposed_plan_updates，由调用方交计划维护者修订；不能伪造已核验的空数组。
+5. 正文审阅后，调用公共工具为明确成员记录内容绑定。必要工作包字段仍须满足独立派发门禁。工具只验证结构与内容身份，不证明语义完整或用户已确认。
+
+```sh
+d2h workflow generation --plan /abs/pages.json --features /abs/features.json \
+  --expected-plan-hash <selected-plan-sha256> --spec-id login-basic
+```
+
+生成方必须先后核对输入身份，任何变化先返回修订请求。generation 命令再次核对当前计划哈希；不会改计划、执行状态或验收结果。它只登记正文已有的成员，不自动写 Spec。derive/dashboard 会读取最新绑定；需要刷新离线阅读报告时由调用方执行 render，不为刷新报告伪造执行事件。记录是原子更新，未指定成员保留；失败不覆盖已有 generation.json。
+
+## 页面正文和内容绑定
+
+页面目录继续只放一份 spec.md，复用完整模板的七个核心章节。每个当前成员的详细行为、异常、数据效果、源码/目标依据、操作和所有 check_id 必须明确，不能用页面或批次摘要替代。正文中用稳定边界包住逐 Spec 章节：
+
+```markdown
+<!-- d2h-spec:start login-basic -->
+### Spec: `login-basic`
+
+<完整的逐 Spec 内容，包含计划全部 check_id，不是只有 ID 的空壳>
+<!-- d2h-spec:end login-basic -->
+```
+
+所有成员边界之外为共享上下文（保留原七章布局，公共章节也可位于成员之后），成员边界内为该 Spec 正文。共享摘要忽略空白分隔行，避免仅追加成员造成无关失效。generation.json 记录每项的规划输入摘要、共享上下文和正文哈希，所选计划版本仅供追溯；不是第二份计划或执行账本。页面共用来源、入口和状态必须放在成员块外的共享上下文，成员变化写各自块；首段版本信息表示该上下文的编写快照，不因无关的总计划 revision 变化机械改写。追加其他成员不应改写已有块或无关共享背景。
+
+新计划下，尚未生成的页面允许不存在；存在的页面仍只允许本地 spec.md。未生成、绑定过期或正文改变时，derive 给出 spec generation readiness_gaps，不能 start/start_batch；当前 accepted 也不沿用失效规格。没有此显式策略的现有 v2 计划维持原行为，不隐式升级。策略升级应释放在途任务并 reconcile。
+
+## 增量与所有权
+
+MVP → 核心：更新 features 的交付目标和差量，复用有效分析/架构，修订后续波次；只有真实架构或来源缺口才返回对应请求。已完成成员不改身份，详细 Spec 只生成新增或受影响部分。逐成员绑定排除全局计划/功能 revision、评分和工时，但包含成员范围、验收/工作包、所有权、能力依赖、关联 scope 与共享契约。无关范围扩展不强制重生旧 Spec；改变其语义或共享背景则使相应绑定失效。旧执行历史经 reconcile 保留，不用 init 重置。start/repair 还把当时的内容身份绑定到实施记录；运行中或已实现正文发生改变，即使重新登记 generation.json，也不能恢复旧验收，必须显式 invalidate/repair 或按语义修订计划。
+
+输入出处与实际源码/架构的一致性、功能—行为映射、范围授权和正文语义仍须 AI/人工核验；哈希绑定不检测未声明的外部源码变化，也不能代替真实验收。

package/contracts/workflow/orchestration.md

@@ -0,0 +1,49 @@
+# 主 Agent 派发与验收
+
+本文由 d2h 使用，负责派发、接收证据、组织验证与验收；不作为实施 Skill 的私有前置。事件字段、证据样例与修订命令只在公共执行协议维护。
+
+## 派发契约
+
+主 Agent 首次派发或写账本时读取 [公共执行协议](execution.md) 的命令与事件章节，核验 ready_batches 后写 start_batch，固定成员清单与 worker；成员启动时再写 start 事件。派发必须包含：
+
+- migration_root、Android/HarmonyOS/repository 绝对路径；
+- pages.json、features.json、execution.json 及派发计划/功能 revision；
+- 当前 milestone、round_id、轮次目标、batch_id、固定 spec_ids、页面 spec.md、当前范围及逐项 requires/provides/checks；
+- 已核验的源分析/目标工程/架构上下文与来源，以及本窗口主模块、目录、共享边界和风险定位；按 [产物契约](artifacts.md) 定向传递，不把来源行号当稳定规划 ID；
+- HEAD、Git status、允许修改路径、共享文件唯一集成负责人；
+- worker 标识、批次预算、设备、证据目录、即时检查、批次检查、验证截止点；明确未领取的同页 Spec。
+
+示例：`Use $d2h-spec-develop. Complete only <spec_ids> in page batch <batch_id>, round <round_id>, at plan revision <revision>. Preserve the page structure; start each member only when its capability gates pass. Return per-Spec evidence and pending checks. Do not add members or edit batch_report.json.`
+
+## 接收、验证与验收
+
+- 新计划派发前核对 readiness_gaps/work_packet_ready，缺口定向交回规划补齐，不重复全量提取。涉及跨 Spec 状态时确认共享通道、载荷、初始化和生命周期均明确；优先检查登出/过期、重复提交及返回恢复等高风险反例。
+- 能力提供者形成实际代码后，主 Agent 核对真实符号、参数/返回与错误语义，通过 [interface 事件](execution.md#实际接口交接) 记录当前候选和代码哈希。接口确认、当前构建和即时契约全部有效才解锁消费者；文件/候选变化或失败后重新确认，不能凭旧签名猜测调用。
+- 在独占窗口内依据 ready 逐个启动成员，避免重新派发 worker 丢失页面上下文。复核源码、实现、断言覆盖和原始受管结果；按 [公共执行协议](execution.md) 的对应事件章节录入，附件清单含 SHA-256。账本脚本只能验证结构和文件身份，主 Agent 必须独立确认命令确实执行、结果和 check 映射真实。
+- candidate 是集成提交或可恢复代码快照。新增代码后记录 candidate 事件（默认所有旧证据 stale）；同一候选构建安装可复用到多个相关 Spec，将相同原始批次证据按真实断言分别映射录入，不能重复声称独立运行。
+- 只有当前构建和 immediate 契约通过才解锁消费者。低风险其余检查可 pending；队列数、预计测试工作量、等待年龄任一达上限时停止新实现，优先验证或修复。测试准备、失败诊断和修复不受“停止新增实现”限制。
+- 失败用 failed，代码或证据变化用 invalidate；修复用 repair，外部阻塞用 block/unblock。受影响消费者即使曾验收也应重新受阻，报告不沿用旧 accepted。
+- 本窗口全部成员已实现且即时门禁通过后 finish_batch 释放；低风险 batch 检查可以继续 pending。中断时先 pause 在途成员再 pause_batch，保留已完成成员，下次只领取剩余就绪项。不能以窗口结束标记整页完成。
+- 全部 checks 和依赖通过后，由主 Agent独立行为复核并逐项 accept。review 说明实际结果、版本和覆盖，不能仅写“脚本通过”。有实现不代表 accepted。
+- 本轮成员全部 accepted 后验证 goal_checks 对应真实路径并 round_accept，才解锁下一轮。后续候选变化保留不可变原始证据支持的历史交付，但当前通过仍需重新验证；失败或显式 invalidate 会使相关轮次重新受阻。
+- 按路径和资源组织测试批次；设备安装/准备/执行期间独占。整个阶段完成前，在最终候选 HAP 上执行覆盖本阶段约定范围的完整 Python Hypium 回归，显式列出所有测试列表，保存证据并逐 Spec 映射。所有本阶段 Spec accepted、无验证债务才可宣布该里程碑完成。
+- 总迁移完成另需覆盖全部约定范围；later/unassigned 或未解决差异须如实报告。d2h 在证据形成后加载 `maintaining-migration-report` 更新并校验实际行为映射，不降低它的证据要求。阶段内成本与缺口写执行账本，完整迁移结束或本次运行明确中止才加载 `reviewing-migration-process`。
+
+计划语义变化调用 `d2h-spec-plan`，先明确处置在途任务、释放活动批次并保存旧版本。状态变化只追加事件、重算并重渲染。实现失败、证据缺失、用户范围取舍是不同状态，不相互替代。
+
+## 基础完成后的再次开发
+
+从 feature_progress.remaining_scope_ids 中选择仍属于本次交付目标的下一轮范围；延期/未分配项由 d2h 核对授权并修订范围版本，再由 d2h-spec-plan 增加 scope_refs 对应 Spec 并 reconcile。复用同一页面、基础 Spec ID 和 requires/provides，不重复认领已完成范围。scope_tracking=false 时先显式升级清单与计划才能声明逐项全量覆盖。milestone_accepted 不能替代全清单 scope_coverage_accepted；全应用当前 HAP 回归属于全迁移完成门禁，本次范围交付须运行覆盖整个目标及必要依赖的当前 HAP 完整回归。
+
+先核对当前交付目标与范围授权：优先采用用户明确选择，无明确选择时由上游写入默认核心范围后交接，不由 worker 临时猜选。MVP/核心/局部交付不因 remaining_scope_ids 非空就自动排期延期层，也不因范围外页面尚未完善而阻止交付；当前目标及必要依赖门禁通过后进入功能 Review，明确交付范围与全量剩余项。已授权全量则按计划继续后续阶段。执行更新后可用 spec_runtime.py dashboard 导出同一账本派生视图，原始基线与 Review 规则见 [交付与看板](delivery.md)。
+
+
+## 窗口上下文复用
+
+派发前使用运行时 `context --batch-id` 获取当前可派发成员的裁剪快照，领取后可再次读取固定窗口。快照只含本窗口 Spec、当前状态、页面定位和所需能力，不能代替 start_batch 或解锁依赖。与上次快照比较 plan_hash、feature_hash、candidate、event_sequence；变化后重新核对相关差异，不把相同摘要当作有效测试证据。
+
+主 Agent 以快照补齐派发契约，并传入页面共享摘要、本轮差异（相对明确 Git 基线的文件/契约变更）、必要源码定位和未决项。首次接手、摘要缺失、来源失效或共享契约变化时定向重读；版本变化本身不要求重扫所有 Facts 和页面。摘要存放原页面 spec.md，使用原计划及执行账本作为真源，不另建长期上下文账本。
+
+同一窗口沿用同一个 worker，内部成员切换仅加载下一个 Spec 的变化和必要依赖。跨窗口复用可验证的摘要与源码定位，不假设新 worker 保留前一 worker 的记忆。不得为维持上下文而超出窗口或延后更高优先级任务。
+
+按 Spec 记录 context_hours（实现投入中理解/准备上下文的子集）、repeated_analysis_hours（context_hours 中重复理解已有材料的子集）；共享投入在成员间仅分摊一次，未知为 null。结合 coordination_share、context_share、repeated_analysis_share 和每窗口 Spec 数复盘，重复分析偏高时先改善摘要/差异交接，再审视拆分与归拢；不根据估计值声称节省 token。

package/contracts/workflow/overview.md

@@ -0,0 +1,58 @@
+# 总览板块与分析通知
+
+看板总览采用四层：状态总览；当前任务 / Spec / 功能摘要；安卓工程 / 环境检查；阻塞与准备缺口。总览不展开完整清单。新增“工程与环境”分页承接代码统计、技术栈、SDK/SO、工具和完整阻塞；分层交付放在规格分页。功能/任务来源保持 F/P/E，不在项目摘要中再建一份任务表。信息少的板块并排，正在实施或记录进行中的分析可显示活动动画；动画不作为百分比或 worker 在线证明，过期快照暂停动画，尊重系统减少动态效果设置。
+
+## 导出
+
+```bash
+d2h workflow dashboard \
+  --plan <pages.json> --features <features.json> --execution <execution.json> \
+  --overview <migration-root>/.migration/dashboard/overview.json \
+  --analysis-progress <run-directory>/analysis.jsonl \
+  --output <same-plan-directory>/dashboard.html
+```
+
+两个新参数均可省略。缺少摘要时对应板块显示未采集，不猜代码量、技术栈、依赖或预检结果。缺少分析文件时不显示假进度。导出命令不运行分析或预检；实时浏览仍由 CLI 调用导出逻辑并提供同源快照端点。
+
+## overview.json：d2h-overview/v1
+
+摘要是可重建的报告视图，不是 Facts、功能计划或执行账本。主 Agent 从实际工具产物和已核验配置归并；把事实来源与迁移处置理由分开。
+
+- schema 固定 d2h-overview/v1，generated_at 为带时区 ISO8601，source_revision 记录实际源版本，candidate 可选且用于失效判断。
+- sources 数组：source_id、path（绝对报告/配置文件路径）、sha256（文件字节 SHA256）。代码块和每个条目用非空 source_refs 引用这些 ID。导出检查文件身份；文件丢失/改变或绑定候选变化会标记摘要过期，不自动把旧工具 PASS 当当前通过。
+- code 可省略/null；存在时有 files、lines（非负整数或 null）、method（统计口径）、languages（name/files/lines）、source_refs。
+- tech_stack 数组：name、version/scope（可选）、source_refs。语言、UI、框架、存储、架构和构建工具按真实配置列出，不根据目录名猜。
+- dependencies 数组：name、kind=sdk/so/library、platform（可选）、provision=self-build/provide-binary/platform-sdk/replace/unknown、status（准备情况文字）、reason（迁移处置依据）、source_refs。
+- tools 数组：name、status=passed/failed/missing/unknown、version/message（可选）、source_refs。版本输出可执行、版本范围合规、目标 SDK 可用、签名就绪及设备可用分别核验，不以 Node/Git 可执行代替 HarmonyOS 预检。
+
+SO 信息需核对 Gradle/CMake/OHPM、ABI/架构、源文件或供应商产物。self-build 表示拟基于现有源码适配编译，不表示已编译成功；provide-binary 必须说明缺哪一目标平台/架构产物。Android .so 存在不能视为 HarmonyOS 可用，无法判定时用 unknown，写清缺口。SDK 的源码声明与本机已安装也分开。
+
+代码统计可执行只读辅助程序：
+
+```bash
+d2h workflow metrics --project <source-project>
+```
+
+stdout 为 d2h-code-metrics/v1。统计已知源码扩展的 LF 物理行数，包含空行/注释，跳过符号链接和报告列出的生成/依赖目录；不等于有效代码量、功能量或完成度。--exclude-dir 可重复传入，显式替换默认排除目录。unreadable_files 非空时必须显示降级，不把漏计称作完整统计。保存实际报告后，在 overview.code 复制 code 部分并添加 source_refs，不改写原始报告。
+
+## AppGraph 事件
+
+appgraph build/spec-analysis 的 --progress-file 输出 appgraph-progress/v1 NDJSON。每个运行使用新文件，run_id 相同、sequence 从 1 连续；只有换行完成的记录才消费，追加中的末尾半行忽略。中间格式错误、序号缺口或混入其他 run 不静默吞掉，导出失败保留原 HTML。
+
+total=null 是总量未知，不算百分比；phase/status 为具体阶段通知。analysis.completed 是整个选用命令结束，warning/unresolved 不因此消失；没有 terminal 不能默认完成。超过 30 秒没有新通知显示暂无新事件并暂停活动动画，不宣称进程已死亡。SIGKILL/宿主失联的判断仍需 CLI 观察进程或心跳。
+
+该分析记录独立于迁移 candidate，不修改已验收状态。主 Agent 显示 source project/run_id/更新时间，避免将其他项目或历史运行冒充当前分析。
+
+## 四层展示口径
+
+阶段条使用分析事件、已有清单/Spec 和当前执行派生值；已有产物不等于人工确认或验收完成。Review 未持久化人工结果时保持待复核。总用时及缺少起止记录的阶段用时显示未记录，不累加并行任务耗时或用文件修改时间补造。分析用时仅为最近接入运行的 elapsed_ms（复用图烟测不代表首次完整分析耗时）。
+
+snapshot.timing.task_started_at 只投影正在执行成员最后一次 start 事件；页面显示起点至 captured_at 的本次派发跨度，不是净工作时长。离线快照不继续累计，在线刷新后更新；总用时仍需后续明确的项目生命周期记录。
+
+Spec 摘要的完成采用当前有效验收，进行中采用 running。功能完成采用所有未排除范围通过；功能进行中为关联任一 running Spec 且该功能尚未全部完成。总数保留清单所有项，存在排除项时提示统计口径。
+
+overview.blockers 为可选数组，每项有 name、category、status=open/resolved、reason、action（可选）及非空 source_refs。用于闭源 SDK/SO、平台接入、App ID / 签名 / 权限等明确缺口；不放凭据本身。dependencies 可用显式 blocking=true 表明阻塞及 action；provide-binary 不自动视为阻塞。总览合并这些记录、失败/缺失工具、任务 external_blockers 和工作包 readiness_gaps，至多显示三条，详情列全。不把正常未完成的 requires 前置一概当外部阻塞。
+
+## 功能分析产物接入
+
+`dashboard --feature-analysis <inventory.json>` 读取新功能清单（兼容旧 feature-analysis.json），要求 features.json 绑定其绝对路径、字节哈希和全部功能行。清单阶段/逐仓实现与证据在分析分页展示；总览功能进度仍按规划与 Spec 派生。技术栈、SDK/SO 和 user_inputs 为报告视图，不自动认定适配产物已可用。--overview 可补充实测代码量和工具；已解决的待办需同报告绑定的 blockers 覆盖。来源行通过公共产物绑定校验；不读取生产 Skill。