@xenonbyte/req-2-plan 0.2.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 xenonbyte
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,172 @@
+English | [简体中文](README.zh-CN.md)
+
+# req-2-plan
+
+[![npm version](https://img.shields.io/npm/v/%40xenonbyte%2Freq-2-plan.svg)](https://www.npmjs.com/package/@xenonbyte/req-2-plan)
+[![node](https://img.shields.io/node/v/%40xenonbyte%2Freq-2-plan.svg)](https://nodejs.org)
+[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
+
+> Turn a raw requirement into an approved, executor-neutral implementation PLAN — the same staged workflow across Claude Code, Codex, and Gemini.
+
+`req-2-plan` installs and manages the `r2p` requirement-to-PLAN workflow for AI
+agent platforms. The workflow is a staged, gated pipeline: a requirement moves
+through **requirement brief → risk discovery → DESIGN → SPEC → PLAN**, and each
+stage must clear a quality gate and a human/main checkpoint before it hands off.
+The result is a plan another agent or engineer can execute without re-deciding
+scope.
+
+The npm package is an installer. From one shared source it generates per-platform
+agent skills and commands and installs them into Claude Code, Codex, and Gemini,
+so the workflow behaves identically on all three.
+
+## Features
+
+- **Staged, gated pipeline** — every stage clears a quality gate and a checkpoint before handoff; nothing advances on a guess.
+- **One lifecycle CLI** — `r2p install`, `r2p uninstall`, `r2p status`, `r2p version`, `r2p help`, using only the Python standard library.
+- **Multi-platform from one source** — generates skills for `claude`, `codex`, and `gemini`.
+- **Owned-only, manifest-backed install** — uninstall removes only files `r2p` created; pre-existing user files are backed up and preserved.
+- **Compact agent skills** — eight `r2p-*` wrappers drive the daily loop.
+
+## Supported platforms
+
+| Platform | Skill format |
+|---|---|
+| `claude` | Command files (`commands/r2p-*.md`) |
+| `codex` | Skill directories (`skills/r2p-*/SKILL.md`) |
+| `gemini` | Command TOML (`commands/r2p-*.toml`) |
+
+## Installation
+
+Requirements: **Node.js 18+** and **Python 3** (available as `python3` or `python`).
+
+```bash
+npm install -g @xenonbyte/req-2-plan
+```
+
+Check the lifecycle CLI:
+
+```bash
+r2p version
+r2p status
+r2p help
+```
+
+> [!NOTE]
+> The lifecycle commands need only the Python standard library, but the daily
+> `r2p-*` skills depend on `pyyaml`. Install it from a checkout with
+> `python3 -m pip install --user -r requirements.txt`, or directly with
+> `python3 -m pip install --user "pyyaml>=6.0"`.
+
+`r2p install` writes platform templates into each agent's home directory, shared
+command wrappers under `~/.req-to-plan/bin/`, and a manifest at
+`~/.req-to-plan/install/<platform>.yaml`. The manifest records every managed path
+so uninstall removes only files `r2p` created and restores backups for files that
+existed beforehand.
+
+## Usage
+
+### Quick start
+
+```bash
+r2p install                       # install all platforms (default)
+r2p-start "Add rate limiting"     # start a workflow run
+r2p-continue                      # advance it stage by stage
+r2p status                        # see what is installed
+```
+
+### Lifecycle commands
+
+Install all platforms, one platform, or a comma-separated list:
+
+```bash
+r2p install
+r2p install --platform claude
+r2p install --platform claude,codex,gemini
+```
+
+Report install status per platform — installed version, drift (missing files or
+version mismatch), or an invalid manifest. `status` is read-only; add `--json`
+for machine-readable output:
+
+```bash
+r2p status
+r2p status --json
+```
+
+Uninstall one platform, a list, or all (omit `--platform`):
+
+```bash
+r2p uninstall --platform claude
+r2p uninstall --platform claude,codex,gemini
+```
+
+> [!WARNING]
+> `r2p install` overwrites an existing install — no confirmation flag is needed.
+> Pre-existing user files are backed up before any overwrite, and uninstall never
+> deletes a file `r2p` did not create.
+
+### Workflow skills
+
+After install, the platform skills call these shared `r2p-*` wrappers — one per
+step of running a workflow:
+
+| Skill | What it does |
+|---|---|
+| `r2p-start` | Start a new run from a requirement (text, or `--file <path>` to read a document's contents). |
+| `r2p-continue` | Continue the active run — advance it to its next stop (gate, checkpoint, or repair). |
+| `r2p-status` | Inspect the current run, or all runs, read-only. |
+| `r2p-switch` | Point the active run at a different `--work-id`. |
+| `r2p-tier-lock` | Lock the active run's complexity tier (`--base light\|standard`). |
+| `r2p-reopen` | Reopen a closed run from a specific `--stage`. |
+| `r2p-gap-open` | Route an upstream gap on an open run back to its `--owner-stage`; downstream artifacts become stale and must be re-derived. |
+| `r2p-gap-resolve` | Close a gap `--route-id` after the owner stage is re-worked and passes `gate-quality`. |
+
+> [!TIP]
+> Add `~/.req-to-plan/bin` to your `PATH` to run the `r2p-*` wrappers directly:
+>
+> ```bash
+> export PATH="$HOME/.req-to-plan/bin:$PATH"
+> ```
+
+### When to use which skill
+
+Most runs only need `r2p-start`, then repeated `r2p-continue`. The other skills
+cover specific situations.
+
+**Lock the tier** — once per run, when `r2p-continue` stops with `tier_not_locked`:
+
+```bash
+r2p-tier-lock --work-id <id> --base standard --modifiers migration,safety --confirm
+```
+
+`--base standard` raises the rigor floor; the `migration`, `safety`, and
+`cross_project` modifiers force a subagent review at the DESIGN / SPEC / PLAN
+checkpoints.
+
+**Reopen a closed run** — revisit a run that was closed at the PLAN checkpoint,
+restarting from an earlier stage (this seeds a new linked run):
+
+```bash
+r2p-reopen --from <closed-id> --stage spec --reason "spec gap found"
+```
+
+**Route an upstream gap** — on an *open* run, when a later stage finds that an
+earlier stage owns a wrong or missing decision. `gap-open` sends the run back to
+the owner stage and marks everything downstream stale; after you re-work the
+owner past `gate-quality`, `gap-resolve` closes the route so the owner can be
+re-approved and the downstream re-derived:
+
+```bash
+r2p-gap-open --work-id <id> --owner-stage design --required-action "fixed-window burst flaw"
+# then re-work the owner stage until it passes gate-quality (r2p-continue guides this)
+r2p-gap-resolve --work-id <id> --route-id R-1
+```
+
+> [!NOTE]
+> Reopen is for a *closed* run; gap routing is for an *open* one. `r2p-continue`
+> walks you through both repair flows with `needs_repair` and `needs_gap_resolve`
+> stops.
+
+## License
+
+[MIT](./LICENSE) © xenonbyte

package/README.zh-CN.md

@@ -0,0 +1,158 @@
+[English](README.md) | 简体中文
+
+# req-2-plan
+
+[![npm version](https://img.shields.io/npm/v/%40xenonbyte%2Freq-2-plan.svg)](https://www.npmjs.com/package/@xenonbyte/req-2-plan)
+[![node](https://img.shields.io/node/v/%40xenonbyte%2Freq-2-plan.svg)](https://nodejs.org)
+[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
+
+> 把原始需求变成一份获批、执行器中立的实现 PLAN——同一套分阶段工作流，在 Claude Code、Codex、Gemini 上一致运行。
+
+`req-2-plan` 为 AI agent 平台安装并管理 `r2p` 需求到 PLAN 的工作流。该工作流是一条
+分阶段、门控的流水线：需求依次经过 **requirement brief → risk discovery → DESIGN →
+SPEC → PLAN**，每个阶段都要先过一道 quality gate 和一个人工/主控 checkpoint 才能交给
+下游。产出是一份另一个 agent 或工程师无需重新决策范围就能执行的计划。
+
+这个 npm 包是安装器：它从一份共享源生成各平台的 agent skill 与命令，并安装进
+Claude Code、Codex、Gemini，让工作流在三个平台上表现一致。
+
+## Features
+
+- **分阶段、门控流水线**——每个阶段交接前都通过一道 quality gate 和一个 checkpoint；不靠猜推进。
+- **单一生命周期 CLI**——`r2p install`、`r2p uninstall`、`r2p status`、`r2p version`、`r2p help`，只依赖 Python 标准库。
+- **一份源、多平台**——为 `claude`、`codex`、`gemini` 生成 skill。
+- **owned-only、manifest 背书的安装**——卸载只删 `r2p` 创建的文件；已存在的用户文件会被备份并保留。
+- **紧凑的 agent 技能**——八个 `r2p-*` wrapper 驱动日常循环。
+
+## Supported platforms
+
+| 平台 | 技能格式 |
+|---|---|
+| `claude` | 命令文件（`commands/r2p-*.md`） |
+| `codex` | 技能目录（`skills/r2p-*/SKILL.md`） |
+| `gemini` | 命令 TOML（`commands/r2p-*.toml`） |
+
+## Installation
+
+环境要求：**Node.js 18+** 与 **Python 3**（以 `python3` 或 `python` 提供）。
+
+```bash
+npm install -g @xenonbyte/req-2-plan
+```
+
+检查生命周期 CLI：
+
+```bash
+r2p version
+r2p status
+r2p help
+```
+
+> [!NOTE]
+> 生命周期命令只需 Python 标准库，但日常 `r2p-*` 技能依赖 `pyyaml`。在仓库 checkout
+> 内用 `python3 -m pip install --user -r requirements.txt` 安装，或直接
+> `python3 -m pip install --user "pyyaml>=6.0"`。
+
+`r2p install` 把各平台模板写入对应 agent 的 home 目录、在 `~/.req-to-plan/bin/` 下写入
+共享命令 wrapper，并生成 `~/.req-to-plan/install/<platform>.yaml` 清单。清单记录每个
+受管路径，因此卸载只移除 `r2p` 创建的文件，并为安装前已存在的文件还原备份。
+
+## Usage
+
+### Quick start
+
+```bash
+r2p install                       # 安装全部平台（默认）
+r2p-start "Add rate limiting"     # 启动一次工作流
+r2p-continue                      # 逐阶段推进
+r2p status                        # 查看已安装情况
+```
+
+### Lifecycle commands
+
+安装全部平台、单个平台，或逗号分隔的列表：
+
+```bash
+r2p install
+r2p install --platform claude
+r2p install --platform claude,codex,gemini
+```
+
+按平台报告安装状态——已装版本、漂移（缺文件或版本不匹配）、或 manifest 无效。`status`
+只读；加 `--json` 得到机器可读输出：
+
+```bash
+r2p status
+r2p status --json
+```
+
+卸载单个平台、列表，或全部（省略 `--platform`）：
+
+```bash
+r2p uninstall --platform claude
+r2p uninstall --platform claude,codex,gemini
+```
+
+> [!WARNING]
+> `r2p install` 直接覆盖已有安装——无需确认参数。覆盖前会先备份已存在的用户文件，
+> 而卸载绝不删除非 `r2p` 创建的文件。
+
+### Workflow skills
+
+安装后，平台 skill 调用这些共享的 `r2p-*` wrapper——运行一次工作流的每一步各一个：
+
+| Skill | 作用 |
+|---|---|
+| `r2p-start` | 从需求启动一次新运行（文本，或用 `--file <path>` 读取文档内容）。 |
+| `r2p-continue` | 继续当前运行——推进到下一个停点（gate、checkpoint 或修复）。 |
+| `r2p-status` | 查看当前运行或全部运行，只读。 |
+| `r2p-switch` | 把活动运行指向另一个 `--work-id`。 |
+| `r2p-tier-lock` | 锁定活动运行的复杂度 tier（`--base light\|standard`）。 |
+| `r2p-reopen` | 从指定 `--stage` 重开一个已关闭的运行。 |
+| `r2p-gap-open` | 把 open run 的上游缺口路由回其 `--owner-stage`；下游 artifact 失效、需重新派生。 |
+| `r2p-gap-resolve` | owner 阶段重做并通过 `gate-quality` 后，关闭一个 `--route-id` 缺口路由。 |
+
+> [!TIP]
+> 把 `~/.req-to-plan/bin` 加入 `PATH`，即可直接运行 `r2p-*` wrapper：
+>
+> ```bash
+> export PATH="$HOME/.req-to-plan/bin:$PATH"
+> ```
+
+### When to use which skill
+
+大多数运行只需 `r2p-start`，然后反复 `r2p-continue`。其余技能针对特定情形。
+
+**锁定 tier**——每个 run 一次，当 `r2p-continue` 停在 `tier_not_locked` 时：
+
+```bash
+r2p-tier-lock --work-id <id> --base standard --modifiers migration,safety --confirm
+```
+
+`--base standard` 抬高刚性下限；`migration`、`safety`、`cross_project` 这几个 modifier
+会在 DESIGN / SPEC / PLAN 检查点强制子 agent 审查。
+
+**重开已关闭的 run**——回到一个已在 PLAN 检查点关闭的运行，从更早的阶段重新开始
+（会派生一个带血缘的新 run）：
+
+```bash
+r2p-reopen --from <closed-id> --stage spec --reason "spec gap found"
+```
+
+**回路上游缺口**——在一个**开着的** run 上，当后面的阶段发现更早的阶段拥有一个错误或
+缺失的决策时。`gap-open` 把 run 退回 owner 阶段并把所有下游标记 stale；待你把 owner
+重做到通过 `gate-quality`，`gap-resolve` 关闭路由，让 owner 可被重新批准、下游重新派生：
+
+```bash
+r2p-gap-open --work-id <id> --owner-stage design --required-action "fixed-window burst flaw"
+# 然后把 owner 阶段重做到通过 gate-quality（r2p-continue 会引导这步）
+r2p-gap-resolve --work-id <id> --route-id R-1
+```
+
+> [!NOTE]
+> reopen 针对**已关闭**的 run；gap 路由针对**开着**的 run。`r2p-continue` 会用
+> `needs_repair` 和 `needs_gap_resolve` 停点带你走完这两种修复流程。
+
+## License
+
+[MIT](./LICENSE) © xenonbyte

package/bin/r2p.js

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+"use strict";
+
+const { spawnSync } = require("node:child_process");
+const path = require("node:path");
+
+const repoRoot = path.resolve(__dirname, "..");
+const args = ["-m", "tools.workflow_cli.install_cli", ...process.argv.slice(2)];
+const env = {
+  ...process.env,
+  PYTHONPATH: process.env.PYTHONPATH
+    ? `${repoRoot}${path.delimiter}${process.env.PYTHONPATH}`
+    : repoRoot,
+};
+
+function runPython(command) {
+  return spawnSync(command, args, {
+    cwd: repoRoot,
+    env,
+    stdio: "inherit",
+  });
+}
+
+let result = runPython("python3");
+if (result.error && result.error.code === "ENOENT") {
+  result = runPython("python");
+}
+
+if (result.error) {
+  console.error(`r2p: failed to start Python: ${result.error.message}`);
+  process.exit(1);
+}
+
+if (result.signal) {
+  process.kill(process.pid, result.signal);
+}
+
+process.exit(result.status ?? 1);

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

@@ -0,0 +1,277 @@
+# 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/`；本文档只做高层描述。