@chenmk/superflow 0.4.0 → 0.5.1

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

@@ -0,0 +1,157 @@
+# 文档交付就绪合同
+
+## 适用性声明
+
+在 change 的 `.openspec.yaml` 中显式声明适用范围。关键词扫描只能提示风险，不能覆盖
+明确的适用性结论。
+
+```yaml
+schema: superflow/v1
+applicability:
+  cross_repo: true
+  complex_logic: true
+  mermaid: required
+  environment: required
+  database: false
+  external_config: false
+  concurrency: false
+  money: false
+```
+
+`money: false` 只表示本次不修改金额计算、舍入、分摊或财务展示，不允许借此绕过真实的
+金额改动。若源码影响面证明涉及金额，必须改为 `true` 并补齐金额合同。
+
+## 三轮评审凭证
+
+文件：`.sdd/reviews/document-review.json`
+
+```json
+{
+  "schemaVersion": "superflow.document-review.v1",
+  "handoffHash": "<当前 64 位 handoff hash>",
+  "verdict": "PASS",
+  "openOwnerDecisions": [],
+  "rounds": [
+    {
+      "round": 1,
+      "lens": "source-contract",
+      "inputHash": "<同一当前 handoff hash>",
+      "findings": []
+    },
+    {
+      "round": 2,
+      "lens": "architecture-minimality",
+      "inputHash": "<同一当前 handoff hash>",
+      "findings": []
+    },
+    {
+      "round": 3,
+      "lens": "e2e-environment",
+      "inputHash": "<同一当前 handoff hash>",
+      "findings": []
+    }
+  ]
+}
+```
+
+发现项不能直接删除。修复后保留记录并写 `"status": "closed"`、证据和关闭位置。所有轮次
+必须重新基于当前 hash 复核；旧 hash 的 PASS 无效。
+
+## 环境预检合同
+
+文件：`.sdd/readiness/environment.json`
+
+```json
+{
+  "schemaVersion": "superflow.environment-readiness.v2",
+  "handoffHash": "<当前 handoff hash>",
+  "scope": "local-dev",
+  "overall": "READY",
+  "ownerHelpRequired": [],
+  "executionContract": {
+    "applicationLocation": "local",
+    "dependencyPolicy": "shared-dev",
+    "allowLocalProvisioning": false,
+    "allowRemoteDevDependencies": true,
+    "allowedOverrides": ["server.port"],
+    "forbiddenOverrides": ["spring.datasource.url"],
+    "services": [
+      {
+        "id": "service-a",
+        "configSource": {
+          "type": "bundled-profile",
+          "ref": "application-prod.yml"
+        },
+        "startupCommandSource": "tests.md#启动命令"
+      }
+    ],
+    "dependencies": [
+      {
+        "id": "redis",
+        "kind": "redis",
+        "provisioning": "shared-dev",
+        "configSource": {
+          "type": "bundled-profile",
+          "ref": "application-prod.yml#spring.redis"
+        }
+      }
+    ]
+  },
+  "checks": [
+    {
+      "id": "service-config",
+      "type": "file",
+      "target": "../../../service-a/src/main/resources/application-prod.yml",
+      "contractRef": "service:service-a",
+      "status": "READY"
+    },
+    {
+      "id": "redis",
+      "type": "tcp",
+      "host": "redis.dev.internal",
+      "port": 6379,
+      "timeoutMs": 1500,
+      "contractRef": "dependency:redis",
+      "status": "READY"
+    }
+  ]
+}
+```
+
+可用检查类型：`file`、`directory`、`executable`、`tcp`、`http`。禁止在 URL 中嵌入
+用户名、密码或 Token。数据库、Redis、MQ 的写操作和生产调用不属于预检；需要真实数据
+时在测试合同中单独声明安全边界。
+
+`executionContract` 是唯一环境事实源，必须在交付开发前冻结：应用运行位置、依赖策略、
+能否自建本地依赖、能否连接共享开发依赖、允许/禁止覆盖的配置，以及每个服务和依赖的
+配置来源。`configSource.type` 只能为 `bundled-profile`、`external-file`、`environment`、
+`cli-override` 或 `generated-fixture`。`local-isolated`、`shared-dev`、`shared-test` 不能互相
+混用；确需混用时显式使用 `mixed`，并逐项声明 `provisioning`。每个服务和依赖必须至少由
+一项 `contractRef` 检查覆盖。旧版 v1 只证明目标可访问，不能作为 Coding Ready 凭证。
+
+## 复杂逻辑图
+
+当 `cross_repo` 或 `complex_logic` 为 `true`，至少提供：
+
+- `sequenceDiagram`：真实入口、模块顺序、成功和失败返回；
+- `flowchart` 或 `stateDiagram`：状态/分支、补偿 owner、禁止 fallback。
+
+## Coding Ready
+
+```bash
+superflow check <change> --level docs
+superflow check <change> --level coding-ready
+```
+
+第二条命令成功后生成 `.sdd/readiness/coding-ready.json`。任何 SDD 文档或 handoff hash
+变化都会让旧凭证失效。开发 Agent 只能接收当前凭证已通过的 change。
+
+## 跨系统失败归属
+
+详设必须填写：
+
+`失败信号 | 解释方 | 补偿方 | 是否允许重试 | 幂等依据 | 可接受的小窗口 |
+极端兜底 | owner确认`
+
+默认采用快速失败、失败关闭、至多一次和调用方补偿。只有 owner 明确要求并证明幂等时，
+才允许透明重试、改投、补发或新的分布式补偿。

package/assets/skills/superflow-pipeline/references/document-templates.md

@@ -70,21 +70,25 @@
 # Tasks: <功能名称>
 
 ## 需求级汇总 SQL 文件
-- 路径：`openspec/changes/{change-id}/sql/{汇总SQL文件名}`（如 `sql/{version}.sql`）
-- 所有新增表、改表、索引、默认值、初始化数据脚本统一追加到该文件
-- 禁止各任务各自新建独立 SQL 文件
+- 详设真源：`openspec/changes/{change-id}/release-sql.md`
+- front matter 必填：`database_change: true`、精确 `target_sql_path`、
+  `copy_policy: verbatim`、`sql_sha256`
+- `release-sql.md` 只允许一个 `sql` 代码块，必须在详设阶段包含完整可执行的前置
+  检查、DDL/DML、迁移和后置验证，不允许占位符或留给研发 Agent 补写
+- 研发任务只把该代码块原样复制到 `target_sql_path` 并核对 SHA-256；禁止自行
+  新建、追加、重排或改写 SQL。发现遗漏退回 `$superflow-docs`
 - 不需要 SQL 的任务也需写明"本任务不新增 SQL，但开始前仍需核查依赖表结构是否已满足设计"
 
 ## 1. Requirement A 实现
 - [ ] 1.1 修改 `FilePath.java`，在 `methodName()` 中增加 X 逻辑
   - 源码锚点：`FilePath.java:line-start-line-end`
   - 验收标准：调用 Y 接口后，Z 状态变为 W
-  - 依赖的汇总 SQL：`openspec/changes/{change-id}/sql/{文件名}` 第 XX-XX 行（或"本任务不新增 SQL，但开始前仍需核查依赖表结构"）
+  - 冻结 SQL：`release-sql.md` → `{target_sql_path}`，仅原样复制并核对 `sql_sha256`（或"本任务不新增 SQL，但开始前仍需核查依赖表结构"）
   - blocked by: 无
 - [ ] 1.2 修改 `FilePath2.java`，调整 `methodName2()` 返回值
   - 源码锚点：`FilePath2.java:line-start-line-end`
   - 验收标准：单元测试通过
-  - 依赖的汇总 SQL：`openspec/changes/{change-id}/sql/{文件名}` 第 XX-XX 行
+  - 冻结 SQL：`release-sql.md` → `{target_sql_path}`，仅原样复制并核对 `sql_sha256`
   - blocked by: 1.1
 ```
 

package/assets/skills/superflow-pipeline/references/feature-gated-workflow.md

@@ -14,6 +14,9 @@
 - 页面、原型和产品文档都没有的字段，不得进入 API 必填项；若后端需要，必须
   标记为后端默认、后端推导或待确认。
 - 后续联调发现的问题必须作为 CR/Px 追加任务新增 prompt，不得污染已执行 prompt。
+- 存量系统需求必须先完成 `source-code-audit.md` 源码事实冻结卡和提问资格门禁。
+  understand-anything 只定位；源码、Mapper/SQL、真实调用方和必要的只读 DB 才能
+  确认现行业务。数据模型与真实入口冲突时必须单列冲突审计。
 
 ## 2. 每个功能点的固定步骤
 
@@ -104,6 +107,17 @@
 - 冻结结论：已冻结，可生成 prompt / 不通过
 ```
 
+### `source-code-audit.md`
+
+记录源码事实冻结卡：
+
+| 业务结论 | understand定位 | 数据模型 | 所有写入方 | 真实用户入口 | 当前调用方 | 遗留冲突 | DB是否必查 | 结论等级 | owner决策 |
+|---|---|---|---|---|---|---|---|---|---|
+
+同时记录 `current/legacy/unmounted/data-model-only/owner-confirmed/blocked`
+证据分类、`List/orderIds/batchInsert/一对多` 冲突审计，以及源码、Mapper/SQL、
+前端/小程序/H5、sibling repo、DB 的提问资格检查。
+
 ## 4. API 先行规则
 
 - 涉及前后端联调时，正式 `api.md` 必须在编码 prompt 之前冻结。

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

@@ -13,6 +13,11 @@
 
 ## 核心原则（强制执行）
 
+涉及数据库变更时，SQL 已在 [release-sql.md](../release-sql.md) 详设阶段冻结。
+研发 Agent 只有原样复制权：按 front matter 的 `target_sql_path` 落盘，统一 LF 且
+保留一个结尾换行，核对 `sql_sha256`。禁止新增、删除、重排、拆分或优化 SQL；
+发现遗漏立即停止并退回 `$superflow-docs`，不得在本 prompt 内补设计。
+
 完成代码修改 ≠ 完成任务
 编译成功 ≠ 完成任务
 Worker 自测通过 ≠ 完成任务
@@ -425,10 +430,13 @@ done
 
 **强制执行步骤：**
 
-1. 阅读本需求汇总 SQL 文件：`../sql/{汇总SQL文件名}`。
+1. 阅读 [冻结发布 SQL](../release-sql.md)，核对精确 `target_sql_path`、
+   `copy_policy: verbatim` 和 `sql_sha256`。
 2. 对照 [design.md](../design.md) / [api.md](../api.md) / [spec.md](../spec.md) / [tasks.md](../tasks.md)，列出本批次所有任务依赖的表、字段、索引、默认值、初始化数据。
 3. 连接开发环境数据库，对每个依赖的表执行 `SHOW CREATE TABLE` / `SHOW COLUMNS` / `SELECT` 等命令确认实际结构。
-4. 如果发现缺失（字段不存在、默认值不对、索引缺失、初始化数据未插入），必须从汇总 SQL 文件中取对应脚本，连接开发环境数据库执行。
+4. 如果发现缺失（字段不存在、默认值不对、索引缺失、初始化数据未插入），只能
+   原样复制 `release-sql.md` 的唯一 SQL 代码块到目标版本文件并执行。冻结 SQL 本身
+   有遗漏时必须返回详设阶段，禁止研发 Agent 追加语句。
 
 ### 跨仓数据合同门禁（按需触发，阻塞级）
 
@@ -472,8 +480,9 @@ done
 **禁止事项：**
 
 - 禁止为绕过数据库缺字段、缺默认值、缺初始化数据而修改业务逻辑（如加 if-null 判断兼容缺失字段、用硬编码代替数据库默认值）。
-- 禁止自行创建独立 SQL 文件。所有 SQL 脚本必须追加到需求级汇总 SQL 文件。
-- 禁止把 SQL 写在临时说明里但不追加到需求汇总 SQL 文件。
+- 禁止自行设计或创建额外 SQL；只允许把 `release-sql.md` 原样复制到冻结目标路径。
+- 禁止把 SQL 写在临时说明、Agent 回复或独立任务文件中；任何变更先回写
+  `release-sql.md`、重算哈希并重新通过 docs/design guard。
 - 禁止用 mock、单测通过或 BUILD SUCCESS 代替真实数据库结构核查。
 - SQL 脚本执行失败时，必须停下来报告真实错误，不允许改业务代码绕过。
 - 禁止因为开发库已经存在字段就跳过总 SQL 收口；发布以版本总 SQL 为准。
@@ -484,7 +493,7 @@ done
 版本总 SQL 收口对账：
 | P编号 | 表 | 字段/索引/数据 | 源码引用 | 总SQL位置 | 开发库状态 | 测试库状态 | 处理结论 |
 |---|---|---|---|---|---|---|---|
-| Pxx | table_name | column_name | 类/Mapper/方法 | sql/...:行号或注释块 | 已存在/缺失/差异 | 已存在/缺失/差异 | 补总SQL/MODIFY/不采纳说明 |
+| Pxx | table_name | column_name | 类/Mapper/方法 | target_sql_path:行号或注释块 | 已存在/缺失/差异 | 已存在/缺失/差异 | 原样复制/退回docs/不采纳说明 |
 ```
 
 **任务交付报告中必须包含的数据库核查章节：**
@@ -554,8 +563,8 @@ done
 **禁止事项：**
 
 - 禁止为绕过数据库缺字段、缺默认值、缺初始化数据、历史数据未迁移而修改业务逻辑
-- 禁止自行创建独立 SQL 文件。所有 SQL 脚本必须追加到需求级汇总 SQL 文件
-- 禁止把 SQL 写在临时说明里但不追加到需求汇总 SQL 文件
+- 禁止自行创建或追加 SQL。只能原样复制 `release-sql.md` 到冻结目标路径
+- 禁止把 SQL 写在临时说明或 Agent 回复里；遗漏必须退回 docs
 - 禁止用 mock、单测通过或 BUILD SUCCESS 代替真实数据库结构核查和数据迁移验证
 - SQL 脚本执行失败时，必须停下来报告真实错误，不允许改业务代码绕过
 - 禁止将本地迁移 SQL 提交到 Git（如项目约定不提交）
@@ -572,7 +581,7 @@ done
 7. 确定构建工具（检查 pom.xml 或 build.gradle）
 8. 确定基础 URL: http://localhost:{port}{context-path}
 9. **读取本需求汇总 SQL 文件**，确认其中包含本批次需要的所有数据库变更脚本
-10. **执行版本总 SQL 收口对账**：源码/Mapper 读写字段、开发库结构、测试库现状 + 总 SQL 最终结构必须一致；发现总 SQL 漏字段/漏索引/漏初始化数据时先补总 SQL
+10. **执行版本总 SQL 收口对账**：源码/Mapper 读写字段、开发库结构、测试库现状 + 冻结 SQL 最终结构必须一致；发现漏字段/漏索引/漏初始化数据时停止并退回 docs
 11. **提取前端真实动作矩阵**：从 api.md 中提取每个按钮/入口对应的 Method、URL、参数位置、响应形态、成功判定字段
 12. **提取文件接口契约**：列出所有导出/下载/模板接口，确认其响应形态（文件流 or JSON）
 13. **提取 Excel 导入契约**：列出所有导入接口，确认 failureCount 与 code 的映射规则
@@ -696,7 +705,7 @@ git status --short
 **通用禁止：**
 
 - 禁止因为字段缺失而在业务代码里写绕过逻辑
-- 禁止自行创建独立 SQL 文件，所有 SQL 统一追加到需求级汇总 SQL 文件
+- 禁止自行创建或追加 SQL，只允许原样复制 `release-sql.md` 到冻结目标路径
 - 禁止用 mock/单测/BUILD SUCCESS 代替真实数据库结构核查和数据迁移验证
 - 禁止报告"开发库已有"来替代"总 SQL 已同步"；测试/发布部署只认版本总 SQL。
 
@@ -1056,9 +1065,9 @@ Worker 完成编码和启动后，必须按以下 checklist 逐项执行接口
    - 错误：不管数据库表结构是否满足设计，直接改业务代码；发现字段缺失时在代码里加兼容逻辑
    - 正确：先连接开发环境数据库 SHOW CREATE TABLE 确认结构 → 发现缺失时执行汇总 SQL → 确认生效后再写代码
 
-17. ❌ **自行创建独立 SQL 文件**
+17. ❌ **实现阶段自行创建、追加或改写 SQL**
    - 错误：每个任务各建一个 SQL 文件，或者把 SQL 写在临时说明里不追加到汇总文件
-   - 正确：所有 SQL 统一追加到需求级汇总 SQL 文件（如 openspec/changes/xxx/sql/{version}.sql）
+   - 正确：退回 docs 更新 `release-sql.md`、哈希和 handoff；实现阶段只原样复制到 `target_sql_path`
 
 18. ❌ **用代码绕过数据库结构缺失**
    - 错误：发现字段不存在时加 if-null 判断、发现默认值缺失时在代码里硬编码、发现初始化数据缺失时在代码里插数据

package/assets/skills/superflow-pipeline/references/managed-work.md

@@ -1,5 +1,19 @@
 # 托管任务执行规则
 
+## 设计宪章门禁
+
+修改 Superflow 托管编排自身时，开始前必须完整读取仓库中的
+`docs/managed-work-design-principles.md` 和 `docs/managed-agent-protocol.md`。实现完成后，
+必须逐项核对宪章的强制回归清单，并在评审结果中说明是否存在原则变更。
+
+确定事实由 Runner/脚本检查；正确性、合理性、风险和证据充分性由 Agent 判断。脚本不得
+通过正则代替语义评审，Agent 也不得接管哈希、Schema、计数或状态迁移等确定性裁决。新增
+长期规则时，必须先同步更新中英文宪章、协议和测试。
+
+托管层只负责双 Agent 调度、冻结上下文、状态、等待、证据和评审循环。API、DB、并发、
+事务及测试方案属于 `api.md`、`design.md`、`tests.md` 和技术详设；Executor Prompt 只继承，
+不得重新设计。修改托管 Prompt 前必须用这一边界逐条审计。
+
 ## 入口
 
 托管任务属于 `superflow-pipeline` 内建能力。用户只需说“用 Superflow 托管完成”并给出
@@ -7,52 +21,146 @@ implementation prompt、change 目录或简单任务，不需要知道内部 Ski
 简单任务生成最小合同；SDD 任务冻结 Superflow 已生成的 implementation prompt，不以
 `tasks.md` 代替执行 Prompt。
 
+Host 启动前必须按资料成熟度分流：只写文档时停在 Coding Ready，不创建托管任务；用户
+评审通过的 change/Prompt 直接冻结；口头小需求进入 minimal/standard。若口头需求存在会
+改变实现方向的 API、数据、并发、跨仓或 owner 决策，先返回澄清/文档流程，不让 Runner
+正则或 Executor 临场设计替代 Host 判断。
+
+已安装 MCP 时，当前主 Agent 必须优先通过 `superflow_managed_*` 工具提交、等待、补充要求
+和提交评审。MCP 是主 Agent 与本地状态机的通道，不是第三个模型；托管只有当前 Host
+直接评审这一种模式，避免嵌套 Supervisor CLI 重复消耗上下文、Token 和评审时间。
+
 ## 角色
 
 - 当前主 Agent：提交任务、查看结果、向用户汇总并申请 Git 批准。
-- 监督 Agent：固定会话、只读检查、生成结构化问题和整改要求。
-- 执行 Agent：固定会话、唯一写入者、实现并完成验证。
-- 后台服务：状态、预算、队列、会话恢复和证据的唯一写入者。
+- 当前 Host Agent：直接只读检查，生成结构化问题和整改要求，不启动嵌套 CLI。
+- 执行 Agent：首次调用在一个不限制工具轮数的 CLI 会话中持续工作，完成后主动返回；仅在
+  评审整改或异常恢复时创建后续会话。它是唯一写入者，负责实现、验证和进程善后。
+- 后台服务：状态、预算、队列、短会话交接和证据的唯一写入者。
 
-## 必须通过 CLI
+## MCP 优先，CLI 兜底
 
-不要由聊天中的 Agent 手工启动另一 CLI。调用：
+MCP 不可用时，不要由聊天中的 Agent 手工启动另一 CLI。调用：
 
 ```bash
 superflow pipeline "<implementation-prompt|change-dir|task>" --managed --project "<root>" \
-  --supervisor <codex|claude> --executor <claude|codex> --language <zh|en>
+  --supervisor current --executor peer --language <zh|en>
 ```
 
-查看：
+`current/peer` 自动识别 Host 与对端；无法识别时必须显式传入 `codex/claude`，不能猜测。
+旧合同未保存监督方式或曾使用旧式后台监督时，恢复阶段统一迁移为当前 Host 直接评审；
+任何入口都不得启动后台 Supervisor CLI。
+
+用户主动询问状态时可查看一次：
 
 ```bash
 superflow status <root>
 ```
 
-托管命令默认启动独立后台服务并监听本地事件账本，直到任务进入交付、阻塞或预算耗尽等
-终态。监听进程退出不影响后台任务。命令返回后，当前 Agent 读取任务报告并在原会话汇总。
+正常托管只保留当前 `pipeline`/`resume` 命令的一次阻塞等待，由 CLI 在本地读取状态文件。
+不得用主 Agent 的模型回合每隔固定时间重复执行 `status`。
+
+MCP 模式默认使用
+`superflow_managed_wait(taskId, afterSequence, timeoutSeconds=240)` 适配常见 Host 的
+300 秒工具调用上限；支持更长调用的 Host 可显式提高到 43200 秒。活动请求通过标准 MCP
+progress notification 展示阶段和健康监督点，不唤醒 Host 模型。单个健康或空闲监督点不
+结束 wait，连续两个无有效里程碑才返回 attention。普通窗口超时只用紧凑快照中的
+`latestSequence` 立即续接 wait，不调用 status、不重启 Executor；只有需要处理状态时才调用
+`superflow_managed_status` 读取完整证据。
+
+执行者返回后，任务进入 `external_supervisor_review_required`。当前 Agent 读取
+`host-review-N.md`，把评审 JSON 写入运行目录外的临时文件，并执行：
+
+```bash
+superflow pipeline --resume-task <task-id> --submit-host-review <review.json>
+```
 
 ## 硬门槛
 
-- 5/7/12 调用上限由状态机先占用后调用，Prompt 无权上调。
+- 5/7/12 调用上限由状态机先占用后调用，Prompt 无权上调；默认再以累计 200 万 Token
+  单位熔断。不同供应商的美元计价不可比，默认不设美元成本熔断，也不向 Claude 传
+  `--max-budget-usd`。
 - 语言写入冻结合同；执行 Prompt、账本、报告、通知、错误和恢复轮次始终使用同一语言。
 - 每次启动和恢复都重新校验冻结合同哈希、不可覆盖权限及 5/7/12 硬上限；磁盘文件被
   改写时按失败关闭，不能继续调用 Agent。
+- 非 Git 工作区由 Runner 文件快照提供变更清单；Executor 不得为 diff、预检或交付执行
+  `git init`，不得创建或替换 `.git`。任务中仓库身份变化仍失败关闭。
+- 上下文清单把冻结需求、设计、Prompt、handoff、规则和任务事实标为 `immutable`，把
+  tasks/test-report 进度证据标为 `retain`。前者只读，后者可更新但不可删除；原生 Hook
+  写入前阻断，所有 Host 仍由 preflight/最终门禁复核。
+- 清理分为 runtime、workspace-temporary、delivery-artifacts、protected-contracts；Executor
+  只清理前两类，源码/SQL/测试/报告和冻结合同保留给 Host 评审。禁止 pkill、killall、裸
+  kill、按端口/名称清理和未经 owner helper 校验的 rm -rf。
 - change 目录必须通过 `.sdd/state.yaml` 的 `implementation_prompt` 定位执行入口；
   `tasks.md` 仅作清单。Prompt 原文复制为托管快照并冻结 SHA-256，执行和评审使用同一份。
-- 两个 session ID 必须落盘，禁止 `--last` / `--continue` 猜测。
+- 第一轮自动把冻结 Prompt 作为研发任务入口，不依赖主 Agent 临时重写任务描述。
+- 真实运行环境任务的首轮 Prompt 必须要求仓库内、单命令、可重复、失败安全且可移植的
+  验收入口；该入口覆盖 preflight、setup、构建、启动、真实调用、断言和 cleanup，并在
+  成功和一个代表性 setup/验证失败时清理资源并证明零残留。Host 首轮一次性审查这些属性。
+- start 前调用 MCP runtime 握手；安装内容变化后旧 MCP 必须在任务落盘前失败关闭并要求
+  重启 Host。详细构建/框架日志落盘，控制台只输出有界摘要和失败尾部。
+- 验证固定分三级：整改轮做受影响验证；engineering/SDD 默认做任务级真实验收；只有冻结
+  Prompt 明确要求、修改 owner helper/托管编排或新增自定义清理原语时做框架认证。冻结合同
+  可提高等级但不得静默降低，历史有效证据只在当前 diff/finding 真正失效时重跑。
+- 普通真实运行任务首轮 Host 评审核对任务 owner PID/启动指纹强绑定、删除门禁、一个代表性
+  setup/真实断言失败和最终零残留；多个业务删除路径仍分别验证，多仓任务仍逐仓和跨服务
+  验证。不得为每个业务任务重复公共 helper 的 PID 复用、非 owner、
+  伪造 state 和全信号灾难套件；通过可配置路径直接复用 helper，禁止复制后另建清理框架。
+  每轮记录 Host usage 或不可用原因。
+- Claude Executor 不传 `--max-turns` 或 `--max-budget-usd`，不得以固定工具步数或不准确的
+  美元估值切断正常研发。默认连续 60 分钟完全无输出或单次执行达到 2 小时才终止；连续
+  供应商错误、Token/调用预算、安全边界或用户暂停仍会终止进程。
+- Claude Executor 默认用官方 `CLAUDE_CODE_AUTO_COMPACT_WINDOW=200000` 和
+  `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=70` 提前压缩长会话，显式用户环境值优先。压缩后
+  必须重读冻结 Prompt 和 handoff；最终 `result.usage` 是该调用的权威用量。
+- 网络、连接关闭、超时和供应商拥塞共享连续失败计数，第三次失败后必须熔断并等待用户；
+  只有完整 Agent 返回才清零。429/529/overloaded 以及确认发生在 Agent 返回前的连接被拒绝、
+  重置、关闭和套接字断开等临时传输失败可抵扣业务预算；权限、Token Plan、quota、billing
+  等失败不抵扣，但均不得绕过三次熔断。
+- 首次调用使用一个连续 session；评审整改或异常恢复创建新 session，旧 ID 进入审计历史。
+  禁止使用 `--last` 或 `--continue` 猜测。后续调用生成 `executor-handoff-N.md`，压缩传递
+  Prompt 哈希、任务完成度、本地剩余、外部前置、全部 finding、diff stat 与最近报告。
+  新会话先读交接包，再以当前工作区核实，不能只靠聊天历史。
+- 首次执行策略写入 preflight 可安全发现的 Java、Maven、Node 和 npm 可执行路径，研发
+  Agent 应直接使用，不得重复花费大量工具调用寻找基础工具链。
+- Handoff 同时写入精确适用规则文件和确定性交付 preflight 命令；Executor 返回前必须运行，
+  行宽、空白、任务勾选、报告缺失等问题在同一会话修正。
 - `.superflow/tasks/<task-id>/runs/<run-id>/progress.jsonl` 是追加式事实账本。
 - 执行角色禁止修改托管目录、Git 提交/推送、发布、生产写入、跳过沙箱。
 - 监督角色禁止修改目标文件。
-- Agent 非零退出、非法 JSON、缺 session ID、工作区在检查期间变化都不能判通过。
+- 非法 JSON、缺 session ID、工作区在检查期间变化都不能判通过；无匹配、无残留和无监听
+  检查使用 `assertion: negative` 明确表达预期 exit 1/2，不再靠命令名称或文案猜测。
+- 预期失败和失败注入必须由父级命令断言子命令非零且自身 exit 0；原始非零只留日志。
+  Runner 收到违规负向证据时直接转 Host 核验，不得启动完整 Executor 整理 JSON。
 - 工程和 SDD 任务至少提供构建、测试、启动/真实调用中的两类成功命令证据；只编译或
   只跑单元测试不能进入正式检查。
 - 最终通过前运行 `superflow-managed-work-check.mjs <root> <task-id>`。
+- `tasks.md` 只认 `local_required/environment_required/release_required`；未标注一律按本地。
+  Runner 根据清单、真实差异、测试报告和成功命令推导基础证据；Executor 只为需要独立
+  证据的任务补充 taskEvidence，不再为每个勾选项重复拼装 JSON。
+- Runner 自动合并冻结基线后的完整 changedFiles，并为命令写入结构化验证类别；同类机械
+  退回最多自动整改一次，累计最多两次，之后直接转当前 Host 评审。单轮出现 3 次及以上
+  权限拒绝时不再启动下一轮 Executor。
+- Runner 自动继承历次通过验证的启动、HTTP、测试与构建命令。Host 确认历史证据完整且
+  仅当前结构化元数据有误时直接通过并审计式晋升，禁止让 Executor 重跑环境或整理 JSON。
+- Spring Boot 成功证据已经覆盖启动、真实 HTTP/runtime 和证据路径，仅缺 `invocation`
+  验证类别时属于验证类别歧义：Runner 直接转 Host，Host 通过后审计式补全，不启动完整
+  Executor 修元数据。
+- Runner 确定性删除结构化数组中的空白项；只读检查 exit 1/2 且明确报告无进程、监听、
+  容器或残留时按成功空结果处理，不得为这两类元数据问题启动 Executor。
+- 状态同时展示物理调用、基础设施抵扣和有效研发调用。供应商切换通过
+  `--provider-switched <reason>` 原地恢复；研发阶段仅在变化时通知 Host 会话。
+- 页面/权限变更机械要求前端启动和 Playwright/Cypress 真实浏览器 E2E；跨端 API 变更要求
+  后端 Controller 与前端请求合同测试和 API export snapshot。
 - 完整性脚本必须先通过，后台才允许写入唯一的 `run.delivery_ready` 事件；脚本失败时
   转入等待人工处理，不得留下“已可交付”的假证据。
-- 通过后只进入等待 Git 批准，不能自动提交。
+- 通过后按源码/环境/发布进度进入三段交付状态，仍不能自动提交。
 
 ## 恢复
 
-后台异常后读取任务合同、事件账本、运行状态、最近检查结果和两个 session ID。恢复原
-会话并从最后确认动作继续。监督会话丢失可在完整接管后显式重建；执行会话丢失默认暂停。
+后台异常后读取任务合同、事件账本、运行状态和最近检查结果，从当前工作区创建新短会话
+继续。旧 session 仅用于审计，不作为恢复依赖。
+健康 `running` 任务执行普通 `--resume-task` 时只允许安全接入并继续等待，不得重置状态、
+预算或重复启动 Executor；只有已记录 PID 被确认死亡时才进入陈旧恢复，PID 未记录时失败
+关闭为接入等待。活动 MCP wait 的 progress notification 只在该请求内有效，不是 Host 回合
+结束后的自主回调。

package/assets/skills/superflow-pipeline/references/orchestration.md

@@ -585,9 +585,9 @@ curl -s http://localhost:{port}{context-path}/actuator/health | grep UP
     - ❌ 错误：不管数据库表结构是否满足设计，直接改业务代码
     - ✅ 正确：先连接开发环境数据库 SHOW CREATE TABLE 确认结构 → 发现缺失时执行汇总 SQL → 确认生效后再写代码
 
-12. **禁止自行创建独立 SQL 文件**
+12. **禁止实现阶段自行设计 SQL**
     - ❌ 错误：每个任务各建一个 SQL 文件
-    - ✅ 正确：所有 SQL 统一追加到需求级汇总 SQL 文件
+    - ✅ 正确：退回 docs 更新 `release-sql.md`，重算哈希并刷新 handoff；研发阶段只原样复制
 
 13. **禁止用代码绕过数据库结构缺失**
     - ❌ 错误：发现字段不存在时加 if-null 判断兼容

package/assets/skills/superflow-pipeline/references/p0-baseline-template.md

@@ -110,7 +110,8 @@ cd ../{project}-p0-worktree
 ### 步骤 4：修复不一致
 对步骤 3 发现的不一致项：
 - 如果 SQL 是正确的（以设计文档为准），修正实体/Mapper/DTO
-- 如果源码/Mapper 和开发库一致但版本总 SQL 缺失，优先补版本总 SQL，不要改业务代码绕过
+- 如果源码/Mapper 和开发库一致但冻结 SQL 缺失，停止实现并退回
+  `$superflow-docs` 更新 `release-sql.md`、哈希和 handoff，不要由研发 Agent 补 SQL
 - 如果测试库已有字段，版本总 SQL 不得重复 ADD；字段类型或注释与开发库不一致时生成 MODIFY 或上报不采纳理由
 - 如果设计文档有模糊之处，停止并报告，不允许自行猜测
 
@@ -157,7 +158,7 @@ P0 基线报告：
 - 版本总 SQL 收口对账：
   - 源码/Mapper vs 开发库：一致 / 不一致
   - 测试库现状 + 总 SQL：一致 / 不一致
-  - 补入总 SQL 的字段/索引/数据：{list}
+  - 需退回详设补入冻结 SQL 的字段/索引/数据：{list}
   - 不采纳项及原因：{list}
 - 编译状态：BUILD SUCCESS / 失败（说明）
 - 修改文件清单：{files}

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

@@ -24,6 +24,7 @@
 | 12  | **Prompt 拆分合理性**              | **如触发拆分条件，已按功能闭环拆分，每份 prompt 边界清晰**                                                                                                                                                  |
 | 13  | **需求/原型字段对账**              | 涉及页面、截图、原型或前端联调时，已建立"页面字段 -> API 字段 -> DTO/VO -> DB -> 测试"映射                                                                                                                  |
 | 14  | **功能点串行门禁**                 | 复杂 PRD、飞书文档、原型图或口头大需求必须具备 `source-ingestion.md`、`feature-gates.md`、`feature-inventory.md`、`ui-contract.md`、`gap-analysis.md`、`spec-freeze-review.md`，且当前功能点状态为 `已冻结` |
+| 14.1 | **源码事实冻结卡** | full workflow 涉及现有行为、DB/表关系、跨仓或真实入口时必须具备 `source-code-audit.md`；覆盖所有写入方、真实入口、current/legacy/unmounted/data-model-only 分类、DB 核查或跳过原因、冲突审计和 owner 边界 |
 
 ### 按需检查项（涉及则必须检查）
 
@@ -66,6 +67,7 @@
 | 48   | **外部集成配置与部署合同**         | **涉及第三方平台/工具、SDK、MQ/Kafka、回调、支付渠道、云服务或其他外部集成时强制** | api.md、sdd-quality-gate.md、Superpowers 技术详设和实现 prompt 包含 `外部集成配置与部署合同` / `External Integration Configuration And Deployment Contract`；列出 endpoint、应用/租户/项目 ID、Topic/Tag/Consumer Group、namespace、webhook、ACL/role、开关、超时和凭据引用在本地/测试/生产的来源与创建方式，以及注入方式、运行 owner、创建 owner/时点、就绪证据、回滚、密钥处理和阻塞项；环境相关值不得只硬编码在注解/常量/业务代码；测试自动创建、历史资源或本地启动成功不能证明生产就绪，缺少生产创建证据必须阻塞发布 |
 | 49   | **并发与幂等归属**                 | **涉及并发、批量下发/开通/续费、重复提交/回调/消费或重复外部调用时强制** | sdd-quality-gate.md、Superpowers 技术详设和实现 prompt 包含 `Concurrency And Idempotency Ownership` / `并发与幂等归属`；明确业务幂等键、应用层原子占用 owner、短事务边界、PENDING/SUCCESS/FAILED 状态流转、重试复用原业务编码、外部调用边界和不确定结果对账；唯一索引不作为默认方案，只能在自然唯一、历史数据、NULL/软删除和冲突处理合同明确后作为可选兜底；测试覆盖并发、重复和重试 |
 | 50   | **复杂度减法评审**                 | **完整 workflow 的 docs/design 阶段强制** | `design.md` 与 Superpowers 技术详设包含 `复杂度减法评审`，逐项记录现有能力/复用证据、必要性、最简实现、删除/拒绝项和证据/阻塞；统计新增表、字段、API、Service/组件、缓存、异步/MQ/事件、定时任务和兼容层；能扩展现有模块、由字段推导或用单事务同步闭环时不得另建平行实现；`sdd-quality-gate.md` 必须给出 PASS/BLOCKED 结论，只有 PASS/通过才能离开 docs/design，存在无证据抽象或未决更简方案时阻塞 |
+| 51   | **冻结发布 SQL**                   | **涉及表/字段/索引/约束/初始化数据/历史迁移时强制** | docs 阶段已生成 `release-sql.md`；front matter 含 `database_change: true`、无占位符的精确 `target_sql_path`、`copy_policy: verbatim`、有效 `sql_sha256`；仅有一个完整可执行 SQL 代码块且包含合同要求的前置检查、DDL/DML、迁移和后置验证；design/tasks/quality gate 明确研发 Agent 只能原样复制，发现遗漏退回 docs，禁止 prompt 阶段临场设计 SQL |
 
 ### 文档完整性强制检查（新增，全部项目必做）
 
@@ -75,12 +77,12 @@
 | 27  | **顶层文档同步更新**                           | 新增/修改 embedded change 后，`tasks.md`、`traceability-matrix.md`、`sdd-quality-gate.md`、`tests.md`、`test-report.md` 已同步更新                                                                                                                                                 |
 | 28  | **implementation prompt 文档引用**             | prompt 中"必读文档"列表必须包含 `design.md`、`tests.md`、`review-checklist.md`、`sdd-quality-gate.md`，不能只引用 `api.md` 和 `spec.md`                                                                                                                                            |
 | 29  | **无"待后续生成"占位符**                       | 文档中不存在"待后续生成"、"待补充"、"TODO"等未完成的占位标记                                                                                                                                                                                                                       |
-| 30  | **需求级汇总 SQL 文件**                        | 如涉及数据库变更，已创建需求级汇总 SQL 文件（如 `sql/{version}.sql`），且 tasks.md / tests.md / prompt 中已明确引用该文件路径                                                                                                                                                      |
+| 30  | **需求级冻结发布 SQL**                        | 如涉及数据库变更，已创建 `release-sql.md` 并冻结目标版本路径和 SHA-256；tasks.md / tests.md / prompt 明确只能原样复制，不能让研发 Agent 追加或改写                                                                                                                                                      |
 | 31  | **tasks.md 标注 SQL 依赖**                     | 每个涉及数据库的任务已标注依赖的汇总 SQL 文件路径，不需要 SQL 的任务已写明"本任务不新增 SQL，但开始前仍需核查依赖表结构"                                                                                                                                                           |
 | 32  | **tests.md 包含数据库结构核查用例**            | 测试用例中包含 SHOW CREATE TABLE / SHOW COLUMNS 等数据库结构核查用例                                                                                                                                                                                                               |
 | 33  | **汇总 SQL 格式规范**                          | SQL 脚本采用简单直接格式（ALTER TABLE / INSERT），不使用 INFORMATION_SCHEMA 判断、PREPARE/EXECUTE 等过度兼容脚本，按任务编号或功能块追加注释                                                                                                                                       |
 | 34  | **数据库迁移类任务 prompt 强制顺序（阻塞级）** | 涉及表结构重构、旧数据迁移、状态字段变更、分页筛选依赖新表/新状态时：① prompt/pXX-xxx.md 中必须包含"强制执行顺序"章节；② 章节必须覆盖：核对数据库结构 → 执行表结构改造 → 执行旧数据迁移 → 回填 test-report 证据 → 才允许 Java 编码；③ 任一缺失视为文档交付不完整，阻塞进入开发阶段 |
-| 35  | **版本总 SQL 收口对账（阻塞级）**              | 每个涉及数据库的 P/CR 任务必须提供 `P编号                                                                                                                                                                                                                                          | 表       | 字段/索引/数据 | 源码引用             | 总SQL位置  | 开发库状态 | 测试库状态                                                                              | 处理结论` 对账表；开发库已有但源码依赖且总 SQL 缺失时必须补总 SQL；测试库已有字段不得重复 ADD，类型/注释不一致时生成 MODIFY；无对账表不得标记完成 |
+| 35  | **版本总 SQL 收口对账（阻塞级）**              | 每个涉及数据库的 P/CR 任务必须提供 `P编号                                                                                                                                                                                                                                          | 表       | 字段/索引/数据 | 源码引用             | 总SQL位置  | 开发库状态 | 测试库状态                                                                              | 处理结论` 对账表；开发库已有但冻结 SQL 缺失时必须退回 docs 更新 `release-sql.md`、哈希和 handoff，研发 Agent 不得补写；无对账表不得标记完成 |
 | 41  | **跨仓实体字段对账（阻塞级）**                 | 多仓共享表、复制实体、MyBatis-Plus `@TableName`/`BaseMapper` 时：① 必须提供 `表                                                                                                                                                                                                    | 真源结构 | 消费仓         | 实体/Mapper/SQL 字段 | 实际库字段 | 处理结论   | 验证证据`；② 任一消费仓映射不存在列或查询旧字段时阻塞；③ 不得通过给测试库补废弃字段绕过 |
 | 42  | **真实入口与测试端点分级（阻塞级）**           | 涉及外部系统链路时：① test-report 必须分开记录 `Mock 验证`、`测试端点验证`、`真实入口验证`；② 测试 Controller/绕过鉴权端点只能标记局部通过；③ 无真实入口 payload/响应/trace/DB 时，不得写真实链路通过                                                                              |
 | 44  | **Red-Green 证据占位（阻塞级）**               | test-report.md 必须预置 `RED 失败证据`、`GREEN 通过证据`、`接口自动化证据`、`DB 核查证据`、`日志核查证据`、`未自动化/阻塞用例`；每项绑定 tests.md 用例 ID                                                                                                                          |
@@ -141,7 +143,7 @@
 - 如果 D2（表结构改造 SQL）执行失败 → **阻塞**，修复 SQL 后重新执行，禁止先写 Java 代码
 - 如果 D3（旧数据迁移 SQL）执行失败或数量核对不一致 → **阻塞**，必须解决迁移问题，禁止用业务代码绕过
 - 如果 D4（迁移证据）缺失 → **阻塞**，明确"不允许进入编码阶段"，必须补齐 test-report 证据
-- 如果 D6（版本总 SQL 收口）缺失 → **阻塞**，必须补齐汇总 SQL 和对账表，不能只说开发库已存在
+- 如果 D6（版本总 SQL 收口）缺失 → **阻塞**，退回 docs 补齐冻结 SQL、哈希和对账表，不能只说开发库已存在
 - D5 只有通过后才能开始 Phase 1（读取文档）之后的编码工作
 
 ### P0 基线特有加禁
@@ -271,7 +273,7 @@
 - 批次报告中必须包含"数据库前置门禁"章节，写明检查了哪些表/字段/索引/初始化数据。
 - 报告中必须包含汇总 SQL 文件路径、执行的具体脚本、执行结果、复查确认结果。
 - 如果业务代码绕过字段缺失、空 SET、默认值缺失、初始化数据缺失等问题，应优先判断是否是 SQL 未执行导致。
-- 如果根因是 SQL 未执行，修复方向应是执行/补齐汇总 SQL，而不是继续加业务兼容代码。
+- 如果根因是 SQL 未执行，执行冻结 SQL；如果冻结 SQL 有遗漏，退回 docs，不能由研发 Agent 补写或加业务兼容代码。
 - 没有真实数据库结构核查和 SQL 执行证据时，结论必须写"未通过，缺少数据库前置门禁证据"。
 - 检查本需求下是否只维护了一个汇总 SQL 文件，是否存在各任务各自新建的独立 SQL 文件。
 - SQL 脚本是否采用简单直接格式，不存在过度兼容脚本（INFORMATION_SCHEMA 判断、PREPARE/EXECUTE 等）。
@@ -296,7 +298,7 @@
   - {批次/任务}：{缺失的数据库核查/SQL 执行证据} → 处理方式：{fix}
   - {批次/任务}：{发现代码绕过数据库缺失} → 根因判断：{SQL 未执行/设计变更} → 修复方向：{执行 SQL / 改设计}
 - 版本总 SQL 收口缺口：X 项
-  - {批次/任务}：{源码引用/开发库字段/测试库状态/总 SQL 缺口} → 处理方式：{补总 SQL / MODIFY / 不采纳并说明}
+  - {批次/任务}：{源码引用/开发库字段/测试库状态/冻结 SQL 缺口} → 处理方式：{退回 docs 更新 release-sql / 不采纳并说明}
 - 跨仓数据合同缺口：X 项
   - {表/消费仓}：{实体/Mapper/SQL 引用字段} → 实际库：{缺失/类型不一致/查询条件旧口径} → 处理方式：{修代码 / @TableField(exist=false) / 补最终合同 SQL / 阻塞}
 - 真实入口验收缺口：X 项

package/assets/skills/superflow-pipeline/references/reviewer-checklist.md

@@ -133,6 +133,13 @@
 | 54 | 真实入口日志闭环 | 检查服务日志 | 从入口日志到业务校验、DB 查询、外部调用或异常返回有同一 trace/业务单号串联 |
 | 55 | 泛化失败归因 | 检查外部错误、业务日志和 DB 旁证 | 外部平台泛化失败时未直接写通过；已区分外部阻塞、合同漂移、代码异常 |
 
+## 负向控制与资源清理检查
+
+| # | 检查项 | 检查方法 | 通过标准 |
+|---|---|---|---|
+| 55.1 | 负向输入是否真实到达 | 对照 `tests.md` 的原始载荷、客户端命令与服务端日志/分支 | 畸形 JSON、错误 Content-Type、越权身份或非法字段以真实线协议注入，并证明命中目标解析/校验分支；不能只因状态码相同而通过 |
+| 55.2 | 任务资源身份闭环 | 对照 owner 记录、资源记录、清理代码与失败用例 | 清理逐项比对 nonce、PID、端口、签名等冻结身份；任一不匹配拒绝清理且有证据。复用认证 helper 时只核对完整性、任务参数、一次失败清理和最终零残留 |
+
 ## 金额精度检查
 
 | # | 检查项 | 检查方法 | 通过标准 |