@harmonyos-arkts/d2h 0.1.19 → 0.1.21

package/docs/incremental-spec-evaluation-design.md

@@ -0,0 +1,670 @@
+> 2026-10-23 入口更新：功能清单现由 `feature-list-analysis` 接管，分析报告 → 版本化 features.json → Spec。本文旧 d2h-feature-planning 名称及 inventory 流程为历史设计；当前执行入口、来源绑定与用户意图规则以新技能的 spec-handoff.md 为准。
+
+# 增量 Spec 评估、任务分配与测试调度设计
+
+状态：已实现单实现 worker 的页面轮次、同页批次、逐项范围验收、裁剪上下文、工作包就绪、共享状态契约、实际接口交接及事件账本；多 worker 并发、非设备证据适配和自动影响范围复用仍为后续增强。
+日期：2026-10-22
+适用范围：d2h 编排与 Spec；涉及 droid2hmos 验证协议的部分按需协同实现。
+
+## 1. 目标与成功标准
+
+以较小投入尽快交付可验收的核心用户路径，再逐步完善功能。首个典型里程碑为“启动 → 基本登录 → 主页面雏形”。不能用页面数量、提交数量或 worker 忙碌程度替代用户可用结果。
+
+设计需要支持：
+
+1. 合并源码分析、前阶段产物和用户手动输入的功能清单，允许调整范围、阶段与顺序。
+2. 将页面拆成可独立验收的功能增量，避免登录等前置页面的完整功能阻塞首页。
+3. 根据里程碑收益、依赖、成本选择 Spec，并评估所需 worker。
+4. 在必要时即时测试，合并重复测试准备，限制待验证工作积压。
+5. 记录计划与实际结果，评估拆分、分工和测试时机是否合适。
+
+初期观察指标：首条核心路径验收耗时、总 worker 投入、验证队列年龄、返工占比、里程碑后发现的缺陷。与范围和环境相近的历史批次比较，暂不设置未经基线验证的提速承诺。
+
+## 2. 原有流程与本次替代的约束
+
+原 `d2h-spec-generate` 使用：
+
+`page_score = enablement × 9 + ordinary_reachability × 6 + shallowness × 5`。
+
+原主流程和 `d2h-spec-develop` 要求逐页串行、一个独立 page-worker 完成整页，实现、构建和验证全部通过后才能开始下一页。当前计划顺序通常在开发时保持不变。
+
+这些约束保证逐页闭环，但不能直接支持本方案：
+
+- 前置依赖粒度为页面时，基本登录会连带其他登录功能提前。
+- 页面深度和可达性不能充分表达当前里程碑的边际收益。
+- 每页独立构建、安装和运行测试可能重复支付准备成本。
+- 固定单 worker 无法表达独立工作包；直接开放并发又会引入文件和设备冲突。
+
+上述为改造前基线。当前已由增量 Spec、页面批次和执行账本替代，实施状态见第 3 节；旧计划需显式升级，不混用新旧完成标准。
+
+## 3. 总体流程与领域边界
+
+### 端到端执行流程
+
+图中 AI 负责需求理解、语义规划与行为复核，程序负责约束和状态校验，CLI 负责真实构建与设备执行。当前实际只有一个实现 worker；证据映射仍由主 Agent 核验后录入。
+
+```mermaid
+flowchart TD
+  A["Facts / UTG / 源码 / 既有清单"] --> C["d2h-feature-planning：统一功能及稳定范围项"]
+  B["用户输入、范围修改和优先级调整"] --> C
+  C --> D["features.json：版本、scope_items、阶段与优先级"]
+  D --> E["d2h-spec-plan：核心路径与最小依赖闭包"]
+  E --> SZ["按独立交付、解锁、风险和延期审视粒度；计入理解与交接成本"]
+  SZ --> F["里程碑 → 页面轮次 → 页面批次 → 增量 Spec"]
+  F --> G["校验 scope_refs/checks、依赖、评分、预算与测试层级/时机"]
+  G --> WP{"当前轮次工作包与共享状态契约就绪？"}
+  WP -- 否 --> WG["定向补行为、不变量、已知坑和阻塞问题"]
+  WG --> G
+  WP -- 是 --> H{"当前是否有验证债务达到上限？"}
+  H -- 是 --> T["先验证待测项或修复失败，停止新增实现"]
+  H -- 否 --> CT["context：裁剪当前窗口成员、能力、版本与页面定位"]
+  CT --> I["核对实时门禁；start_batch 固定成员与基线"]
+  I --> CX["交接共享摘要、本轮差异和必要源码；缺失或变化时定向补读"]
+  CX --> J["同一 worker 连续实施窗口成员，逐项保留验收"]
+  J --> K["主 Agent 确认真实代码接口；受管构建与即时契约测试"]
+  K --> L{"即时门禁通过？"}
+  L -- 否 --> R["记录失败或阻塞；修复后重新验证"]
+  R --> K
+  L -- 是 --> M["其余检查按计划批次测试；共享同一候选的准备成本"]
+  T --> M
+  M --> N["主 Agent 核对原始结果、实际断言与当前 HAP"]
+  N --> O["追加 execution.json 事件；派生 batch_report.json"]
+  O --> CO["记录理解、重复分析和协调成本；分摊共享投入一次"]
+  CO --> P{"本轮 Spec 与真实路径目标通过？"}
+  P -- 否 --> H
+  P -- 是 --> Q["round_accept；里程碑结束时执行阶段完整回归"]
+  Q --> U{"还有约定范围未完成？"}
+  U -- 是 --> V["选择后续轮次；未分配或延期范围先回上游排期"]
+  V --> CH{"是否需要修改需求、排期或计划语义？"}
+  CH -- 是 --> C
+  CH -- 否，已有计划继续执行 --> H
+  U -- 否 --> W["全应用当前 HAP 回归、迁移报告核对与最终验收"]
+```
+
+每次候选代码变化仍按当前保守策略使旧证据失效；图中的测试复用仅限证据确实有效的同一候选。外部阻塞保留在账本，依赖未满足时不能推进消费者。
+
+
+### 模块拆分与当前适配状态
+
+上游独立模块命名为“功能规划”（d2h-feature-planning），由 `skills/d2h-feature-planning/` 承担，统一使用功能规划技能名称，保留源码盘点模式并支持功能规划模式。它综合 Facts、UTG、既有 inventory 和用户输入，维护范围、阶段、用户优先级与显式顺序，输出 `.migration/feature-planning/features.json`（`d2h-feature-plan/v2`）。此输出是需求与用户意图，不是 AppGraph 事实，也不是执行账本。
+
+当前模块命名为“Spec 规划与调度”（spec-planning-and-scheduling）。它消费上游文件路径与 revision，保留 feature_refs，负责下文的增量拆分、能力依赖、系统评分、worker、测试调度及执行反馈。不得静默修改上游用户优先级；冲突通过带证据的建议返回功能规划模块。
+
+这是模块整体名称，不新增一个包揽规划、调度和实现的大 Skill。能力沿现有链路演进：d2h-feature-planning 保持独立；d2h-spec-plan 融合新的 Spec 规划规则；主 Agent d2h 负责运行时调度；d2h-spec-develop 演进为增量执行与验证能力。具体职责与迁移见第 3.4 节。
+
+上游已更名为 d2h-feature-planning 并保留原 inventory 导出；下游已实现 d2h-spec-plan、d2h-spec-develop、主 Agent 调度规则及随附契约程序。程序支持 v2 计划校验、优先级继承、能力门禁、验证背压、事件账本、版本修订和报告生成。代码已完成行为回归测试，不表示某个真实应用已经迁移或通过设备验收；多 worker 并发仍未开放。下文“本次”专指当前模块实施范围。
+
+### 3.1 范围与角色标记
+
+本次建议范围为“消费版本化功能清单 → 增量 Spec → 依赖与评分 → worker 分配建议 → 测试调度与复盘”的评估闭环，覆盖第 13 节阶段一、阶段二及阶段三的评估记录部分。功能发现、清单归并、用户手动修改与排序、里程碑及用户优先级维护，均由独立上游 d2h-feature-planning 模块承担，不在当前模块重复建设。实际多 worker 并发执行、隔离和资源锁作为后续实施项。本次不包含具体应用的迁移实现，也不重建已有事实提取和构建测试工具。以下“本次”表示当前模块范围；具体实现与已知限制以本节状态及 runtime-contract.md 为准。
+
+- **本次新增/调整**：本轮需要建设或修改的机制。
+- **上游模块**：d2h-feature-planning 的独立职责；当前模块只消费其交接产物，或返回有证据的调整建议。
+- **已有复用**：继续调用已有能力，仅接入新流程。
+- **后续增强**：预留契约，本轮不开放实际并发。
+- **AI**：理解需求、阅读证据、提出拆分与评估、解释结果。
+- **程序**：结构校验、公式计算、约束检查、状态持久化及工具执行。
+- **用户**：输入目标与范围、调整优先级，处理确实无法推断的业务取舍；不要求每个环节反复确认。
+
+```mermaid
+flowchart TD
+  subgraph UP[上游独立模块：d2h-feature-planning]
+    A[已有输入｜Facts 与前阶段材料｜程序] --> C[功能发现与清单归并｜AI + 程序]
+    B[用户新增 修改 排序｜用户 + AI] --> C
+    C --> D[里程碑 范围 用户优先级与版本｜用户 + AI + 程序]
+    D --> O[交接产物｜features.json + revision]
+  end
+  subgraph CURRENT[当前模块：Spec 规划与调度]
+  O --> P[本次｜接收与校验版本化清单｜程序 + AI]
+  P --> E[本次｜行为增量、粒度审视与能力依赖｜AI + 程序]
+  E --> W[本次｜目标轮次与同页批次归拢｜AI + 程序]
+  W --> F[本次｜风险评估与测试计划｜AI + 程序]
+  F --> G[本次｜收益 成本评分｜AI + 程序]
+  G --> H[本次｜worker 建议与验证调度｜AI + 程序]
+  H --> CT[本次｜裁剪快照、共享摘要与差异交接｜AI + 程序]
+  CT --> I[已有执行能力接入｜连续实现与即时检查｜AI + 程序]
+  I --> J[本次调整合批策略｜集成验证｜AI + 程序]
+  J --> K[本次｜验收记录与复盘｜AI + 程序]
+  K --> CC[本次｜分析与协调成本反馈｜AI + 程序]
+  CC --> G
+  I --> L[本次｜验证队列与背压｜程序]
+  L --> H
+  H -. 后续增强 .-> N[多 worker 并发执行与隔离｜AI + 程序]
+  end
+  E -. 依赖或范围冲突建议 .-> D
+```
+
+### 3.2 各环节本次工作与 AI 职责
+
+| 环节 | 本次需要做什么 | AI 负责什么 | 程序负责什么 |
+|---|---|---|---|
+| 源码 Facts 与前阶段材料 | 上游负责发现与归并；当前模块复用证据核验依赖和 Spec | 按引用读取源码、事实及诊断，不重复维护功能清单 | 加载引用产物和版本，不改提取引擎 |
+| 用户输入与调整 | **上游 d2h-feature-planning**；当前模块不重复提供编辑入口 | 上游解析功能、优先级、阶段与范围变更 | 上游保存原始输入、稳定 ID 和修订历史 |
+| 统一功能清单 | **上游 d2h-feature-planning**；当前模块消费其结果 | 上游判断同义项与重叠范围 | 上游校验清单结构与显式顺序 |
+| 里程碑与范围 | **上游 d2h-feature-planning**；当前模块不得静默改写 | 当前模块发现目标不可达时反馈最小调整建议 | 上游保存基线与变更；当前模块固定消费版本 |
+| 清单交接与更新接入 | **本次新增**：接收路径、schema、revision 及 feature_refs，检查未决项 | 理解约定结果与范围，识别影响规划的歧义 | 校验契约和引用，保存消费版本，计算更新影响范围 |
+| 增量 Spec 与依赖 | 调整当前整页 Spec 规则 | 阅读证据、拆分可验收增量、识别 requires/provides | 校验覆盖关系、引用、依赖环和契约字段 |
+| 轮次与页面归拢 | **本次已实现**：目标轮次、同页批次、实际派发窗口及页面完善状态 | 选择基础可用路径，判断状态/代码/测试复用，说明归拢理由与预算 | 校验成员唯一归属、轮次顺序、批次依赖环与预算；限制优先级及独占窗口 |
+| 粒度与上下文复用 | **本次已实现**：拆分准则、裁剪快照及成本字段 | 判断拆分收益；维护摘要、差异与源码定位 | context 输出窗口快照；校验成本子集，不能代替语义复核 |
+| 开工与接口交接 | **本次已实现**：工作包就绪、共享状态和当前实际接口 | 核对行为、参数/数据流、真实代码符号及状态生命周期 | 阻止缺口成员派发；检查契约参与者、接口文件哈希与候选，不解析符号语义 |
+| 风险与测试计划 | 新增风险分级、即时门禁、合批项及截止点 | 识别风险、设计断言、估算验证成本 | 执行强制升级规则，校验门禁及截止配置 |
+| 收益与成本评分 | 替换现有页面评分，保留旧版本含义 | 提出维度分、成本区间、置信度及证据理由 | 计算公式、应用用户约束和稳定排序；不自行编造评分依据 |
+| worker 分配 | 新增人数和工作包建议，本次仍单实现 worker 执行 | 评估并行性、耦合和契约，建议分工并解释 | 校验包边界、依赖和可用容量；执行配置的人数上限 |
+| 实现与即时检查 | 复用现有 worker 和工具，改为领取增量范围及门禁 | worker 实现、生成或调整测试，主 Agent 复核 | 受管构建测试、记录退出状态和证据身份 |
+| 集成验证 | 调整为按路径、风险和容量合批 | 选择相关场景、审查断言覆盖、诊断失败 | 调用现有工具，绑定版本/HAP/设备/断言，标记证据失效 |
+| 验证队列与背压 | 新增队列、容量、年龄及截止检查 | 解释阻塞和建议资源调整 | 达阈值阻止新增实现；不允许 AI 用解释绕过门禁 |
+| 验收与复盘 | 新增指标、归因及下一轮校准建议 | 审查行为结果、分析分工及测试时机是否合理 | 汇总实际指标，检查验收证据完整性，保存结论和配置版本 |
+| 多 worker 并发执行 | 后续增强，本次仅保留分配建议和数据契约 | 后续按契约派发及集成 | 后续实现安全隔离、资源互斥和并发容量控制 |
+
+AI 的判断必须记录依据和不确定性；程序通过不等于业务语义已经正确。验收需要同时满足可执行证据与主 Agent 的行为复核，AI 的总结不能替代实际测试结果。
+
+### 3.3 仓库与产物边界
+
+| 领域 | 本次范围 | AI 使用方式 | 边界 |
+|---|---|---|---|
+| AppGraph | **已有复用**；默认不修改 | AI 消费 Facts、诊断和源码证据 | 继续输出确定性事实，不写入用户偏好或主观评分 |
+| d2h / d2h-feature-planning | **独立上游，已有技能适配**：功能发现、用户修改、清单归并及 features.json | AI 理解需求与归并功能 | 上游维护用户意图；当前模块只消费产物及反馈建议 |
+| d2h / Spec 规划与调度 | **本次主要修改范围**：清单接入、Spec 生成和开发规则、主 Agent 编排、计划/账本 schema、校验及报告 | AI 负责 Spec 拆分、依赖判断、估分、分工建议和复核 | 不恢复旧 SPEC/PLAN/TASK 多 Agent 文档链；程序校验服务于 AI 决策，不用静态推断替代源码理解 |
+| droid2hmos | **已有工具优先复用**；仅在现有证据无法表达批次到 Spec/断言映射时做最小扩展 | AI 调用受管工具、解释结果和诊断失败 | 不重建构建测试引擎，不新增与 Kernel Task Plan 冲突的任务真源 |
+| 上游功能清单 | **上游维护，当前模块接入**：features.json | 上游 AI 维护需求决策；当前 AI 理解与引用 | 固定消费 schema/revision，不维护可编辑副本 |
+| 当前计划与执行账本 | **本次新增/演进**：pages.json v2、execution.json | AI 提交结构化规划和复核意见 | 程序校验后持久化，保留来源版本、派发版本及事件历史 |
+| 报告 | **本次调整**：展示实现/验收进度、验证债务及计划与实际差异 | AI 补充原因和复盘说明 | 状态及指标来自账本与真实证据，不能将计划或推测渲染为通过 |
+
+当前模块实施结束时应具备：可追溯的上游清单接入与变更反馈、增量 Spec 和评分结果、worker 分配建议、可执行的测试时机及背压规则、可追溯的验收与复盘账本。功能清单编辑能力由上游提供；实际多 worker 提速不属于本次验收承诺。
+
+### 3.4 与现有 Skill 的关系及演进方式
+
+采用“复用并演进现有规划能力、保留独立功能规划、分离运行时调度与执行”的结构。不另建一个与既有页面 Spec 生成能力并列、同时维护依赖、评分和 Spec 的技能，避免两套计划真源。
+
+| 能力 | 现有归属 | 目标归属 | 负责内容与输出 |
+|---|---|---|---|
+| 功能规划 | d2h-feature-planning | 保持独立 | 功能范围、里程碑、用户优先级与顺序；输出 features.json 及 revision |
+| Spec 规划 | 原 d2h-spec-generate | 已演进为 d2h-spec-plan | 增量边界、能力依赖与最小前置闭包、评分依据、worker 工作包建议和测试计划；输出 Spec 与版本化计划 |
+| 运行时调度 | 主 Agent d2h | 仍由主 Agent d2h 承担 | 根据计划及执行账本形成就绪集合、计算派生优先级、选择及派发任务、落实资源与验证背压、触发必要重规划 |
+| 实现与验证 | 原 d2h-spec-develop | 已演进为 d2h-spec-develop | 接受固定页面批次成员和版本，在同一 worker 窗口内逐 Spec 实现、受管检查及返回证据，不自行追加成员 |
+| 构建与测试工具 | droid2hmos、d2h-hypium-forge | 复用现有能力并按需扩展映射 | 执行构建测试，保存实际结果和版本身份，不决定用户优先级 |
+
+技能目录、frontmatter、主 Agent 路由和测试引用已同步重命名。没有并行保留旧技能入口；安装器按 skills 目录发现新入口。新技能不再以整页作为执行单位，但保留页面归属索引；旧 v1 计划需显式迁移，不自动继承通过状态。
+
+```text
+d2h-feature-planning
+    ↓ features.json + revision
+d2h-spec-plan（由原页面 Spec 生成技能演进）
+    ↓ 目标轮次 + 页面批次 + 增量 Spec + 依赖与测试计划
+主 Agent d2h
+    ↓ 固定轮次、页面批次成员与版本的独占派发
+d2h-spec-develop（由原逐页开发技能演进）
+    ↓ 实际结果 + 能力验证证据 + 阻塞
+主 Agent更新执行账本与调度；必要时调用 d2h-spec-plan 修订受影响计划
+```
+
+主 Agent 的调度依据是 AI 阅读过证据的版本化计划，程序负责明确公式、依赖与门禁校验、派生状态计算及持久化，不使用静态推断代替 AI 进行语义拆分和任务决策。规划技能提出 worker 数量及测试时机建议，主 Agent 根据实时资源和门禁决定何时派发；执行技能遵守派发契约，不扩大范围。
+
+区分两类变化，避免每次状态更新都重新生成文档：
+
+- **执行状态变化**：能力通过或失败、证据失效、设备恢复、验证队列变化，由主 Agent 按既定规则更新账本、继承优先级及就绪集合。计划语义未变化时，不重新生成全部 Spec。
+- **规划语义变化**：发现新依赖、原拆分不可行、用户修改范围或阶段，主 Agent 调用 d2h-spec-plan 修订受影响部分；涉及用户意图变化先经 d2h-feature-planning 更新上游版本。保留计划修订、派发基线及执行历史。
+
+旧版“开发期间计划不可重生成、必须整页闭环、账本原位编辑”规则已由版本化 reconcile、能力即时门禁和 execution.json 真源替换。批次报告允许重新生成；计划修订必须保存旧基线并明确处置在途任务。
+
+### 3.5 技能的渐进式加载
+
+技能采用“发现描述 → 简短入口 → 按模式/角色读取参考”的三层结构。入口保留职责、产物和不可丢失的约束，操作步骤、JSON 样例和角色细节按实际任务加载；不按行数机械拆文件，也不把全部 references 作为默认上下文。
+
+| 技能 | 入口保留 | 按需读取 |
+|---|---|---|
+| d2h-feature-planning | 盘点/规划/导出的模式判断、事实与用户意图分离、下游边界 | 源码发现读 inventory-extraction.md，调整范围或优先级读 feature-planning.md，导出已有盘点读 inventory-export.md；框架、层级与 schema 再由盘点流程按需定位 |
+| d2h-spec-plan | 规划职责、版本和真源、全量追踪与基础可用原则 | 起草或语义修订读 planning-method.md，写 JSON 或校验读 plan-contract.md，派发/事件/证据/版本修订读 runtime-contract.md 的对应章节 |
+| d2h-spec-develop | 固定窗口、单 worker、能力门禁与真实证据、分层完成状态 | 主 Agent 协调读 parent-workflow.md，worker 实施读 worker-workflow.md；worker 不因写代码预先加载主 Agent 的所有事件与验收程序 |
+
+已有可信功能清单时直接规划，不为加载模式重跑源码扫描；仅更新状态不重新规划；仅重新导出不重新盘点。每个步骤/数据格式只有一个维护位置，以链接交接而非在入口和参考各保留一份。运行随附校验脚本不要求预读其全部实现，只有诊断或修改脚本时再读源码。本次整理仅调整指导文档的加载方式，不改变执行程序、门禁、产物字段或自动发现策略。
+
+## 4. 统一功能清单与用户调整
+
+本节描述上游 d2h-feature-planning 的职责及交接约束，作为当前模块的输入契约背景，不属于当前模块新增的功能清单维护逻辑。涉及用户范围和优先级的修改应回到上游，当前模块只保存消费版本及调整建议。
+
+### 4.1 输入及归并
+
+输入支持自动提取功能、前阶段已有清单、用户自然语言或结构化清单。为每个功能分配稳定 `feature_id`，记录 `source=extracted|user|merged`、原始描述和证据引用。
+
+优先按稳定引用归并，名称相似仅产生候选，不自动覆盖。用户新增且源码不存在的功能以用户需求与验收条件为依据，标记为新增范围，不伪造源码证据。描述不清且影响实现时列为待澄清，其余独立功能可继续规划。
+
+用户可以新增、修改、拖动顺序、指定阶段必做、延后或排除功能。延后仍在总范围内；排除从约定范围移出，保留原因与历史。删除显示项不能静默消灭原始需求。
+
+### 4.2 用户意图与调度优先关系
+
+按以下次序处理：
+
+1. 检查硬依赖和必要约束，拒绝环形依赖。
+2. 应用用户指定的里程碑、优先级和明确先后关系。
+3. 对必要前置切片计算继承后的有效调度优先级，再按第 6.3 节选择就绪任务；不回写用户优先级。
+4. 根据 worker、文件和设备资源选择可派发任务。
+
+`must` 表示当前阶段必须交付，不等于所有 must 功能同时开工。用户拖动的顺序默认作用于同一阶段；若跨依赖，展示阻塞能力及最小前置切片，不静默拉入整个前置页面。必要调整依据既有授权执行；无法满足用户要求或涉及范围取舍时再澄清。
+
+### 4.3 变更管理
+
+功能清单和计划分别保留 revision。未派发任务重新计算受影响部分；执行中的任务固定派发版本，记录继续、缩减、暂停或取消决定。已完成结果保留，新增范围建立后续 Spec，不回写历史为未曾发生。
+
+范围变化时同时展示原基线与新基线，防止通过排除未完成项抬高完成率。相同证据、用户输入、配置与版本应产生稳定排序；分数相同按稳定 spec_id 排序。
+
+## 5. 增量 Spec 模型
+
+页面作为归属、结构设计和连续开发单位；Spec 是最小需求追踪与验收单位；页面开发批次是 worker 的派发单位。通过页面轮次先达到基础可用，再按优先级集中增强，最后覆盖全部约定功能。功能与 Spec 可以多对多：一个登录功能拆成多个增量；跨页增量指定唯一归属页面，显式列出共享改动，不能重复派发。
+
+每个 Spec 必须包含：
+
+- 目标里程碑、所属页面、feature_refs、req_refs，以及用户可观察结果。
+- 本次 required、明确 deferred 及后续归属、排除范围。
+- 依赖能力 `requires`、交付能力 `provides` 及其契约和验证条件。
+- 实现边界、预计修改路径、共享接口与唯一集成负责人。
+- 验收项、即时阻塞检查、可批次检查、最晚验证点。
+- 评分依据、成本区间和置信度、worker 建议及理由。
+
+例如依赖 `session.basic`，而不是依赖“登录页全部完成”。能力只有对应契约通过实际验证才可标记 ready，下游不能把“代码已写”当作前置满足。
+
+拆分检查：有独立可观察结果；具有可描述的输入输出；延后部分不破坏当前结果；测试成本与交付收益相称。不能为提高分数将一个行为拆成大量无独立价值的微任务。复杂但不可并行的任务先收敛契约，而不是机械增加 worker。
+
+原型数据和模拟鉴权可用于明确约定的原型里程碑，必须标注 prototype，不计入真实功能验收。正式最小登录必须具备真实鉴权、必要状态及基本失败反馈，不能以固定成功值替代。
+
+### 5.1 里程碑、轮次、页面批次与 Spec 的关系
+
+| 层级 | 回答的问题 | 关系与约束 | 完成依据 |
+|---|---|---|---|
+| 里程碑 milestone | 本阶段最终交付什么 | 来自上游用户范围；包含一轮或多轮 | 当前候选全部约定 Spec、轮次目标和阶段完整回归通过 |
+| 页面轮次 round | 这一波先实现什么可用结果 | 每轮属于一个里程碑，有 order、kind、goal 和 goal_checks；只覆盖需要的页面 | 各成员 Spec 分别验收，真实用户目标路径通过 round_accept |
+| 页面 page | 哪个持续演进的界面承担功能 | 页面 ID、结构与目录稳定，可在多轮中反复完善 | 已核对全量约定范围，且该页全部 Spec 在当前候选通过 |
+| 页面开发批次 page_batch | 这次集中开发该页哪些增量 | 一个批次仅属于一个页面和一轮，包含一个或多个 Spec；每个 Spec 只归属一个批次 | 成员逐项验收，不能用批次汇总抹掉单项失败 |
+| 实际派发窗口 | 当前一个 worker 一次承担哪些成员 | 固定批次、成员、worker、版本与基线；按优先级可能仅领取批次的一个子集 | 本次领取成员实现且即时门禁通过，可 finish_batch；其余批次测试仍可 pending |
+| Spec | 哪项行为如何验收、依赖什么 | 保留 feature_refs、能力契约、独立状态与证据；归拢不合并稳定 ID | 当前构建、全部检查、依赖与主 Agent 行为复核通过 |
+
+```text
+里程碑：约定范围迁移交付
+├─ R1 基础可用：启动 → 基本登录 → 首页可用
+│  ├─ 登录页基础批次：输入校验 Spec + 登录/会话 Spec + 首页跳转 Spec
+│  └─ 首页基础批次：导航结构 Spec + 核心内容 Spec + 必要状态 Spec
+├─ R2 增量增强：优先完成核心业务操作
+│  ├─ 首页增强批次：搜索 Spec + 同状态下的筛选 Spec
+│  └─ 详情页基础批次：详情展示 Spec + 核心操作 Spec
+└─ R3 完善交付：补齐剩余约定范围
+   ├─ 登录页补全批次：其他登录方式 Spec + 找回密码 Spec
+   └─ 各页剩余批次：剩余交互、异常分支与视觉验收 Spec
+```
+
+轮次不限三轮；中间可有多轮 incremental。每个里程碑从一个 baseline 轮开始，completion 若存在必须在该里程碑最后；完成轮名称本身不证明页面已经完整。每轮不必遍历所有页面，新页面也可在后续轮首次出现。全局 round.order 与页面局部 page_pass 区分：详情页可能在全局第二轮才迎来自己的第一次开发。
+
+### 5.2 轮次、目标和 Spec 对照示例
+
+以下为同一“约定范围迁移交付”里程碑中的示例，不自动改变真实用户的范围或顺序。
+
+| 页面轮次 | 目标 | 涉及页面及批次 | 归拢的 Spec 示例 | 本轮暂不做 | 验收边界 |
+|---|---|---|---|---|---|
+| R1 baseline | 从真实入口登录并使用首页 | 启动基础、登录基础、首页基础 | 必要初始化；输入及校验、真实登录、必要会话、跳转；导航、核心内容、加载/空/失败反馈 | 启动动画精修、其他登录方式、复杂筛选 | 真实“启动→登录→首页”路径；每项即时能力检查保留 |
+| R2 incremental，可重复 | 按用户优先级增加核心业务价值 | 首页增强、详情基础等 | 同页且共享数据状态的搜索、筛选；详情展示与核心操作 | 未影响当前目标的低优扩展 | 当前业务路径通过；原有基础路径按影响回归 |
+| R3 completion | 全部约定页面与行为完整交付 | 登录补全、首页补全、其他页剩余批次 | 其他认证方式、找回密码、剩余业务与异常路径 | 仅用户明确排除项 | 全量范围核对、逐 Spec 验收、最终候选完整回归 |
+
+基础页面不是仅有壳或模拟成功的原型；后续轮次在原页面和状态模型上累积实现，不重新覆盖生成页面。后续 Spec 仍在全量清单与计划中可追踪，基础轮完成不能将这些项计为已完成。
+
+### 5.3 页面归拢评估与优先级保护
+
+AI 读取实现和依赖后决定归拢，记录 goal、rationale 与批次预算，程序校验明确边界：
+
+- 同一轮、同一主页面，并复用组件、状态模型、修改文件或测试准备时优先归拢；仅名称或页面相同不足以合并无关业务。
+- 每个 Spec 只归属一个批次，不跨页面或轮次混装。内部依赖保持拓扑顺序，能力契约未通过前，后续成员仍不可启动。
+- 对批次压缩后的依赖图也检查环。例如页面 A 的 A1 → 页面 B 的 B1 → 页面 A 的 A2，不能把 A1/A2 打成不可交接的一次批次，应拆成多次页面访问。
+- max_specs 与 max_effort_hours 限制批次范围；超预算就拆分，不能以“同页顺便”扩展到整页全部功能。opportunistic_hours 限制低优顺带项，默认 0。
+- 调度先满足当前轮次目标和依赖，再按有效优先级、关键路径与共享解锁比较；这些相同时，优先连续开发同页，再比较收益成本和稳定批次 ID。
+- 同页低优成员仅在预算允许、且没有其他就绪页面的更高优任务会被延误时随批次领取；否则本次派发只领取核心成员，低优成员仍保留在原批次。窗口成员固定，执行中不能擅自追加。
+- 新窗口只能选择就绪集合的最高有效优先级层。领取顺带项后若更高优的外部任务恢复，在开始该顺带项前应暂停窗口让出资源；不静默抢占已经在途的成员。
+- 中途外部阻塞时，先停止在途成员，再 pause_batch 保存已实现与已验证结果；恢复后只领取剩余就绪成员。共享文件、设备独占和验证背压仍生效。
+
+### 5.4 轮次推进与当前候选证据
+
+只有本轮全部 Spec 逐项 accepted，且 goal_checks 对应的真实路径实际通过并由主 Agent round_accept 后，才解锁下一轮。批次实现完毕或页面可见不能替代轮次目标验收。
+
+若当前里程碑需要一个更早里程碑中的轮次，则将该轮完整成员及其同里程碑更早轮次纳入就绪计算，再递归补齐依赖，避免只纳入半个目标而无法验收。它们仍须是用户已授权范围内的显式计划成员，不动态扩展需求。
+
+区分“历史上已交付该轮目标”与“当前候选仍通过”：后续轮次改变代码时，历史交付不被抹去，也不因保守全量证据失效而自动把开发进度退回第一轮；但当前能力、Spec、页面完整度与里程碑通过仍必须有当前证据。历史轮次证据的 HAP 和报告应以不可变版本归档，文件缺失或被覆盖时不再视为可证明的历史交付。
+
+发现真实失败或显式 invalidate 时，撤销受影响轮次及依赖消费者轮次的可用交付证明，并要求修复。计划语义变化也使不匹配的目标签名失效；仅优先级或分数变化保留仍适用的历史证明。修改在途批次前必须显式暂停，不能静默变更成员。
+
+最终里程碑要求所有相关轮次在当前候选重新得到目标路径证据；同一最终回归可映射为多轮 goal_checks 与各 Spec 的真实断言，复用实际执行，不伪造多次运行。
+
+### 5.5 Spec 粒度与上下文复用成本
+
+需求可独立验收不等于必须单独派发。基础登录的一次完整用户行为可以包含输入校验、提交状态和失败反馈，由一个 Spec 的多个范围项与 checks 覆盖；只有独立交付、下游解锁、风险/验证时机差异或跨轮延期才拆开。已有独立 Spec 按同页窗口连续实施，不反复从整页文档重新提取任务，也不为减少数量改写已验收范围。
+
+规划估算计入理解上下文与交接成本；远期延期范围先保留稳定条目和去向，到对应阶段再细化实现和测试。页面 spec.md 的共享摘要集中维护结构、状态、能力及源码版本，增量只补差异；摘要不成为另一份状态真源或通过证据。
+
+派发使用 `spec_runtime.py context --batch-id` 的只读裁剪快照，携带本窗口成员、页面定位、所需能力、版本/哈希、candidate 和事件序号。AI 补充共享摘要、明确基线的变更差异及必要源码定位。同一窗口同一 worker 连续实施；跨窗口不依赖隐含记忆，版本或契约变化后定向核验。该命令不认领窗口，不绕过优先级、依赖或验证背压。
+
+复盘记录 context_hours 和 repeated_analysis_hours，作为 implementation_hours 的嵌套子集，避免重复计费；结合协调占比与每窗口成员数判断粒度是否合适。未知投入保留 null，不设置无依据的固定阈值，不声称已实现自动 token 节省或跨候选测试复用。
+
+## 6. Spec 优先级评估
+
+### 6.1 价值维度
+
+各项取整数 0～5，记录证据及评分理由；1、2、4 按相邻锚点判断。
+
+| 维度 | 权重 | 0 分 | 3 分 | 5 分 |
+|---|---:|---|---|---|
+| 里程碑贡献 M | 30% | 当前阶段无贡献 | 支持一项阶段验收 | 直接完成核心路径关键结果 |
+| 后续解锁 U | 25% | 无近期消费者 | 解锁一个重要消费者 | 解锁多个近期关键 Spec |
+| 用户核心价值 V | 20% | 非必要装饰 | 常用辅助行为 | 核心业务动作 |
+| 风险消减 R | 15% | 无关键未知 | 解决局部实现未知 | 验证可能导致广泛返工的关键假设 |
+| 反馈价值 F | 10% | 无新增可观察反馈 | 可独立观察部分结果 | 可获得核心路径真实运行反馈 |
+
+`value_score = 6M + 5U + 4V + 3R + 2F`，满分 100。
+
+只计算相对当前实现的增量收益。已有基本登录后，其他登录方式不得沿用基本会话能力的解锁分。风险消减是开展工作的收益，测试风险是验证强度，两者分别记录。
+
+### 6.2 成本与排序
+
+`E = 实现投入 + 测试准备及执行投入 + 集成投入 + 预期返工投入`。
+
+`priority_index = value_score / E`。
+
+E 使用 worker 小时，不能与日历耗时混用。估算记录低、中、高区间及置信度；无历史样本时使用粗粒度成本档和统一换算表，避免伪精确。共享测试准备成本以批次记录并分摊一次，不能重复计算或从所有 Spec 中遗漏。
+
+优先指数用于辅助同优先级候选比较，不覆盖硬依赖和用户顺序。低置信度且影响关键路径的项可先创建有明确结论及时间预算的调研增量。调度时检查当前最高优先级任务是否被长期饿死，记录资源冲突及等待原因。
+
+### 6.3 高优目标的多层阻塞与调度
+
+原则：用户优先级决定目标，依赖关系决定路径，最小前置能力决定实现范围。高优功能不能执行时，应推进它所需的就绪前置能力，不能把不可执行目标一直放在队首，也不能直接转去实现无关的低优功能。
+
+#### 依赖展开与分类
+
+AI 基于 Facts、源码、当前实现及测试证据，从目标 Spec 的 requires 递归展开到能力提供者，形成依赖闭包。程序校验引用、提供者选择、环及状态。依赖边必须记录所需能力、契约及证据，不能仅因页面导航先后就认定需要完整前页功能。
+
+| 类型 | 示例 | 处理 |
+|---|---|---|
+| 必须新增的能力 | 订单读取需要有效会话 | 纳入目标依赖闭包 |
+| 已有且证据有效的能力 | 已验证的会话管理 | 复用，不重复建实现任务 |
+| 可以缩小的前置范围 | 登录有多种方式，目标只需一种 | 提前最小真实登录切片，其他增量留在原阶段 |
+| 非必要前置 | 启动动画、登录视觉精修 | 不纳入闭包，不继承优先级 |
+| 外部阻塞 | 账号、接口、设备不可用 | 记录外部条件、负责人及恢复信号，不伪装成实现任务 |
+| 依赖尚不确定 | 动态接口或平台行为缺少依据 | 先开展有预算的定向调查，不能凭猜测宣布已就绪 |
+
+同一能力有多个可行提供者时，选择满足契约且新增范围与成本合理的方案，记录选择依据；不要把互为替代的方案全部加入必须完成的闭包。依赖闭包超出当前约定范围、需要已排除功能、跨入用户明确延后阶段，或与用户显式顺序冲突时，反馈最小调整建议。未解决前保持阻塞，不自动扩展授权范围。
+
+#### 优先级继承
+
+保留两个字段：user_priority 是上游用户意图；effective_priority 是下游计算的临时调度优先级，取自身优先级与所有有效消费者沿必要依赖传递的最高优先级（must > normal > later）。记录 inherited_from 对应的目标及依赖路径。
+
+继承仅用于当前阶段已授权的必要能力切片，不提升同页全部功能，不改变原始价值分或用户优先级。多个目标共享前置能力时保留全部继承来源，成本只计算一次。某目标取消或延后后，只移除该目标的提升来源；其他目标仍需要时继续保留提升。
+
+#### 就绪任务选择
+
+每次调度按以下步骤形成结果，并记录选择理由：
+
+1. 检查当前授权范围、显式顺序、能力门禁及验证背压；排除外部阻塞和不可派发项。
+2. 优先从最高有效优先级目标的依赖闭包中选择就绪任务。若无就绪项，展示具体阻塞，继续独立工作前确认不会扩大受阻目标的返工或验证债务。
+3. 在 page-batches 模式，先限制到当前未交付目标的轮次，再对就绪页面批次比较有效优先级、关键路径、共享解锁；同等级优先连续开发同页，之后比较 priority_index 和稳定 batch_id。Spec 仍独立评分，批次价值/成本按本次领取成员汇总，不提高用户优先级。
+4. 当前按单实现 worker 串行派发固定页面批次窗口，内部成员依赖通过后再启动。未来并发仍需满足资源、文件与契约边界；不能因批次包含多个 Spec 就误认为多个 worker 并行。
+
+关键路径按依赖 DAG 上的剩余日历耗时估算，包含串行验证和可预计的资源等待，与第 6.2 节 worker 投入成本分别记录。缺少可靠耗时的边标记 unknown，展示估算区间与置信度，不声称精确的最早完成时间。外部恢复时间未知时不得给出确定交付时间。
+
+能力提供者完成代码后，只有 required 契约实际验证通过且证据有效，才能解除对应阻塞。未被消费者依赖的补充场景可以依照测试策略进入有截止点的验证队列；这不等于整个提供者 Spec 已验收。
+
+#### 阻塞展示与动态重算
+
+报告为每个高优目标展示：用户和有效优先级、完整阻塞路径、各边所需能力及状态、下一可执行任务、关键路径及未知项、剩余投入区间、外部恢复条件、相关证据和最后重算事件。
+
+重算触发包括用户调整、目标取消或延后、依赖发现或修正、能力通过/失败、证据失效、估算变化、外部资源恢复及验证背压变化。程序按当前计划版本重算受影响闭包、继承来源和就绪集合；AI 在依赖语义或拆分范围变化时重新审阅依据。没有新语义变化时不要求 AI 重做整份计划。
+
+重算不静默中断在途 worker；保留派发版本，必要时记录继续、缩减、暂停或取消决定。任何降级原型或范围缩减均需符合用户已授权的目标，不得以模拟结果解除真实能力阻塞。
+
+## 7. worker 评估与任务分配
+
+### 7.1 评估维度
+
+| 维度 | 记录内容 | 调度含义 |
+|---|---|---|
+| 工作量 | 总投入和目标完成时间 | 判断是否需要拆分或支援 |
+| 可并行性 | 无互相等待的工作包、关键路径 | 决定有效并发上限 |
+| 修改耦合度 | 文件重叠、共享状态和路由修改 | 高耦合减少并发 |
+| 契约成熟度 | 接口、状态模型、验收是否稳定 | 不稳定先由单负责人收敛 |
+| 验证资源 | 设备、账号、构建容量 | 限制实现后的验证吞吐 |
+
+比较可行人数 n 的预计耗时：
+
+`T(n) = 串行耗时 + 可并行工作量 / 有效并发数(n) + 协调集成耗时(n)`。
+
+选择满足里程碑目标且总投入合理的最小人数。此式只是估算框架，不声称所有任务能均匀切分；应同时检查工作包 DAG 的最长路径。总人数明确区分主 Agent、实现 worker、测试 worker；实现与测试并发限制分别设置。
+
+### 7.2 派发契约
+
+执行顺序：derive 核对就绪和背压 → context 裁剪窗口 → start_batch 固定成员 → 补齐共享摘要和本轮差异 → 同一 worker 连续实施 → 逐 Spec 返回证据与成本。context 读取后若账本变化，重新核对门禁；快照不能作为派发锁或当前通过证据。
+
+
+每个工作包有单一 owner、基线提交及计划版本、允许修改路径、输入输出契约、验收项、预算、证据目录和阻塞上报条件。共享文件由单一负责人集成，其他 worker 提交约定变更请求。
+
+并发修改使用隔离工作目录或同等安全隔离；若无法隔离且路径重叠，串行执行。隔离方式须遵守现有分支及 PR 规则，不能为实现并发擅自新建集成分支。一个共享设备同一时间仅允许一个会改变设备状态的测试批次。测试锁覆盖安装、数据准备、执行与清理。
+
+主 Agent 负责最终范围与证据复核。默认一个实现 worker，不为每个 Spec 固定增加测试 worker；只有独立准备或执行工作能够减轻瓶颈时才增加。
+
+## 8. 测试介入与积压控制
+
+### 8.1 测试风险评估
+
+四个维度各取 0～3：错误影响、共享影响范围、实现不确定性、依赖放大程度。合计 0～3 为低、4～7 为中、8～12 为高，作为初始可配置档位。
+
+以下情况直接升级为高风险，不受总分抵消：数据丢失或损坏、鉴权边界、启动阻断、关键会话和共享状态契约变更。新平台能力且缺少可靠证据时，先进行定向验证。
+
+### 8.2 三个介入时机
+
+| 时机 | 触发 | 必须完成 | 阻塞范围 |
+|---|---|---|---|
+| Spec 设计时 | 进入可派发队列前 | 验收断言、定位、数据、设备和耗时预估 | 不可测的 Spec 不派发 |
+| 实现时即时验证 | 代码形成；风险或依赖要求 | 当前构建、必要逻辑检查、高风险及被依赖能力的定向验证 | 阻塞受影响消费者 |
+| 路径或里程碑批次 | 用户路径形成、队列达阈值、验证截止 | 真实入口、跨页状态、数据效果及相关失败路径 | 阻塞里程碑验收 |
+| 阶段完整回归 | 阶段交付前 | 约定范围的完整回归与证据核对 | 阻塞阶段交付 |
+
+测试设计提前，不意味着所有设备测试立即执行。可合批的是低风险局部场景，不能延后下游使用前必需的能力验证。
+
+多个相关 Spec 可共享一次候选版本构建、安装及环境准备；测试结论绑定集成提交、HAP 哈希、设备、配置和实际执行列表。代码变化后按影响关系使相关证据失效；无法证明不受影响时重新验证。旧日志不能冒充新版本通过证据。
+
+为页面定向测试准备合法会话可减少重复登录；真实启动和登录链路仍在里程碑测试中执行。断言覆盖结果而非仅检查控件存在。合批测试准备开销记录到批次，Spec 通过映射引用对应断言和证据。
+
+### 8.3 验证债务与背压
+
+验证债务同时包含待验证 Spec 数、预计验证投入、最早进入时间、截止点及消费者。高风险必测项失败或未通过时不允许相关消费者启动。
+
+建议试运行默认阈值：普通待设备验证 Spec 最多 3 个；待验证投入不超过下一测试批次容量；等待时间不超过一个约定批次周期；任何项不得越过所属里程碑截止点。任一阈值命中即停止启动新增实现，优先验证或修复。批次周期和容量在阶段开始时明确配置，无历史数据时不能假定无限容量。
+
+若验证预计吞吐持续低于实现吞吐，减少实现并发，把可用资源转向测试准备、设备诊断及修复；设备本身是瓶颈时，增加测试 agent 不会自动提高吞吐。
+
+测试失败按影响阻塞相关能力，独立且不扩大验证债务的工作可继续。环境受阻单独标记，记录诊断与重试预算，不改成通过。严重安全或数据问题扩大阻塞范围由主 Agent 明确记录。
+
+## 9. 状态机、完成度与失效规则
+
+建议分别记录三个轴，避免组合状态含义模糊：
+
+| 轴 | 状态 |
+|---|---|
+| 实现 | planned / ready / in_progress / implemented / cancelled |
+| 验证 | not_ready / pending / running / passed / failed / blocked / stale |
+| 验收 | pending / accepted / superseded |
+
+`implemented` 仅表示范围内代码完成；即时门禁通过后可进入集成验证队列。只有全部当前验收项通过、证据与候选版本一致、主 Agent 复核后，才置 `accepted`。
+
+能力 ready 单独由其契约测试决定，不要求所在 Spec 所有非依赖场景均已验收。若能力证据失效，则撤销 ready，并对消费者标记影响和重新验证需求。
+
+报告分别展示实现进度、验收进度和待验证债务。主进度以固定范围版本下已验收的用户结果为依据，不能按可随意拆分的 Spec 数计分。可以在里程碑基线固定验收项权重，范围变化展示差异和新旧分母；不采用开发过程中动态优先分作为完成率权重。
+
+## 10. 计划与账本数据契约
+
+建议在现有 `.migration/page-specs/` 内演进，不创建独立旧式任务流水线：
+
+- 上游 `.migration/feature-planning/features.json`：由独立功能规划模块维护的版本化功能清单、用户调整和里程碑范围。当前模块只记录消费路径和 revision，不在 page-specs 内维护副本。
+- `pages.json` v2：保留页面索引，新增稳定 spec_id、能力依赖、评分、测试策略和工作包。目录稳定标识与可变执行顺序分离，改优先级不重命名目录。
+- 新计划使用 v2 的显式扩展 `dispatch_mode=page-batches`，增加 rounds 和 page_batches，页面记录 scope_complete 及完整范围核对引用。旧 v2 无此模式时维持单 Spec 行为；启用页面轮次须先显式修订并 reconcile，不能偷偷归拢在途任务。
+- 页面目录 `spec.md`：保留单文件约定，以增量章节描述本页 Spec；跨页 Spec 指定唯一归属，其他页面引用。
+- 结构化执行账本 `execution.json`：任务状态、派发版本、实际投入、验证队列、批次证据和事件历史。
+- `batch_report.json`：由结构化账本生成的展示视图，不再作为第二份可独立修改的状态真源。
+
+计划结构以 [plan-contract.md](../skills/d2h-spec-plan/references/plan-contract.md) 为准，执行事件和证据以 [runtime-contract.md](../contracts/workflow/execution.md) 为准，校验入口为 `workflow/spec_runtime.py`。计划使用 `schema_version=d2h-page-plan/v2`，执行账本使用 `schema=d2h-spec-execution/v1`；计划字段和完整示例只在计划契约维护。五项评分放在 ratings，能力的检查映射为 provides[].checks，用户优先级从 feature_refs 读取，effective_priority、inherited_from 和 blocked_by 由 derive 计算，不手改计划保存第二份真源。
+
+程序支持 validate/init/derive/context/event/render/reconcile。context 为只读窗口快照，不认领任务、不保存第二份状态，不自动生成语义摘要。事件数组整体成功才写入，写入需 expected-sequence 并持有独占锁。候选代码变化默认使旧证据全量失效；原始证据文件或 HAP 哈希变化也撤销有效状态，不自动推断不受影响的代码。此保守策略可能增加回归成本，后续才扩展有可靠差异证明的证据复用。
+
+执行中的任务固定派发基线；范围修订保存旧计划、功能清单及 Spec，受影响任务重新实现/验证，未变化任务保留证据。废弃增量在 retired_specs 显式记录 ID 与原因，旧状态保留在账本历史。旧 v1 不自动换算评分或继承 PASS。
+
+所有字段引用须可解析；未决事实保留诊断。用户输入和源码文本作为数据处理，不作为编排指令执行。计划变更保留原因、来源和受影响项。程序只能检查契约与证据身份，实际命令、断言覆盖、计数及业务结果仍须主 Agent 独立复核。
+
+## 11. 事后评估与校准
+
+| 维度 | 指标 | 解释 |
+|---|---|---|
+| 交付有效性 | 里程碑耗时、真实解锁能力、验收结果 | 是否推进用户目标 |
+| 估算准确性 | 实际投入/预计投入；实际耗时/预计耗时 | 分开评估资源和工期 |
+| 分工合理性 | 等待占比、交接次数、冲突次数 | 是否具备有效并行边界 |
+| 协调成本 | 协调集成投入/总投入 | 更多 worker 是否产生过高成本 |
+| 理解与重复分析 | context_share、repeated_analysis_share、每窗口成员数 | 拆分收益是否覆盖重复阅读与交接；优先改进摘要和差异交接，再调整粒度 |
+| 实现质量 | 首次验收通过率、返工投入占比、回归缺陷 | 是否以质量换速度 |
+| 测试调度 | 排队时长、队列年龄、准备开销、缺陷发现时的消费者数量 | 测试介入过早或过晚 |
+| 范围控制 | 非计划工作、需求遗漏、延后项归属 | Spec 是否过大或模糊 |
+| 依赖调度 | 高优目标受阻时间、前置能力投入、继承提升次数及来源、非必要前置比例 | 是否真正优先推进目标，是否把前置范围扩大 |
+| 页面归拢 | 页面切换次数、每个派发窗口 Spec 数、暂停窗口数、重复测试准备开销 | 归拢是否减少切换，还是扩大批次导致等待和返工 |
+
+区分 worker 活跃投入、等待时间和日历耗时；记录开发、测试、协调、返工等分类，避免重复计时。耗时来源可以是运行事件和人工修正，但缺失值应标 unknown，不能以零填充。
+
+归因建议：冲突和等待高时减少并发或重划边界；单个共享能力成为关键路径时先收敛契约；准备开销高时优化合批；下游开始后才发现前置缺陷时提前能力门禁。没有可信单人基线，不报告并行加速比。
+
+每个里程碑复盘后提出参数调整，记录依据和配置版本，下一轮生效；不根据单次偶然结果自动大幅改权重。
+
+## 12. 示例：先形成主页面雏形
+
+| 增量 | 用户优先级 | 当前范围 | worker 初始建议 | 验证安排 |
+|---|---|---|---|---|
+| 启动入口 | must | 必要初始化和正确跳转 | 归属同页时可同批，否则串行 | 启动及跳转即时检查 |
+| 基本登录 | must | 一种真实登录、会话、基本失败反馈 | 1 个实现 worker | 鉴权及会话即时验证 |
+| 首页雏形 | must | 主导航、核心首屏、必要加载和空状态 | 默认 1 个；独立契约稳定后再评估拆分 | 局部检查，路径形成后集中验收 |
+| Splash 精修 | later | 动画、视觉细节 | 后续按需 | 合并视觉及启动回归 |
+| 登录补全 | later | 其他方式、找回密码、剩余异常场景 | 后续按需 | 对应 Spec 验证及鉴权回归 |
+
+基本会话通过后即可解锁首页，其他登录增量不阻塞。首页形成后执行真实“启动 → 登录 → 首页”路径测试，断言实际会话和页面结果。该里程碑通过仅表示首页雏形完成，不代表登录全部迁移完成或应用整体交付。
+
+### 多层阻塞示例：优先在首页查看订单
+
+```text
+首页订单展示（目标：must）
+  └─ orders.read：订单数据读取
+       └─ session.basic：有效会话
+            └─ auth.login：基本登录
+                 └─ startup.config：必要启动配置
+```
+
+仅在证据证明这些前置确实必需时建立上述边。若闭包均在当前授权范围内，就绪的必要启动配置首先继承 must 并执行，随后逐步验证基本登录、会话和订单读取，最后完成首页订单展示；启动动画、找回密码及其他登录方式不随之提前。若会话能力已经有效，则直接复用，跳过相应实现工作。
+
+若订单接口不可用，报告明确标记外部阻塞和未知恢复时间。可在既定范围内继续首页导航、加载或空状态等独立增量；真实订单结果保持未验收。建议用户拆分交付目标时，保留原始需求与待完成项，不能将页面框架展示计作订单功能完成。
+
+## 13. 分阶段落地
+
+### 阶段一：增量范围与评分
+
+规划与执行能力已分别迁移到 d2h-spec-plan、d2h-spec-develop，上游为 d2h-feature-planning。主 Agent、元数据、校验引用和测试同步调整，旧入口不继续独立维护。安装器动态发现新目录；已安装旧副本的环境应重新安装并核对实际入口，避免继续调用旧规则。
+
+接入独立 d2h-feature-planning 输出及修订版本，消费其用户优先级、顺序和里程碑约束；不重复建设功能清单编辑与归并。调整 Spec 生成规则，支持能力级依赖、增量章节及新评分。保持一个实现 worker，先验证拆分是否能减少首个里程碑耗时。新增交接与计划 schema 校验及稳定性测试。
+
+同时实现最小前置闭包、优先级继承、就绪集合选择和阻塞链展示；先按现有严格验证门禁串行推进。能力通过、失效或用户变更时重算；阶段二再允许已验证能力与非依赖场景的待批次验证分离，避免只实现评分而继续阻塞整个页面。
+
+### 阶段二：测试队列与证据
+
+增加独立验证状态、即时能力门禁、批次映射、证据失效和背压。同步修改主 Agent、开发 Skill、报告脚本和完成标准；先以单实现 worker 验证，避免同时引入并发干扰归因。
+
+### 阶段三：受限并发与复盘
+
+建立工作包边界、共享文件和设备锁、隔离与集成契约；对独立任务逐步开放多人。采集实际投入与等待数据，按里程碑校准。
+
+迁移旧计划时保留稳定 page_id、路径和历史记录；v1 评分继续保留其含义，不把旧 page_score 直接解释为新优先指数。已有通过证据按版本核实后复用；缺少可验证依据的状态不能自动升级。结构化账本切换后禁止旧脚本继续原位写入报告状态。
+
+## 14. 实施验收场景
+
+上下文复用新增验收：裁剪快照不含无关后续 Spec、不写账本、只能读取就绪或当前活动窗口；版本/候选/事件变化反映在快照身份；重复分析工时不重复加总，且不能超过已知上下文与实现工时。CLI 与运行时行为回归已覆盖这些约束；实际 token 和耗时改善需真实迁移数据验证。
+
+
+1. 用户要求首页优先、登录基本可用时，仅基本登录依赖提前，找回密码等进入后续范围。
+2. 用户新增无源码功能时，保留用户来源、独立验收和范围变更，Facts 不被改写。
+3. 用户调整顺序产生依赖环时，计划校验失败并给出具体路径。
+4. 相同输入重复规划保持稳定 ID 和顺序；调整优先级不重命名已有目录。
+5. 高风险能力未验证时消费者不能派发；能力失败或证据失效时正确传播影响。
+6. 多个低风险 Spec 合批共享构建安装，结果仍能定位到每个实际断言和 Spec。
+7. 验证队列任一上限触发时，停止新增实现并优先清理，不能靠标记 implemented 消除债务。
+8. 共享文件或设备资源冲突时，不并发写入或安装；隔离变更集成后重新验证受影响行为。
+9. 中途变更范围不覆盖派发基线；已完成历史保留，报告显示范围分母变化。
+10. 尚未执行、零执行、跳过必测项或旧 HAP 证据都不能得到 accepted。
+11. 首页订单展示被多层能力阻塞时，必要前置逐层继承目标优先级；非必要启动精修及登录扩展不被提升，也不产生整页强制依赖。
+12. 两个高优目标共享前置时只实现一次，保留各自继承来源；取消其中一个目标不错误撤销另一个目标需要的提升。
+13. 已验证能力被复用；证据失效或验证失败时消费者重新受阻，不能继续引用旧 ready 状态。
+14. 依赖闭包超出授权范围、命中排除项或与用户顺序冲突时，给出具体路径及最小调整建议，不自动改写上游清单。
+15. 外部接口恢复时间未知时，报告不承诺确定完成时间；受阻目标不长期占住队首，独立工作遵守验证债务上限。
+16. 用户调整优先级或资源恢复后，派生优先级与就绪集合按事件重算，相同输入得到稳定结果；在途任务不被静默换范围。
+17. 规划技能只输出规划及修订；主 Agent 选择和派发；执行技能只处理固定任务，三个职责不互相抢占且不存在第二份计划真源。
+18. 纯执行状态更新不会重新生成全部 Spec；语义变化仅修订受影响计划，保留消费的功能清单版本、历史计划及在途派发基线。
+19. 技能重命名后，主 Agent、元数据、安装入口及测试引用一致；如保留旧入口，它只路由到唯一规则真源，不继续独立生成旧计划。
+20. round、page_batch 和 Spec 的关系全量可追踪；每个 Spec 恰好归属一个同页同轮批次，预算超限、跨页归拢和批次压缩依赖环均被拒绝。
+21. 基础轮全部 Spec accepted 后仍需真实目标路径证据；缺少 round_accept 时不能开始增强轮，批次实现完成不代表页面完善。
+22. 一次派发多个同页 Spec 但始终只有一个实现 worker；内部依赖未验证、窗口外任务或另一个页面批次不能越过当前独占派发。
+23. 同页低优顺带项不能挤占另一页面的更高优就绪任务；无更高优竞争且新增成本在预算内时才可搭配领取。
+24. 候选变化保留可证明的历史轮次交付，但不沿用当前通过状态；真实失败、证据丢失或依赖语义变化使相关轮次重新受阻。
+25. 页面首轮已验收与页面完整完成分别展示；范围未全量核对或仍有后续 Spec 时不得宣称该页完善。批次中断、恢复和计划修订保留逐 Spec 历史。
+
+实现时先做以上决策、状态和证据映射的聚焦回归测试，再运行 d2h 的 `npm run check` 与 `npm test`；如修改 CLI 则运行 droid2hmos 的 `npm run verify`。只有涉及 AppGraph 事实契约才修改并验证 appgraph。集成遵守仓库既有 fork 分支与 PR 规则。
+
+
+## 15. 功能范围的持续维护与全量收口
+
+功能清单新版本为 `d2h-feature-plan/v2`，每个功能维护稳定 `scope_items`；每项包含 `scope_id/description/acceptance/status/milestone`，非 included 项还需 reason。替代 v1 的 required_scope/deferred_scope，避免平行真源。功能 milestone 为默认归属，实际执行阶段由范围项决定。
+
+| 登录功能范围 | 第一轮：首页基础可用 | 后续完善 | 完成判断 |
+| --- | --- | --- | --- |
+| basic：真实基础登录 | S-LOGIN-BASIC | 保留原 Spec，复用能力 | 对应 checks 当前有效 |
+| session：约定登录态恢复 | deferred/unassigned，保留 ID | 排期后新增 S-LOGIN-SESSION | 新 Spec 通过，基础路径回归有效 |
+| 其他约定范围 | 单独登记，不提前实现 | 分轮新增增量 Spec | 所有未排除范围验收后功能才完整 |
+
+Spec 使用 `scope_refs[{feature_id,scope_id,checks}]` 映射需求与检查，每个授权且已分配的范围项恰好一个 Spec 负责；不得用 feature 被引用一次代替全范围覆盖。一个范围过大需要多个 Spec 时先拆范围项，复用依赖通过 requires/provides。AI 负责语义拆分与原始材料完整性核对，脚本保证 ID、授权、阶段、唯一负责者和检查映射。
+
+执行账本不复制需求完成字段；derive 从当前 Spec 验收派生 `feature_progress`（逐项 Spec、accepted、remaining_scope_ids）、`scope_tracking` 与 `scope_coverage_accepted`。延期、未分配和待澄清项阻止全量范围通过，但不阻止当前已约定里程碑完成；排除项保留理由。该范围门禁仍不代替全应用回归和真实迁移报告。
+
+同页 spec.md 持续追加范围项/轮次/Spec/checks 对照，基础 Spec 验收后不改变其范围。新增完善项通过新 Spec + reconcile；修改原要求修订原 Spec 并重新验证，原能力回归则 invalidate/repair。新增无关范围不重置基础 Spec，代码候选变化仍遵循既有证据失效规则。页面 complete 除原有门禁外，还保守要求该页关联功能的全部范围解决。
+
+旧 v1 清单与计划继续读取，但输出 scope_tracking=false、scope_coverage_accepted=false，不能据此声明全量完成。升级由 AI 归档旧输入、显式拆分范围项并递增版本、补 scope_refs，使用 --previous 与 reconcile 保留历史；旧 PASS 不自动证明新映射范围。范围 ID 后续不得删除；拆分替代保留旧项并说明排除原因。
+
+
+### 基础 Spec 到全量完善的维护流程
+
+```mermaid
+flowchart TD
+  A["F-LOGIN：登录功能的全部约定范围"] --> B["basic：基础登录，第一轮 included"]
+  A --> C["session：登录态恢复，后续阶段或 unassigned"]
+  A --> D["其他已知范围：逐项保留 ID、处置及理由"]
+  B --> E["S-LOGIN-BASIC：scope_refs → basic → checks"]
+  E --> F["实现并验收；提供 session.basic 能力"]
+  F --> G["首页 Spec 复用能力，形成第一轮基础可用路径"]
+  G --> H["第一轮目标交付；F-LOGIN 仍部分完成"]
+  C --> I["上游明确后续阶段并改为 included；保留 scope_id"]
+  H --> I
+  I --> J["新增 S-LOGIN-SESSION；依赖已有能力"]
+  J --> K["reconcile：保留基础 Spec 与历史，新增增量任务"]
+  K --> L["在同一登录页面增量开发；验证新增及受影响行为"]
+  L --> M["按当前候选派生逐项验收与剩余范围"]
+  D --> M
+  M --> N{"所有未排除范围当前验收通过？"}
+  N -- 否 --> I
+  N -- 是 --> O["feature_progress.complete = true"]
+  O --> P["全部功能范围通过 + 最终回归及报告核对 → 全迁移完成"]
+  F -. 原需求改变 .-> R["修订原 Spec 并重新验收"]
+  F -. 原能力回归 .-> S["invalidate / repair；保留历史"]
+```
+
+后续新增 Spec 复用的是页面和能力，不重复认领基础范围；只有原需求变化才修订原 Spec。`scope_coverage_accepted` 只表示约定范围逐项通过，不能替代最终回归。新增未关联范围不会因计划修订重置基础 Spec；新代码候选仍需当前有效的验证证据。
+
+## 16. 开工与交接门禁
+
+新流程在现有粒度与上下文机制上补齐“当前轮次自足工单 → 开工就绪 → 实际代码接口 → 能力验证 → 消费者”，沿用单 worker 与逐项验收，不增加另一套编排层。
+
+新计划显式启用 work_packet_policy=required-v1；旧计划不隐式改变。implementation_brief 包含行为、不变量、已知坑和阻塞性问题；testing.layers 为每项检查标注计划验证层级；shared_contracts 按需明确状态生产者、消费者、通道、载荷、初始化和生命周期。readiness_gaps 缺口阻止成员派发，不能夹带进同页批次。字段规则只在 [工作包参考](../skills/d2h-spec-plan/references/work-packets.md) 维护。
+
+接口签名从当前实际代码复核，以 interface 事件记入 execution.json。文件、候选变化，或 failed/invalidate/repair 后不再交接旧接口；相关工作包与共享契约语义修订通过 reconcile 重置参与者并保留历史。文件哈希不是符号或调用链语义证明，AI 仍负责源码核验。消费者不仅要接口有效，还需当前构建和即时契约通过。
+
+分层目前是计划与前置排错手段：正式 test evidence 仍只支持受管设备结果，不能把静态/逻辑/集成检查声明为设备 PASS。聚合验证可共享同一候选的真实结果；鉴权、启动及共享契约不延后。定向修复保留已明确需求和上下文，不反复全量探索；当前候选变化仍保守撤销旧证据。运行内反馈记账本，完整迁移结束或明确中止后再写流程复盘。