@chenmk/superflow 0.4.0 → 0.5.1

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

@@ -64,12 +64,30 @@ For complex requirements, verify these before writing docs:
   checks when source is insufficient. Graph output or chat explanation alone is
   not sufficient. If this evidence is missing and the relationship affects
   design, stop and return to `$superflow-clarify`.
+- For full-workflow existing-system changes, `source-code-audit.md` must contain
+  the source fact freeze card, current/legacy/unmounted/data-model-only/
+  owner-confirmed/blocked classifications, all writers and real callers, DB
+  evidence or a skip reason, and the owner decision boundary. `List`,
+  `orderIds`, `batchInsert`, or one-to-many schema signals that conflict with a
+  single-item real entry require an explicit conflict audit. Missing evidence
+  blocks docs even when understand-anything contains a plausible summary.
 - For any database-backed design, the docs include table-to-code reverse impact
   evidence: every affected table/field, all writers/readers/filters, sibling
   repo or third-party consumers, real user-facing endpoints, reverse-state
   scenarios, and validation cases. If the docs only describe the write/sync
   path and do not prove consumers, stop and return to `$superflow-clarify`. Use
   `$superflow-table-impact-analysis` when available.
+- For any schema, index, constraint, seed-data, or historical-data change,
+  docs MUST create `release-sql.md` during the contract-design phase, before
+  `$superflow-design` or implementation prompts. It must contain exactly one
+  complete executable `sql` block plus front matter:
+  `database_change: true`, exact `target_sql_path`, `copy_policy: verbatim`,
+  and normalized payload `sql_sha256`. Prechecks, DDL/DML, post-verification,
+  defaults, constraints, indexes, and migration semantics must be frozen here.
+  `design.md`, `tasks.md`, and `sdd-quality-gate.md` must reference it and state
+  that implementation agents may only copy it verbatim. A placeholder path,
+  missing hash, SQL fragment, or instruction to design/append SQL later blocks
+  docs completion.
 - For any status, enum, sync, derived, default, or compatibility behavior, the
   docs include business semantic evidence:
   `真源字段 | 真源枚举 | 目标字段 | 目标枚举 | 消费方解释 | 业务依据 | 不确定项`.
@@ -112,6 +130,13 @@ Binding` with:
   chain, no-fallback/no-guessing boundary, and pre-coding agent self-check. If
   any gate is missing from `design.md`, `tests.md`, or quality gate, stop and
   complete the docs first.
+- Low-freedom means the Executor has no unresolved implementation or test-design
+  choice. `design.md` names reusable modules, exact change points, call/data flow,
+  transaction and concurrency boundaries, error behavior, and implementation
+  order. `tests.md` names environment, fixtures, startup command, steps,
+  automation command, response/DB/log assertions, cleanup, and evidence paths.
+  If two materially different implementations or acceptance paths remain valid,
+  return to clarification/design instead of delegating the choice to development.
 - For full workflow changes, `design.md` must include `复杂度减法评审` before
   docs freeze. Inventory every proposed table, field, API, Service/component,
   cache, async/MQ/event flow, scheduled job, compatibility layer, and new
@@ -123,6 +148,30 @@ Binding` with:
   `PASS` or `BLOCKED`; only `PASS` may leave docs/design. Missing reuse evidence, unexplained parallel APIs/models,
   redundant persisted fields, speculative cache/async/compensation, or an
   unresolved simpler option blocks docs completion.
+- After a reviewable full-workflow contract draft exists, run
+  `$superflow-requirement-review` before docs guard completion. It must create
+  `requirement-review.md`, repair canonical documents for every confirmed
+  `BLOCKER/IMPORTANT` finding, and re-review from source evidence. Record its
+  verdict and unresolved findings in `sdd-quality-gate.md` and `test-report.md`.
+  Source-resolvable unknowns must be investigated, owner decisions must return to
+  clarification, and implementation-affecting external contracts must be evidenced and frozen.
+  Merely documenting or assigning a blocker does not close it. A missing report, non-READY
+  implementation verdict, or nonzero blocker count prevents transition to design.
+- 完整 workflow 在交给开发前，必须针对当前 handoff hash 完成三轮独立评审：
+  `source-contract`、`architecture-minimality`、`e2e-environment`，并写入
+  `.sdd/reviews/document-review.json`。可自行调查的问题继续修订；只把业务 owner、
+  不可获得的权限/凭据和外部资源集中到最后一次澄清。
+- 按配置文件探索本地/开发/测试环境，把失败安全检查写入
+  `.sdd/readiness/environment.json`，并用 v2 `executionContract` 唯一冻结应用位置、依赖
+  策略、配置来源和允许/禁止覆盖项。`tests.md` 必须使用已验证的启动命令、端口、模拟器和
+  依赖；不能把环境探索留给开发 Agent，也不能只用“地址可连接”代替环境合同。
+- 跨仓、跨服务、设备、MQ、回调、状态机或三个以上模块的复杂逻辑必须提供 Mermaid
+  `sequenceDiagram` 与 `flowchart`/`stateDiagram`。
+- 实现 Prompt 完成后必须通过 `superflow check <change> --level coding-ready`，生成与
+  当前 handoff hash 绑定的 Coding Ready 凭证；失败的 implement 门禁不能转交开发 Agent。
+- 跨系统明确失败且上游拥有退款/撤单补偿时，默认快速失败、失败关闭、至多一次和调用方
+  补偿；禁止下游透明重试、改投或补发。额外兜底必须在“跨系统失败归属与补偿边界”中
+  获得 owner 确认。
 - `design.md` stays the OpenSpec/SDD design contract: requirement mapping,
   API/DB/field semantics, source facts, real-entry call chain, no-fallback
   boundary, risks, and acceptance hooks. It must not try to own all source-level
@@ -183,12 +232,19 @@ applicable:
 - `specs/<capability>/spec.md`
 - `design.md`
 - `tasks.md`
+- `tasks.md` 每个 checkbox 必须带且只带一个机器分类：`[local_required]`、
+  `[environment_required]` 或 `[release_required]`。能够在本地完成的编码、测试、启动和浏览器
+  验证必须是 local_required；不得用自由文本 Blocker/owner 代替分类。
 - `tests.md`
 - `test-report.md` skeleton
 - `sdd-quality-gate.md`
 - `traceability-matrix.md` when tasks are split
 - `mock.md` when external dependencies exist
 - `review-checklist.md` when implementation will be split
+- `requirement-review.md` for full-workflow changes before docs completion
+- `source-code-audit.md` for full existing-system, DB, cross-repo, or real-entry changes
+- `release-sql.md` for every database change; omit it only when the docs prove
+  that no schema/data migration is required
 - `.sdd/state.yaml`
 - `.sdd/handoff/sdd-context.md`
 - `.sdd/handoff/sdd-context.json`
@@ -305,8 +361,23 @@ DB 状态 | 结算/通知/展示消费点 | 真实验证方式`.
 - `tests.md` is a pre-implementation contract. It must not be a vague checklist.
   Every case must include:
   `用例ID | 需求/Scenario | 层级L1/L2/L3/L4 | 前置数据 | 操作步骤 |
-自动化命令 | 响应断言 | DB断言 | 日志断言 | RED预期失败 | GREEN预期通过 |
-test-report证据位置`.
+  自动化命令 | 响应断言 | DB断言 | 日志断言 | RED预期失败 | GREEN预期通过 |
+  test-report证据位置`.
+- 对 L3/L4 的输入校验、协议拒绝或异常分支，`tests.md` 还必须冻结真实注入载荷及其到达
+  目标解析/校验分支的证据；仅断言同一个 HTTP 状态码不算覆盖。原始畸形 JSON、错误
+  Content-Type、越权身份或非法字段必须按真实线协议发送，并同时断言无副作用。
+- 当任务新增或复制本地进程、容器或临时资源的 owner/清理原语时，`design.md`、`tests.md`
+  与 `test-report.md` 必须冻结资源身份字段、生产方与消费方的相等关系及每个不匹配时拒绝
+  清理的用例（例如 nonce、PID、端口、进程签名）。复用未改动的认证 owner helper 时，
+  只记录其完整性、任务参数、一次失败清理和最终零残留，不重复写成框架认证。
+- When a design uses a version field for optimistic locking, `design.md` must
+  freeze the database-level atomic compare-and-set boundary, conflict response,
+  and zero-row distinction between missing data and stale version. A
+  read-then-write check alone is blocked. `tests.md` must include two concurrent
+  requests holding the same old version and assert exactly one success, one
+  conflict, and one version increment. The implementation prompt only inherits
+  these frozen case IDs and commands; managed orchestration must not invent the
+  business design later.
 - Each visible UI field, button action, list column, dropdown, and enum must map to API/DTO/DB/tests or be explicitly out of scope.
 - Every spec scenario must have at least one test case.
 - Every implementation batch must have at least one test that can fail before
@@ -340,6 +411,26 @@ test-report证据位置`.
   `RED 失败证据`, `GREEN 通过证据`, `接口自动化证据`, `DB 核查证据`,
   `日志核查证据`, `未自动化/阻塞用例`, and `Partially verified 边界`.
   Each section must reference concrete `tests.md` case IDs.
+- `tests.md` must freeze runtime-specific acceptance instead of leaving it to
+  managed orchestration:
+  - Spring Boot/backend services: verified startup command, dynamic or planned
+    isolated port, readiness condition, at least one real HTTP invocation, and
+    failure evidence when the environment blocks startup.
+  - `.vue/.tsx/.jsx`, frontend API registration, page permission, or visible UI
+    behavior: frontend startup plus real-browser Playwright/Cypress cases and
+    page assertions; build, static inspection, and mocks are supplementary only.
+  - Controller/API DTO plus frontend request changes: backend Controller contract,
+    frontend request contract, and dynamic API export/call-resolution snapshot
+    when applicable.
+  - Named runtime backends such as MySQL, Testcontainers, a real browser, or a
+    real service: exact backend and command; H2, mocks, stubs, in-memory stores,
+    and compatibility modes never close the named gate.
+  - Multi-repository/service changes: build/runtime checks for every affected
+    repository plus the real cross-repository path; one repository's evidence
+    never substitutes for another.
+  `design.md` records why each runtime and repository is in scope; `tasks.md`
+  classifies local, environment, and release work; the implementation prompt
+  inherits the exact case IDs, commands, assertions, and evidence paths.
 - For money-related changes, `test-report.md` must also include `Money Precision
   Boundary` evidence: original calculation inputs and precision, actual rounding
   boundary and mode, half-cent/residual/multi-detail cases, and reconciliation

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

@@ -7,38 +7,82 @@ description: SDD 总入口和路由技能。Use when the user says sdd, SDD 流
 
 This is the lightweight SDD router. Do not load the whole SDD process when a smaller phase skill is enough.
 
+维护 Superflow CLI 自身时，必须先读取仓库根目录
+`docs/superflow-cli-design-principles.md` 和
+`docs/superflow-cli-evaluation-framework.md`；涉及托管时再读取托管专项宪章与协议。
+先判定责任层，再修改并按统一评价体系留下基线、假设、实例、结果和回滚条件。
+
 ## 托管任务与双 Agent 闭环
 
+主 Agent 已安装 Superflow MCP 时，优先使用
+`superflow_managed_start/status/wait/message/submit_review`，不要再从聊天中手工启动
+`superflow pipeline` 子进程。MCP 任务固定为 `external_host`：当前主 Agent 与用户保持对话并
+直接评审，后台只启动对端研发 Agent，禁止嵌套 Supervisor CLI。等待进度必须调用
+`superflow_managed_wait` 在本地阻塞，不得用模型回合定时查询。MCP 不可用时才使用下面的
+CLI 等价流程。
+创建任务前先调用 `superflow_managed_runtime`。若运行时指纹过期，必须要求重启当前 Host，
+禁止用安装前的旧 MCP 进程启动新验证任务。
+
 当用户说“用 Superflow 托管完成”并给出 implementation prompt、change 目录或一个简单
 任务时，直接使用内建托管模式。不要要求用户说出 `superflow-pipeline`、角色参数或底层
 CLI 命令：
 
+启动前先做一次 Host 语义分流：用户只要求文档时，完成文档自主评审和 Coding Ready 后
+停止，不创建托管 Task；已有用户评审通过的 change/Prompt 时原路径冻结；只有边界清晰的
+口头小需求才直接进入 minimal/standard。若口头需求存在会改变实现方向的 API、数据、
+并发、跨仓或 owner 决策，先进入澄清/文档流程，不能把这一判断交给 Runner 正则或 Executor。
+
 ```bash
 superflow pipeline "<implementation-prompt 路径、change 目录或简单任务>" --managed --project "<项目根目录>" \
-  --supervisor codex --executor claude --language zh
+  --supervisor current --executor peer --language zh
 ```
 
-当前入口是 Claude 时交换两个角色。命令默认由独立后台服务执行，同时监听本地任务账本
-直到终态，再由当前 Agent 读取报告并在同一会话汇总。监听中断不影响后台任务。执行前
-必须阅读 `references/managed-work.md`，不得直接手工递归启动 peer CLI。
+`current/peer` 会自动识别当前 Host：Codex Host 驱动 Claude，Claude Host 驱动 Codex；
+识别不明确时失败关闭并要求显式指定。后台只调用执行 Agent；当前 Host Agent 直接完成只读
+评审，不得再启动同名嵌套 CLI。执行者返回后，读取 `host-review-N.md`，把结构化评审写入
+JSON，再用 `--resume-task <task-id> --submit-host-review <json>` 恢复。监听中断不影响后台
+任务。执行前必须阅读 `references/managed-work.md`，不得手工递归启动 peer CLI。
+
+托管目标是用相对低成本的研发 Agent 承担实现与验证，让高成本主 Agent 只负责目标冻结、
+监督和交付质量评审。主 Agent 不参与编码、构建、启动、测试或进程管理。收到
+`external_supervisor_review_required` 后必须在当前回合自动评审、提交结果并继续等待；
+不得停下来等待用户人工接力。只有业务 owner 决策、不可获得的外部权限或最终 Git 批准
+可以中断用户。
 
 硬规则：
 
-- 每个任务固定监督会话和执行会话，后续轮次按明确 session ID 恢复。
+- 每次执行与整改都创建短会话，以当前工作区、冻结 Prompt、落盘结果和 finding 交接；
+  禁止无限恢复长会话。旧 session ID 只用于审计。
+- 第一轮必须自动下发冻结的任务 Prompt；后续每轮必须先生成并完整读取压缩交接包，至少
+  包含 Prompt 路径与哈希、任务完成度、本地剩余项、外部前置、当前全部 finding、差异统计
+  和最近报告。旧会话或新会话接手都以交接包和当前工作区为准。
+- `external_host` 模式由当前 Agent 评审，后台不得启动第二个 Codex/Claude CLI。
+- MCP Host 的对话和评审不计后台 Agent 调用；只有真实研发 Agent 调用进入执行预算。
 - 任务合同、事件账本、检查结果和证据文件是事实源，不依赖聊天上下文。
 - 正式检查最多 5 轮、执行最多 7 次、Agent 总调用最多 12 次。
 - 每次启动和恢复都校验冻结合同与硬上限；工程任务只有一类验证证据时不得进入检查。
 - 输入是 change 目录时必须从 `.sdd/state.yaml` 解析 `implementation_prompt`；输入是
   `tasks.md` 时必须阻塞。执行前冻结 Prompt 快照和 SHA-256，两个 Agent 使用同一快照。
 - 监督角色只读，执行角色禁止修改 `.superflow/tasks` 和自动 Git 提交/推送/发布。
-- 最终通过后状态必须停在 `awaiting_git_approval`，当前主 Agent 汇总并获得用户批准后
-  才能提交 Git。
-- 使用 `superflow status <project-root>` 查看状态；不得通过模型轮询询问进度。
+- 冻结需求、设计、Prompt、handoff、规则和任务事实属于 immutable 受保护输入；tasks 与
+  test-report 属于 retain 进度证据，可回填但不可删除。runtime 和 workspace-temporary 由
+  Executor 清理，delivery-artifacts 和 protected-contracts 必须保留到 Host 评审。
+- 禁止 pkill、killall、裸 kill、只按端口/进程名清理和未经 owner helper 校验的 rm -rf；
+  原生 Hook 写入前阻断，preflight/最终门禁对所有 Host 复核。
+- 最终通过后按三套进度进入 `environment_validation_blocked`、`local_delivery_ready` 或
+  `release_ready`；任何状态都必须获得用户批准后才能提交 Git。
+- 使用 MCP 等待时默认采用 240 秒 Host 兼容传输窗口；窗口超时后只用返回的
+  `latestSequence` 立即续接，不调用 status、不读取完整事件、不重启 Executor。支持长工具
+  调用的 Host 可显式提高到 12 小时；仅 attention 状态执行语义监督。
+- 用户指定任务 Prompt 文档时必须把原路径传给 start 并核对冻结 SHA-256，禁止用主 Agent 摘要替代。
+- 页面/权限变更必须启动前端并执行真实浏览器 E2E；跨端 API 变更必须执行前后端合同测试。
 - 运行产物完整性必须通过 `superflow-managed-work-check.mjs`。
 - 只有完整性脚本先通过，状态机才能记录唯一的交付就绪事件。
 - 托管命令返回终态后，当前 Agent 必须读取任务报告并向用户汇总；不能只报告任务编号。
 - 语言必须冻结进任务合同；执行 Prompt、恢复轮次、进度账本、任务报告、通知和错误提示
   必须继承合同语言，不能在中途切换。
+- Claude Executor 长会话默认提前自动压缩，显式用户环境值优先；压缩后重读冻结 Prompt 和
+  handoff。最终 `result.usage` 是权威调用用量，不得仅凭数值大就判断 Runner 重复累计。
 
 ## Choose The Right SDD Skill
 
@@ -52,6 +96,10 @@ superflow pipeline "<implementation-prompt 路径、change 目录或简单任务
   remember.
 - Use `$superflow-clarify` only when product inputs are complex and must be frozen one
   feature at a time before creating OpenSpec artifacts.
+- Use `$superflow-requirement-review` when the user asks for 需求评审、反向评审、
+  挑战需求、找遗漏、查错误、可测性审查、过度设计检查，或要求确认现有
+  OpenSpec/SDD 设计有没有走偏。它在 docs 内形成独立复审闭环，不新增 workflow
+  phase；阻塞级发现必须修正 canonical 文档后复审。
 - Long PRDs, Lark/Feishu exports, screenshot-heavy requirements, and mixed
   product documents must not be converted into proposal/tasks in one pass.
   Route them through `$superflow-clarify` first. The clarify phase must create a
@@ -65,6 +113,11 @@ superflow pipeline "<implementation-prompt 路径、change 目录或简单任务
   output: API-first checks, UI/API/DB/test traceability, real-data test
   evidence, quality gates, and prompt handoff checks. Do not let `$superflow-docs`
   replace the OpenSpec skill workflow for core OpenSpec artifacts.
+- Full-workflow docs must run `$superflow-requirement-review` after a reviewable
+  contract draft exists and before docs guard completion. Record the result in
+  `requirement-review.md`; unresolved source investigations, owner decisions,
+  implementation-affecting external contracts, or `BLOCKER/IMPORTANT` findings block design.
+  A blocker is not closed merely because the docs name it or defer it to integration.
 - Use `$superflow-design` after `$superflow-docs` passes when full workflow needs
   Superpowers source-level HOW, technical design, reverse impact analysis,
   TDD/RED strategy, Worker/Tester/Reviewer split, or worktree/port planning.
@@ -113,6 +166,19 @@ When the router selects embedded deep clarification, follow these rules inside
 
 ## Non-Negotiable Rules
 
+### 源码事实冻结与提问资格（阻塞级）
+
+- full workflow 涉及现有行为、DB/表关系、跨仓或真实入口时，docs 阶段必须生成
+  `source-code-audit.md`，并填写：
+  `业务结论 | understand定位 | 数据模型 | 所有写入方 | 真实用户入口 |
+当前调用方 | 遗留冲突 | DB是否必查 | 结论等级 | owner决策`。
+- understand-anything 只作 locator，不作最终事实源。证据必须区分 `current`、
+  `legacy`、`unmounted`、`data-model-only`、`owner-confirmed`、`blocked`。
+- `List`、`orderIds`、`batchInsert` 或一对多模型与单笔真实入口冲突时，必须完成
+  冲突审计；不能从数据结构反推当前产品行为。
+- 提问前必须完成源码、Mapper/SQL、前端/小程序/H5 调用方、sibling repo 和
+  必要的只读 DB 核查。仓库可查事实不得作为澄清题交给用户。
+
 ### OpenSpec change 目录唯一性（阻塞级）
 
 - Superflow 必须遵守 OpenSpec CLI 的单层目录规范：
@@ -317,6 +383,7 @@ context_compression | created_at | verified_at | updated_at`
 `traceability-matrix.md` 里留一条链接就进入实现。
 
 **任务本地必备文件：**
+
 - `.openspec.yaml`
 - `proposal.md`，说明背景、目标、非目标、影响范围、验收标准
 - `bug-fix-plan.md`，仅 bug fix / incident / report-driven 修复必备
@@ -332,6 +399,7 @@ context_compression | created_at | verified_at | updated_at`
 - `prompt/<p-or-cr-task-name>.md`
 
 **根级挂接必备：**
+
 - 根级 `tasks.md` 必须链接任务目录、任务 prompt、`api.md`、`tests.md`、
   `test-report.md`。
 - 根级 `tests.md` 必须挂入任务用例 ID、自动化命令、DB/log 断言和真实入口。
@@ -343,6 +411,7 @@ context_compression | created_at | verified_at | updated_at`
   prompt。
 
 **阻塞规则：**
+
 - 缺任一任务本地必备文件，阻塞生成实现 prompt 或进入编码。
 - 只有根级 prompt、没有任务本地 `prompt/`，阻塞。
 - 只有根级 traceability、没有任务本地 `traceability-matrix.md`，阻塞。
@@ -358,6 +427,7 @@ locator / 代码地图 / 影响面初筛工具，不能作为设计事实源，
 Mapper/XML、数据库样例、接口契约和真实消费入口验证。
 
 **影响面发现方式（优先但可降级）：**
+
 - 优先检查当前仓库是否存在 understand-anything 相关索引/产物，例如
   `.understand-anything/`、`understand-anything.md`、`understand anything.md`、
   或项目约定的 understand-anything 图谱文件。
@@ -374,6 +444,7 @@ Mapper/XML、数据库样例、接口契约和真实消费入口验证。
   跨仓数据合同门禁和真实集成测试门禁。
 
 **阻塞规则：**
+
 - 没有任何平台级影响面发现证据，只阅读当前文件、当前 Service、当前接口，阻塞。
 - 只阅读当前文件、当前 Service、当前接口，不分析平台级调用和消费方，阻塞。
 - 把 understand-anything 图谱、聊天解释或旧索引当成最终事实源，未回读当前源码、
@@ -425,6 +496,7 @@ Mapper/XML、数据库样例、接口契约和真实消费入口验证。
 本节规则执行并在交付中说明降级原因。
 
 **触发条件（任一满足即触发）：**
+
 - 新增/修改表、字段、索引、枚举、默认值、初始化数据或同步规则。
 - 引入状态字段，例如 `running_status`、`connector_status`、`own_status`、
   `is_online`、`is_use`、`deleted/is_deleted`。
@@ -432,6 +504,7 @@ Mapper/XML、数据库样例、接口契约和真实消费入口验证。
   第三方适配器或启动/扫码/支付/退款等业务入口间接使用。
 
 **强制反查步骤：**
+
 1. 以每张表和字段为 key 反查全部引用。understand-anything 可用时作为定位工具；
    不可用或不可信时，必须用 `rg`、Mapper/XML、实体注解、SQL、DTO、枚举、
    日志模板、配置和 sibling repo 搜索完成反查。
@@ -445,6 +518,7 @@ Mapper/XML、数据库样例、接口契约和真实消费入口验证。
    任务本身成功。
 
 **阻塞规则：**
+
 - 只证明“同步任务执行成功”，没有证明消费该表的真实入口通过，阻塞。
 - 只看写入方，不反查读取/过滤/启动前校验/扫码/小程序入口，阻塞。
 - 状态字段只测置为不可用，不测恢复可用和旧值清理，阻塞。
@@ -458,6 +532,7 @@ SDD 设计、评审、实现 prompt 和测试报告中，字段/状态/枚举/
 当作正确结果。
 
 **强制设计要求：**
+
 - 对每个状态字段、枚举字段、同步字段，必须写清：
   `真源字段 | 真源枚举 | 目标字段 | 目标枚举 | 消费方解释 | 业务依据 | 不确定项`。
 - 如果上下游字段名相似、数值相同或看起来可转换，仍必须回到源码、数据库样例、
@@ -471,6 +546,7 @@ SDD 设计、评审、实现 prompt 和测试报告中，字段/状态/枚举/
   不能只断言字段存在、非空、接口 200 或同步任务成功。
 
 **阻塞规则：**
+
 - 只写默认值/兜底值，没有业务依据和 owner 确认，阻塞。
 - 用“有值”的字段替代真实业务真源，例如用枪口状态替代桩运行状态，阻塞。
 - 只验证返回有值或链路成功，不验证值是否符合消费方业务语义，阻塞。
@@ -509,6 +585,7 @@ prompt、代码评审、测试到 verify 继承同一份 `Money Precision Bounda
 证据锚点 | 禁止用法 | 不确定项/owner`
 
 要求：
+
 - 不能用字段名相似、类型相同、值非空来判断两个字段等价。
 - 像 `{externalDeviceId}`、`{siteId}`、`{portId}`、`{tenantId}`、
   `{businessId}`、`{contractId}`、`{benefitType}` 这类字段，
@@ -524,6 +601,7 @@ prompt、代码评审、测试到 verify 继承同一份 `Money Precision Bounda
 DB column | 后续读取方 | 消费入口 | 验证 SQL | 测试用例`
 
 要求：
+
 - 只看到 Java setter 不等于已落库；必须核对 Mapper XML、注解 SQL、BaseMapper、
   resultMap 和条件更新。
 - 成组字段必须作为一个合同验证，例如业务绑定三元组
@@ -538,6 +616,7 @@ DB column | 后续读取方 | 消费入口 | 验证 SQL | 测试用例`
 DB 状态 | 结算/通知/展示消费点 | 真实验证方式`
 
 要求：
+
 - 不能只写 Service 方法或工具类；必须写到 Controller/RPC/MQ/定时任务/设备/小程序/
   第三方真实入口。
 - 同一能力存在多条路径时必须拆开，例如用户入口、后台操作、外部集成、MQ 补偿。
@@ -566,16 +645,69 @@ DB 状态 | 结算/通知/展示消费点 | 真实验证方式`
 
 任一项未填、填“不确定”但继续编码、或未记录证据，均视为阻塞。
 
+### 文档可交付性自主闭环（阻塞级）
+
+完整 workflow 的文档 Agent 不能把“guard 退出 0”当成“100% 可实施”。交付开发前必须
+基于同一份当前 handoff hash 完成至少三轮独立视角评审，并把机器可验证的结果写入
+`.sdd/reviews/document-review.json`：
+
+1. `source-contract`：核对源码、跨仓调用方、字段/API/状态合同和真实入口；
+2. `architecture-minimality`：核对职责边界、复用、最小实现、失败归属和过度设计；
+3. `e2e-environment`：核对启动顺序、配置环境、模拟器、自动化命令、DB/日志断言和清理。
+
+每轮必须记录 `inputHash`、`lens`、完整 findings 和关闭状态。能够从源码、配置、日志或
+安全探测获得的事实必须由 Agent 自行调查和修订；只有业务 owner 决策、不可获得的凭据/
+权限或外部资源才能写入 `openOwnerDecisions`。问题必须集中收集到最后一次询问，禁止逐个
+打断用户。存在未关闭 finding 或 owner decision 时只能标记 `BLOCKED_FOR_OWNER_BATCH`，
+不得宣称 100%。
+
+测试环境必须在文档阶段按配置文件优先探索，并写入
+`.sdd/readiness/environment.json`。只允许 `file`、`directory`、`executable`、`tcp`、
+`http` 等失败安全探测；不得输出凭据或向生产写数据。每项状态只能是 `READY`、
+`LOCAL_FIXTURE_READY`、`OWNER_HELP_REQUIRED` 或 `BLOCKED`。环境合同约定本地/开发环境时，
+不得擅自要求测试或生产环境。报告必须使用 `superflow.environment-readiness.v2`，把应用
+运行位置、`local-isolated/shared-dev/shared-test/mixed` 依赖策略、配置来源、允许/禁止覆盖项
+和每项检查的 `contractRef` 冻结为唯一环境执行合同；不能只证明某个地址当前可连接。
+
+跨服务、跨仓、设备、MQ、回调、定时任务、状态机、补偿链路或三个以上模块的复杂逻辑，
+`.openspec.yaml` 必须声明 `complex_logic: true` 或 `mermaid: required`，设计文档至少包含
+一张 `sequenceDiagram` 和一张 `flowchart`/`stateDiagram`。图中必须展示失败出口、补偿
+owner 和明确禁止的 fallback。
+
+实现 Prompt 生成完成后执行：
+
+```bash
+superflow check <change> --level coding-ready
+```
+
+该命令必须通过 YAML、OpenSpec、docs/design/implement、全 Prompt 继承与精确交叉链接、
+多轮评审、环境预检和 Mermaid 检查，并生成与当前 handoff hash 绑定的
+`.sdd/readiness/coding-ready.json`。没有当前 Coding Ready 凭证时不得分发开发 Agent，
+也不得把完善 implement 门禁列为开发任务。
+
+### 跨系统失败归属与补偿边界（阻塞级）
+
+跨系统调用必须先记录：
+`失败信号 | 解释方 | 补偿方 | 是否允许重试 | 幂等依据 | 可接受的小窗口 |
+极端兜底 | owner确认`。
+
+当上游能够收到明确失败并负责退款、撤单或状态回退时，下游基础设施/适配层默认采用
+`Fail-fast + Fail-closed + At-most-once + Caller-owned compensation`：返回明确失败，
+不透明重试、不自动改投、不补发、不猜测成功。短暂误失败的代价低于重复副作用时，可以
+接受有边界的小并发窗口。只有业务 owner 明确要求且有幂等依据时才设计额外兜底；详设
+必须把这个例外与其他 owner-only 问题一起集中澄清，不能自行增加分布式补偿机制。
+
 ### 测试先行与接口自动化门禁（阻塞级）
 
 SDD 文档必须先冻结测试，再允许生成实现 prompt。研发 agent 不得先编码再临场补
 测试，也不得把人工随手调用、编译成功或接口 200 当作验收。
 
 **测试冻结要求：**
+
 - `tests.md` 必须为每个 spec scenario、API、状态/枚举分支、DB 写入闭环和真实
   消费入口生成可执行测试用例，包含：
   `用例ID | 层级L1/L2/L3/L4 | 前置数据 | 操作步骤 | 自动化命令 | 断言 |
-  RED预期失败 | GREEN预期通过 | DB核查 | 日志核查 | test-report证据位置`。
+RED预期失败 | GREEN预期通过 | DB核查 | 日志核查 | test-report证据位置`。
 - 涉及接口、CRUD、Mapper/XML、数据库字段、配置驱动行为或跨系统链路时，至少
   有一个 L3/L4 自动化接口用例。用例必须写出完整 Base URL、token/cookie 获取
   方式、curl/Postman/Newman/pytest/RestAssured 等可执行命令、请求体、响应断言、
@@ -590,6 +722,7 @@ SDD 文档必须先冻结测试，再允许生成实现 prompt。研发 agent
   不得把 mock-only 或跳过测试写成 Passed。
 
 **实现前阻塞规则：**
+
 - `tests.md` 没有可执行自动化命令，阻塞。
 - `test-report.md` 没有 Red-Green 证据占位和接口自动化证据表，阻塞。
 - prompt 未引用 `tests.md` 的具体用例 ID、自动化命令和 RED/GREEN 要求，阻塞。
@@ -685,6 +818,7 @@ SDD 文档必须先冻结测试，再允许生成实现 prompt。研发 agent
 6. 当前阶段未生成 prompt，且用户没有明确禁止生成 prompt
 
 **以上任一条件触发时，必须阻止进入开发阶段，并在输出中显式报告：**
+
 > ⚠️ Prompt 衔接检查未通过：P{xx} 缺少实现 prompt 或交叉挂接。必须先生成
 > `prompt/pXX-xxx.md` 并更新 `prompt/implementation.md`、`tasks.md`、
 > `traceability-matrix.md`、`tests.md`、`test-report.md`，不得只提醒后续生成。
@@ -713,12 +847,14 @@ starter、connector 或任何被当前项目引用的外部项目时，必须把
 不能只改本地源码或同版本 SNAPSHOT。
 
 **触发条件（任一满足即触发）：**
+
 - 修改 `*-api`、`*-sdk`、公共 jar、协议类、DTO、枚举、校验注解或序列化字段类型。
 - 修改 sibling repo 后，当前仓库通过 Maven/Gradle 依赖、RPC、HTTP SDK 或本地 jar 消费它。
 - 字段类型、方法签名、setter/getter、接口入参出参发生变化。
 - 需要先在另一个仓库 `mvn install/deploy`，当前仓库才能编译或运行。
 
 **强制要求：**
+
 - 在 `bug-fix-plan.md` / `design.md` / `tasks.md` / prompt 中写明：
   `引用项目 | 当前版本 | 目标版本 | 当前仓库依赖文件 | 发布/安装命令 | 验证命令`。
 - 修改被引用项目的协议/API 时，必须升级版本号，例如 `1.0.8-SNAPSHOT -> 1.0.9-SNAPSHOT`；
@@ -729,6 +865,7 @@ starter、connector 或任何被当前项目引用的外部项目时，必须把
 - 如果版本号由发布平台统一管理，必须把"由谁发布/发布到哪里/当前仓库如何引用"写成阻塞项。
 
 **阻塞规则：**
+
 - 被引用项目改了代码但未升级版本号，阻塞。
 - 当前仓库未更新依赖版本，阻塞。
 - 只在本机同版本 SNAPSHOT 覆盖安装，阻塞。
@@ -738,12 +875,27 @@ starter、connector 或任何被当前项目引用的外部项目时，必须把
 
 开发环境数据库结构与设计文档一致是业务代码正确运行的前提。历史上多次出现研发 agent 忘记执行增量 SQL，导致字段缺失、默认值缺失、初始化数据缺失，最终用业务代码绕过数据库问题，产生隐蔽 bug。以下规则必须严格执行：
 
+- **SQL 必须在合同详设阶段冻结**：只要需求涉及表、字段、索引、约束、初始化
+  数据或历史数据迁移，`$superflow-docs` 必须先生成 `release-sql.md`。文件必须包含
+  `database_change: true`、无占位符的精确 `target_sql_path`、
+  `copy_policy: verbatim`、归一化 SQL 正文的 `sql_sha256`，以及唯一一段完整可执行
+  `sql` 代码块。前置检查、DDL/DML、迁移、后置对账、默认值、约束和索引必须在
+  此阶段定稿。
+- **实现 Agent 只有复制权**：研发 prompt 必须引用 `release-sql.md`，把唯一 SQL
+  代码块原样复制到 `target_sql_path` 并核对 SHA-256。不得在实现阶段新增、删除、
+  重排、拆分或“优化”SQL；发现设计遗漏必须停止并退回 `$superflow-docs`，刷新
+  handoff 后再继续。
+- **禁止路径和 SQL 占位符**：`testN.sql`、`{version}.sql`、`待定路径`、伪 SQL、
+  只有字段表格而无完整脚本均不得通过 docs/design guard。
+
 #### 通用规则（所有涉及数据库的任务）
 
 - **写代码前必须先检查数据库**：研发 agent 在写任何业务代码前，必须先对照 design.md / api.md / spec.md / tasks.md 中涉及的表、字段、索引、默认值、枚举值、初始化数据，连接开发环境数据库执行 DESC / SHOW CREATE TABLE / SHOW COLUMNS / SELECT 等命令确认实际结构。
 - **发现缺失必须先执行 SQL**：如果数据库结构或数据不满足设计要求，研发 agent 必须先找到本需求的汇总 SQL 文件，连接开发环境数据库执行对应脚本，执行成功后再继续开发。
 - **禁止用代码绕过数据库缺失**：不得因为字段缺失、默认值缺失、初始化数据缺失而在业务代码里写绕过逻辑、兼容逻辑或假修复。根因是 SQL 未执行时，修复方向应是执行 SQL，不是改代码。
-- **只维护需求级汇总 SQL 文件**：同一个需求下所有新增表、改表、索引、默认值、初始化数据脚本，统一追加到该需求的汇总 SQL 文件（如 `sql/{version}.sql`），禁止各任务各自新建独立 SQL 文件。
+- **只落一个冻结目标 SQL 文件**：同一需求的表、字段、索引、默认值和初始化数据
+  必须已在 `release-sql.md` 合并冻结；实现 Agent 只能原样复制到唯一
+  `target_sql_path`，禁止各任务另建或追加 SQL。
 - **独立 P/CR 任务必须回写版本总 SQL**：开发库已有、局部 SQL 已执行、agent 回复里写过 SQL，都不等于交付完成。只要源码/Mapper 依赖了表结构或初始化数据，必须确认版本总 SQL 已包含对应变更。
 - **任务完成必须有 SQL 收口对账表**：涉及数据库的任务必须输出 `P编号 | 表 | 字段/索引/数据 | 源码引用 | 总SQL位置 | 开发库状态 | 测试库状态 | 处理结论`。没有该表不得标记完成。
 - **发布前必须做三方对账**：最终脚本必须对齐 `源码/Mapper 读写字段`、`开发库结构`、`测试库现状 + 版本总 SQL 执行后结构`。测试库已有字段不得重复 ADD；类型/注释不一致时生成 MODIFY 或写明不采纳理由。
@@ -756,6 +908,7 @@ starter、connector 或任何被当前项目引用的外部项目时，必须把
 同一张业务表被多个服务读取、复制实体、复用 Mapper 或通过外部集成/网关链路间接消费时，必须把表结构当作跨仓合同处理。单仓 SQL 执行成功不代表其他消费仓可运行。
 
 **触发条件（任一满足即触发）：**
+
 - 多仓共享同一数据库表、视图、字典或初始化数据
 - 一个仓库复制了另一个仓库的 PO/Entity/Mapper/DTO
 - MyBatis-Plus `@TableName` + `BaseMapper` 自动 SELECT 实体字段
@@ -764,6 +917,7 @@ starter、connector 或任何被当前项目引用的外部项目时，必须把
 - 真实链路入口在 A 服务，业务校验落在 B 服务或 sibling service
 
 **强制要求：**
+
 1. 指定表结构真源：明确本需求以哪个 SQL 文件、哪个库的 `SHOW CREATE TABLE`、哪个仓库模型作为最终合同。
 2. 列出全部消费仓：包括直接 CRUD 仓库、外部集成仓库、定时任务、回调服务、导入导出服务和测试端点。
 3. 对每个消费仓执行字段对账：`@TableName` 实体字段、`BaseMapper` 默认查询列、Mapper XML/resultMap、手写 SQL、查询条件必须逐项对照 `information_schema.columns` 或 `SHOW CREATE TABLE`。
@@ -773,6 +927,7 @@ starter、connector 或任何被当前项目引用的外部项目时，必须把
 7. test-report 必须记录跨仓对账表：`表 | 真源结构 | 消费仓 | 实体/Mapper/SQL 字段 | 实际库字段 | 处理结论 | 验证证据`。
 
 **阻塞规则：**
+
 - 任一消费仓存在实体映射不存在列、Mapper 查询不存在列、查询条件依赖已删除字段时，阻塞进入真实验收。
 - 只有主仓编译通过、主仓 SQL 执行成功、主仓接口通过，不能关闭跨仓数据合同任务。
 - 测试库缺字段时，必须先判断字段是否属于当前最终合同；如果不是最终合同字段，禁止补库绕过，必须修消费仓代码。
@@ -780,6 +935,7 @@ starter、connector 或任何被当前项目引用的外部项目时，必须把
 #### 数据库迁移类任务硬门禁（涉及以下任一条件时触发）
 
 **触发条件（任一满足即触发硬门禁）：**
+
 - 新增表
 - 删除字段
 - 物理删除旧字段
@@ -919,6 +1075,7 @@ Load only the reference needed for the current phase:
 - API contract: `references/api-design-template.md`
 - OpenSpec format: `references/openspec-format.md`
 - Document quality: `references/quality-standards.md`
+- Document delivery readiness: `references/document-readiness.md`
 - Quality gate: `references/quality-gate.md`
 - 金额精度算法基线：`references/money-precision-algorithms.md`
 - Batch prompt split: `references/batch-split-guide.md`

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

@@ -27,25 +27,32 @@
 - [api.md](../api.md)
 - [tests.md](../tests.md)
 - [prompt/implementation.md](implementation.md)
-- **本需求汇总 SQL 文件**：`../sql/{汇总SQL文件名}`（如不存在，说明本需求尚无数据库变更，但开始前仍需核查依赖表结构）
+- **冻结发布 SQL**：[release-sql.md](../release-sql.md)（数据库变更时必读；按
+  `target_sql_path` 原样复制并核对 `sql_sha256`）
 
 > Markdown 链接要求：本 prompt 中引用的其他 `.md` 交接文档必须使用相对路径
 > Markdown 链接，且能从当前 prompt 文件位置点击跳转；不要只写纯文本文件名。
 
 ## 数据库前置门禁（强制，在写任何代码前必须完成）
 
+SQL 已在详设阶段冻结。本批只有原样复制权：禁止新增、删除、重排、拆分或优化
+`release-sql.md` 的 SQL；发现遗漏必须停止并退回 `$superflow-docs`，刷新 handoff
+后才能继续。
+
 在修改业务代码前，必须先完成数据库结构核查，确保开发环境数据库与设计文档一致：
 
 1. **列出本批次依赖的表/字段/索引/默认值/初始化数据**：对照 design.md / api.md / spec.md / tasks.md 中涉及的数据库变更，列出本批次需要的全部数据库结构。
 2. **连接开发环境数据库执行核查**：对每个依赖的表执行 `SHOW CREATE TABLE` / `SHOW COLUMNS` / `SELECT` 确认实际结构。
-3. **发现缺失时执行汇总 SQL**：如果数据库结构或数据不满足设计要求，从本需求汇总 SQL 文件中找到对应脚本，连接开发环境数据库执行。
+3. **发现缺失时执行冻结 SQL**：如果数据库结构或数据不满足设计要求，把
+   `release-sql.md` 唯一 SQL 代码块原样复制到 `target_sql_path`，核对 SHA-256 后执行。
 4. **复查确认**：执行成功后再次查询确认结构/数据已生效。
 5. **只有数据库满足设计后，才能继续业务代码开发。**
-6. **完成前必须收口版本总 SQL**：本批新增/修改的表、字段、索引、默认值、初始化数据必须已合并进需求级汇总 SQL 文件，不能只存在于开发库、临时 SQL 或 agent 回复中。
+6. **完成前必须核对冻结 SQL**：目标版本文件必须与 `release-sql.md` 的归一化
+   SQL 正文哈希一致；实现阶段不得产生额外数据库变更。
 
 禁止：
 - 禁止为绕过数据库缺字段、缺默认值、缺初始化数据而修改业务逻辑。
-- 禁止自行创建独立 SQL 文件（所有 SQL 统一追加到需求级汇总 SQL 文件）。
+- 禁止自行设计或创建额外 SQL；只允许原样复制到已冻结的目标版本文件。
 - 禁止用 mock、单测通过或 BUILD SUCCESS 代替真实数据库结构核查。
 - SQL 脚本执行失败时必须停下来报告真实错误，不允许改业务代码绕过。
 - 禁止因为开发库已有字段就跳过总 SQL；测试/发布部署以版本总 SQL 为准。
@@ -56,11 +63,11 @@
 
 | P编号 | 表 | 字段/索引/数据 | 源码引用 | 总SQL位置 | 开发库状态 | 测试库状态 | 处理结论 |
 |---|---|---|---|---|---|---|---|
-| P{batch-id} | {table} | {column/index/data} | {class/mapper/method} | {sql file + line/comment block} | {已存在/缺失/差异} | {已存在/缺失/差异} | {补总SQL/MODIFY/不采纳说明} |
+| P{batch-id} | {table} | {column/index/data} | {class/mapper/method} | {target_sql_path + line/comment block} | {已存在/缺失/差异} | {已存在/缺失/差异} | {原样复制/退回docs/不采纳说明} |
 
 收口规则：
 - 源码/Mapper 会读写的字段，必须能在 `测试库当前结构 + 版本总 SQL 执行后结构` 中找到。
-- 开发库已有但总 SQL 缺失时，必须补总 SQL。
+- 开发库已有但冻结 SQL 缺失时，必须退回 docs 更新 `release-sql.md`、哈希和 handoff。
 - 测试库已有字段不得重复 `ADD COLUMN`；如果字段类型或注释与开发库不一致，生成 `MODIFY` 或写明不采纳理由。
 - 临时 SQL、单个 P 任务 SQL、开发库手工变更都不能替代版本总 SQL。
 
@@ -115,8 +122,8 @@
 
 **禁止事项：**
 - 禁止为绕过数据库缺字段、缺默认值、缺初始化数据、历史数据未迁移而修改业务逻辑
-- 禁止自行创建独立 SQL 文件。所有 SQL 脚本必须追加到需求级汇总 SQL 文件
-- 禁止把 SQL 写在临时说明里但不追加到需求汇总 SQL 文件
+- 禁止自行创建或追加 SQL。只能原样复制 `release-sql.md` 到冻结目标路径
+- 禁止把 SQL 写在临时说明或 Agent 回复里；遗漏必须退回 docs
 - 禁止用 mock、单测通过或 BUILD SUCCESS 代替真实数据库结构核查和数据迁移验证
 - SQL 脚本执行失败时，必须停下来报告真实错误，不允许改业务代码绕过
 - 禁止将本地迁移 SQL 提交到 Git（如项目约定不提交）
@@ -420,7 +427,8 @@ curl -s -c /tmp/cookies.txt -b /tmp/cookies.txt \
 **汇总 SQL 文件**：`openspec/changes/{change-id}/sql/{汇总SQL文件名}`
 
 - 本批次所有数据库变更脚本必须从该文件获取
-- 如果需要新增数据库变更，必须追加到该汇总 SQL 文件（按任务编号注释，如 `-- P16 业务字段补齐`）
+- 如果实现时发现需要新增数据库变更，必须停止并退回 docs 更新
+  `release-sql.md`、`sql_sha256` 和 handoff；研发 Agent 不得追加 SQL
 - SQL 脚本采用简单直接格式（ALTER TABLE / INSERT），不使用 INFORMATION_SCHEMA 判断、PREPARE/EXECUTE 等过度兼容脚本
 - 如果本批次不需要新增 SQL，写明"本批次不新增 SQL，但开始前仍需核查依赖表结构是否已满足设计"