ch3sh-lc/myworkflow/integration-verify

触发

• 显式触发：用户/leader（或派发方）说"验证集成/检查接口/集成检查/验证子任务/检查模块接口"；L3 经「myworkflow-task-dispatch」下 mission 后检测到所有交付物 owner 的 completion.md 就绪（L2 平铺子交付物同理）。
• 隐式触发（满足任意一条）：
• 整批触发：.task-manifest/task-contract.yaml 中列出的所有 task-id 的 completion.md 均已生成
• 批次触发：某一并行批次（如同一 depends_on 层级）的全部 task-id 的 completion.md 均已生成 → 可先验证该批次，不等全部完成
• 超时触发：自派发后超过 30 分钟仍有交付物执行者（L2 子智能体 / L3 member）未提交 completion.md → 触发本 skill 的缺失处理流程
• 不触发：交付物执行者仍在运行（completion.md 未全部生成且未超时）；task-contract.yaml 不存在（先完成拆解）；用户只是想看某个交付物的产出（直接读文件）；只有 1 个交付物（L1 当前智能体直接检查）。
• 模式：批次验证 = 同一并行层全完成即可验证该批次（跑该批次各任务的自动层 1–4.5）并继续派发下一批；全体验证 = 所有批次完成走完整验证（自动层 1–4.5 + 判断层 5–7.5，含跨模块兼容性与全分支最终代码审查）；增量验证 = 修正循环中某任务重新提交，只对该任务重跑自动层 1–4.5，不走完整判断层。
• 组织口径（三级模型）：跨交付物兼容验证按交付物/owner 组织——一个 owner 的产物一个归口；L1 单智能体完成自己的交付物后直接自检，L2 子智能体各自交回自己的小件、由 leader / 派发方统一核，L3 各 member 在自己域内闭环、leader 只做裁决。禁止把同一交付物按「先实现→再验证→再审查」拆阶段接力（阶段在交付物内部，不跨窗口）。

前置强制步骤

核心原则：验证可自动化——能自动检查的不依赖人工判断。重试有上限——修正最多 3 轮，之后升级为人工介入。

1. 读取合约：读 .task-manifest/task-contract.yaml，加载所有任务的接口定义。

• 合约文件不存在 → 区分两种场景：.task-manifest/ 目录也不存在 = "合约从未创建"，提示用户先运行「myworkflow-task-dispatch」拆解任务；目录存在但 task-contract.yaml 缺失 = "合约被删除"，尝试恢复：检查 git 历史（git log -- .task-manifest/task-contract.yaml）或询问用户是否重新拆解。

1. 收集元文件：对每个 task-id，检查 .task-manifest/outputs/{task-id}/interface-declaration.md、self-check.md、completion.md 是否存在且非空。缺失或为空 → 标记"未完成"或"交付物执行者可能崩溃"（L2 子智能体 / L3 member）。
2. 确认依赖已满足：对每个子任务，检查其 depends_on 中列出的任务是否已完成，同时验证引用的 task-id 在合约中确实存在。未满足 → 标记"依赖未就绪"；task-id 不存在 → 标记"合约引用错误"。

缺失/空 completion.md 的处理（交付物执行者可能崩溃、超时或仍在运行）：

• self-check.md 存在且全部 [x] → 执行者可能忘了写 completion.md，提示补写。
• completion.md 存在但为空 → 执行者异常中断（崩溃或提前退出），视同缺失处理：检查 self-check.md 状态，决定补写还是重新派发。
• self-check.md 也不存在或未完成 → 执行者可能崩溃或超时。向用户报告该交付物状态，询问：重新派发 / 跳过该任务 / 人工完成。
• 执行者仍在运行（Agent 或团队工具状态判断）→ 不在本回合内等待/轮询：记录状态并结束回合，等二次唤醒后再查；判定阈值 = 10 分钟无状态更新（只看状态判定，不作为等待/同步依据；≥30 秒的命令一律后台或派 leaf）。

状态路由（解析 completion.md 的 **状态**: 字段）：

• DONE → 正常进入自动验证层
• DONE_WITH_CONCERNS → 提取"已知担忧"条目，注入判断层作为高优先级检查项；正常进入自动验证层
• NEEDS_CONTEXT → 暂停该任务验证，向用户展示缺失信息列表，询问补充后重新派发
• BLOCKED → 暂停该任务验证，报告阻塞原因，询问是否解除阻塞或跳过该任务

关联Skill：输入 ←「myworkflow-task-dispatch」产出的 task-contract.yaml 作为验证基准；输入 ←「myworkflow-subagent-protocol」产出的 interface-declaration.md 和 self-check.md 作为验证对象。

执行流程

主线：自动验证层（检查 1–4.5）→ 全部通过 → 判断验证层（检查 5–7.5）→ 通过 → 生成验证报告；自动层不合规 → 修正循环（≤3 轮）→ 仍不通过 → 人工评估清单。

编号说明：带 .5 的检查是补充性检查，条件满足才启用——1.5 只对有 test_passes 条目的任务执行，4.5 只在深度审查模式执行，7.5 是分支级检查（不属于任何单个任务），其余检查对所有任务执行。报告模板中这些检查项同样有落位（未启用时填 —）。

自动验证层（检查 1–4.5）

检查 1：文件存在性 + 跨任务路径唯一性 — 对合约中每个 output.file，用 PowerShell Test-Path 验证文件存在且非空。跨任务路径冲突检查：收集所有任务的 outputs[].file，若两个不同任务声明相同输出文件路径 → ❌ 标记"路径冲突"（子智能体将互相覆盖文件）——从源头恢复被覆盖文件，同时修复合约中的路径冲突以防再次发生。

检查 1.5：副作用任务执行验证 — 对 verification 中包含 test_passes 条目的任务（通常 outputs 为空），在 shell 中执行对应命令：退出码 0 → ✅；退出码非 0 → ❌ 记录失败输出；如果命令依赖运行时环境（需先构建/启动），在修正循环中处理，首次标记 ⚠️ "待环境就绪后验证"。

检查 2：导出签名匹配（best-effort） — 按文件类型执行对应检查：

判定：所有 verification.export_matches 的名称在文件中可找到 → ✅；缺失 → ❌；参数数量不匹配 → ⚠️ 警告。 风险标注审查：如果 interface-declaration.md 的"风险和假设"中标注了合约签名问题（如"合约中 Session 类型缺少 refreshToken 字段"），读取这些标注并与合约对比。如果执行者按风险标注修正了签名（与合约不一致但标注了原因），标记 ℹ️ "合约建议修正"而非 ❌；如果签名与合约不一致且无风险标注 → ❌。

检查 3：声明-合约一致性 — 合约 outputs 是否全部在 interface-declaration.md 中被承诺；声明中的导出是否覆盖合约 verification.export_matches；声明中有但合约中没有的产出 → ℹ️ 信息性警告。

检查 4：自检诚实度 — 对比 self-check.md 与自动验证结果。self-check 声称通过但自动验证发现不匹配 → 标记 self-check-unreliable。

检查 4.5：Per-task 规范符合性 + 代码质量审查（深度审查模式） — 任务对代码质量有较高要求时启用。派发 fresh 审查执行者（L2 子智能体；L3 由独立审计或 leader 裁决），输入为 task-contract.yaml、交付物产出 diff、交付物自检报告。两个独立判决：

审查纪律：审查者直接读 diff 文件（不通过实现者报告间接判断）；"不信任自检报告"——每个声明在 diff 中找到对应代码变更；只报告有代码证据的问题。审查后处理：🔴 → 派给该交付物 owner 修复（L2 子智能体 / L3 member）；🟠 → 记录，用户判定。

判断验证层（检查 5–7.5）

检查 5：跨模块接口兼容性 — 对每对有依赖关系的任务（A 依赖 B），检查：A 引用的类型名是否与 B 导出一致；A 调用 B 的函数时参数数量是否与 B 声明签名一致；A 的 import 路径是否与 B 的实际产出文件路径一致。判定：所有引用一致 → ✅；不匹配 → ⚠️ 记录兼容性问题。

语言适配：以上以 TypeScript/JavaScript 为默认语法。其他语言对应检查：Python 检查 import 路径和函数签名、Rust 检查 use 声明和 trait 实现、Go 检查 import 和函数签名。

检查 6：质量抽查 — 抽查关键模块（被多任务依赖的、自检最完美的）：接口契约是否诚实履行、错误处理是否覆盖、有没有空函数体/硬编码返回值/未实现 TODO。抽查 20-30% 模块即可（至少抽查 1 个；如果 ≤3 个任务则全查）。

检查 7：集成风险标注 — 标注自动层无法检测的风险：语义不匹配、隐含假设冲突、缺失的接口。

检查 7.5：全分支最终代码审查 — 所有子任务完成且自动验证层通过后自动触发。先用以下命令取整个分支的完整 diff（可直接复制执行；<base-branch> 通常是 main 或 master，取决于仓库）：

# 写法一：显式算出合并基点，再取三点 diff（推荐）
git diff $(git merge-base <base-branch> HEAD)...HEAD
 
# 写法二：三点语法简写（前提：本地已存在名为 main 的分支，且它就是当前分支的分叉基点）
git diff main...HEAD
 
# 先确认 base 分支名（本地不一定有 main，可能是 master）
git branch --list main master

边界情况：若本次工作直接发生在 base 分支上（没有独立特性分支），git merge-base main HEAD 就等于 HEAD，三点 diff 为空。此时改用「本次工作起点」到 HEAD 的两点 diff，例如 git diff {起始commit}..HEAD（起点可用 git log --oneline 定位）。

拿到 diff 后派发 fresh 审查执行者（L2 子智能体；L3 由 leader 裁决或独立审计）。审查是本次验证动作的内部检查步骤，不是独立交付物——不得把被验交付物的「实现 → 验证 → 审查」拆给不同窗口接力，同一验证任务由当前 owner 一次做完。审查维度：跨模块一致性（命名不一致、数据格式冲突、隐式约定被破坏）、全局模式（重复逻辑、错误处理不统一）、盲点（所有 per-task 审查遗漏的问题）。输出 🔴 阻断 / 🟠 重要 / 🟡 建议。优化：如果只有 1 个交付物 → 合并到 per-task 审查。处理：🔴 → 回修复阶段；🟠+🟡 → 记录，用户判定。

审查独立性原则：

• 禁止在审查 prompt 中预判：❌ "这个模块应该没问题"（诱导降低标准）；❌ "忽略 X 方面的检查"（除非注明理由）；❌ 预先降级预期发现。
• 计划规定的缺陷 → 标注 🟠 "plan-mandated"→ 用户决定。
• 控制器角色：✅ 选审查 prompt、确保审查者访问所有文件、汇总结果；❌ 在审查完成前评估/过滤发现；❌ 在审查后 downgrade 发现。

修正循环

自动层发现不合规时：

第 0 步（仅首轮）：合约审视 — 在生成修正 prompt 之前，先判断不合规的根因：多个子任务都因同一合约条目不合规 → 可能是合约定义有问题，向用户提议审视合约；风险标注审查（检查 2）发现"合约建议修正"标注 → 优先审视这些标注，判断是否应修复合约而非修正代码；只有单个子任务不合规且无风险标注 → 进入正常修正流程。

第 1 步：生成修正 prompt：

你的子任务 {task-id} 在集成验证中发现以下不合规项：
- [{检查X}] 期望: {expected}，实际: {actual}，位置: {file:line}
请修正实现使接口与合约一致。
如果你认为合约定义本身有误（而非你的实现问题），请在修正报告中标注 [合约异议] 并说明原因——不要默默按错误合约实现。
修正后由该交付物 owner 端到端重做自己的修正（L2 子智能体原样重跑；L3 member 在自己域内闭环），**不要按「先读合约→再改实现→再补测试」拆阶段接力**。

第 2 步：派发修正执行者 — 派给该交付物 owner（L2 新建 Agent / L3 member），传入修正 prompt + 合约条目；同一交付物的修正不拆窗口。

第 3 步：重试验证 + 跨模块影响检查 — 修正完成后：重新走自动层（检查 1–4.5），同时检查是否引入了新的不合规项（对比修正前后的检查结果差异）。跨模块影响检查：如果该任务被其他任务依赖（检查合约中的 depends_on），验证修正后的接口签名是否仍与依赖方兼容。如果该任务修改了导出的函数签名或类型定义 → 对所有依赖此任务的下游任务标记 ⚠️ "上游接口变更，需验证兼容性"。同时标记所有传递依赖方（B 依赖 A，C 依赖 B，A 修改后 C 同样受影响）为 ⚠️ "需验证传递兼容性"。

第 4 步：判定：

• ✅ 全部通过 → 进判断层
• ⚠️ 执行者标注 [合约异议] → 暂停修正循环，审视合约。合约确实有误 → 修复合约 → 重新派发所有受影响任务；合约无误 → 继续修正
• ❌ 仍有不合规 → 轮次+1
• ❌ 第 3 轮后仍不通过 → 标记 REQUIRES_MANUAL_INTERVENTION，建议审视合约
• ❌ 如果 >50% 任务标记 REQUIRES_MANUAL_INTERVENTION → 建议重新审视整个合约——可能是拆解粒度或接口定义存在系统性问题，考虑重新运行「myworkflow-task-dispatch」

生成验证报告

写入 .task-manifest/verification-report.md。报告必须包含以下表格和内容（小规模 ≤3 个子任务只保留必填字段）：

# 集成验证报告 — {项目名}
> 验证时间: {ISO 8601 时间戳}
 
## 总览
| 任务 ID | 自动层 (1–4.5) | 修正轮次 | 判断层 (5–7.5) | 最终状态 |
|---------|---------------|---------|---------------|---------|
| {task-id} | ✅ 全部通过 / ⚠️ 检查2失败 / ❌ 检查1+2+3失败 | N | ✅ / — | ✅ 通过 / ❌ 需人工介入 |
 
**汇总**: N/N 通过，N 需人工介入
 
## 自动验证详情
### {task-id}
| 检查项 | 结果 | 备注 |
|--------|------|------|
| 1. 文件存在性 + 跨任务路径唯一性 | ✅/❌ | [文件+大小，是否空壳；路径冲突] |
| 1.5. 副作用任务执行 | ✅/❌/⚠️/— | [执行的命令 + 退出码 + 失败输出；无 test_passes 条目填 —] |
| 2. 导出签名匹配 | ✅/❌/⚠️ | [导出名+缺失项，第 N 轮修正情况] |
| 3. 声明-合约一致性 | ✅/❌ | [覆盖情况/额外导出] |
| 4. 自检诚实度 | ✅/⚠️ self-check-unreliable | [不一致项] |
| 4.5. 规范符合性 + 代码质量 | ✅/🔴/🟠/— | [漏做/多做/误解规范；关注点分离/错误处理/DRY/边界；未开深度审查模式填 —] |
| 修正轮次 | N | [每轮修正内容与结果] |
 
> 4.5 的审查结论若有多条发现，可在该任务下追加子表：`| 维度（规范符合性/代码质量） | 发现 | 严重度 | 处理（🔴 派发修复 / 🟠 记录待用户判定） |`。
 
## 修正历史
| 任务 ID | 轮次 | 不合规项 | 修正结果 |
|---------|------|---------|---------|
| {task-id} | N | [检查项+期望vs实际] | ✅/❌ |
 
## 跨模块兼容性
| 依赖关系 | 状态 | 备注 |
|---------|------|------|
| {task-A} → {task-B} | ✅/⚠️ | [类型名/参数/路径匹配情况] |
 
## 质量抽查
| 抽查任务 | 发现 | 严重程度 |
|---------|------|---------|
| {task-id} | [接口契约/错误处理/空函数体/TODO] | 🔴/🟠/🟡/🔵 |
 
## 集成风险
| 风险 | 相关任务 | 建议 |
|------|---------|------|
| [语义不匹配/隐含假设冲突/缺失接口] | {task-id} | [用户决定或修复建议] |
 
## 全分支代码审查（检查 7.5）
> 分支级检查，不归属任何单个任务；只有 1 个子任务时合并进该任务的 4.5，此节填 `—`。
**审查范围**: `git diff $(git merge-base {base-branch} HEAD)...HEAD`（base = {main/master}）
| 维度 | 发现 | 严重度 | 处理 |
|------|------|--------|------|
| 跨模块一致性 | [命名不一致/数据格式冲突/隐式约定被破坏] | 🔴/🟠/🟡 | [🔴 回修复阶段 / 🟠🟡 记录待用户判定] |
| 全局模式 | [重复逻辑/错误处理不统一] | 🔴/🟠/🟡 | 同上 |
| 盲点 | [所有 per-task 审查遗漏的问题] | 🔴/🟠/🟡 | 同上 |
 
## 需人工介入
**任务**: {task-id}
**问题**: [3 轮仍不通过的详细原因——文件缺失/骨架代码/自检造假/无改善]
**建议**: [审视合约是否模糊 / 拆分更细粒度子任务 / 移除 self-check 改自动化编译检查]

示例参考（user-auth-system）：

• build-shared-types：检查 1–4.5 全部 ✅（无 test_passes 条目、未开深度审查模式，1.5 与 4.5 记 —），0 修正轮次 → 通过。
• build-auth-logic：检查 2 第 0 轮 ❌（loginUser 参数为 (username, password) 而合约要求 (req: LoginRequest)）→ 第 1 轮修正后 ✅ → 通过。
• build-auth-middleware：第 3 轮后仍缺 verifyToken.ts、auth.ts 仅 // TODO 骨架、self-check 持续造假 → 标记 REQUIRES_MANUAL_INTERVENTION，建议拆分为 verifyToken 与 authenticate 两个子任务并附加单元测试要求。

后置更新步骤

1. 确认验证报告已生成。
2. 确认所有通过的模块可集成。
3. 处理需人工介入的模块。
4. 清理修正临时文件（可选保留用于审计）。

完成标志

• [ ] 自动验证层（检查 1–4.5）对所有子任务完成（未启用的 1.5 / 4.5 已记 —）
• [ ] 所有修正循环已结束（通过或升级人工介入）
• [ ] 判断验证层（检查 5–7.5）已完成（7.5 已执行或已说明为何跳过）
• [ ] 跨模块兼容性无阻塞问题
• [ ] 验证报告已生成
• [ ] 需人工介入的项目已向用户报告

证据口径映射（与 myworkflow-subagent-protocol 一致，不重复其长段）

• produced（回执）：验证报告与修正记录已产出（路径 + 结论摘要）；只有报告路径不算完成。
• verified（可复核证据）：自动层每项检查都有真实命令 + exit code + 关键输出；有产物 sha256/runId 时一并写入报告。
• accepted（owner 验收）：判断层全过且报告落盘（.task-manifest/verification-report.md）才算通过；超时、无输出、非空文件都不算完成。
• 修正轮次只是过程，不等于 accepted；轮次上限（≤3）用完仍不通过 → 标记需人工介入。

协作语义与等待纪律（硬规则）

• L3 只用于大型、长程任务：把一个超大任务切成若干相互独立的部分，模仿真人团队「各自独立工作 → 沟通 → 整合」；每个 member ≈ 一个 L2（端到端做完自己那份再整合）。不要因为“任务大”就建团——要因为“需要持续负责人与并行独立交付”才建团。
• member 之间可直接沟通：任务切分不可能一开始就完美，执行中会出现交叉、重叠、接口变化；member 之间直接协商比“上报 leader 再转发”高效。leader 只在边界冲突需裁决、目标变更、验收标准修改时介入；改了交付边界同步 leader（记录在案），不必阻塞等批准。
• member ≠ leaf：leaf 寿命绑定单个任务、只与派发者沟通、任务完成即结束；member 长期存在（睡眠/随时唤醒复用），管一个领域、可跨任务复用、可直接与其它 member/leader 沟通。
• 等待纪律（硬规则）：本 skill 涉及长命令 / 测试 / 构建 / 网络请求时，≥30 秒一律放后台任务或派 leaf，本回合内不等待（不轮询、不 sleep、不反复检查同一任务）；结果靠二次唤醒取。leader 与 member 都不阻塞。

证据纪律（反臆测 E1–E6）

• E3 检查零猜想（严格）：每条判定必须绑定可复核证据——命令 + exit code（含末行输出）/ 文件 + 行号 / runId / 日志片段；只写“跑过了”“看过了”不算证据。不能核实的写「未核实 / 无法判定」，禁止用「应该/大概/可能」下结论。反例：报告写“接口应该没问题”却无命令与输出 → 判违规，退回补证据；补齐前该检查项不得标通过。
• E6 交叉核对：关键事实至少两个独立来源（源码 + 运行输出 / 文档 + 实测）；两源冲突时以可执行结果为准，并记录冲突双方的出处、各自结论与实测判定，不得静默取一方。检查点：仅单一来源、或冲突未实测 → 标「未核实 / 无法判定」。
• 证据口径：判定分三档——通过（证据齐全且可复核）、不通过（失败输出可复核）、未核实（缺证据）；报告每条结论后附证据引用，便于他人复跑。
• 衔接：规则要有出处，判定不凭记忆，先读源码/跑命令（E1）；证据不足先写「假设（未核实）」并立即核实（E2）；禁止编造证据、行号、runId、日志（E5）——宁可少写，不可补造。

E7 代价优先（谨慎执行）

• 检查结论写「可以改 / 没问题」时，必须附代价与风险说明：影响面、是否不可逆、能否回滚；缺一项只算「未核实」。
• 高风险变更（覆盖生产文件、改历史、发布、重启、删数据）的核对必须含备份、预演要求与回滚路径。