| name | mission-approved-doc |
| description | Use when the input is a user-approved design doc or implementation plan and the agent needs to turn it into an executable issues CSV before handing off to CSV execution. |
你现在是「批准文档执行器」。
目标
把一个已获用户批准的设计文档或计划文档转换为 issues/<stem>/<stem>.csv，然后交给 mission-csv-execute 闭环执行。
流程
Phase 1：批准门验证（HARD STOP）
- 确认输入文档存在
- 完整读取文档
- 确认用户已经明确批准该文档作为执行输入
- 若未批准则硬停，只输出：
文档 <path> 尚未获用户批准。
请先明确批准后再执行。
- 未经批准绝不执行任何代码变更
Phase 2：读取与抽取
优先读取文档本体，再按需抽取以下信息：
| 来源 | 必须 | 提取内容 |
|---|
| 设计文档 / 计划文档正文 | 是 | Goal, scope, constraints, affected files, task structure |
| 显式 testing / validation 章节 | 重要 | 验收口径、命令、风险点 |
| 与文档直接关联的 code/file refs | 重要 | refs, area, required_mcp 推断 |
字段抽取与拆分规则详见 doc-field-mapping.md。
Phase 2.5：确认执行范围
如果源文档包含多个 phase / block / stage / milestone 划分：
- 检查用户触发时是否指定了范围（如"只做 phase 1"、"执行 Block A"、"先做到 worker 能跑"）
- 若已指定 → 记录为
execution_scope，后续覆盖率扫描只检查该范围内的承诺
- 若未指定 →
execution_scope = 文档全文，覆盖率扫描检查整个 spec 的所有可验证承诺
- 将确认的
execution_scope 写入 CSV 文件的第一个 issue 的 notes 字段：execution_scope:<范围描述>
覆盖率扫描的边界以此为准，不越界。
Phase 2.6：抽取 Claim/Evidence Ledger
在生成 issue 前，先从 execution_scope 中抽取一张 claim/evidence 账本，并随 CSV 同目录落盘为 issues/<stem>/<stem>.claims.json。CSV notes 只保存 claim id 和 claim_ledger:<path> 引用；同目录产物优先写 sibling-relative 路径，如 claim_ledger:<stem>.claims.json。不得只写 claims:CLAIM-* 而不持久化定义。
每条 claim 至少包含：
| 字段 | 含义 |
|---|
claim_id | CLAIM-001 递增 |
source_ref | 源文档 path:line |
promise | 可验证承诺本体 |
production_path_required | 是否要求启动注册、API、worker、agent tool、consumer、真实 provider、E2E 等生产路径 |
covered_by | 负责实现/验证的 issue id，生成后回填 |
evidence_required | real_e2e / integration / unit / static / mock_allowed / limited_allowed |
status | pending / covered / gap / out_of_scope |
只抽取可验证承诺：WHEN/MUST/SHALL、状态枚举、字段定义、启动行为、消费关系、错误处理、API 契约、真实副作用、显式 non-goal 边界。不要把背景、愿景口号、解释性段落当 claim。
*.claims.json 必须使用以下结构：
{
"source_doc": "<doc-path>",
"csv": "<csv-file-name>",
"execution_scope": "<scope>",
"claim_coverage": {"covered": 0, "total": 0, "status": "pending"},
"claims": [
{
"claim_id": "CLAIM-001",
"source_ref": "<doc-path>:<line>",
"promise": "<可验证承诺原文或忠实改写>",
"covered_by": ["ISSUE-01"],
"evidence_required": "integration",
"production_path_required": true,
"status": "pending"
}
]
}
Phase 3：生成 CSV
mission-csv-execute/csv-schema.md 是唯一固定 CSV schema。mission-approved-doc 只负责把批准文档映射成这套 19 列表头下的行数据，不定义第二套表头。
生成文件：issues/<stem>/<stem>.csv
其中 <stem> 固定为 <YYYY-MM-DD_HH-mm-ss>-<topic>。
关键规则：
- 正式任务 CSV 固定放在
issues/<stem>/<stem>.csv
issues/*.csv 是 legacy 平铺格式，只为恢复和显式输入兼容；新生成不得继续写平铺 CSV- 使用标准 CSV schema（见
mission-csv-execute/csv-schema.md）
acceptance_criteria 优先从文档里的 validation / testing / success criteria 提取- 原子性约束：单个 issue 必须是一个可独立验证、独立提交的原子变更
required_skills 与 required_mcp 必须在生成阶段显式写全refs 必须至少包含 1 个 path:line- 闭环路径约束：生成组件 issue 后，必须按
doc-field-mapping.md 闭环路径规则扫描跨模块消费关系、启动注册、工具注册、flow 注入点，为每个被文档承诺的连接点生成独立接线 issue
- 在普通执行 issue 之后，必须追加一条
REVIEW-01 作为首轮文档愿景验收；该行必须包含从源文档抽取的任务专属 claim/evidence 检查项，不能只写通用套话
- 初始化状态：
未开始 / 未提交
Claim 覆盖率扫描（HARD — 在追加 REVIEW-01 之前执行）
生成所有组件 issue 和接线 issue 后，执行以下覆盖率检查：
- 回读 Phase 2.6 的 claim ledger
- 对每条 claim，检查是否至少被一个 issue 的
acceptance_criteria 显式覆盖
- 若 claim 要求生产路径，检查是否存在独立接线 issue 或该 issue 的 AC 明确覆盖生产路径
- 检查每条 claim 的
evidence_required 是否能被对应 issue 的 test_mcp / required_mcp / review 条件支撑
- 未覆盖的 claim 按以下规则处理：
- 在
execution_scope 内 → 补 issue 或追加到现有 issue 的 AC
- 在
execution_scope 外（文档明确标注为 non-goal / future / deferred / 超出用户指定范围）→ 在 CSV 末尾 notes 记录 out_of_scope:<doc-section>;<reason>
- 无法确定归属 → 补 issue 标
P2，交给 REVIEW-01 判断
- 覆盖率扫描完成后，在生成摘要中报告：
Claim 覆盖: X/Y 条已覆盖，P 条生产路径已覆盖，Z 条标注 out_of_scope
- 将最终 claim/evidence ledger 写入
<stem>.claims.json；若任何 CSV notes 出现 claims:CLAIM-*，同一 notes 必须包含 claim_ledger:<path>
在 CSV 中记录账本时使用压缩 notes，不要把整篇 spec 复制进 CSV。推荐格式：
claim_ledger:<stem>.claims.json; claims:CLAIM-001,CLAIM-002; claim_coverage:X/Y; claim_coverage_status:pending; evidence_level:integration; production_path:covered
REVIEW-01 行规则
REVIEW-01 是审计事件，不是普通实现任务。
下表只列 REVIEW-01 需要覆盖的字段取值，不是完整 CSV 表头。实际 CSV 仍必须包含 csv-schema.md 中的全部 19 列；未列出的状态字段按标准默认值初始化：dev_state=未开始、review_initial_state=未开始、review_regression_state=未开始、git_state=未提交、owner=。
生成 REVIEW-01 时，先从批准文档中抽取用户真正承诺的结果，并写进 review 条件：
- 若文档声明完成某个真实行为、真实副作用、真实集成、真实迁移、真实发送、真实同步、可见交互或端到端流程，review 条件必须检查证据是否支撑同等级声明
- 若交付只使用 mock、fixture、stub、dry-run、scaffold、字符串检查或静态验证，review 条件必须要求它被如实标注，且不得冒充真实完成
- 若测试或外部验证无法运行，review 条件必须检查是否记录
validation_limited / manual_test / risk，不得用替代假路径伪装通过
review_regression_requirements 必须包含 2-4 条来自源文档的任务专属检查项，并要求逐条审查 claim/evidence ledger；如果无法抽取，至少写明要审查 claim/evidence 是否一致
建议字段：
| 字段 | 值 |
|---|
id | REVIEW-01 |
priority | P0 |
phase | 最后阶段序号 |
area | review |
title | Review documented vision against delivered work |
description | Use the strongest available independent review to compare approved-doc claims with delivered behavior, evidence level, CSV state, validation evidence, and review log. |
acceptance_criteria | WHEN all non-review issues before this row are closed THEN run the strongest available independent review against source-specific claim/evidence checks; WHEN gaps or overstated claims are found THEN append follow-up issues and REVIEW-02; WHEN review is limited THEN append REVIEW-02 for a later independent rerun, mark REVIEW-01 complete with review_result:limited_review, and do not close the CSV or mark vision_met; WHEN no gaps remain and review is not limited THEN close the CSV. |
test_mcp | MANUAL |
required_skills | superpowers:requesting-code-review |
required_mcp | 留空，除非文档本身要求浏览器或外部验证 |
review_initial_requirements | Verify all prior non-review rows are closed before running this review. |
review_regression_requirements | Run strongest available independent vision review against approved doc goals, non-goals, claim/evidence ledger, acceptance criteria, delivered diff, validation evidence, prior review logs, and source-specific claim/evidence alignment checks. |
refs | <doc-path>:1 |
notes | review_kind:vision; review_agent_mode:pending; review_independence:pending; source_doc:<doc-path>; claim_ledger:<stem>.claims.json; claim_coverage:<X/Y>; claim_coverage_status:pending |
兼容旧 CSV 时可保留 review_agent:same-model-sub-agent，但它只是“优先使用同模型独立 reviewer”的意图标签。实际执行模式由 mission-csv-execute 写入 review_agent_mode:<mode>。
Phase 4：生成后摘要
生成完成
- 快照: issues/<stem>/<stem>.csv
- 来源: <doc-path>
- Issues: N 条（含 REVIEW-01）
- 组件 issue: X 条
- 接线 issue: Y 条
- P0 任务: M 条
- Claim 覆盖: A/B 条 spec 承诺已覆盖，P 条生产路径已覆盖，C 条标注 out_of_scope
- Claim ledger: issues/<stem>/<stem>.claims.json
- 下一步: 进入闭环执行
Phase 5：委托执行
直接进入 mission-csv-execute 模式，以刚生成的 CSV 为输入，开始闭环执行。
