@harmonyos-arkts/d2h 0.1.22 → 0.1.27

package/skills/d2h-spec-develop/SKILL.md

@@ -1,41 +1,135 @@
----
-name: d2h-spec-develop
-description: Implement assigned Android-to-HarmonyOS Specs with source-grounded code, managed build and test evidence, scoped commits, and implementation handoff. Use for page or incremental Spec development under the caller's dispatch.
----
-
-# Spec 实施
-
-按调用方指派的 Spec 范围实施 HarmonyOS 页面与业务能力。worker 的创建、每批 Spec/页面数量、执行顺序和逐页复核由主 Agent 或调用方决定，本 Skill 不另设数量或调度限制。
-
-
-
-输入包含增量 v2 计划时，按公共 `d2h workflow contract dispatch` 核对固定 spec_ids、计划/范围版本及批次绑定；绑定缺失或冲突时返回具体缺口。页面 Spec 输入按调用方给定的页面范围执行，不要求先生成 v2 计划。
-
-返回真实实现、证据和未解决请求，由调用方维护执行账本、阶段状态及报告并决定验收。
-
-# Spec 实施与结果交接
-
-只处理输入明确指派的 Spec。先核对计划/范围版本、Git 基线、允许路径和成员；存在冲突时返回具体缺口，不覆盖用户修改。派发数据字段见公共 `d2h workflow contract dispatch`，本 Skill 不要求任何规划技能先运行。
-
-## 理解与实施
-
-1. 阅读页面 spec.md 中当前 spec_id/check 的完整行为、异常、操作、源码依据与实现范围，定向追踪 Android 入口、状态、数据副作用和导航。页面共享摘要用于定位，不能代替源码理解。
-2. 沿用已给定的目标模块、目录、资源规范和状态/生命周期边界。接口缺失、所有权不清或与实际代码冲突时，返回带源码定位的 requiredInputs / planChangeRequests，不自行改方案或扩大范围。
-3. 同一窗口沿用页面上下文，逐成员实施。提供者形成实际代码后返回真实符号、路径、参数/错误语义与生命周期说明，等待调用方确认当前能力再实施消费者；不能用规划签名猜接口。
-4. 实现真实可达的 UI、导航、业务状态、数据效果和要求的失败路径。每个 check 对应实际行为、稳定语义定位和结果断言；不得添加测试替代控件、固定成功值、吞错或不可达页面。
-5. 当前范围涉及平台 API、原生库、身份/资源/i18n 等未知问题时，返回领域请求：问题、来源、当前尝试、所需结论及消费者。调用方提供结论后继续，不在此加载其他技能。
-
-## 构建、检查与提交
-
-- 依据输入项目配置运行已授权的 `droid2hmos build harmony <ANDROID_PROJECT>`，命令非交互且有超时，保留真实命令、退出状态、时间、日志、HAP 路径和哈希。
-- 已提供可执行测试资产且授权本次检查时，可直接运行受管 CLI，保留实际断言、设备、执行数、原始报告和 managedEvidence。缺少测试设计、资产、设备或需共享安装窗口时返回 verificationRequests，不能只写测试未跑却报告通过。
-- 即时契约和高风险检查必须有实际结果，缺口交调用方组织验证；低风险合批待测明确列出，不暗示已验收。静态检查/服务探针不能代替正式设备证据。
-- 修复本范围实现或检查缺陷，保留现有理解与原始失败证据。真实外部问题在诊断和有限重试后可返回 blocked；实现错误不能改写为平台差异。
-- 仅暂存当前实现、资源、必要共享修改和实际测试资产。构建及已要求的即时检查通过后创建或交回作用域提交；允许明确标注待合批验证的实现提交，不把它称为验收提交。残留本任务修改、用户文件及其他任务修改分别列明，不一并提交。
-- 实现提交与后续状态/证据记录分开，由调用方维护后者，避免提交 ID 自引用。当前候选变化后的旧 HAP/证据是否失效由公共运行时维护，不把旧结果绑定新代码。
-
-## 返回
-
-逐 spec_id/check 返回：实际修改与可达行为、接口与消费者、提交/源码身份、构建和测试证据、未执行检查与原因、剩余缺口、请求及用户修改保留情况。耗时未知填 null，不编造节省比例。
-
-不选择下一个批次，不更新执行账本、阶段状态或任何报告。调用方独立核对实现、断言、当前候选、HAP 和设备身份后记录状态与决定验收。
+---
+name: d2h-spec-develop
+description: Implement ordered Android-to-HarmonyOS page tasks from pages.json, batch_report.json, and page-scoped spec.md files. Use during page development when a dedicated page-worker must complete one page's ArkTS implementation and managed build; the parent agent owns testing and fixes, rebuilding, evidence, commits, and final acceptance before the next page starts.
+---
+
+# Page development loop
+
+Each page-worker implements only the selected page and brings its build to a pass. After development is complete, the parent agent takes over testing, defect fixes, and acceptance for the current task.
+
+## Inputs and boundaries
+
+- Use `batch_report.json` for task identities, dependencies, planning and execution state. Read included tasks and execution order from its bound planning field; legacy ledgers without planning use tasks order only when no selected scope is supplied. Do not read plan.json for execution or recovery. Keep task IDs and page packages unchanged.
+- Use the selected page package's `spec.md` as the authority for page scope, behavior, acceptance sequences, Android evidence, and expected HarmonyOS files.
+- When a development scope is supplied, require bound ledger planning and execute only its included tasks. Never select an excluded task because its Spec exists or its ledger state is pending. Return mixed selected/unselected behavior in one Spec as a scope conflict before implementation.
+- Read `.migration/utg/page.json` when the Spec references a UTG node or the arrival path needs clarification. Read cited Android source before implementing or fixing behavior.
+- Each `page_NNNN_<name>-<id>/` directory contains only `spec.md`. Do not add `ui-design.md`, copied screenshots, copied `view.xml`, or test/build evidence to page packages. Keep evidence in the resolved task evidence directory.
+- Do not regenerate `pages.json`, page Specs, or `batch_report.json` during ordinary development. Correct an owning artifact only when current source proves it wrong, record the reason, and preserve execution history.
+- Use `droid2hmos` managed build and test entry points. Do not use task-planning commands or static scripts to choose or execute page work.
+- Preserve unrelated user changes throughout implementation, parent fixes, and commits. Never reset, discard, or include them in a page commit.
+
+## Parent-agent mode
+
+1. Read `pages.json` and `batch_report.json`; verify task identities, Spec paths and dependencies against pages.json, and use ledger planning for development scope and execution order. Verify planning references, counts and states. Reject missing, stale or invalid planning instead of falling back to all tasks when a selected scope or planning is present.
+2. Select the earliest eligible task in planning milestone/wave order (or legacy ledger tasks order when allowed) whose development/build/validation states are not `implemented/passed/passed` and whose declared dependencies are satisfied.
+3. Resolve the page package, Android root, HarmonyOS root, repository root, current `HEAD`, Git status, device target, and task evidence directory.
+4. Dispatch exactly one page-worker with absolute paths, selected task ID, dispatch baseline, device target, and evidence directory. Do not run page-workers in parallel. Wait for its result before the parent begins testing and fixes.
+5. After the worker returns, the parent takes ownership of the current page and executes testing and all fixes according to **Managed page tests and fixes** below until current build and required tests pass.
+6. Execute **Parent report and commits** below.
+7. Apply **Parent verification** below. Only after the page reaches `implemented/passed/passed`, evidence is current, and all page-owned changes are committed may the parent select the next page and dispatch a new worker.
+
+Use this worker prompt contract:
+
+```text
+Use $d2h-spec-develop in page-worker mode. Complete the initial implementation and managed build for exactly <TASK_ID>.
+Skill path: <absolute path to this SKILL.md>
+Migration root: <absolute path>
+Page package: <absolute path>
+Android root: <absolute path>
+HarmonyOS root: <absolute path>
+Repository root: <absolute path>
+Dispatch baseline: <HEAD and recorded Git status>
+Execution ledger: <absolute batch_report.json path; planning revision/hash, milestone ID, wave ID when present>
+Device target: <target>
+Evidence directory: <absolute task/run directory>
+
+Own the complete page loop: read spec.md, UTG evidence and cited Android source;
+implement the page; run managed build; update the migration report and batch_report.json in place;
+create scoped commits;  Do not start another page.
+After handoff, the parent owns all testing, defect fixes, rebuilding, and acceptance.
+```
+
+If independent page-worker execution is unavailable, return that the required mode cannot run. Do not silently implement multiple pages in the parent agent.
+
+## Page-worker mode
+
+### 1. Claim and understand the page
+
+- Confirm the task is the earliest incomplete eligible task in ledger planning (or legacy task order when allowed) and no other page is being implemented or awaiting parent acceptance.
+- Compare the checkout with the dispatch baseline. Preserve and avoid unrelated dirty files; if ownership conflicts with a build-affecting file, return the exact conflict instead of overwriting it.
+- Mark only the selected task `in_progress` in `batch_report.json`.
+- Read the complete `spec.md`, the referenced `.migration/utg/page.json` node, every cited Fact, and every cited Android source file. Follow handlers, state transitions, repositories, navigation, persistence, error paths, and platform side effects far enough to establish the observable result.
+- Inspect the HarmonyOS architecture, routes, resources, shared components, tests, and current implementation. Load `arkts-mvvm-architecture` before planning or writing ArkTS.
+- Build a private checklist mapping every `F-xxx` to reachable code, a stable semantic locator, an executed test assertion, and an observable result. Do not create another planning file.
+- Resume valid existing work for this same task instead of duplicating it.
+
+### 2. Implement
+
+- Implement all page-scoped UI and UI resources, navigation, overlays, state transitions, persistence/data effects, error paths, and required shared integration.
+- Use the Android source and observable behavior for functional truth. Use HarmonyOS-native architecture and components for the target implementation.
+- Give tested interactive elements stable, unique semantic locators. Do not add controls solely to make testing easier.
+- Load the applicable domain Skill for identity, i18n, drawable conversion, icon sizing, or third-party substitution.
+- Before implementing platform capabilities or uncertain HarmonyOS APIs (`@kit.*` Kit imports or `@ohos.*` modules), and when build or test failures point to API signatures or behavior, load `d2h-cloud-knowledge`.
+- Keep shared changes limited to capabilities this page actually needs and record downstream consumers.
+- Do not leave stubs, fixed success values, swallowed errors, unreachable pages, placeholder controls, or TODO implementations.
+
+### 3. Managed build
+
+- Run a fresh, non-interactive, bounded build through `droid2hmos build harmony <ANDROID_PROJECT>` using the resolved project configuration.
+- Save the exact command, exit status, timestamps, relevant log, produced HAP path, and HAP SHA-256 in the task evidence directory.
+- Fix compilation errors caused or exposed by the implementation within this worker until the build passes.
+- An older HAP, static analysis result, direct Hvigor run, or previous log is not current build evidence.
+
+### 4. Worker report and commits
+
+- Load `maintaining-migration-report` while evidence is fresh. Record real HarmonyOS files, Android source provenance, current managed evidence, differences, and source-proven discoveries; run report validation.
+- After a successful build, inspect Git status and diff and create a scoped initial implementation commit containing only this page's implementation, resources, required shared files, and source-proven Spec corrections. Do not commit unrelated changes.
+- Update the existing `batch_report.json` task object, summary, evidence, files, implementation commit, timestamps, blockers, and append-only history in place. Do not rerun `build_batch_report.py`. When planning is present, record planning_ref with revision, sha256, milestone_id and wave_id in this run's task history. Preserve planning and planning_history when updating task results.
+- Set `implemented/passed/not_run` only when all three states are supported by current evidence. Use AI inspection to confirm task/summary/history consistency and preserve all prior history.
+- Return the handoff and stop modifying this page. Do not generate or execute tests or select the next page.
+
+## Managed page tests and fixes
+
+- The parent agent loads `d2h-hypium-forge` to perform testing. Add or update executable Python Hypium tests for every `F-xxx`, with paired `.py` and `.json` test-list assets and stable semantic locators.
+- Cover navigation or overlay lifecycle, state changes, data effects, and error behavior required by the Spec. Assertions must prove the declared result, not merely that a page or button exists.
+- Run only the current page's test lists (the `pageNNNN_*` lists owned by this task) through the managed entry point. Do not append regression lists from other pages.
+
+  ```text
+  droid2hmos test harmony <ANDROID_PROJECT> \
+    --runner python --hypium-project <HARMONY_PROJECT>/.hypium_forge \
+    --test-list <THIS_PAGE_LIST> --target <DEVICE> \
+    --ref <ACTUALLY_ASSERTED_REF>...
+  ```
+
+- Save the exact command, result, native report/log, device target, timestamps, hashes, and returned `managedEvidence` in the task evidence directory.
+- A written-but-unexecuted test, screenshot-only check, coordinate-only replay, direct local runner, old log, or zero-test result is not a pass.
+- After application fixes, repeat managed build, installation, and managed tests until current build and required tests pass. Only persistent external environment, signing, or device failures may become `blocked` after bounded retries and recorded diagnostics.
+
+## Parent report and commits
+
+- Load `maintaining-migration-report` while evidence is fresh. Record real HarmonyOS files, Android source provenance, current managed evidence, differences, and source-proven discoveries; run report validation.
+- Inspect the final diff. After current build and tests pass, commit the parent's page fixes, test files, and necessary shared changes.
+- Update the existing `batch_report.json` task object, summary, evidence, files, implementation commit, timestamps, blockers, and append-only history in place. Do not rerun `build_batch_report.py`. When planning is present, record planning_ref with revision, sha256, milestone_id and wave_id in this run's task history. Preserve planning and planning_history when updating task results.
+- Set `implemented/passed/passed` only when all three states are supported by current evidence. Use AI inspection to confirm task/summary/history consistency and preserve all prior history.
+- Commit the ledger and immutable task evidence separately from the implementation commit. Do not create a self-referential commit field.
+
+## Parent verification
+
+Before dispatching a worker for the next page, the parent confirms:
+
+- every dispatched `F-xxx` has reachable implementation, a stable locator, and an actually executed assertion;
+- the page is reachable from the real app entry without a test-only route or replacement control;
+- final build logs, installed HAP hash, source snapshot, test reports, managed evidence, migration-report refs, and recorded implementation commit correspond to the final tested application;
+- `batch_report.json` is internally consistent and the selected task row is `implemented/passed/passed`;
+- all page-owned implementation, tests, report, ledger, and evidence changes are committed, while unrelated user changes remain untouched;
+- no implementation defect was reclassified as a platform difference or external blocker.
+
+If any check fails, the parent continues fixing the issues and repeats the necessary build/install/test and reporting steps.
+
+## Batch regression
+
+Run the batch regression only when the user explicitly requests it. During ordinary page development, run only the current page's test lists.
+
+## Worker result
+
+Return the task ID and page, final states, implementation and test files, managed build command/HAP/evidence, implementation and ledger commit IDs, unrelated Git changes left untouched, and any genuine blocker or unresolved item.

package/skills/d2h-spec-generate/SKILL.md

@@ -1,20 +1,11 @@
 ---
 name: d2h-spec-generate
-description: Generate detailed Android-to-HarmonyOS spec.md from a selected versioned incremental plan, or use the original standalone page-plan/v1 mode. In from-plan mode preserve scope, IDs and waves and return revision requests; never write the input plan or execution ledger. Original standalone mode generates pages.json and initial batch_report.json from migration Facts, `.migration/utg/page.json`, source code, and existing HarmonyOS implementation, then build batch_report.json with the bundled renderer. Use when pages, dialogs, sheets, or page modes need evidence-backed development specifications and ordered execution records without copied UI artifacts.
+description: Generate page-scoped Android-to-HarmonyOS spec.md files from migration Facts, `.migration/utg/page.json`, source code, and existing HarmonyOS implementation. Use when pages, dialogs, sheets, or page modes need evidence-backed development specifications without copied UI artifacts. Milestones, waves and development scope are planned after generation.
 ---
 
 # Page Spec generation
 
-## Select a mode before writing
-
-- `legacy-page`: original standalone flow below, for no supplied incremental plan or an explicitly selected v1 page flow. Preserve its existing evidence, content and ledger rules.
-- `from-plan`: caller supplies a v2 plan and selected revision/hash plus round/batch/spec IDs. Read [plan consumption](references/from-plan.md) and the public `d2h workflow contract generation`. Only this reference governs writes; do not run legacy steps 2–3 or 6, reorder the plan, require all UTG nodes as tasks, create a v1 plan/ledger, or load another Skill.
-
-A supplied v2 plan always selects from-plan. Missing/invalid bindings or inputs return needs-input/needs-revision, never silently fall back to legacy-page. The input artifact, not the producer Skill, is the dependency. Reuse the original source verification, seven core sections, exception behavior and acceptance requirements in either mode.
-
-## Original standalone flow (legacy-page only)
-
-Generate one implementation-ready `spec.md` for every Android page, dialog, sheet, and behaviorally distinct page mode. The AI determines page boundaries, evidence mapping, dependencies, and development order by reading the actual migration workspace and source code.
+Generate one implementation-ready `spec.md` for every Android page, dialog, sheet, and behaviorally distinct page mode. The AI determines page boundaries, evidence mapping, dependencies and initial order from page.json, Facts and source. User-selected development scope, milestones and waves are handled after full generation.
 
 Do not invoke task-planning, graph-generation, migration, or page-validation scripts. Do not modify Android source, HarmonyOS source, `.migration/spec/`, `.migration/utg/`, `.migration/tasks/`, or the migration report.
 
@@ -29,12 +20,11 @@ Resolve these paths before writing:
 - `harmony_root`: `.migration/config.json.harmonyProject`, resolved relative to `migration_root` when not absolute, unless explicitly supplied.
 - `legacy_tasks_root`: optional `<migration_root>/.migration/tasks`; use existing briefs, core facts, source context, and acceptance files only as read-only evidence from an older flow.
 - `output_root`: default `<migration_root>/.migration/page-specs`.
-
 Facts are the deterministic structured evidence baseline extracted from Android source. They support scope discovery, entity and interaction linkage, report initialization, and omission checks, but unresolved items and extraction gaps mean they are not substitutes for reading Android source and, where necessary, observing runtime behavior. Legacy Task artifacts are read-only indexes from the older flow. Existing HarmonyOS files and tests are implementation evidence, not proof that a behavior is complete.
 
 ## Output contract
 
-Each page unit contains only `spec.md`. `pages.json` and `batch_report.json` live at the output root:
+Each page unit contains only `spec.md`. `pages.json` and the initial `batch_report.json` live at the output root:
 
 ```text
 .migration/page-specs/
@@ -47,7 +37,7 @@ Each page unit contains only `spec.md`. `pages.json` and `batch_report.json` liv
 └── ...
 ```
 
-Directory names encode the AI-selected development order. Use a four-digit sequence and a stable unique suffix derived from the strongest page identity already present in Facts or `page.json`. Re-running against unchanged evidence must preserve existing directory names and order unless the evidence proves the previous boundary or dependency order was wrong.
+Preserve existing page identities and package directories when evidence is unchanged; return source-proven mismatches for reconciliation without resetting execution history.
 
 ## Workflow
 
@@ -63,36 +53,18 @@ Directory names encode the AI-selected development order. Use a four-digit seque
 ### 2. Determine page units with AI reasoning
 
 1. Start from `page.json.pages[]`, then join each page node to Facts surfaces, entries, controls, and interactions by stable ref, declared source, transition, and source behavior.
-2. Treat independently reachable pages, dialogs, sheets, and behaviorally distinct add/edit or selection modes as separate units when they have their own user-visible lifecycle or acceptance flow.
+2. Treat independently reachable pages, dialogs, sheets, and distinct add/edit or selection modes as separate units when they have their own lifecycle or acceptance flow.
 3. Prefer exact ref or normalized identity matches between `page.json.pages[].node_id` and Facts surfaces. Then use labels, `declared_at`, parent relations, navigation steps, source symbols, controls, and Android source behavior.
 4. Never assign behavior from name similarity alone. Record ambiguous mappings in the owning Spec under “未决项与平台差异”.
 5. `capture=false`, an empty `expected`, or a `skip_reason` does not remove a source-proven page. Use those fields as evidence limitations and verify the page through Facts and Android source.
-6. Do not create a fake page for background-only capabilities. Assign startup, notification, widget, receiver, persistence, or other shared responsibilities to the earliest real page that requires them and list downstream consumers.
-7. Legacy page work packages may contain many unrelated surfaces. Split them by actual page lifecycle and behavior ownership rather than retaining the old aggregate.
-
-### 3. Decide development order
-
-Rate each dimension using an integer from 0 to 5, then calculate the score using the following formula:
-
-`page_score = enablement × 9 + ordinary_reachability × 6 + shallowness × 5`（满分 100，分数越高越优先）。
-
-- **Enablement (45%)** — use the highest evidence-backed enablement rating among the page's REQs. `5`: difficult to mock or bound, ambiguous in data ownership, and correctness-relevant across many features. `3`: reused across several features but cleanly isolatable. `1`: page-local. Repeated persistence keys, storage operations, data-flow hops, and consumers are evidence; a feature name is not.
-- **Ordinary reachability (30%)** — `5`: reachable in normal app state. `3`: needs a common business state such as existing data, login, or permission. `0`: first-launch only or reachable only after clearing/resetting app-global state. Use intermediate ratings where evidence supports them.
-- **Shallowness (25%)** — `5`: launch/main page; `4`: one page navigation; `3`: two; `2`: three; `1`: four or more. Derive depth from page boundaries in `page-path`, not click count. `__shared_capability__` uses neutral `3`.
+6. Do not create a fake page for background-only capabilities. Assign startup, notification, widget, receiver, persistence, or other shared responsibilities to the earliest real page that needs them and list downstream consumers.
+7. Split aggregate packages by actual page lifecycle and behavior ownership, keeping one complete Spec per page unit.
 
-When ordering, first satisfy evidence-backed prerequisites so that data or state providers precede their consumers. Sort all remaining pages by page_score in descending order, breaking ties by the normalized stable page_id in ascending order. Finally, assign consecutive order values starting from 1. Prerequisites may override score-based ordering; no other arbitrary reordering is allowed.
+### 3. Determine initial page order
 
-Write the ordered decisions to `<output_root>/pages.json` before creating page directories. Also write the ordinal, dependencies, and concise rationale into each Spec.
+Place evidence-backed prerequisites before consumers, then sort by `page_score = enablement × 9 + ordinary_reachability × 6 + shallowness × 5`, breaking ties by stable page_id. Each rating is 0–5: enablement measures shared correctness impact, ordinary_reachability measures accessibility in normal app state, and shallowness measures page-navigation depth. Record evidence and rationale for each rating; this initial order is a reference for subsequent planning.
 
-Use schema `d2h-page-plan/v1`. Every `pages[]` item must contain:
-
-- consecutive one-based `order`;
-- stable `page_id`, `kind`, `package`, and `page_path`;
-- `spec_refs` and `req_refs` backed by Facts/source evidence;
-- integer `page_score`;
-- `decision_ledger.enablement.rating`, `ordinary_reachability.rating`, and `shallowness.rating`, with evidence and a concise calculation/rationale.
-
-`package` must exactly match `page_NNNN_<name>-<id>`. Every `page.json` node must be represented by a page item or by an explicit exclusion/unmatched entry with a reason. The AI authors and checks this plan; do not use it as a substitute for reading source.
+Before writing Specs, create pages.json with `schema_version: d2h-page-plan/v1`. Each page has consecutive one-based order, page_id, kind, package (`page_NNNN_<name>-<id>`), page_path, spec_refs, req_refs, dependencies, page_score and decision_ledger entries for the three ratings with evidence. Every page.json node must be covered or have an explicit exclusion/unmatched reason. Keep existing task identities when resuming.
 
 ### 4. Verify source before writing
 
@@ -101,11 +73,11 @@ Use schema `d2h-page-plan/v1`. Every `pages[]` item must contain:
 3. Use `page.json` navigation steps, selectors, guards, expected-arrival rules, required state, and depth to reconstruct the semantic arrival path. Source-derived reachability is planning evidence, not runtime confirmation.
 4. Translate selectors into semantic control names only when Facts, resources, or Android source support the mapping. Keep missing or ambiguous selectors explicitly unresolved.
 5. Verify every listed Android path exists under `android_root`. Verify every HarmonyOS path marked `existing` exists under `harmony_root`; otherwise mark it `planned`.
-6. When page features touch platform capabilities (camera, location, files, notifications, Bluetooth, share, Web, background tasks, etc.) or uncertain HarmonyOS APIs (`@kit.*` Kit imports or `@ohos.*` modules), load `d2h-cloud-knowledge` to confirm the corresponding Kit/API availability and system-capability limits before writing: check `.migration/knowledge/kb_cache.json` first, query only on cache miss, cite the doc `title`/`uri` in「未决项与平台差异」or the supporting feature item, and record the topic in the cache with this page as `usedBy`.
+6. When page features touch platform capabilities (camera, location, files, notifications, Bluetooth, share, Web, background tasks, etc.) or uncertain HarmonyOS APIs (`@kit.*` Kit imports or `@ohos.*` modules), confirm the corresponding Kit/API availability and system-capability limits before writing: read supplied knowledge evidence and `.migration/knowledge/kb_cache.json` first; on a gap return knowledgeRequests with the capability, source and question to the caller. Cite confirmed doc `title`/`uri` in「未决项与平台差异」or the supporting feature item. Do not assume API availability or load another Skill here.
 
 ### 5. Write only `spec.md`
 
-Use these headings in every page Spec:
+Use these headings in every page Spec, preserving complete behavior, exception paths and acceptance assertions. F-xxx labels identify page-local behaviors:
 
 ```markdown
 # <页面名称> 迁移 Spec
@@ -122,7 +94,7 @@ Use these headings in every page Spec:
 
 - 顺序：<NNNN>
 - 前置依赖：<无或其他页面标识/共享能力>
-- 排序理由：<基于前置依赖和页面评分的说明>
+- 排序理由：<引用页面依赖、初始顺序和依据>
 
 ## 页面功能
 
@@ -157,9 +129,9 @@ Use these headings in every page Spec:
 
 When a page has no independent interaction, write one display/reachability feature and acceptance sequence instead of leaving the feature sections empty.
 
-### 6. Generate `batch_report.json`
+### 6. Initialize the execution ledger
 
-After all page Specs are complete, generate `<output_root>/batch_report.json` from `pages.json` with the bundled renderer:
+After all page Specs exist, create the initial batch_report.json with the bundled renderer:
 
 ```bash
 python scripts/build_batch_report.py \
@@ -167,41 +139,21 @@ python scripts/build_batch_report.py \
   --output-root <output_root>
 ```
 
-The script requires every planned package to contain `spec.md`, never requires `ui-design.md`, and refuses to overwrite an existing report.
-
-The report must contain:
-
-- the source `pages.json` path and SHA-256;
-- generation timestamp and ordered page count;
-- `schema_version: d2h-page-batch-report/v1`, `source`, `created_at`, and `updated_at`;
-- one ordered `tasks[]` object per page with stable `task_id` (`PAGE-NNNN`), page identity, `spec` relative path, dependencies, scores, `development`, `build`, and `validation`;
-- each task's `implementation_files`, `test_files`, `android_evidence`, `implementation_commit`, `source_snapshot`, `build_evidence`, `test_evidence`, `differences`, `started_at`, `ended_at`, `updated_at`, `blockers`, and append-only `history`;
-- `summary` counts derived from `tasks[]`: classify each task once, in order: `blocked` if any state is blocked, `failed` if build/validation failed, `completed` if implemented/passed/passed, `pending` if pending/not_run/not_run, otherwise `in_progress`; counts sum to `total`;
-- `regression` with status, tested HAP/device, evidence, behavior review, unresolved items, timestamp, and append-only history. Empty values use `null` or `[]`, never Markdown placeholders.
-
-Use these status values:
-
-- development: `pending | in_progress | implemented | blocked`;
-- build: `not_run | passed | failed | blocked`;
-- validation: `not_run | passed | failed | blocked`.
-
-Initial generation uses `pending`, `not_run`, and `not_run`, with empty implementation, test, evidence, commit/snapshot, timestamp, and blocker fields. Do not infer completion from existing HarmonyOS files or local test artifacts.
-
-Once development has started, never rerun the renderer or overwrite `batch_report.json`. Update the owning `tasks[]` object, summary, timestamps, and history in place. If the plan, Spec set, or order no longer matches, reconcile the mismatch without resetting statuses. An existing Markdown ledger must be explicitly migrated with all statuses, evidence and history preserved; changing its extension is insufficient, and the initializer refuses to replace it.
+The renderer requires pages.json v1 and one spec.md per package. Tasks start pending/not_run/not_run; do not infer completion from existing implementation or tests. Never rerun initialization over an existing ledger, reset history, or fabricate acceptance. Return input/Spec mismatches for reconciliation; milestone/wave planning and execution updates belong to the subsequent skills.
 
 ## Quality gates
 
-- Every known source-proven page, dialog, sheet, and behaviorally distinct mode has exactly one `spec.md`, or its ownership is explicitly assigned to another Spec.
+- Every source-proven page, dialog, sheet, and behaviorally distinct mode has exactly one `spec.md`, or its ownership is explicitly assigned to another Spec.
 - Every distinct interaction has a unique `F-xxx`, and feature IDs match UI operation/acceptance sections one-to-one.
 - Each feature states a user action and observable result, not an implementation instruction.
 - Navigation, state changes, persistence, destructive confirmation, external intents, cancellation, dismissal, and error behavior remain explicit.
 - Facts refs, `page.json` node IDs, Android source paths, and HarmonyOS paths are real and correctly classified.
 - Existing HarmonyOS code or tests never cause a feature to be marked complete without current build and executed test evidence.
 - Uncertainty remains explicit. Do not invent control names, outcomes, source mappings, runtime captures, or implementation status.
-- Each `page_NNNN_<name>-<id>/` directory contains exactly one file named `spec.md`.
-- `output_root` contains only `pages.json`, `batch_report.json`, and page directories; it contains no copied UI evidence, UI design, or generated validation artifact.
-- Every page directory has exactly one `tasks[]` object in valid `batch_report.json`; task IDs, order, Spec paths, states, and summary counts agree.
-- A task is complete only when development is `implemented` and both build and validation are `passed` with current evidence.
+- Each planned package directory contains exactly one file named `spec.md`.
+- `output_root` contains pages.json, batch_report.json and page directories; it contains no copied UI evidence, UI design, or invented validation artifact.
+- Every page has one matching task in batch_report.json; IDs, directories, Spec paths and task counts agree. Existing execution results and history are preserved.
+- Spec generation does not mark a task complete. Implementation, current build/test evidence and acceptance remain the caller’s separate execution gates.
 
 ## Result
 
@@ -213,6 +165,6 @@ Return:
 - unreachable pages, capture-disabled nodes, and pages with incomplete arrival rules in `page.json`;
 - ambiguous mappings and unmatched Facts;
 - unresolved selector steps;
-- legacy aggregate packages that were split;
 - the absolute `batch_report.json` path;
+- status and evidence-backed unresolved items or requests;
 - the absolute `output_root`.

package/skills/d2h-spec-generate/assets/spec-template.md

@@ -12,7 +12,7 @@
 |---|---|---|---|---|---|
 | `<feature>/<scope>` | `<milestone>/<round>` | `<batch>` | `<spec>` | `<真实 check_id>` | `<本轮/后续轮/延期/未决/排除及理由>` |
 
-> 成员和边界与 pages.json、features.json 保持一致。延期/未决未分配项不虚构 batch_id 或 spec_id。此文档不保存运行中完成状态，当前验收读取 execution.json 的派生结果。
+> 成员和边界与 pages.json、features.json 保持一致。延期/未决未分配项不虚构 batch_id 或 spec_id。此文档不保存运行中完成状态，当前验收读取 batch_report.json 的派生结果。
 
 ## 页面范围
 

package/skills/d2h-spec-generate/references/from-plan.md

@@ -1,19 +1,27 @@
 # 消费已有增量计划生成规格
 
-仅用于 mode=from-plan，不执行独立旧页面流程的全量拆分、评分排序和账本初始化。结构与生命周期见公共 `d2h workflow contract generation`、`contract plan`、`contract dispatch`，不读取生产者 Skill 的私有资源。
+唯一流程是消费选定的增量计划，不执行全量拆页、评分排序或账本初始化。结构与生命周期见公共 `d2h workflow contract generation`、`contract plan`、`contract dispatch`，不读取生产者 Skill 的私有资源。
 
 ## 核对输入与生成选择
 
 读取计划/功能清单、明确 revision/hash 和选定 spec_ids，核对所属 round/batch、scope_refs/checks、requires/provides、目标文件所有权及当前执行摘要。缺失选择或身份变化返回 needs-input/needs-revision，不默认全量生成。AI 逐项核对 scope_id 到行为、页面和非页面入口的证据；UTG 节点只提供到达/采集线索，不逐节点生成任务。
 
+若交接包含原始 inventory.json，按其稳定来源映射核对选定成员未关联 should_develop=false 的功能；与 features.json/pages.json 不一致时返回范围修订请求，不直接过滤成员或改写计划。should_develop=true 也不授权展开计划外子范围。生成只消费已确认的 scope_refs/checks；清单开关变化不自动重生成已有正文。
+
 已有有效分析与架构直接复用，仅对当前范围补读源码。需要平台知识、原生依赖或架构结论时返回 requests，说明证据、缺口和受影响 Spec，由调用方选择能力；不加载其他 Skill。用户新增需求记录用户来源，不伪造 Android 实现证据。
 
-## 复用原有内容质量
+## 内容质量
+
+用户明确要求复用且不重新生成时，只做已有正文和绑定的只读核对，按下节复用与绑定复核返回 reused、需修订成员和缺口；不执行下面的正文展开或写入绑定步骤。
 
-沿用独立模式第 4 步的源码核验、导航/状态/持久化/取消和异常覆盖、真实路径核对；用 [完整内容要求](spec-content.md) 和 [正式模板](../assets/spec-template.md) 展开当前成员。保留七个核心章节与逐项操作、预期可观察结果、源码和平台依据；不以分组摘要替代成员。正式模板的目录、顺序和依赖从输入计划读取，不执行旧 page_score 公式，不把未选登录方式等整页扩展夹带进来。
+按入口 Workflow 的完整证据索引、页面归属核验与逐项源码追踪执行，保留导航/状态/持久化/取消和异常覆盖、真实路径核对；用 [完整内容要求](spec-content.md) 和 [正式模板](../assets/spec-template.md) 展开当前成员。保留七个核心章节与逐项操作、预期可观察结果、源码和平台依据；不以分组摘要替代成员。正式模板的目录、顺序和依赖从输入计划读取，不执行旧 page_score 公式，不把未选登录方式等整页扩展夹带进来。
 
 仅修改所选成员块和必要共享背景。同页追加新成员时保留原内容、独立 spec_id 和验收状态；未来成员可没有文件或明确待细化，不能拿占位内容登记为完整。使用公共契约规定的成员边界，保证全部 check_id 及对应断言出现在其块内。当前页面的公共章节保留原七章布局，放在所有成员块之外（可在成员之后），逐成员的具体来源/目标实现定位写在该成员块内。
 
-生成中发现规划边界、前置能力、检查层级或 implementation_brief 不足时，返回 proposed_plan_updates 和证据。计划维护者应用后增加 revision，调用方重新选定版本，再完成绑定。生成方不能修改 pages.json、features.json、execution.json、旧批次报告或实际工程代码。
+生成中发现规划边界、前置能力、文件耦合、测试准备、风险或 implementation_brief 与计划假设不符时，返回受影响成员、proposed_plan_updates 和源码证据，不自行分组或调整测试策略。计划维护者应用后增加 revision，调用方重新选定版本，再完成绑定。生成方不能修改 pages.json、features.json、batch_report.json、旧批次报告或实际工程代码。
+
+返回 status、输入与内容版本、generated/updated/reused 的 spec_ids、绝对产物路径、unresolved/requests、已核对成员及建议修订，未审查范围不标为已复核；已复用规格仍核对逐成员绑定。确认结构与正文完整后，使用公共 generation 命令记录明确成员，得到 generation.json；它是文件绑定，不是用户授权或运行通过。发现现有页面不符合本模式边界，先保留备份并返回显式迁移请求，不能覆盖旧文档或旧账本。
+
+## 复用与绑定复核
 
-返回 status、mode、输入绑定、generated/updated/reused 的 spec_ids、绝对产物路径、unresolved/requests、建议修订；已复用规格仍核对逐成员绑定。确认结构与正文完整后，使用公共 generation 命令记录明确成员，得到 generation.json；它是文件绑定，不是用户授权或运行通过。发现现有页面不符合本模式边界，先保留备份并返回显式迁移请求，不能覆盖旧文档或旧账本。
+逐成员核对正文与共享上下文、规划摘要及关联范围。全局计划或功能哈希变化不自动要求重生全部正文；缺少旧输入或成员绑定失效时保留原文，返回具体修订请求，不用当前哈希覆盖旧值作为有效性证明。仅复核或用户禁止重生时不写 spec.md、generation.json，也不自动搬迁目录；reused 只表示正文保留，不能宣称可开工或已验收。

package/skills/d2h-spec-generate/references/spec-content.md

@@ -2,15 +2,13 @@
 
 生成新页面文档、细化当前轮次或审查实施内容时读取 [spec-template.md](../assets/spec-template.md)。模板恢复原页面 Spec 中已使用的七个核心章节：页面范围、开发顺序、页面功能、UI 操作与验收、Android 证据、HarmonyOS 实现范围、未决项与平台差异；在此基础上增加当前增量流程的稳定范围、轮次、批次及逐 spec_id 内容。
 
-这次复用原模板的内容要求，不恢复旧的固定 page_score 排序、带序号目录、逐页全量实现或手写 batch_report 状态。pages.json、features.json 和 execution.json 的职责不变；模板不改变计划 schema，也不证明实际应用已经验收。
-
 ## 生成组织
 
 1. 从选定计划读取完整功能范围去向、稳定 spec_id、依赖、轮次与同轮同页的 page_batches，不重新决定或改写计划。优先通过分组复用上下文，不以减少 Spec 数量或压缩文档为目标。
-2. 每页目录仍只有一份 spec.md；from-plan 模式的七个公共章节保留原布局并置于所有成员块之外，各成员的来源与实现细节保留在自己的稳定块内；页面共用入口、状态与证据写一次，当前轮次的每个 Spec 使用 `### Spec: <spec_id>` 稳定标题，逐项写清范围、行为、异常、数据、副作用及检查。一个文件含多个 Spec 不等于合成一个执行/验收单元。
-3. 按计划组细化当前轮次潜在派发成员，包括组内尚待提供者解锁的消费者。未知契约保留开工问题，不臆造接口。组内成员分别完整，不用组摘要替代。
+2. 每页目录仍只有一份 spec.md；当前流程的七个公共章节保留原布局并置于所有成员块之外，各成员的来源与实现细节保留在自己的稳定块内；页面共用入口、状态与证据写一次，当前轮次的每个 Spec 使用 `### Spec: <spec_id>` 稳定标题，逐项写清范围、行为、异常、数据、副作用及检查。一个文件含多个 Spec 不等于合成一个执行/验收单元。
+3. 只细化调用方在固定版本上选定的成员；其中可以包含尚待提供者解锁的消费者，但不能因其属于同组就自行扩大选择。未知契约保留开工问题，不臆造接口。选定成员分别完整，不用组摘要替代。
 4. 远期内容保留真实已知的范围、前置、验收目标、延期去向与待细化内容，不提前扩成完整实施工单。已授权范围仍须符合 scope_refs 覆盖要求；到达轮次前补齐内容与工作包。
-5. 一个组可以包含一个或多个 Spec，数量按行为、复用、依赖、风险和预算决定。归拢不能抹去独立验收身份，紧密关联的同一闭环也不机械按控件拆分。不同页面或轮次保持不同 batch_id。
+5. 开发组、成员数量、依赖、风险权衡和预算以选定计划为准，生成方不重新分组。可为上下文容量分次完成正文，但不改变 spec_id/round_id/batch_id、范围或验收身份，也不创建新的开发批次。分组证据由 pages.json 维护，正文只引用计划身份；发现问题返回修订请求。
 
 ## 写入前核验（延续原生成要求）
 
@@ -27,7 +25,7 @@
 - 每个范围有唯一负责 Spec，文档与 scope_refs、轮次/批次成员一致；未选范围有去向，没有被“合并”隐去。
 - 每个 check 都有可执行场景、入口/输入、操作、明确断言及验证层级/时机。断言不能只写“正常”“成功”或“符合预期”。
 - 正常与必要失败分支、数据读写与共享生命周期、HarmonyOS 路径、契约边界及阻塞问题足以可靠实施；背景可引用，核心行为不能仅写“同上”。
-- 同页修订只更新受影响 Spec 章节，保留其他成员、已验收身份和历史。补解释文字不自动撤销验收；改范围、checks 或共享契约按语义修订和 reconcile 处理。
+- 同页修订只更新受影响 Spec 章节，保留其他成员、已验收身份和历史。补解释文字不自动撤销验收；改范围、checks 或共享契约由调用方按实际影响修订计划并衔接账本。
 
 内容缺失时主 Agent 返回具体 spec_id/check_id 和待补内容，不派发该成员。现有 readiness_gaps 校验工作包字段与接口等结构约束，并不解析 Markdown、证明章节语义完整；不能因为模板标题存在或程序通过就省略此审查。若后续需要程序化内容门禁，应另行设计显式策略，不能假装当前已有。
 

package/skills/d2h-spec-plan/SKILL.md

@@ -1,38 +1,37 @@
 ---
 name: d2h-spec-plan
-description: Plan reviewable incremental HarmonyOS scope, dependencies, waves and acceptance outlines from versioned scope and architecture. Revise after user adjustments or scope expansion. Returns a versioned plan and gaps; does not generate detailed spec.md, dispatch workers or maintain execution state.
+description: 基于已确认功能范围、选定架构和已有页面规格规划里程碑与波次。用于首次排期、生成后绑定及后续局部修订；保留页面范围、规格和执行历史，不负责 Spec 划分、生成、开发或验收。
 ---
 
-# 增量 Spec 规划
+# Spec 规划
 
-把明确的交付范围转为可评审、可调整的增量计划。先提出波次供用户调整，再按选定版本交给独立生成能力展开详细规格；已有明确授权时无需重复确认。消费的是产物和调用参数，不要求先运行指定技能，也不加载其他技能。缺少领域结论时返回请求，由调用方决定如何补齐。
+消费已确认的功能范围、选定架构和已有分析，组织“里程碑 → 波次 → 已有页面任务”。本技能将已确认范围映射到已有任务，安排任务排序、交付目标、里程碑和波次；页面划分、依赖、初始顺序、Spec 内容及初始账本由规格生成流程负责，逐页实施和验收由页面开发流程负责。
 
-## 输入
+1. 里程碑（Milestone）: 用户确认范围内的阶段目标。
+2. 波次（Wave）: 里程碑内一组按计划顺序推进的完整页面任务，明确目标、必要前置和结束条件。
+3. 页面任务: 引用已有 pages.json 的 page_id、order、package 及执行账本任务 ID，不新建 spec_id 或拆分一个页面的开发闭环。
 
-- 版本化 `features.json`：稳定功能/范围 ID、用户选择、优先级、里程碑、来源与版本。已有有效清单直接复用，不重新分析功能或改写授权。
-- Android 源码、现有实现及目标工程定位；Facts、UTG 到达/采集计划、架构上下文和既有证据按当前任务需要读取。UTG 的 `page.json` 不是业务页面或开发任务队列，不能逐节点转换成 Spec。
-- 修订时提供旧计划/Spec、范围差异和当前能力/在途摘要。执行账本可以提供只读线索，不由本 Skill 修改。
+## 开发范围与排序
 
-需要字段定义或结构校验时使用公共工具 `d2h workflow contract plan`、`d2h workflow contract scope`、`d2h workflow validate --planning-only --plan <pages.json> --features <features.json>`。这是显式工具依赖；工具不可用时返回缺少的能力，不加载其他 Skill 或自行安装工具。
+将用户已确认范围映射到已生成任务，仅把已选范围及获授权的必要前置纳入波次；其余任务明确排除，保留规格和账本，不参与本次完成判断。
 
-## 按任务读取
+必要前置涉及未选或明确排除的独立功能，或同一 Spec 混合已选和未选功能时，返回具体范围冲突，由调用方处理，不自行扩大范围或整份派发。
 
-| 任务 | 本 Skill 的参考 |
-|---|---|
-| 初次规划、范围/依赖/批次组织变化 | [planning-method.md](references/planning-method.md) |
-| 接收目标目录、所有权与共享边界 | [architecture-handoff.md](references/architecture-handoff.md) |
-| 评估本轮范围、最小前置与验收 | [round-scope-assessment.md](references/round-scope-assessment.md) |
-| 细化实施工作包和共享接口约束 | [work-packets.md](references/work-packets.md) |
+按用户目标、优先级和实际依赖确定任务排序，划分里程碑和波次；页面归属及生成时的顺序仅作参考。排序不得绕过前置，页面范围或依赖有误时返回调用方处理。
 
-## 输出与边界
+## 风险与测试安排
 
-- `pages.json` v2：范围映射、Spec 身份、依赖、轮次、固定同页批次、实现位置、工作包、成本和测试安排。
-- 便于评审的波次摘要：目标、范围、前置、延期、估算与验收概要。摘要从 pages.json 派生，不成为第二份计划真源。
-- 新增 `spec_generation_policy=required-v1`。本 Skill 不写 spec.md 或 generation.json；生成任务的输入/输出见公共 `d2h workflow contract generation`。
-- 返回 `status`（planned / needs-input / needs-revision）、`artifacts`、`changes`、`unresolved` 与 `requests`。修订差异明确受影响/保留的 Spec、批次与范围；请求说明所需知识、接口、工程或验证结论及消费者，不指定下一项 Skill。
+记录波次成本、风险、外部条件及结束时需要核对的页面验收结果，不改变逐页构建、测试、提交和验收要求。页面未完成不能因波次收尾而跳过；阶段完成必须引用执行账本和当前证据。
 
-调用方维护用户范围及交付目标。只在独立交付、解锁依赖、风险差异或跨轮延期需要时拆 Spec，按源码与真实行为归并页面；不从模块名、控件或 UTG 节点机械拆分。缺口阻止相应成员开工，不冒充已实现或已验收。
+## 交付与记录
 
-版本变化保留稳定 ID 和历史；已有在途成员时先返回修订建议，由调用方处置派发与状态再应用。MVP 扩展到核心时复用仍有效的分析和架构，保留已完成 Spec、目录和历史，仅规划新增范围与受影响依赖；范围缺口返回调用方，不机械重跑前置阶段。
+里程碑、波次、排序和纳入/排除任务统一保存到 `batch_report.json.planning`，由主 Agent 核对后原位写入；修订前将旧规划完整追加到 planning_history。开发与恢复只读取该账本，不维护独立的当前 plan.json。
 
-规划不写 `execution.json`，不生成执行报告或看板，不选择 worker，不决定构建/测试时机的实际执行，不判定验收通过。
+分析及评审保存在 `<migration_root>/.migration/spec-planning/analysis.md` 和 `planning-review.md`，调用方指定目录时沿用其路径。pages.json 和 spec.md 只读，规划更新不修改账本任务结果、证据或执行历史。交接账本绝对路径及 planning 的 revision/hash；在途任务先由主 Agent 处置，仅调序不使既有验收失效，范围变化另行复核。
+
+## 按需参考
+
+- 正式规划时，参考 [规划工作](references/planning-method.md#规划工作)；写入计划时核对 [计划格式](references/plan-contract.md)。
+- 确定波次目标、前置及结束条件时，参考 [每轮需要回答的问题](references/round-scope-assessment.md#每轮需要回答的问题)。
+- 核对页面依赖和原验证要求时，参考 [共享状态与验证安排](references/work-packets.md)。
+- 交付计划、复核及变更时，参考 [规划交付与评审记录](references/planning-review.md)。

package/skills/d2h-spec-plan/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
-  display_name: "页面轮次与增量 Spec 规划"
-  short_description: "围绕目标组织页面轮次、同页开发批次、依赖和测试计划"
-  default_prompt: "Use $d2h-spec-plan to read the feature plan and source evidence, then author or revise a reviewable v2 wave plan, preserving user choices and completed scope. Return fixed IDs, dependencies and acceptance outlines; do not write detailed spec.md."
+  display_name: "里程碑与波次规划"
+  short_description: "根据已确认范围与已有页面任务规划里程碑和波次"
+  default_prompt: "Use $d2h-spec-plan to plan milestones and waves over existing page tasks, preserving their scope, identities, generation and development contracts while ordering execution by user goals and dependencies."

package/skills/d2h-spec-plan/references/plan-contract.md

@@ -1,13 +1,38 @@
 # 计划产物契约
 
-`pages.json` v2 是稳定的产物协议，不属于某个计划生产者。字段与兼容规则由公共工具维护：
+里程碑、波次、任务排序和本次开发范围保存在 `.migration/page-specs/batch_report.json` 的 planning 字段，作为执行与恢复时的唯一规划依据。tasks、summary、regression 及已有证据和历史保留；不另行维护当前 plan.json。
 
-```text
-d2h workflow contract plan
-d2h workflow contract scope
-d2h workflow validate --planning-only --plan <pages.json> --features <features.json>
+以下为账本新增字段示例，不是完整账本，不能据此覆盖已有文件：
+
+```json
+{
+  "planning": {
+    "schema_version": "d2h-milestone-plan/v1",
+    "revision": 1,
+    "phase": "bound",
+    "sha256": "<planning-content-sha256>",
+    "sources": [{"path": "/abs/features.json", "sha256": "<file-sha256>"}],
+    "milestones": [{"milestone_id": "usable", "goal": "基础路径可用", "rationale": "用户确认目标"}],
+    "excluded_tasks": [],
+    "waves": [{
+      "wave_id": "wave-1", "milestone_id": "usable", "goal": "首页及必要前置可用",
+      "task_ids": ["PAGE-0001"],
+      "prerequisites": ["账本任务声明的前置已满足"],
+      "exit_criteria": ["所引任务完成实现、构建及验收，并有当前证据"],
+      "rationale": "按用户目标和依赖安排执行顺序"
+    }]
+  },
+  "planning_history": []
+}
 ```
 
-本 Skill 输出轻量 Spec 条目、依赖、轮次/批次、已知工作包约束和验收概要；详细正文与生成绑定由独立生成能力维护。新计划开启 spec_generation_policy=required-v1。生成输入输出读取 d2h workflow contract generation。规划校验不要求页面目录或 spec.md 已存在，规划方法见 [planning-method.md](planning-method.md)。调用方执行事件、派发和生成报告；规划不创建执行状态。
+- planning 可在全量规格及账本生成后添加，不要求修改生成脚本。无该字段的已有账本按既有任务顺序执行；已确认选择开发范围或已有 planning 时，不得因 planning 缺失、无效或非 bound 而回退全量开发。生成前的功能草案只记入分析，不能伪造任务或账本。
+- milestones、waves 的 ID 各自唯一，wave.milestone_id 必须指向已声明里程碑。本次纳入任务在 waves[].task_ids 中恰好出现一次，必须存在于 tasks[]；未纳入任务在 excluded_tasks 记录 task_id 和 reason。两者不重叠，合计覆盖全部账本任务；混合已选/未选行为及前置授权冲突未解决时不能标为 bound。
+- 执行顺序由 milestones、所属 waves 及 task_ids 的数组顺序确定，任务前置必须先于消费者。任务 ID、生成时的 order、Spec 路径及目录不随排序改变；里程碑和波次不复制任务执行状态。
+- sources 保存已确认范围等输入的路径与字节 SHA-256。planning.sha256 只对 planning 去掉 sha256 后的内容计算：`sha256(json.dumps(content, sort_keys=True, ensure_ascii=False).encode('utf-8'))`；任务状态、证据及整个账本哈希不参与，避免每次执行使规划身份变化。
+- spec-plan 交付 planning 内容，由主 Agent 核对引用、范围、依赖及当前账本后原位写入；写入前重新读取并确认账本未被其他执行更新，发生变化先复核，不覆盖新历史。首次添加仅新增规划字段；修订先将旧 planning 完整追加到 planning_history，再增加 revision、计算新哈希并更新 planning，保留 tasks、证据和执行历史。无实质变化不增版；在途任务先交调用方处理，不能静默切换其执行版本。
+- worker 在 tasks[].history 的本次执行记录中保存 planning_ref：revision、sha256、milestone_id、wave_id。重新排期不能覆盖旧执行关联；仅调整排序不使既有验收失效，范围变化须复核，不能自动沿用旧验收。
+- summary 继续统计全量任务；本次、里程碑及波次进度从 planning 的成员与 tasks 的当前结果关联计算。未选任务保留状态，不标通过、不阻塞本次交付，本次范围完成不等于全量迁移完成。
+- 历史 plan.json 只作归档。迁移时核对实际任务和历史，再将完整规划写入账本；存在两处规划且不一致时返回冲突，不按文件更新时间猜测有效版本。开发和恢复读取账本 planning，不读取归档计划。
 
-结构校验通过不代表源码理解、授权范围、架构归属或实际行为已通过人工复核。只使用已给定输入，不根据产物缺失猜测执行状态或强制运行特定生产技能。
+analysis.md 与 planning-review.md 的来源、修订及评审规则见 [规划交付与评审记录](planning-review.md)。本模式由 AI 核对，不以增量 Spec v2 的 workflow validate --planning-only 冒充此账本关联已通过校验。