@chenmk/superflow 0.5.8 → 0.5.10

package/assets/skills/superflow-pipeline/references/document-review-coverage.md

@@ -0,0 +1,82 @@
+# 需求 × 真实入口评审
+
+0.5.10 起，完整文档交付在已有 `document-review.json` 中添加 `coverage`。
+这是现有来源清单、源码审计、入口台账和测试合同的机器索引，不是第二套需求文档。
+稳定 ID 复用现有清单；正文继续放原文档。不要从 FIX 任务倒推入口全集。
+
+## 谁负责什么
+
+- Agent：从用户原文和确认记录提取需求；从当前调用方、控制器、写入方发现真实入口。
+  独立对照这两份清单，检查新增、遗漏、收窄、反转和排除。源码可解的问题自行查明。
+- 脚本：检查每个需求与每个已登记入口的适用性、来源文件指纹、用例引用、逐项评审记录。
+  无法证明清单完整、排除合理、断言充分或实现正确；结构 PASS 不是语义 PASS。
+- 用户：只确认新的业务歧义、实现方向和需要授权的操作，不接收本应自行排查的源码问题。
+
+## 必须执行的语义审查
+
+1. 明确区分“允许执行某行为”和“该行为允许产生什么归属/状态/资源”。
+   不能把“允许，但应归属原主体”改成“拒绝且零副作用”。
+2. EXCLUDED 只能对应一个需求维度 × 一个入口，不能因“不适用站点过滤”等理由
+   把同一入口在账号归属、权限、资金或其他需求维度整体排除。
+3. 评审覆盖 FIX、VERIFY_EXISTING、EXCLUDED 和不改代码的入口。每个排除项必须回到
+   原始需求核验；引用源码当前行为不能授权偏离需求。确需改范围回到用户确认。
+4. 按角色从真实用户动作走到实际请求、业务写入、查询可见性及下游资源。
+   同页面不同角色的分支用不同入口 ID；不得只测试开发者选中的新接口。
+5. 验收同时断言返回、最终状态和禁止的副作用。只读/纯函数场景也要给出明确
+   无持久化变更的理由，不能留空。browser 入口必须有 browser 验收，API 测试只能补充。
+
+## 凭证扩展
+
+下面是 `coverage` 最小结构，添加到现有三轮凭证，不替换其它字段。
+`sources.path` 相对 change 目录，可引用授权范围内的跨仓文件；在线来源保存带 URL、
+原文和确认上下文的本地快照。SHA-256 是文件字节哈希，不是 handoff 的规范化哈希。
+不要复制源码正文；只登记定位与指纹。`sourceRefs` 均引用 sources 中的 ID。
+
+```json
+{
+  "schemaVersion": "superflow.review-coverage.v1",
+  "sources": [
+    {"id":"S1","role":"requirement","path":"source-ingestion.md","sha256":"<64 hex>"},
+    {"id":"S2","role":"code","path":"../../../src/caller.ts","sha256":"<64 hex>"},
+    {"id":"S3","role":"contract","path":"tests.md","sha256":"<64 hex>"}
+  ],
+  "requirements": [
+    {"id":"R1","statement":"用户确认的完整约束，保留允许行为和结果边界","sourceRefs":["S1"]}
+  ],
+  "entries": [
+    {"id":"E1","kind":"browser","actor":"指定角色","route":"页面动作 -> 实际请求路径","sourceRefs":["S2"]}
+  ],
+  "decisions": [
+    {"requirementId":"R1","entryId":"E1","disposition":"FIX","rationale":"该入口适用此需求，详见设计","currentBehavior":"当前实际行为","targetBehavior":"保留允许动作并约束归属","sourceRefs":["S1","S2"],"caseIds":["C1"]}
+  ],
+  "cases": [
+    {"id":"C1","entryId":"E1","level":"browser","action":"角色从实际页面执行动作","sourceRefs":["S3"],
+     "assertions":{"response":"约定成功结果","state":"归属及查询结果正确","forbiddenEffects":"不会创建独立资源"}}
+  ]
+}
+```
+
+- 每个 requirements × entries 组合必须有唯一 decision。按已界定 change 范围登记，
+  不扫描无关全平台。EXCLUDED 必须有 requirement 来源和具体理由、空 caseIds；
+  FIX/VERIFY_EXISTING 必须有对应入口的用例，不接受拿另一条接口用例顶替。
+- `kind`/`level` 为 `browser|api|job|event|library|cli`，用例等级必须匹配入口。
+- `source-contract` 和 `e2e-environment` 轮都添加
+  `"reviewedPairs": [["R1", "E1"]]`，覆盖全部组合（包括排除项），不得填完即视为审查完成。
+- 先完善权威文档与清单，再刷新 handoff，再由 Agent 三轮核验当前内容、填写 coverage
+  文件指纹及评审记录，最后执行 coding-ready。未关闭发现保留，禁止刷 hash 冒充复审。
+
+## 验证与失效
+
+`superflow-document-audit.mjs` 校验内容和清单；coding-ready 绑定评审文件指纹。
+CLI/托管启动重算 handoff 和所有来源指纹；编辑 Hook 同步核验文档与评审，但允许实现阶段
+源码变化。复用 handoff 既有规范化：任务勾选、test-report 回填不使合同失效。
+新 Prompt 派发前若前一批已改变入口源码，主 Agent 检查影响并刷新相应评审，不能盲目更新指纹。
+coding-ready 复检失败会写 BLOCKED 撤销旧 READY。
+
+升级后已有评审文件仍可读取；缺 coverage/reviewHash 的旧文档交付不能用于新的启动，
+需按上述步骤补齐复审，不能填空对象绕过。已启动托管 Run 的恢复协议不变。
+直接编辑 Hook 遇旧凭证也需补齐；这属于修复旧门禁误放行，不自动重写项目资料。
+
+验收阶段沿同一 R/E/C ID 在 `test-report.md` 回填实际角色、动作、请求路由、状态/
+副作用断言、原始日志路径及结果。主 Agent 对照原始来源和实际证据，不只看测试汇总。
+计划用例不是执行证据；API-only 不能报页面 E2E 成功。脚本未验证业务语义的部分不得宣称自动保证。

package/assets/skills/superflow-pipeline/references/implementation-prompt-template.md

@@ -39,16 +39,16 @@ Worker 自测通过 ≠ 完成任务
 12. 涉及第三方/设备/支付/客户端/外部集成时，已区分 mock、测试端点和真实入口证据；mock-only 不得标记真实链路完成
 13. 五项硬门禁全部通过：字段语义合同、写入闭环、真实入口调用链、禁止 fallback 与猜测实现、Agent 执行前自检
 14. Superpowers 技术详设接管源码级 HOW，但不得覆盖 OpenSpec/SDD 的需求、API、DB、字段语义、tests 或验收门禁
-15. SDD handoff hash 已继承并核对，不能凭压缩后的聊天记忆继续开发
+15. SDD handoff 继承已核对（.sdd/state.yaml 与 sdd-context.sha256 一致），不能凭压缩后的聊天记忆继续开发
 
 ## Superpower 技术详设继承（强制）
 
 读取 [Superpowers 技术详设](../docs/superpowers/specs/YYYY-MM-DD-{change-id}-technical-design.md)，继承其中与本批次相关的源码级 HOW 和执行约束。
 本章节只允许描述实现路径、团队组织、拆分、TDD/RED、独立测试、Review 和验证闭环，不允许新增或替换需求/API/DB/tests 合同。
 
-| 执行模式 | 团队角色 | 拆分建议 | TDD/RED切入点 | 独立Tester验证点 | 高风险猜测点 | 禁止自由发挥项 | handoff_hash | 进入prompt的强制要求 |
-|----------|----------|----------|----------------|------------------|--------------|----------------|--------------|----------------------|
-| ____ | Worker / Tester / Reviewer / Leader | ____ | ____ | ____ | ____ | ____ | ____ | ____ |
+| 执行模式 | 团队角色 | 拆分建议 | TDD/RED切入点 | 独立Tester验证点 | 高风险猜测点 | 禁止自由发挥项 | 进入prompt的强制要求 |
+|----------|----------|----------|----------------|------------------|--------------|----------------|----------------------|
+| ____ | Worker / Tester / Reviewer / Leader | ____ | ____ | ____ | ____ | ____ | ____ |
 
 规则：
 - OpenSpec/SDD 的 [design.md](../design.md)、[api.md](../api.md)、[tests.md](../tests.md) 是 WHAT/API/DB/tests 事实源。
@@ -61,17 +61,17 @@ Worker 自测通过 ≠ 完成任务
 
 - Handoff: [.sdd/handoff/sdd-context.md](../.sdd/handoff/sdd-context.md)
 - Handoff JSON: [.sdd/handoff/sdd-context.json](../.sdd/handoff/sdd-context.json)
-- Handoff hash: `{handoff_hash}`
 - State file: [.sdd/state.yaml](../.sdd/state.yaml)
+- Hash 绑定：`.sdd/state.yaml` 的 `handoff_hash` 单点维护，编码前核对其与 sdd-context.sha256 一致
 
 执行规则：
 1. Worker、Tester、Reviewer 都必须先读 handoff，再回读原始 [api.md](../api.md)、
    [design.md](../design.md)、[tests.md](../tests.md) 和 Superpowers 技术详设。
-2. 如果任何 SDD 文档发生修改，先执行：
+2. 如果需求、设计、API、SQL、测试合同或任务内容发生修改，先执行（任务勾选和测试报告回填除外）：
    `~/.codex/skills/superflow-pipeline/scripts/superflow-handoff.sh {change-dir} --refresh`
    并比较新的 `.sdd/handoff/sdd-context.sha256`。
-3. prompt、test-report、design.md 中记录的 hash 必须一致；不一致时停止并返回
-   `$superflow-docs`，不得继续编码。
+3. hash 仅由 `.sdd/state.yaml` 的 `handoff_hash` 绑定，必须与
+   `.sdd/handoff/sdd-context.sha256` 及当前合同一致；正文只链接上下文包，不复制 hash。
 4. 进入验证前执行：
    `~/.codex/skills/superflow-pipeline/scripts/superflow-guard.sh {change-dir} implement`
    失败则补文档或 prompt，不得把失败项写成通过。

package/assets/skills/superflow-pipeline/references/quality-gate.md

@@ -57,10 +57,10 @@
 | 38   | **真实入口调用链**                 | **所有接口/MQ/定时/设备/小程序/第三方/后台操作链路强制**                                | design.md 包含 `用户/外部动作                                                                                                                                                                                                                                                                                              | 上游服务/接口       | 本仓入口           | MQ/异步回调          | 关键字段变化               | DB 状态      | 结算/通知/展示消费点                                                                                          | 真实验证方式`；测试端点不能替代真实入口                                                                                  |
 | 39   | **禁止 fallback 与猜测实现**       | **所有实现任务强制**                                                                    | sdd-quality-gate.md 或 design.md 明确禁止默认值、兜底反查、替代字段、保留旧值、空值转可用、静默跳过、下游补偿；批准兼容必须有 owner 确认和暴露/移除规则                                                                                                                                                                    |
 | 40   | **Agent 执行前自检占位**           | **所有实现 prompt 强制**                                                                | test-report.md 或 prompt 中预置 `真实入口已定位                                                                                                                                                                                                                                                                            | 字段语义合同已核对  | 写入闭环已核对     | 禁止兜底边界已确认   | RED 测试已执行             | 允许修改文件 | 禁止修改文件                                                                                                  | 阻塞项`                                                                                                                  |
-| 41   | **Superpowers 技术详设（HOW）**    | **完整 SDD 实现任务强制**                                                               | `docs/superpowers/specs/YYYY-MM-DD-*-technical-design.md` 存在并记录当前 handoff_hash；Superpowers 接管源码级 HOW、TDD/RED 切入点、团队/Reviewer/Tester 分工、worktree/端口计划和执行风险；不得覆盖 OpenSpec/SDD 的需求、API、DB、SQL、字段语义、tests 或验收门禁                                                          |
+| 41   | **Superpowers 技术详设（HOW）**    | **完整 SDD 实现任务强制**                                                               | `docs/superpowers/specs/YYYY-MM-DD-*-technical-design.md` 存在并链接当前 handoff 上下文包；Superpowers 接管源码级 HOW、TDD/RED 切入点、团队/Reviewer/Tester 分工、worktree/端口计划和执行风险；不得覆盖 OpenSpec/SDD 的需求、API、DB、SQL、字段语义、tests 或验收门禁                                                          |
 | 42   | **字段/状态反向影响面**            | **涉及字段值、状态/枚举、在线离线、删除恢复、同步标记、支付退款状态、第三方状态时强制** | Superpowers 技术详设包含 `Field And Status Reverse Impact`，列出 `字段/状态                                                                                                                                                                                                                                                | 写入点              | 读取/过滤点        | 派生/同步点          | 跨模块消费方               | 消费方测试   | 缺口/阻塞`；必须执行 `rg`/Mapper XML/实体/DTO/SQL/定时/MQ/回调/第三方/兄弟仓反查；只改直接 setter/writer 阻塞 |
 | 43   | **架构师视角的模块职责与调用方向** | **涉及跨仓、跨服务、SDK、MQ、定时、设备、回调、第三方、小程序、网关或适配层时强制**     | Superpowers 技术详设包含 `Architecture Boundary And Call Direction`，列出 `链路步骤                                                                                                                                                                                                                                        | 调用方向            | owner模块          | 既有入口/出口        | 拟新增入口/出口            | 是否允许     | 证据锚点                                                                                                      | 禁止绕路`；必须证明业务入口、出口适配、协议转换、设备网关、MQ 消费者的职责边界没有反转；不能仅以“技术上能调用”为设计依据 |
-| 44   | **上下文防漂移 handoff**           | **所有进入实现的任务强制**                                                              | `.sdd/handoff/sdd-context.md`、`.json`、`.sha256` 和 `.sdd/state.yaml` 已生成；design.md、sdd-quality-gate.md、prompt、test-report 记录同一 handoff_hash；`superflow-guard.sh <change-dir> docs` 通过                                                                                                                      |
+| 44   | **上下文防漂移 handoff**           | **所有进入实现的任务强制**                                                              | `.sdd/handoff/sdd-context.md`、`.json`、`.sha256` 和 `.sdd/state.yaml` 已生成；handoff_hash 仅在 .sdd/state.yaml 绑定并与上下文包及当前合同一致；正文链接上下文包；`superflow-guard.sh <change-dir> docs` 通过                                                                                                                      |
 | 45   | **SDD 状态机字段**                 | **所有进入实现的任务强制**                                                              | `.sdd/state.yaml` 包含 workflow、phase、handoff_hash、build_mode、isolation、tdd_mode、review_mode、verify_mode、implementation_prompt、verification_report、archived；`superflow-state.sh status/next/recover` 输出一致                                                                                                   |
 | 46   | **外部枚举绑定确认**               | **涉及第三方、SDK、BEM/停车、支付退款、财务展示、来源字段、状态同步或外部字典时强制**   | api.md、sdd-quality-gate.md 和 Superpowers 技术详设包含 `外部枚举绑定确认` / `External Enum Binding`，列出 `业务字段                                                                                                                                                                                                       | 本系统真源字段/枚举 | 外部系统字段       | 外部枚举/字典值      | 展示文案/业务语义/财务语义 | 取值来源     | owner/确认时间                                                                                                | 不确定项/阻塞处理                                                                                                        | 测试证据`；不得用请求成功、值非空或字段存在替代业务语义确认；未确认时必须阻塞 |
 | 47   | **金额精度边界**                   | **涉及金额、费用、优惠、抵扣、退款、分账、支付、发票、余额、电费、服务费、套餐结算、比例分摊、明细分配、对账或财务展示时强制** | Superpowers 技术详设包含 `Money Precision Boundary` 及金额恒等式、权威总额、独立计算项、差额反推项与公式、计算态来源、中间精度、舍入边界、scale/rounding mode、分配/对账规则、禁止提前舍入点和测试证据；存在加法恒等式且总额是真源时，最后一个组成项必须由权威总额减去其余组成项合计得到，禁止所有组成项分别计算和舍入后重建总额；测试必须覆盖半分、尾差或多明细分配场景 |
@@ -87,7 +87,7 @@
 | 42  | **真实入口与测试端点分级（阻塞级）**           | 涉及外部系统链路时：① test-report 必须分开记录 `Mock 验证`、`测试端点验证`、`真实入口验证`；② 测试 Controller/绕过鉴权端点只能标记局部通过；③ 无真实入口 payload/响应/trace/DB 时，不得写真实链路通过                                                                              |
 | 44  | **Red-Green 证据占位（阻塞级）**               | test-report.md 必须预置 `RED 失败证据`、`GREEN 通过证据`、`接口自动化证据`、`DB 核查证据`、`日志核查证据`、`未自动化/阻塞用例`；每项绑定 tests.md 用例 ID                                                                                                                          |
 | 45  | **Superpowers 技术详设继承（阻塞级）**         | implementation prompt 必须包含 `Superpower 技术详设继承`，链接 state 中的 `technical_design`，继承源码级 HOW、TDD/RED 顺序、团队分工和执行边界；prompt 不得让 agent 覆盖 OpenSpec/SDD 的 API、DB、字段语义、tests 或验收门禁                                                       |
-| 46  | **handoff hash 继承（阻塞级）**                | implementation prompt 必须包含 `上下文防漂移与状态继承`，链接 `.sdd/handoff/sdd-context.md`，记录 handoff_hash，并要求修改 SDD 文档后重跑 `superflow-handoff.sh --refresh` 和 `superflow-guard.sh <change-dir> implement`                                                          |
+| 46  | **handoff hash 继承（阻塞级）**                | implementation prompt 必须包含 `上下文防漂移与状态继承`，链接 `.sdd/handoff/sdd-context.md`，引用 state.yaml 单点绑定，并要求修改冻结合同后（任务勾选与测试报告回填除外）重跑 `superflow-handoff.sh --refresh` 和 `superflow-guard.sh <change-dir> implement`                                                          |
 | 47  | **状态机执行决策（阻塞级）**                   | implementation prompt 必须包含 `状态机执行决策`，记录 build_mode、isolation、tdd_mode、review_mode、implementation_prompt、worktree_ports，并要求进入 verify 前执行 `superflow-state.sh scale` 和 `superflow-guard.sh implement --apply`                                           |
 
 **结果处理**
@@ -123,7 +123,7 @@
 | 15  | **RED-GREEN 收口**   | 检查 test-report 同一用例的前后证据                               | 编码前 RED 失败输出存在且失败原因正确；编码后同一命令 GREEN 通过；测试后补或未观察 RED 一律阻塞                                           | Worker + Tester + Leader |
 | 16  | **接口自动化收口**   | 检查每个 L3/L4 用例证据                                           | 包含真实命令、请求体来源、响应断言、DB SELECT、日志关键词和环境信息；HTTP 200 或 DB-only 不能单独通过                                     | Tester + Leader          |
 | 17  | **五项硬门禁收口**   | 检查 prompt/test-report/design/tests                              | 字段语义合同、写入闭环、真实入口调用链、禁止 fallback 与猜测实现、Agent 执行前自检均有证据；任一缺失阻塞                                  | Reviewer + Leader        |
-| 18  | **上下文防漂移收口** | 检查 `.sdd/handoff/*`、`.sdd/state.yaml`、prompt、test-report     | handoff_hash 一致；`superflow-guard.sh <change-dir> implement` 或 `verify` 通过；换会话/并行窗口后的执行报告证明已重读 handoff 和原始文档 | Leader                   |
+| 18  | **上下文防漂移收口** | 检查 `.sdd/handoff/*`、`.sdd/state.yaml`、prompt、test-report     | state.yaml 与当前合同的 handoff_hash 一致；`superflow-guard.sh <change-dir> implement` 或 `verify` 通过；换会话/并行窗口后的执行报告证明已重读 handoff 和原始文档 | Leader                   |
 | 19  | **状态机收口**       | 检查 `.sdd/state.yaml` 和 `superflow-state.sh recover/next`       | verify 前 phase 已由 implement guard 推进；verify 后 verification_report、verify_result、verified_at 正确；archive 前必须等待用户确认     | Leader                   |
 
 ### 数据库迁移类任务特有加禁（触发条件：涉及表结构重构、旧数据迁移、状态字段变更、分页筛选依赖新表/新状态）

package/assets/skills/superflow-pipeline/references/quality-standards.md

@@ -121,7 +121,7 @@ review.md（设计评审，检查 spec → design → tasks → tests 一致性
 
 ## Superpowers Technical Design Handoff
 - 技术详设：`docs/superpowers/specs/YYYY-MM-DD-<change-id>-technical-design.md`
-- handoff_hash: `<sha256>`
+- hash 绑定：`.sdd/state.yaml` 的 `handoff_hash` 单点维护，正文不嵌入原始 hash
 - 边界：OpenSpec/SDD 管 WHAT/API/DB/tests，Superpowers 管源码级 HOW/执行编排
 
 ## API Design（如有）

package/assets/skills/superflow-pipeline/references/superpower-technical-design-template.md

@@ -11,7 +11,6 @@ semantics, tests, and acceptance gates.
 ---
 change: <change-id>
 status: draft|ready|final
-handoff_hash: <sha256>
 canonical_sources:
   - ../../openspec/changes/<change-id>/proposal.md
   - ../../openspec/changes/<change-id>/api.md
@@ -247,5 +246,6 @@ already-rounded money.
 - Do not invent API fields, DB columns, status semantics, fallback behavior, or
   acceptance criteria.
 - Keep unresolved source facts as blockers. Do not convert them to guesses.
-- Record the same `handoff_hash` as `.sdd/handoff/sdd-context.sha256`.
+- Hash binding is owned by `.sdd/state.yaml` (`handoff_hash`); this document
+  must not embed the raw hash.
 ```

package/assets/skills/superflow-pipeline/references/test-execution-template.md

@@ -2,6 +2,12 @@
 
 记录测试的执行环境、执行过程和结果，作为交付物的一部分。
 
+运行验收必须使用 tests.md 冻结的环境，不能擅自以本地容器或 Mock 替代共享开发环境。
+用户要求全部接口实测时，先冻结“接口 × 角色 × 场景”矩阵，共用一次应用启动和测试账号，
+逐项记录脱敏请求、响应文件、数据库预期集合与实际集合；遗漏、失败和阻塞单独列出。
+进程健康且代码/配置未变化时复用同一实例，不为每个接口重启；必要重启记录原因。
+开发任务仅以约定的开发环境验收，后续发布环境不得自动升级为当前开发交付门禁。
+
 ## 文档结构
 
 ```markdown

package/assets/skills/superflow-pipeline/scripts/superflow-guard.sh

@@ -309,11 +309,13 @@ require_hash_recorded() {
     issues+=("handoff hash file is empty")
     return 0
   }
-  if ! grep -Riq "$hash" \
-    "$CHANGE_DIR/design.md" "$CHANGE_DIR/sdd-quality-gate.md" \
-    "$CHANGE_DIR/test-report.md" "$CHANGE_DIR/prompt" 2>/dev/null; then
-    issues+=("handoff hash is not recorded in design, quality gate, prompt, or test-report")
-  fi
+  # The state file is the machine-readable binding point.  Requiring the raw
+  # hash inside prose documents turned every refresh into a four-file manual
+  # backfill loop that blocked real delivery work, so a human-readable pointer
+  # is enough here.
+  local binding
+  binding="$(state_get handoff_hash)"
+  [[ "$binding" == "$hash" ]] || issues+=("state handoff_hash does not match handoff pack; run superflow-handoff.sh --refresh")
 }
 
 change_has_field_status_risk() {

package/assets/skills/superflow-pipeline/scripts/superflow-handoff.sh

@@ -21,14 +21,26 @@ sha_file() {
   # Ignore generated state/hash marker lines so recording the handoff hash in
   # SDD docs does not change the handoff hash itself.
   if command -v sha256sum >/dev/null 2>&1; then
-    sed -E '/handoff_hash/d;/context_hash/d;/sdd-context\.sha256/d;/[a-f0-9]{64}/d;/pending/d;/^[[:space:]]*$/d' "$1" \
+    canonical_contract "$1" \
       | sha256sum | awk '{print $1}'
   else
-    sed -E '/handoff_hash/d;/context_hash/d;/sdd-context\.sha256/d;/[a-f0-9]{64}/d;/pending/d;/^[[:space:]]*$/d' "$1" \
+    canonical_contract "$1" \
       | shasum -a 256 | awk '{print $1}'
   fi
 }
 
+canonical_contract() {
+  # Reports are execution evidence, not frozen requirements. Their existence
+  # and validity are checked separately by the delivery/report gates.
+  if [[ "${1##*/}" == "test-report.md" ]]; then
+    return 0
+  fi
+  sed -E \
+    -e '/^[[:space:]]*(handoff_hash|context_hash):[[:space:]]*[^[:space:]]*[[:space:]]*$/d' \
+    -e 's/^([[:space:]]*[-*][[:space:]]+)\[[xX ]\]/\1[ ]/' \
+    -e '/^[[:space:]]*$/d' "$1"
+}
+
 json_escape() {
   sed 's/\\/\\\\/g; s/"/\\"/g'
 }
@@ -144,6 +156,7 @@ fi
 context_hash_input=""
 while IFS= read -r file; do
   rel="${file#"$CHANGE_DIR"/}"
+  [[ "${file##*/}" == "test-report.md" ]] && continue
   hash="$(sha_file "$file")"
   context_hash_input+="${rel}:${hash}"$'\n'
 done < "$TMP_LIST"

package/assets/skills/superflow-requirement-review/SKILL.md

@@ -5,6 +5,10 @@ description: 对已澄清或已形成 OpenSpec/SDD 草案的需求和设计执
 
 # Superflow Requirement Review
 
+必须读取并执行[需求×真实入口评审](../superflow-pipeline/references/document-review-coverage.md)。
+从原始需求独立建立核对清单，不从 FIX 任务反推范围；逐需求维度核对全部入口，特别是
+EXCLUDED、VERIFY_EXISTING 和无代码改动的路径。用户允许的动作不能被擅自改成拒绝。
+
 对当前 OpenSpec change 进行独立、对抗式但基于证据的反向评审。评审不是旁路建议：
 阻塞级问题必须回写并修正文档，复审通过后才能离开 docs 阶段。
 

package/assets/skills/superflow-verify/SKILL.md

@@ -5,6 +5,10 @@ description: Use when an SDD/OpenSpec change is ready for verification, test-rep
 
 # SDD Verify
 
+完整 workflow 验收必须读取[需求×真实入口评审](../superflow-pipeline/references/document-review-coverage.md)。
+沿 R/E/C ID 在现有 test-report 回填实际角色、页面动作、请求路由、最终状态与禁止副作用
+的原始证据。独立对照原始来源及实际调用方；API-only 不得冒充 browser E2E，计划不等于执行。
+
 Verification is a phase, not a final sentence. Use this skill after
 implementation work claims completion and before archive or delivery.
 

package/assets/skills-en/superflow-docs/SKILL.md

@@ -5,6 +5,12 @@ description: Use when confirmed requirements or OpenSpec artifacts need SDD cont
 
 # SDD Docs
 
+For full document delivery, read and apply
+[requirement × real-entry review](../superflow-pipeline/references/document-review-coverage.md).
+Extend the existing three-round receipt with original-source, real-caller,
+EXCLUDED/VERIFY_EXISTING and assertion coverage. Internal document consistency
+is not evidence of fidelity to the user's original semantics.
+
 Use this skill after a feature is frozen or after `$openspec-propose` has
 created the base OpenSpec artifacts. This skill is an SDD contract-doc wrapper;
 it must not replace the installed OpenSpec skills for core artifact generation

package/assets/skills-en/superflow-pipeline/SKILL.md

@@ -252,10 +252,10 @@ Before moving phases, run the local scripts from this skill directory:
 Rules:
 
 - Never proceed when superflow-guard fails.
-- If any SDD/OpenSpec document changes, regenerate handoff and update all stored
-  handoff_hash references.
-- design.md, sdd-quality-gate.md, implementation prompts, and test-report.md
-  must record the same handoff_hash as .sdd/handoff/sdd-context.sha256.
+- If a frozen SDD/OpenSpec contract changes, regenerate handoff and its state-file
+  binding. Task checkbox progress and test-report updates do not require refresh.
+- The handoff_hash binding lives in .sdd/state.yaml. Prose documents reference
+  the handoff context by path; do not copy the raw hash into every document.
 - After context compaction or session handoff, reload .sdd/state.yaml and
   .sdd/handoff/sdd-context.md before acting.
 

package/assets/skills-en/superflow-pipeline/references/batch-prompt-template.md

@@ -9,7 +9,7 @@
 - Branch: {branch}
 - Ports: app={port}, debug={port}
 - Handoff: .sdd/handoff/sdd-context.md
-- Handoff hash: {hash}
+- Handoff binding: `.sdd/state.yaml` → `.sdd/handoff/sdd-context.sha256`; link the context pack without copying the hash into this prompt.
 - Technical design: {path}
 
 ## Required Reading

package/assets/skills-en/superflow-pipeline/references/document-readiness.md

@@ -1,5 +1,9 @@
 # Document Delivery Readiness Contract
 
+The base review example below is not a complete receipt. From 0.5.10, also apply
+[requirement × real-entry review](document-review-coverage.md): add `coverage` and
+`reviewedPairs` to source-contract/e2e-environment rounds. Old receipts require re-review.
+
 ## Applicability
 
 Declare applicability in `.openspec.yaml`. Keyword scans may suggest a risk but

package/assets/skills-en/superflow-pipeline/references/document-review-coverage.md

@@ -0,0 +1,89 @@
+# Requirement × real-entry review
+
+Starting in 0.5.10, full document delivery adds `coverage` to the existing
+`document-review.json`. It indexes the existing source inventory, source audit,
+entry ledger and test contract; it does not create a second requirements authority.
+Reuse stable IDs. Discover entries from current callers/writers, never from FIX tasks alone.
+
+## Ownership and semantic checks
+
+The Agent extracts requirements from original user statements/confirmations, independently
+discovers actual entry points, and checks omissions, narrowing, inversion and exclusions.
+The script checks declared coverage, references, file hashes and review records. A structural
+PASS cannot prove inventory completeness, business correctness or test sufficiency.
+Ask the user only about real business ambiguity, implementation direction or authorization;
+investigate source-resolvable questions autonomously.
+
+1. Distinguish permission to act from allowed ownership/state/resource effects. Never change
+   “allowed, but owned by the original principal” into “reject with zero effects”.
+2. EXCLUDED applies to one requirement × one entry. Inapplicability of one filter must not
+   exclude ownership, permissions, financial or other constraints on the same entry.
+3. Independently review FIX, VERIFY_EXISTING, EXCLUDED and unchanged paths against original
+   requirements. Existing code is not authorization to deviate. Scope changes return to owner confirmation.
+4. Follow each actor's real action through caller branch, request, writes, visibility and
+   downstream resources. Give different actor branches distinct entry IDs. Do not test only
+   the newly selected API.
+5. Assert response, final state and forbidden effects. For read-only/pure-function work explain
+   why no persistent change applies; do not leave blanks. Browser paths require browser acceptance;
+   API checks can supplement, not replace them.
+
+## Receipt extension
+
+Add the following `coverage` object to the existing three-round review; preserve its other
+fields. Paths are relative to the change and may reference authorized sibling repositories.
+Save online originals as local snapshots with URL and confirmation context. SHA-256 hashes
+file bytes, unlike the normalized handoff hash. Reference code, do not copy its body.
+
+```json
+{
+  "schemaVersion": "superflow.review-coverage.v1",
+  "sources": [
+    {"id":"S1","role":"requirement","path":"source-ingestion.md","sha256":"<64 hex>"},
+    {"id":"S2","role":"code","path":"../../../src/caller.ts","sha256":"<64 hex>"},
+    {"id":"S3","role":"contract","path":"tests.md","sha256":"<64 hex>"}
+  ],
+  "requirements": [
+    {"id":"R1","statement":"Complete confirmed constraint, preserving allowed actions and outcome boundaries","sourceRefs":["S1"]}
+  ],
+  "entries": [
+    {"id":"E1","kind":"browser","actor":"specified actor","route":"page action -> actual request path","sourceRefs":["S2"]}
+  ],
+  "decisions": [
+    {"requirementId":"R1","entryId":"E1","disposition":"FIX","rationale":"This entry is subject to the requirement; see design","currentBehavior":"actual current behavior","targetBehavior":"preserve allowed action and constrain ownership","sourceRefs":["S1","S2"],"caseIds":["C1"]}
+  ],
+  "cases": [
+    {"id":"C1","entryId":"E1","level":"browser","action":"Actor performs action on actual page","sourceRefs":["S3"],
+     "assertions":{"response":"contracted success","state":"correct ownership and visibility","forbiddenEffects":"no independent resources"}}
+  ]
+}
+```
+
+- Every requirements × entries pair requires exactly one decision. Bound the inventory to
+  the change; do not scan irrelevant platform modules. EXCLUDED requires a requirement source,
+  a specific rationale and empty caseIds. FIX/VERIFY_EXISTING require cases for that same entry.
+- `kind`/`level`: `browser|api|job|event|library|cli`; case level must match entry kind.
+- Both `source-contract` and `e2e-environment` rounds add
+  `"reviewedPairs": [["R1", "E1"]]` covering every pair, including exclusions.
+  Filling the record is not a substitute for performing the review.
+- Complete canonical documents/inventories, refresh handoff, perform all three reviews against
+  current content, record coverage file hashes, then run coding-ready. Retain findings;
+  updating hashes alone is not re-review.
+
+## Verification, invalidation and migration
+
+Document audit checks current content and coverage. Coding-ready binds the review file hash.
+CLI/managed dispatch recomputes handoff and every source hash. The edit Hook checks documents
+and review while allowing implementation source changes. Existing handoff normalization
+preserves task checkbox updates and test-report progress without invalidating contracts.
+If an earlier batch changed entry source before a new Prompt dispatch, the Host assesses its
+impact and refreshes affected review evidence rather than blindly updating hashes.
+A failed coding-ready recheck persists BLOCKED, revoking an earlier READY.
+
+Old receipts remain readable but cannot authorize new dispatch or source edits without
+coverage/reviewHash. Follow the migration/re-review steps above; empty objects do not bypass
+them. Existing managed Run recovery protocols are unchanged. No project records are silently rewritten.
+
+During verification, reuse R/E/C IDs in `test-report.md`, recording actual actor, action,
+request route, state/forbidden-effect assertions, raw evidence paths and outcomes. The Host
+compares them to original sources, not only a test summary. Planned cases are not execution
+evidence; API-only results cannot claim browser E2E. Do not claim automatic semantic assurance.

package/assets/skills-en/superflow-pipeline/references/implementation-prompt-template.md

@@ -6,11 +6,12 @@ Use this as the prefix for every implementation prompt.
 
 - Handoff: [.sdd/handoff/sdd-context.md](../.sdd/handoff/sdd-context.md)
 - Handoff JSON: [.sdd/handoff/sdd-context.json](../.sdd/handoff/sdd-context.json)
-- Handoff hash: {handoff_hash}
+- Hash binding: `handoff_hash` in `.sdd/state.yaml` must match `.sdd/handoff/sdd-context.sha256` and the current contract. Do not copy the hash into prose.
 - State: .sdd/state.yaml
 
-If any SDD/OpenSpec doc changes, rerun superflow-handoff.sh --refresh and compare
-the new hash before continuing.
+If requirements, design, API, SQL, test contracts or task content change, rerun
+superflow-handoff.sh --refresh. Task checkbox progress and test-report updates
+do not invalidate the frozen contract hash.
 
 ## Contract Boundary
 

package/assets/skills-en/superflow-pipeline/references/quality-gate.md

@@ -67,7 +67,7 @@
 
 ## Implementation Gate
 
-- Every prompt references handoff hash and technical design.
+- Every prompt links the handoff pack, state-file hash binding and technical design; no prose hash backfill is required. Task checkbox progress and test-report updates do not change the contract hash.
 - Every prompt includes TDD RED/GREEN plan.
 - Every L3/L4 test has executable command and evidence target.
 - Workers update only task-local docs.

package/assets/skills-en/superflow-pipeline/references/superpower-technical-design-template.md

@@ -11,7 +11,6 @@ semantics, tests, and acceptance gates.
 ---
 change: <change-id>
 status: draft|ready|final
-handoff_hash: <sha256>
 canonical_sources:
   - ../../openspec/changes/<change-id>/proposal.md
   - ../../openspec/changes/<change-id>/api.md
@@ -228,4 +227,4 @@ already-rounded money.
 - Do not invent API fields, DB columns, status semantics, fallback behavior, or
   acceptance criteria.
 - Keep unresolved source facts as blockers. Do not convert them to guesses.
-- Record the same `handoff_hash` as `.sdd/handoff/sdd-context.sha256`.
+- Link the handoff pack; `.sdd/state.yaml` owns the hash binding and must match `.sdd/handoff/sdd-context.sha256`. Do not copy raw hashes into this document.

package/assets/skills-en/superflow-pipeline/references/test-execution-template.md

@@ -1,5 +1,14 @@
 # Test Execution Template
 
+Use the environment frozen in tests.md; do not substitute local containers or
+mocks for an explicitly required shared development environment. When the user
+requires every endpoint to be exercised, freeze an endpoint/role/scenario matrix,
+reuse one healthy application instance and test accounts, and record redacted
+requests, response files, and expected versus actual database sets for every row.
+List missing, failed and blocked rows explicitly. Restart only when code,
+configuration or process health requires it, and record the reason. Future release
+environments must not become gates for a development-only delivery.
+
 ## Test Case
 
 - ID:

package/assets/skills-en/superflow-pipeline/scripts/superflow-guard.sh

@@ -309,11 +309,13 @@ require_hash_recorded() {
     issues+=("handoff hash file is empty")
     return 0
   }
-  if ! grep -Riq "$hash" \
-    "$CHANGE_DIR/design.md" "$CHANGE_DIR/sdd-quality-gate.md" \
-    "$CHANGE_DIR/test-report.md" "$CHANGE_DIR/prompt" 2>/dev/null; then
-    issues+=("handoff hash is not recorded in design, quality gate, prompt, or test-report")
-  fi
+  # The state file is the machine-readable binding point.  Requiring the raw
+  # hash inside prose documents turned every refresh into a four-file manual
+  # backfill loop that blocked real delivery work, so a human-readable pointer
+  # is enough here.
+  local binding
+  binding="$(state_get handoff_hash)"
+  [[ "$binding" == "$hash" ]] || issues+=("state handoff_hash does not match handoff pack; run superflow-handoff.sh --refresh")
 }
 
 change_has_field_status_risk() {

package/assets/skills-en/superflow-pipeline/scripts/superflow-handoff.sh

@@ -21,14 +21,26 @@ sha_file() {
   # Ignore generated state/hash marker lines so recording the handoff hash in
   # SDD docs does not change the handoff hash itself.
   if command -v sha256sum >/dev/null 2>&1; then
-    sed -E '/handoff_hash/d;/context_hash/d;/sdd-context\.sha256/d;/[a-f0-9]{64}/d;/pending/d;/^[[:space:]]*$/d' "$1" \
+    canonical_contract "$1" \
       | sha256sum | awk '{print $1}'
   else
-    sed -E '/handoff_hash/d;/context_hash/d;/sdd-context\.sha256/d;/[a-f0-9]{64}/d;/pending/d;/^[[:space:]]*$/d' "$1" \
+    canonical_contract "$1" \
       | shasum -a 256 | awk '{print $1}'
   fi
 }
 
+canonical_contract() {
+  # Reports are execution evidence, not frozen requirements. Their existence
+  # and validity are checked separately by the delivery/report gates.
+  if [[ "${1##*/}" == "test-report.md" ]]; then
+    return 0
+  fi
+  sed -E \
+    -e '/^[[:space:]]*(handoff_hash|context_hash):[[:space:]]*[^[:space:]]*[[:space:]]*$/d' \
+    -e 's/^([[:space:]]*[-*][[:space:]]+)\[[xX ]\]/\1[ ]/' \
+    -e '/^[[:space:]]*$/d' "$1"
+}
+
 json_escape() {
   sed 's/\\/\\\\/g; s/"/\\"/g'
 }
@@ -144,6 +156,7 @@ fi
 context_hash_input=""
 while IFS= read -r file; do
   rel="${file#"$CHANGE_DIR"/}"
+  [[ "${file##*/}" == "test-report.md" ]] && continue
   hash="$(sha_file "$file")"
   context_hash_input+="${rel}:${hash}"$'\n'
 done < "$TMP_LIST"

package/assets/skills-en/superflow-requirement-review/SKILL.md

@@ -5,6 +5,11 @@ description: Perform source-backed reverse review of clarified requirements and
 
 # Superflow Requirement Review
 
+Read and apply [requirement × real-entry review](../superflow-pipeline/references/document-review-coverage.md).
+Build an independent checklist from original requirements, not FIX tasks. Review every entry
+per requirement dimension, especially EXCLUDED, VERIFY_EXISTING and unchanged paths.
+Never silently turn a user-authorized action into a rejection.
+
 Independently challenge the current OpenSpec change with source-backed evidence. This is not
 an advisory side path: blocking findings must repair canonical documents and pass re-review
 before the docs phase can close.

package/assets/skills-en/superflow-verify/SKILL.md

@@ -5,6 +5,11 @@ description: Use when an OpenSpec/SDD change is ready for verification, real evi
 
 # SDD Verify
 
+For full workflow acceptance, read [requirement × real-entry review](../superflow-pipeline/references/document-review-coverage.md).
+Reuse R/E/C IDs in the existing test-report with actual actors, page actions, request routes,
+final state and forbidden-effect evidence. Independently compare originals and actual callers;
+API-only is not browser E2E, and planned cases are not execution evidence.
+
 Verification is a phase, not a final sentence. Use this skill after
 implementation work claims completion and before archive or delivery.