@xenonbyte/req-2-plan 0.2.3 → 0.4.0

package/docs/req-to-plan-design.md

@@ -1,277 +0,0 @@
-# req-to-plan — 需求与设计文档（项目权威 SSOT）
-
-> 本文档是 req-to-plan 的权威入口文档（single-source-of-truth）：承载背景、目标、
-> 架构与质量模型。它是 `docs/` 下唯一保留的文档，因此**自包含**——不依赖任何外部
-> 文档。机器事实（exit code、状态、状态转移、tier 表、命令与参数名）的唯一真相在
-> 代码 `tools/workflow_cli/`，本文档只做高层描述、不复述，以免成为漂移源。本文档与
-> 代码在机器事实上冲突时，以**代码为准**，本文档即缺陷。
->
-> **可执行性边界**：本文档里的"强制"首先是产品/流程规则；其中由 CLI 机械检查的子集见
-> §5.5。尚未机械化的语义规则必须由 agent 生成、子 agent 审查和人工/主控检查点执行。
-
----
-
-## 0. 本文档的范围
-
-**本文档负责**：问题陈述、目标与质量底线、端到端架构、跨阶段质量模型。
-
-**本文档不负责（也不复述）**：
-
-- 机器事实——exit code、状态、`ALLOWED_TRANSITIONS`、tier 表、命令与参数名。它们由
-  代码 `tools/workflow_cli/` 定义，本文档只引用模块名、不抄写其值。
-- 载体语法——具体 CLI 参数、`r2p-*` agent 快捷命令、安装细节。它们以代码与
-  `--help` 为准。
-
----
-
-## 1. 背景
-
-### 1.1 问题
-
-把一个原始需求变成"工程师或 agent 不必重新决策范围就能执行"的东西，是绝大多数"AI 把
-东西做错"的根源。失败几乎不在编码环节，而在上游，且反复呈现四种形态：
-
-1. **范围漂移**——做出来的不是被要求的，因为设计开始前范围从未被冻结。
-2. **歧义下推**——一个未决问题（用哪个方案？契约是什么？）被悄悄交给离决策权最远的
-   人解决，通常是实现者在猜。
-3. **空心规格**——一份*看起来*完整（段落齐全）但实质为空的计划：不可测的"契约"、
-   套话式的否决理由、把目标复述一遍的验收标准。
-4. **仍在做决策的计划**——一份"计划"里还留着未决的设计选择，执行时不得不重开设计。
-
-单遍 prompting（"给我写个 X 的计划"）把这四种失败压进同一遍、没有任何检查点，于是
-一个都抓不住。
-
-### 1.2 方法
-
-req-to-plan 用**分阶段、门控的流水线**替代单遍：每个阶段只拥有一种权威、不能行使别的
-阶段的权威，且必须通过一道可证伪的质量门、再由人工/主控检查点冻结，才能交给下游：
-
-```
-原始需求
-  -> 需求简报 Requirement Brief        (拥有：做什么、范围、验收)
-  -> 风险与问题发现 Risk & Question Discovery (拥有：阻塞项、假设、风险、输入)
-  -> 设计 DESIGN                        (拥有：唯一方案 + 理由 + 边界)
-  -> 规格 SPEC                          (拥有：可测的行为契约)
-  -> 计划 PLAN                          (拥有：执行器中立的任务、排序、回滚)
-```
-
-### 1.3 在生态中的定位
-
-这条流水线属于**规格驱动开发（spec-driven development）**家族（GitHub spec-kit 的
-specify→plan→tasks；AWS Kiro 的 requirements→design→tasks）中加固的一员。相比该家族
-额外加了：
-
-- **Stage-Gate 纪律**——每次交接有一道质量门（进入/退出标准）加一个人工/主控检查点。
-- **双向可追溯**——每个下游条目都导入一个稳定的上游 ID 并必须闭合它
-  （闭合标记或路由；具体闭合取值以代码为准），从而需求可追到任务、也可反追。
-- **变更影响路由**——下游阶段发现上游缺了某个决策时，往回路由给拥有它的阶段而不是
-  自己猜（上游缺口路由；具体状态名以代码 `RunStatus` 为准），并伴随失效标记（`stale`）级联
-  （这是设计原则；当前 CLI 操作面的实现边界见 §6）。
-- **Agent/CLI 分离**——CLI 管状态、校验结构；Agent 生成语义内容。CLI 从不写 artifact
-  正文。
-
----
-
-## 2. 目标与非目标
-
-### 2.1 目标
-
-- **G1 — 设计前冻结范围。** 需求简报检查点批准前不开始设计；DESIGN 不得重定义需求。
-- **G2 — 权威本地且不可转移。** PLAN 不发明契约；SPEC 不发明设计；DESIGN 不重定义
-  需求；风险发现把阻塞项路由给其拥有者而不是自己解决。
-- **G3 — 每个 artifact 可证伪。** 每条承重断言都带一个能证明它错的东西（可测条件、
-  反例、决策的失效条件）。见 §5。
-- **G4 — 评审稳定地找缺陷，而不是只查缺段落。** 检查点评审按利益相关者视角、配每阶段
-  缺陷分类来读，从而抓住*空心达标*（段落在但是空的），而不是橡皮图章。
-- **G5 — 完整可追溯。** 检查点批准前，每个导入的上游 ID 都有且仅有一个下游闭合状态。
-- **G6 — 投入随复杂度伸缩。** 复杂度 tier 设定刚性下限；小任务用轻量 artifact，但
-  绝不跳过 DESIGN。
-- **G7 — 执行器与平台中立的产物。** PLAN 可被另一个 agent 或工程师在 claude / codex /
-  gemini 上直接执行，无需重新决策方向。
-
-### 2.2 质量底线（可度量的退出条件）
-
-一个阶段 artifact 只有在满足以下条件时才算*完成*：
-
-- 每条契约 / 决策 / 任务都**具体且可测**（评审者能说出"什么观察会证伪它"）；
-- 每个导入的上游 ID 都有显式**闭合**状态；
-- 每个选定决策都记录其**被否决的备选项，以及该决策应被重新考虑的条件**（不只是"它为何
-  好"）；
-- 没有任何段落是**空心**的——段落在但内容套话，与缺段落一样判定为不合格。
-
-### 2.3 非目标
-
-- **不是执行器。** req-to-plan 止步于一份获批的 PLAN，不写应用代码。
-- **不绑定实现栈。** PLAN 执行器中立。
-- **不自动批准。** 子 agent 产出证据与建议；冻结 artifact 必须由人工/主控检查点裁决。
-- **不是通用文档工具。** 它只治理*本工作流*的 artifact。
-
----
-
-## 3. 核心概念
-
-下表只作定位。**具体取值（状态串、tier 名、命令/参数名）一律以右列代码为准，本文档
-不复述**——这是 §0 的纪律。
-
-| 概念 | 一句话含义 | 代码归属（取值的唯一真相） |
-|---|---|---|
-| Work-id / run | 一个需求的工作流实例（id 形如 `WF-<日期>-<slug>`） | `models.py`, `state.py` |
-| Artifact | 带 YAML frontmatter、按阶段顺序编号的阶段产物文件 | `artifact.py` |
-| Stage | 工作流阶段枚举；包含入口 `raw_requirement`、五个规划阶段和关闭哨兵 | `models.py`（`Stage`） |
-| Run 状态 | run 生命周期状态机；取值与合法转移以代码为准 | `models.py`（`RunStatus`, `ALLOWED_TRANSITIONS`） |
-| Artifact 状态 | 单个 artifact 的状态字段，与 run 状态是**两套不同取值** | `artifact.py` |
-| Quality Gate | 阶段退出标准；CLI 机械检查结构子集，语义标准由检查点评审执行 | `gates.py`；语义标准见 §5 + 检查点评审 |
-| Checkpoint | 人工/主控冻结决策；唯一能批准（approve）的环节 | `state.py` |
-| Tier | 复杂度下限，决定所需刚性；档位取值与估算以代码为准 | `tier.py`（`TierBase`）, `tier_keywords.yaml` |
-| 追溯链 | `Risk Plan Input → DESIGN Plan Input → SPEC-PLAN-* → PLAN item`，逐级闭合 | `models.py`, `state.py` |
-| 失效标记 | 下游导入了已变更上游输入时打的标记（如 `stale`） | `artifact.py` |
-
-**不可协商项**（使 G2 可执行的权威边界）：
-
-- 需求简报不选设计。
-- DESIGN 不重定义需求。
-- SPEC 不发明缺失的设计决策。
-- PLAN 不发明缺失的契约、不选执行器特定格式。
-- 子 agent 产出证据，不产出检查点批准。
-- 上游修复后，被修阶段必须重新通过其 Quality Gate 与 Checkpoint，下游 artifact 才能
-  再次被批准。
-
----
-
-## 4. 流水线
-
-除入口摄取外，每个规划阶段都是：**进入门 → 工作步骤 → Quality Gate → 检查点评审 →
-人工/主控检查点**。子 agent 审查在带代码定义的高风险 modifier 的 DESIGN / SPEC / PLAN
-上是强制要求，也是普通阶段的推荐审查方式；具体 modifier 取值与匹配规则以
-`tools/workflow_cli/` 为准。最终批准仍只能由人工/主控检查点完成。下表给各阶段的本质
-（权威/禁区/产物）。
-
-> **注意（诚实声明）：各阶段逐步执行的方法论——如何具体产出每种 artifact、各门的检查
-> 清单与模板——当前不在本仓库内。** 它随旧 `*-workflow.md` 文档一并移除，仅存于 git
-> 历史。本文档只确立权威边界与质量底线（§2、§5），不是逐步操作手册；CLI 代码做的是
-> 状态管理与结构校验，也不含语义方法论。需要逐步细节时，从 git 历史取回相应
-> `*-workflow.md` 并入本文档或另存，不要假设它能"运行时凭空生成"。现有 agent 模板只负责
-> 驱动 `r2p-*` 停点和命令，不提供完整 artifact 写作方法论。
-
-| 阶段 | 拥有的权威 | 不得做 | 关键产物 |
-|---|---|---|---|
-| **原始需求** | 捕获用户原始输入、生成 run 与 tier 初估证据 | 改写需求含义、补全范围 | `00-raw-requirement.md`、`01-intake-brief.md` |
-| **需求简报** | 目标、范围、非范围、验收、来源出处 | 选方案 | 稳定简报、范围清单、验收标准 |
-| **风险与问题发现** | 阻塞项、假设、风险、讨论点、下游输入 | 解决不属于自己的阻塞项 | 风险清单、设计触发器、spec/plan 输入 |
-| **DESIGN** | 唯一方案 + 理由、边界、迁移、回滚、变更点 | 重定义需求 | Option Analysis（推荐/最小/被否决）、变更点清单、Spec/Plan 输入 |
-| **SPEC** | 从 DESIGN 派生的可测行为契约 | 发明缺失的设计 | 契约（具体/可测/可追溯）、验收场景、`SPEC-PLAN-*` |
-| **PLAN** | 执行器中立的任务、排序、验证、回滚、停止条件 | 发明契约、选执行器格式 | `PLAN-TASK-*`、契约到任务映射、回滚/安全计划 |
-
----
-
-## 5. 质量模型（强制门控标准与执行边界）
-
-各门已经把*结构*管得很好；残余风险是**空心达标**——一份 artifact 通过了每一道结构门，
-实质却是空的。LLM 生成尤其易犯此病：它擅长把模板填得令人信服。质量模型是同时加固生成
-与评审、对抗空心的唯一杠杆，**以下各项是阶段完成的强制退出条件——不满足即判不合格，
-等同于缺段落，不再作为"建议"**。其中可被 CLI 机械检查的项目见 §5.5；其余项目必须在
-生成、子 agent 审查和检查点批准时执行。
-
-> **让每条承重断言可证伪，然后按"找反例"而非"查齐全"来评审。**
-
-### 5.1 生成——强制对比式、可证伪内容（门控）
-
-只要断言（"推荐方案：X"）就会招来套话。质量住在对比与翻转条件里。每条承重断言必须带一个
-**falsifier**：能证明它错的观察。门控要求：
-
-- **DESIGN**——对每个选定决策做 pre-mortem：「什么条件会让我们退回某个被否决方案？」
-- **SPEC**——每条契约必须带**一个通过示例 + 一个违反示例**（Specification by Example）。
-- **PLAN**——每个任务的验证步骤必须写明「什么结果算失败」。
-
-falsifier 字段天然抗套话：`收益：提升性能` 可以随便写；`失效于：突发请求超过限额 2 倍时，
-因固定窗口在突发中途重置而被放行` 写不出来就说明没想清楚。**缺 falsifier = 门不过。**
-
-### 5.2 评审——用 Perspective-Based Reading（多视角）替代单遍通读（门控）
-
-不再"派一个子 agent 评审 SPEC"，而是派**多个视角子 agent**，各自从一个利益相关者视角、
-带固定问题集（= 每阶段缺陷分类）读同一份 artifact。这是需求/设计评审中实证最强的技术。
-
-下列是几个**代表性原型视角**，用于示范问题集与审查身份；它们不穷尽——§5.4 可按阶段特化
-或扩充专门视角（如 SRE、迁移/回滚、成本对手、执行 agent）。每个阶段实际必须覆盖的最小
-视角以 §5.4 的阶段化表为准：§5.4 是强制规则，本节只提供视角的通用语义示范。一个 reviewer
-可以覆盖多个视角，但审查记录必须分别回答被覆盖视角的问题。缺少 §5.4 要求的阶段视角时，
-该检查点评审不构成有效评审：
-
-- **测试者**——"我能不能为每条契约写出一个会失败的测试？哪条不可测？"
-- **实现者**——"哪里欠规格到无法直接动手？哪里还藏着未解的设计选择？"
-- **对手/操作者**——"什么输入打穿它？哪条破坏性路径没有 guard？"
-- **追溯审计**——"每个导入 ID 的闭合是*真覆盖*还是空心？"
-
-### 5.3 修复——分级、局部、原视角复检（门控）
-
-- 评审发现项必须带 **severity**（blocker / major / minor）；minor 不阻断检查点，但
-  blocker / major 未闭合不得批准。
-- 一次修复只重验**受影响的导入条目**（用闭合 ID 圈定影响半径），不整篇重读。
-- **发现缺陷的那个视角复检其修复**，杜绝改一处、坏一处的评审循环。
-
-### 5.4 各阶段强制门控项
-
-本表是检查点评审的阶段化最低要求；它替代"每阶段固定同一组 reviewer"的理解。若代码或
-运行配置对某阶段增加高风险审查要求，新增要求与本表叠加。
-
-| 阶段 | 生成必带的 falsifier | 必覆盖的评审视角 | 要判为不合格的空心缺陷 |
-|---|---|---|---|
-| 需求简报 | 每条验收：证明其未达成的*可观测*结果 | 用户/操作者 + 测试者 | 验收不可观测；把目标复述当验收 |
-| 风险发现 | 每个风险：触发输入/条件 + 不处理的最坏结果 | 对手 + SRE | 风险无触发条件；风险未路由到拥有者 |
-| DESIGN | 每个决策：应退回某被否决方案的条件 | 实现者 + 迁移/回滚 + 成本对手 | 套话式否决理由；最小方案形同虚设 |
-| SPEC | 每条契约：一个通过示例 + 一个违反示例 | 测试者（写不出失败测试=不可测）+ 实现者 | 标"可测"却写不出测试；场景复述需求 |
-| PLAN | 每个任务验证：什么结果算失败 | 执行 agent + 回滚 + 追溯审计 | 任务藏隐含决策；验证不可判定；闭合对不上 |
-
-### 5.5 当前实现覆盖与缺口
-
-当前 `tools/workflow_cli/` 已经机械执行的检查子集如下；其中一部分属于 Quality Gate，另有
-检查点批准前置的独立检查。具体 exit code、字段名、锚点格式、modifier 取值和命令参数以
-代码与 `--help` 为准，本文档只记录实现覆盖范围：
-
-- tier 必须先锁定；
-- artifact 正文不能为空；
-- 被引用的上游 ID 必须带显式闭合标记；
-- artifact 内定义的 ID 不能重复；
-- SPEC 必须包含非空、非占位的外部文档检查清单，或显式说明没有外部依赖；
-- 达到代码定义任务锚点要求的 PLAN 必须包含任务锚点；启用 TDD 骨架要求的任务必须提供带非空
-  信息标记且正文非空的 `Skeleton` 代码块；
-- 命中代码定义高风险 modifier 的 DESIGN / SPEC / PLAN，在检查点批准前必须存在版本匹配的
-  subagent review 文件；文件是否确由只读 reviewer 生成、内容是否有效，仍由 agent / 主控语义审查确认。
-
-当前尚未由 CLI 机械证明、但仍是检查点批准前的强制语义要求：
-
-- falsifier / pre-mortem / 通过与违反示例是否真实有效；
-- 多视角审查是否覆盖 §5.2 的视角，以及审查发现是否按 severity 闭合；
-- subagent review 文件是否来自隔离只读审查，以及是否覆盖对应阶段的必要视角；
-- `DEFERRED`、`N/A`、`OUT-OF-SCOPE` 等闭合是否合理，而不是绕过追溯；
-- PLAN 是否真正执行器中立、没有隐藏设计选择；
-- 下游重新派生是否完整反映了上游修复。
-
-因此，当前可行的落地方式是：CLI 阻断结构性缺陷，agent 负责生成语义内容，子 agent /
-人工/主控检查点按 §5.1-§5.4 阻断空心达标。若希望这些语义标准也自动化，需要在
-`gates.py` 或独立审查器中新增可测试规则，并为对应 fixture 添加回归测试。
-
----
-
-## 6. 变更传播
-
-下游阶段绝不悄悄修补已批准的上游 artifact：发现上游缺口时，应把缺口交还给拥有该决策的
-阶段；拥有阶段修复并重新通过其 Quality Gate + Checkpoint；受影响的下游导入项应失效并重新
-派生（若 ID 无法干净 remap 则整篇重建）后再重新过门。
-
-**当前实现边界**：上游缺口路由的状态模型（`RunStatus.UPSTREAM_GAP_ROUTING`、`OpenRoute`、
-`StaleArtifact` 及相关 state helper）现已通过 operator 操作面暴露。未关闭的 run 用 `gap-open`
-把缺口路由回 owner 阶段——下游 artifact 被标记失效、其已批准 checkpoint 失效、run 退回 owner
-的重做态；owner 重做并通过 `gate-quality` 后用 `gap-resolve` 闭合路由，再经常规
-review/approve/advance 重新派生下游。二者也暴露为 `r2p-gap-open` / `r2p-gap-resolve` shortcut。
-已在 PLAN 检查点关闭的 run 仍用 `run-reopen` 重开。路由与失效进度在 `status-run`
-（`open_routes_detail` / `stale_artifacts` / `outstanding_stale`）与 `status-next` 可见。
-**具体命令语法、状态名与合法转移集合一律以代码和 `--help` 为准。**
-
----
-
-## 约定
-
-- 本文档语言：简体中文。
-- §5 质量模型为**强制门控标准**，非建议。
-- 机器事实唯一真相在 `tools/workflow_cli/`；本文档只做高层描述。