@harmonyos-arkts/d2h 0.1.21 → 0.1.26

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

@@ -1,143 +1,126 @@
----
-name: d2h-spec-develop
-description: Implement fixed versioned incremental Specs in from-plan mode, or use the original ordered page-ledger flow in legacy-page mode. 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 through ArkTS implementation, managed build, Python Hypium tests, scoped commits, migration-report evidence, and in-place ledger updates before the next page starts.
----
-
-# Spec implementation modes
-
-- `from-plan`: a v2 plan, fixed spec_ids/batch and detailed generated Specs are supplied. Follow [fixed implementation](references/worker-workflow.md) and public `d2h workflow contract dispatch`. Return scoped code, evidence and requests; do not select tasks, load other Skills, write execution/report ledgers or claim acceptance. Do not execute the legacy workflow below.
-- `legacy-page`: the original v1 pages.json and tasks[] ledger flow below. Preserve its serial page worker, implementation, actual evidence and ledger requirements.
-
-A supplied incremental v2 plan selects from-plan. Invalid/missing version bindings return needs-input, never silently fall back to legacy or mix ledger schemas.
-
-## Original page workflow (legacy-page only)
-
-# Page development loop
-
-Implement and verify one ordered page task at a time. The parent agent selects and reviews the task; a dedicated page-worker owns exactly one page's complete loop.
-
-## Inputs and boundaries
-
-- Use `.migration/page-specs/pages.json` as the immutable page order and `batch_report.json` as the mutable execution ledger.
-- Use the selected page package's `spec.md` as the authority for page scope, behavior, acceptance sequences, Android evidence, and expected HarmonyOS files.
-- Read `.migration/utg/page.json` when the Spec references a UTG node or the arrival path needs clarification. Read cited Android source before implementing behavior.
-- Do not require or generate `ui-design.md`, copied screenshots, copied `view.xml`, or any other page-package artifact. Each `page_NNNN_<name>-<id>/` directory continues to contain only `spec.md`.
-- 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. Never reset, discard, or include them in a page commit.
-
-## Parent-agent mode
-
-1. Read `pages.json` and `batch_report.json`; use AI judgment to verify their task IDs, order, links, counts, and current states agree.
-2. Select the earliest ordered page 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 or give one worker multiple pages.
-5. Wait for the worker to complete the selected page. If it is incomplete or fails review, send the same page back for repair; do not select another page.
-6. Independently verify the resulting implementation, current managed build/test evidence, migration report, commits, batch ledger, and Git status.
-7. Only after the selected task is genuinely `implemented/passed/passed` may the parent select the next task.
-8. Only when the user explicitly requests it, enumerate every Python Hypium test list and run one managed batch regression. Append the batch evidence to `batch_report.json` and the migration report.
-
-Use this worker prompt contract:
-
-```text
-Use $d2h-spec-develop in page-worker mode. Complete exactly <TASK_ID>.
-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>
-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; load $d2h-hypium-forge and execute the
-page tests through the managed Python runner; update the migration report;
-create scoped commits; and update batch_report.json in place. Do not start another page.
-```
-
-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 row and no other task is `in_progress`.
-- 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 the working copy of `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, navigation, overlays, state transitions, persistence/data effects, error paths, resources, 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 when the page touches that domain. 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`: check `.migration/knowledge/kb_cache.json` first, query only on cache miss, and record conclusions with doc `title`/`uri` back into the cache, the page spec evidence, and the migration report.
-- 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.
-- Treat compilation errors caused or exposed by the implementation as work to fix. Repeat edit/build until the managed build passes.
-- An older HAP, static analysis result, direct Hvigor run, or previous log is not current build evidence.
-
-### 4. Managed page tests
-
-- Load `d2h-hypium-forge`. 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.
-- Fix implementation or test defects and repeat managed build/test until both pass. Only a persistent external environment, signing, or device failure may become `blocked`, after bounded retries with diagnostics recorded.
-
-### 5. Report and commit
-
-- 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 Git status and diff. Stage only the selected page's implementation, resources, tests, necessary shared files, and a source-proven correction to this page's `spec.md` when required. Do not include unrelated changes.
-- Create a scoped implementation commit only after the managed build and page tests pass. Record its commit ID.
-- If build-affecting page changes remain after the commit, correct the commit and rerun build/test so the evidence proves the committed tree.
-- Update the selected `tasks[]` object in `batch_report.json`: states, evidence, files, implementation commit, differences, timestamp, blockers, and append-only history. Recalculate `summary` using the classification in `d2h-spec-generate` and update the report timestamp. Do not rerun `build_batch_report.py`.
-- Set `development/build/validation` to `implemented/passed/passed` only with current evidence. Check task/summary consistency and preserve all prior history; store batch regression evidence and review in `regression`.
-- Commit the ledger and immutable task evidence separately from the implementation commit. Do not create a self-referential commit field.
-
-## Parent verification
-
-Before accepting the worker result, independently confirm:
-
-- every `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;
-- build logs, HAP hash, test reports, managed evidence, and migration-report refs correspond to the implementation commit;
-- `batch_report.json` is valid JSON, its summary matches `tasks[]`, and the selected task is `implemented/passed/passed`;
-- both scoped commits exist and no uncommitted change owned by the page remains;
-- user changes and other pages were not reset or included;
-- no implementation defect was reclassified as a platform difference or external blocker.
-
-Review failure returns the same task for repair. The worker never selects or starts the next task.
-
-## 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 (see Step 4). The parent agent's final delivery gate in `agents/d2h.md` remains responsible for application-wide acceptance.
-
-When a batch regression is requested:
-
-1. Enumerate every current Python Hypium test list explicitly; the Python runner does not use `--all`.
-2. Run one managed command with all required `--test-list` values on the qualified device, using only refs actually asserted by the batch.
-3. Require non-zero execution with no failures, errors, or ignored tests.
-4. Append the managed batch evidence and timestamp to `batch_report.json`, then update and validate the migration report.
-5. Treat this managed Python batch as the primary application-wide regression for the page-spec workflow. Run ArkTS `--all` only as supplemental coverage when the project maintains relevant ArkTS ohosTest assets; it is not a fixed completion gate for this workflow.
-
-## Worker result
-Return the task ID and page, final states, implementation and test files, managed build command/HAP/evidence, managed test command/evidence, implementation and ledger commit IDs, unrelated Git changes left untouched, and any genuine blocker or unresolved item.
+---
+name: d2h-page-develop
+description: Implement ordered Android-to-HarmonyOS page tasks from pages.json, batch_report.md, and page-scoped spec.md files. Use during page development when a dedicated page-worker must complete one page through ArkTS implementation, managed build, Python Hypium tests, scoped commits, migration-report evidence, and in-place ledger updates before the next page starts.
+---
+
+# Page development loop
+
+Implement and verify one ordered page task at a time. The parent agent selects and reviews the task; a dedicated page-worker owns exactly one page's complete loop.
+
+## Inputs and boundaries
+
+- Use `.migration/page-specs/pages.json` as the immutable page order and `batch_report.md` as the mutable execution ledger.
+- Use the selected page package's `spec.md` as the authority for page scope, behavior, acceptance sequences, Android evidence, and expected HarmonyOS files.
+- Read `.migration/utg/page.json` when the Spec references a UTG node or the arrival path needs clarification. Read cited Android source before implementing behavior.
+- Do not require or generate `ui-design.md`, copied screenshots, copied `view.xml`, or any other page-package artifact. Each `page_NNNN_<name>-<id>/` directory continues to contain only `spec.md`.
+- Do not regenerate `pages.json`, page Specs, or `batch_report.md` 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. Never reset, discard, or include them in a page commit.
+
+## Parent-agent mode
+
+1. Read `pages.json` and `batch_report.md`; use AI judgment to verify their task IDs, order, links, counts, and current states agree.
+2. Select the earliest ordered page 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 or give one worker multiple pages.
+5. Wait for the worker to complete the selected page. If it is incomplete or fails review, send the same page back for repair; do not select another page.
+6. Independently verify the resulting implementation, current managed build/test evidence, migration report, commits, batch ledger, and Git status.
+7. Only after the selected task is genuinely `implemented/passed/passed` may the parent select the next task.
+8. Only when the user explicitly requests it, enumerate every Python Hypium test list and run one managed batch regression. Append the batch evidence to `batch_report.md` and the migration report.
+
+Use this worker prompt contract:
+
+```text
+Use $d2h-page-develop in page-worker mode. Complete exactly <TASK_ID>.
+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>
+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; load $d2h-hypium-forge and execute the
+page tests through the managed Python runner; update the migration report;
+create scoped commits; and update batch_report.md in place. Do not start another page.
+```
+
+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 row and no other task is `in_progress`.
+- 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 the working copy of `batch_report.md`.
+- 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, navigation, overlays, state transitions, persistence/data effects, error paths, resources, 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 when the page touches that domain. 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`: check `.migration/knowledge/kb_cache.json` first, query only on cache miss, and record conclusions with doc `title`/`uri` back into the cache, the page spec evidence, and the migration report.
+- 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.
+- Treat compilation errors caused or exposed by the implementation as work to fix. Repeat edit/build until the managed build passes.
+- An older HAP, static analysis result, direct Hvigor run, or previous log is not current build evidence.
+
+### 4. Managed page tests
+
+- Load `d2h-hypium-forge`. 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.
+- Fix implementation or test defects and repeat managed build/test until both pass. Only a persistent external environment, signing, or device failure may become `blocked`, after bounded retries with diagnostics recorded.
+
+### 5. Report and commit
+
+- 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 Git status and diff. Stage only the selected page's implementation, resources, tests, necessary shared files, and a source-proven correction to this page's `spec.md` when required. Do not include unrelated changes.
+- Create a scoped implementation commit only after the managed build and page tests pass. Record its commit ID.
+- If build-affecting page changes remain after the commit, correct the commit and rerun build/test so the evidence proves the committed tree.
+- Update the existing `batch_report.md` queue row, detail section, counts, evidence, files, implementation commit, timestamp, blocker, and chronological notes in place. Do not rerun `build_batch_report.py`.
+- Set `implemented/passed/passed` only when all three states are supported by current evidence. Use AI inspection to confirm queue/detail/count 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 accepting the worker result, independently confirm:
+
+- every `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;
+- build logs, HAP hash, test reports, managed evidence, and migration-report refs correspond to the implementation commit;
+- `batch_report.md` is internally consistent and the selected row is `implemented/passed/passed`;
+- both scoped commits exist and no uncommitted change owned by the page remains;
+- user changes and other pages were not reset or included;
+- no implementation defect was reclassified as a platform difference or external blocker.
+
+Review failure returns the same task for repair. The worker never selects or starts the next task.
+
+## 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 (see Step 4).
+
+## Worker result
+Return the task ID and page, final states, implementation and test files, managed build command/HAP/evidence, managed test command/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, existing HarmonyOS implementation, and selected versioned plan inputs. Use when pages, dialogs, sheets, or page modes need evidence-backed development specifications without copied UI artifacts. Scope, ordering, waves and batches come from the input plan; execution state is maintained by the caller.
 ---
 
 # 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 selected Android page, dialog, sheet, and behaviorally distinct page mode. The AI verifies evidence mapping and behavior by reading the actual migration workspace and source code. Page/Spec boundaries, dependencies, development order, waves and batches are supplied by the selected plan; return discrepancies instead of replanning.
 
 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,25 +20,29 @@ 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`.
+- `plan`: pages.json v2 and features.json absolute paths, selected revision/hash and explicit spec_ids; preserve their scope_refs/checks, page packages, round_id/batch_id and allowed implementation paths. Missing or changed inputs return needs-input/needs-revision.
+
+Use the public `d2h workflow contract generation` for input/output bindings. Consume artifacts, not the producer Skill or its private resources.
 
 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`. The input `pages.json` and caller-owned `batch_report.json` live at the output root; this Skill writes page Specs and the generation binding only:
 
 ```text
 .migration/page-specs/
 ├── pages.json
-├── batch_report.json
-├── page_0001_<name>-<id>/
+├── batch_report.json  # caller-owned execution ledger, read-only
+├── generation.json   # generated content binding
+├── <plan.package-A>/
 │   └── spec.md
-├── page_0002_<name>-<id>/
+├── <plan.package-B>/
 │   └── spec.md
 └── ...
 ```
 
-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.
+Use the stable package directories supplied by the plan. Re-running against unchanged evidence must preserve existing directory names and the selected order; evidence of incorrect boundaries or dependencies is returned as a proposed plan revision, not applied here.
 
 ## Workflow
 
@@ -60,39 +55,21 @@ Directory names encode the AI-selected development order. Use a four-digit seque
 5. Read the current migration report to understand existing mappings and unresolved items, without treating report status as proof of implementation.
 6. Inspect HarmonyOS route registration, `.ets`/`.ts` components, shared state, resources, and tests to distinguish existing implementation from planned work.
 
-### 2. Determine page units with AI reasoning
+### 2. Verify planned 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. Verify that independently reachable pages, dialogs, sheets, and behaviorally distinct add/edit or selection modes have explicit planned ownership when they have their own user-visible lifecycle or acceptance flow. Return missing or incorrect ownership as a revision request.
 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`.
-
-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.
+6. Do not create a fake page for background-only capabilities. Verify the planned ownership of startup, notification, widget, receiver, persistence, or other shared responsibilities and list downstream consumers; return missing ownership instead of assigning it here.
+7. A planned package may contain several independent Specs. Verify each selected member against its actual lifecycle and behavior ownership; do not merge identities or silently expand the selection.
 
-Write the ordered decisions to `<output_root>/pages.json` before creating page directories. Also write the ordinal, dependencies, and concise rationale into each Spec.
+### 3. Consume development order
 
-Use schema `d2h-page-plan/v1`. Every `pages[]` item must contain:
+Read scope, ownership, dependencies, order, rounds and page batches from the selected pages.json. Do not recalculate scores, change members, create groups, rename packages, or write another plan. Cite the planned order, dependencies and rationale in each Spec. Source-proven conflicts return proposed_plan_updates and evidence to the caller.
 
-- 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.
+Generation may run in multiple writing passes to fit the available context, but those passes do not change development batches, budgets, spec_id/round_id/batch_id, or independent acceptance identities.
 
 ### 4. Verify source before writing
 
@@ -101,11 +78,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. For incremental members, keep this seven-section content and use [the detailed template](assets/spec-template.md) and [content requirements](references/spec-content.md) to bind each selected spec_id/check_id to its own complete behavior and acceptance block. F-xxx labels remain page-local behavior labels, not replacements for planned identities:
 
 ```markdown
 # <页面名称> 迁移 Spec
@@ -122,7 +99,7 @@ Use these headings in every page Spec:
 
 - 顺序：<NNNN>
 - 前置依赖：<无或其他页面标识/共享能力>
-- 排序理由：<基于前置依赖和页面评分的说明>
+- 排序理由：<引用输入计划中的依赖、顺序和依据>
 
 ## 页面功能
 
@@ -157,51 +134,25 @@ 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`
-
-After all page Specs are complete, generate `<output_root>/batch_report.json` from `pages.json` with the bundled renderer:
-
-```bash
-python scripts/build_batch_report.py \
-  --pages-plan <output_root>/pages.json \
-  --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`.
+### 6. Review and record generated content
 
-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.
+After the selected Specs are complete, follow [the generation handoff](references/from-plan.md) to verify their source coverage and selected input hash, then use public `d2h workflow generation` to record generation.json for the explicit members. This records content identity, not semantic approval or runtime acceptance.
 
-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.
+Do not initialize or update batch_report.json, generate task state, or infer completion from existing HarmonyOS files or local test artifacts. The caller owns the sole execution ledger and its events. Return missing inputs, unresolved behavior, and proposed plan updates with concrete source evidence; do not reset history or fabricate ready/accepted status.
 
 ## 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 selected source-proven page, dialog, sheet, and behaviorally distinct mode has exactly one `spec.md`, or its planned 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` keeps caller-owned inputs and ledger, generation.json, derived reading views, and planned page directories; it contains no copied UI evidence, UI design, or invented validation artifact.
+- Every selected member agrees with its planned directory, scope and checks; supplied execution records are read-only. No task or summary state is written by this Skill.
+- 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 +164,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;
+- the absolute generation.json path and caller-owned `batch_report.json` path when supplied;
+- the selected input versions, generated/updated/reused spec_ids, status and evidence-backed unresolved/requests/proposed_plan_updates;
 - 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 只表示正文保留，不能宣称可开工或已验收。