@aibyzero/byz 0.0.0 → 0.1.1

package/workflows/cm/skills/cm-prd/SKILL.md

@@ -0,0 +1,521 @@
+---
+name: cm-prd
+description: 用户说“把需求拆成可开发规格”“变更现有功能需求”或要求整理方案、任务和验收时使用。支持新项目、存量二开与需求变更；完成后停在人审规格，不直接编码。
+---
+
+# cm-prd — 需求文档 → 开发规格生成
+
+执行前读取 `../../runtime/project-context.md`、`../../runtime/review.md`、
+`../../runtime/model-efficiency.md` 与 `../../runtime/logging.md`。Codex 入口为
+`$cm-prd`；Claude Code 跨平台入口为 `/cm-prd`，macOS/Linux 另有历史别名 `/cm:prd`。
+
+新建和变更模式都读取 `references/phase-timing.md`，只为实际执行的阶段写配对
+`progress/start|complete`；人工等待前关闭 segment，恢复后递增，不手算耗时。
+
+用户明确要求外部专家，或为本次规格任务开启 AUTO 时，读取
+`../../runtime/external-expert.md` 并执行 `../external-expert/SKILL.md` 的任务路由。
+AUTO 可把复杂方案比较路由到 CONSULT、权威事实查证路由到 VERIFY，其余保持 LOCAL。
+外部结论属于需求/设计输入，必须在本地对照项目事实并进入正常规格人审；AUTO 不
+授权外发 docs 或代码内容。
+
+支持两种模式：新建需求和需求变更。
+
+## 输入参数
+
+`用户本轮输入` 格式：
+
+- **新建模式**：`$cm-prd {项目文件夹路径}`
+- **变更模式**：`$cm-prd --change {N}.{feature-name} 变更内容描述`
+- **可选用例输入**：追加 `--cases {json/md/txt路径}`，或在本轮消息直接粘贴用例
+
+用户提供一个项目文件夹路径，文件夹结构约定：
+
+```text
+{项目文件夹}/
+├── docs/           ← 需求文档（必须存在，PRD 从这里读取）
+├── 1.xxx/          ← 已有的 specs（如有）
+├── 2.xxx/          ← 本次生成的 specs
+└── ...
+```
+
+## 项目角色路由
+
+路径验证通过后，使用 `{CM_WORKFLOW_ROOT}/scripts/cm_workflow_config.py` 读取有效配置，
+分别解析 `analyst`（需求分析）、`planner`（方案/任务拆分）及 `policies.generate_cases`：
+
+```bash
+python3 {CM_WORKFLOW_ROOT}/scripts/cm_workflow_config.py \
+  --project {CODE_PROJECT} --role analyst --runtime {codex|claude} --print-role
+python3 {CM_WORKFLOW_ROOT}/scripts/cm_workflow_config.py \
+  --project {CODE_PROJECT} --role planner --runtime {codex|claude} --print-role
+python3 {CM_WORKFLOW_ROOT}/scripts/cm_workflow_config.py \
+  --project {CODE_PROJECT} --print-effective
+```
+
+把返回的 `adapter`、`model`、`source` 和 `route_state` 当作本轮的请求路由元数据，
+在对应分析/规划提示中注明；`model` 是别名，不能声称为已观测的后端模型。每次角色
+边界按 `runtime/workflow-routing.md` 写一条 `decision`/`phase: route` 事件。配置未提供
+时使用内置默认值；resolver 返回非零或配置错误时立即 `BLOCKED` 并报告字段路径，
+不得进入分析/规划或生成规格。配置的适配器当前运行时不可用时记录 `warning`/`degrade`，
+不得伪造调用成功或把外部专家变成编码执行器。
+
+`analyst` 与 `planner` 的上下文和输出按 `runtime/model-efficiency.md` 分包：前者只取
+当前需求与相关业务地图，后者接收分析结论、波及模块、约束和 AC 候选。稳定规则前缀
+与动态需求分离；不得为方便而重复发送完整项目地图、全部源码或前序对话。只有真实
+适配器响应返回 usage 时才记录计数。`route_state: managed-adapter` 时按共享合同调用
+`cm-openai-compatible-call.py`，由它写唯一的 `model_usage`；不得由 Skill 重复写。
+
+`generate_cases: false` 只关闭 CM 根据需求自动补生成的 `origin: generated` 用例；用户
+或需求源已提供的测试用例仍须保留、规范化并进入审批，不能用项目配置删除测试意图。
+
+项目/specs 路径验证通过后按 `runtime/logging.md` 写 `run_start`。生成规格、重置
+审批位或终止时分别写 `spec_lifecycle` 与 `run_done`；详细需求和设计内容不进入主日志。
+
+## 模式判断
+
+如果 `用户本轮输入` 以 `--change` 开头 → **读取 `references/change-mode.md`** 执行变更模式（C1–C8）
+否则 → 进入新建模式
+
+---
+
+## 新建模式
+
+### Step 1: 解析输入，读取需求文档
+
+从 `用户本轮输入` 提取项目文件夹路径，记为 `SPECS_DIR`。
+
+读取 `{SPECS_DIR}/docs/` 下的所有文件作为需求源：
+
+- 支持 `.md`、`.txt`、`.pdf`、`.html` 等文档格式
+- **HTML 交互原型（可点击 PRD）→ 执行交互遍历协议，禁止只做静态截图**。可交互原型是一份可执行的需求文档，必须用无头浏览器（Playwright / Chrome DevTools）**主动遍历**：
+
+  1. **枚举**每个页面的全部可交互元素（按钮/链接/tab/表单/开关/列表项…）
+  2. **逐个操作**并记录三元组：`元素 → 动作 → 结果`（跳转到哪/弹了什么/状态怎么变/无响应）
+  3. 产出**功能点清单**：每个有响应的交互 → 对应一条 [F-xxx]；**点了没反应的 → 列为"原型死区"进开放问题**（问用户：是原型没做完，还是本就不需要？不许静默丢弃）
+  4. **覆盖率自检**：可交互元素总数 = 功能需求数 + 死区数，对不上不得进入 Step 6
+  5. 遍历过程中逐状态截图（Step 8.5 的候选基准）；三元组记录直接生成**交互流 AC 与 E2E 走查清单**
+
+  原型首先是需求，其次才是视觉候选。注意原型通病：只画理想态——异常态/空态/边界值靠 Step 5.5 歧义五问补齐
+- 如果 docs/ 下有多个文件，全部读取并综合分析
+- 输入含 `--cases` 或本轮粘贴了测试用例时，将其作为用户来源交给 Step 10.4；
+  JSON 先做语法校验，Markdown/文本在生成时归一化为测试合同
+- 如果 docs/ 不存在或为空，报错提示用户先在 docs/ 下放入需求文档
+
+### Step 2: 获取项目名称
+
+- 从当前目录的 `package.json` name 字段、`Cargo.toml`、`go.mod` 等提取项目名
+- 如无法提取，使用当前目录名
+- 转为 kebab-case，记为 `PROJECT_NAME`
+
+### Step 3: 探测项目架构类型
+
+**代码项目根的确定（防在错误目录生成脏规格）**：`用户本轮输入` 中显式给了代码项目路径（如 `代码在~/code/app`）→ 以其为准；未给 → 用当前工作目录（约定:在代码项目内运行本命令），但**必须先自检**——当前目录含项目描述文件或源码、且其内容与需求文档所述业务相符；明显不符（如当前目录是另一个项目/工具仓库）→ **停下询问代码项目路径**，不得静默把错误目录当项目上下文（空目录检测只兜全空 case，兜不住"错但有效"的目录）。
+
+扫描项目根目录、配置文件、目录结构、依赖声明，自行判断架构类型（monorepo / 多仓库 / 单体应用 / Web3 等）。记录 `ARCH_TYPE`。
+
+交付形态为微信小程序，或项目存在原生 `project.config.json` + `app.json`、Taro/uni-app
+微信构建目标时，标记 `DELIVERY_SHAPE=wechat-miniprogram` 并读取
+`../cm-miniprogram-engineer/references/platform-readiness.md`。只出现“小程序”字样但
+形态证据不足时进入 Step 5.5 确认，不得根据仓库名猜测。
+
+**空项目检测**：代码项目不存在、或为空目录（无 package.json / Cargo.toml / go.mod 等项目描述文件，且无源码目录）→ **先问用户确认空目录的含义，不得自行假设**：
+
+> "代码目录为空——这是【全新项目】（走 0→1 分支，我来推荐架构和脚手架），还是【存量项目还没 clone】（请先 clone 到该目录，再重新运行 $cm-prd）？"
+
+- 确认全新项目 → 标记 `GREENFIELD=true`，**读取 `references/greenfield.md`** 叠加 G1–G4 规则，Step 4 跳过
+- 确认未 clone → **中止本次执行**，提示 clone 完成后重跑（在不存在的项目上下文上生成 design.md 是有毒规格）
+
+### Step 4: 读取项目上下文（存量项目 = 二开模式，叠加 B 规则）
+
+- 按 `runtime/project-context.md` 读取项目约束和本需求相关规则，扫描两层目录了解模块划分
+- 读取 `references/context-scope.md`，先做定向代码搜索，再设置
+  `CONTEXT_SCOPE=targeted|full`、加载对应地图/代码，并写 `decision/context_scope` 日志
+- **B1 代码库参考文档判定**：先读代码项目根 CLAUDE.md 的「业务地图」字段（多层仓库
+  下以代码项目根为准，仓库根 CLAUDE.md 无此字段再看地图 00-index 头部；init 已判定过，
+  不重复判断）。字段=已生成/已刷新或目录存在 → 按 context-scope 清单渐进加载；字段=
+  跳过(小项目) → 不建议 scan，按范围直接读代码；字段缺失且文档不存在 → 建议先执行
+  `/codebase-context scan`，本轮按直接代码搜索继续；skill 未安装 → 提示重装最新包并按
+  直接代码搜索继续。任何路径都不得因追求 targeted 猜测波及面
+
+**二开模式追加规则**（GREENFIELD=false 且本次需求会修改存量代码时生效）→ **读取 `references/brownfield.md`** 执行 B2 波及面 / B3 防护网基线 / B4 增量 specs / B5 拆分锚定地图。
+
+
+### Step 5: 分析需求
+
+**调用 `cm-product-manager` skill 执行本步和 Step 5.5**——用户故事、编号功能需求、验收标准的编写方法和歧义五问以该 skill 为准。
+
+需求涉及**交易/资产/支付/代币/证券/金融营销**时，同时加载 `cm-finance-expert` skill 协同：领域正确性审核 + 营销合规红线扫描 + 合规开放问题（并入 Step 5.5）。法域确认结果须写入代码项目 `.claude/rules/finance.md` 头部字段；文件不存在时，以 `{CM_WORKFLOW_ROOT}/templates/rules/finance.md` 为骨架现场补生成，并在 AGENTS.md 与 CLAUDE.md 的相关规则说明中补充引用。
+
+从文档中提取功能目标、用户故事、验收标准、约束条件、依赖。
+
+### Step 5.5: 开放问题确认
+
+分析需求后，如果存在以下情况，**必须暂停并与用户对话确认**，不要自行假设：
+
+- 需求描述模糊或有歧义的功能点
+- 多种技术实现方案且差异较大
+- 缺少关键信息（如目标平台、兼容性要求、第三方服务选型）
+- 业务逻辑有矛盾或不完整
+- 涉及权限、支付、敏感操作等需要明确确认的功能
+
+`DELIVERY_SHAPE=wechat-miniprogram` 时追加平台就绪检查：账号主体、服务类目/资质、
+变现路径、权限与隐私、后端/合法域名和发布通道。会改变功能可行性或范围但未确认的
+项目必须暂停；只影响后续提审的材料可记为发布待决，不阻塞本地规格与开发。平台政策
+结论须记录当前官方查证日期与来源，无法查证时保留开放问题。
+
+格式：
+
+```
+❓ 需要确认以下问题：
+
+1. {问题描述} — {为什么需要确认}
+2. {问题描述} — {为什么需要确认}
+
+请逐一回复后继续生成 specs
+```
+
+所有问题确认完毕后再进入 Step 6。
+
+### Step 6: 推断 feature 名称
+
+根据需求内容生成一个简洁的 kebab-case 英文名称。
+
+### Step 7: 生成 specs 目录
+
+检查 `{SPECS_DIR}/` 下已有的编号目录（如 `1.xxx/`、`2.xxx/`），取最大编号 +1。
+
+```text
+{SPECS_DIR}/
+├── docs/                        ← 需求文档（输入）
+├── 1.比如这是一个已有的标题/     ← 已有 specs
+└── 2.{feature-name}/            ← 本次新建
+    ├── requirements.md
+    ├── design.md
+    ├── tasks.md
+    └── test-cases.json           ← 有可观察行为时生成
+```
+
+### Step 8: 生成 requirements.md
+
+```markdown
+# {Feature 名称} — 需求规格
+
+## 概述
+
+{一句话描述}
+
+## 项目信息
+
+- 项目名: {PROJECT_NAME}
+- 架构类型: {ARCH_TYPE}
+
+## 需求版本
+
+| 日期         | 版本 | 说明     |
+| ------------ | ---- | -------- |
+| {YYYY-MM-DD} | v1   | 初始需求 |
+
+## 用户故事
+
+- 作为 {角色}，我想要 {功能}，以便 {价值}
+
+## 功能需求
+
+1. [F-001] {需求描述}
+2. [F-002] {需求描述}
+
+## 非功能需求
+
+- 性能: {要求}
+- 安全: {要求}
+- 兼容性: {要求}
+
+## 验收标准
+
+- [ ] [AC-001] {标准描述}
+
+## 依赖
+
+- {外部服务/库}
+
+## 平台就绪（仅微信小程序生成）
+
+{按 cm-miniprogram-engineer/references/platform-readiness.md 记录状态、证据与负责人；
+不写任何密钥、证件、Cookie 或测试账号密码}
+
+## 开放问题
+
+- {待确认事项}
+```
+
+### Step 8.5: UI 设计基准（涉及 UI 的 feature）
+
+feature 涉及页面/界面时，在生成 design.md 前确定设计基准：
+
+- **有 Figma/设计稿** → 通过 MCP 导出截图 + token 提取物，落盘 `{SPECS_DIR}/{N}.{feature-name}/design-baseline/`（防链接失效与云端改版导致基准漂移）
+- **有 Stitch 项目** → 通过 Stitch MCP 拉取设计并导出 HTML/CSS 落盘 design-baseline/；导出的 HTML **按 Step 1 交互遍历协议处理**（多屏/流转设计可直接提取交互流与功能点）——Stitch 导出物默认按像素基准对待（它就是设计本体，不是示意）
+- **有 HTML 交互原型**（Step 1 已截图）→ **必须人工三选一确认基准档位**（中性提问不带引导；高保真原型建议像素档，线框灰稿建议结构档）：
+  - **① 像素基准**：UI 与交互 **1:1 还原**——截图落盘 design-baseline/ 作 BackstopJS 基准（≤1%），且**交互流提取为 E2E 走查清单**（每个跳转/状态切换/反馈逐条断言，交互不 1:1 视为验收失败）
+  - **② 结构基准**（多数原型的合理档）：页面结构、信息层级、**交互流程必须一致**，视觉样式可再设计——验收为逐页元素清单核对 + 流程走查
+  - **③ 纯参考**：仅辅助理解需求，无对照验收——选此档即明确接受 UI 由 AI 自行发挥（历史事故：原型被降为参考后，产出与原型完全不符）
+  档位写入 design.md「设计基准」节；**无论哪档，原型的页面清单与跳转流程都已是需求的一部分（Step 1 规则），流程不允许自由发挥**
+- **无设计稿且环境已安装 `huashu-design` skill** → 调用其生成高保真原型（**要求包含 hover/空态/错误态等交互态**），落盘同上；**人审规格时一并确认设计方向**（复用既有强制卡点，执行期零设计决策）
+- **两者皆无** → 不建基准、**不生成 UI 还原任务**，该 feature 的 UI 由前端任务按 design.md 自行实现；可提示用户 `npx skills add alchaincyf/huashu-design`
+
+**基准机读化(四种来源统一要求——截图给人看,规格表给 AI 抄)**:design-baseline/ 除截图外必须含**逐元素规格表**(spec-sheet.json:字体五件套/色值/几何/间距)。AI 看图估值的精度天花板极低,是还原度不理想的头号根因(实跑反馈);规格表按基准形态产出:
+
+- Figma MCP → 直接读取节点精确值(排版/填充/自动布局间距)导出成表,不经截图转译
+- Stitch 导出 / HTML 原型 → 用 `{CM_WORKFLOW_ROOT}/templates/ui-lens/cm-ui-lens-extract.mjs` 对基准页提取计算值成表；样式值优先**移植改造**而非重新想象
+- **纯截图(最弱形态)** → 色板可精确采样成表;几何只能估算——规格表标注「几何估算档」,并明确提示用户:有 Figma/原型源尽量给源,纯截图基准的还原精度天花板显著更低
+- **基准字体文件一并落盘**(还原页先加载同款字体再对比,防字体回退噪声淹没真差异)
+
+有基准时，design.md 记录基准路径，且「接口契约」节须包含**组件契约**（组件名 / props / 事件）。
+
+### Step 9: 生成 design.md
+
+复用 Step 4 已加载的项目约束与规则；根据最终波及层补读新命中的相关规则，禁止再次
+全量读取未变化的 CLAUDE/rules。设计方案必须遵循项目已有的技术规范和约定。
+
+按功能模块设计，每个模块说明涉及哪些层（前端、后端、数据库、合约等），具体分层根据项目实际架构决定，不做硬编码限制。
+
+```markdown
+# {Feature 名称} — 技术设计
+
+## 设计版本
+
+| 日期         | 版本 | 说明     |
+| ------------ | ---- | -------- |
+| {YYYY-MM-DD} | v1   | 初始设计 |
+
+## 项目架构
+
+- 架构类型: {ARCH_TYPE}
+- 涉及层: {根据项目实际情况列出}
+
+## 功能模块设计
+
+### 模块 1: {模块名}
+
+{技术方案，遵循 .claude/rules/ 中的规范}
+
+**涉及层及关键设计:**
+
+{根据项目实际分层描述，如数据模型、API 接口、组件设计、合约接口等}
+
+### 模块 2: {模块名}
+
+...
+
+## 接口契约
+
+{API、RPC、合约接口等 — 根据项目类型决定}
+
+## 数据模型
+
+{数据表/模型/链上存储 — 根据项目类型决定}
+
+## 安全考虑
+
+{基于 .claude/rules/security.md 和项目特有的安全规范}
+
+## 技术决策
+
+| 决策 | 选项 | 理由 |
+| ---- | ---- | ---- |
+```
+
+### Step 9.5: 方案对抗审查（最贵的决策补上第二双眼睛）
+
+design.md 生成后，满足任一触发条件 → 按 `runtime/review.md` 交**新上下文的独立审查者对抗审查一轮**：
+
+- GREENFIELD 的 ADR（架构选型是最贵决策）
+- design 含新模块、架构边界或依赖方向变化、跨模块/跨仓库数据流
+- 新增第三方运行时依赖或改变核心工具链
+- 修改公开接口契约、数据模型/数据库迁移、认证授权、支付资产或其他安全敏感逻辑
+- 功能点 F ≥ 5 的大 feature
+
+**仅修改存量模块不再单独触发本步。** 单模块内部的文案、样式、小交互、校验、
+现有模式下的小型 CRUD、缺陷修复或补测试，在没有命中上述风险信号时跳过本步，
+并把关键方案检查合并到 Step 10.6。执行过程中一旦发现真实范围扩大并命中风险信号，
+必须补做本步后再继续生成最终任务单。
+
+**投喂内容**：requirements.md + design.md 全文 + 项目上下文中的相关规范 +（二开）「波及面」段与被改存量模块现状代码。
+提示词要义："**这是隔壁同事做的方案，详细审查一下**"——重点查架构隔离、模块边界、与现有管线的耦合、数据流缺口；只报告有具体失败场景的问题，零发现明说（审查产出纪律同 N4）。
+
+调 reviewer 前先真跑 `cm-prd-review-gate.py inspect --stage design`，证据固定为
+`prd-{feature}-design-r1.md`，处置回执固定为
+`prd-{feature}-design-disposition.json`：`dispatch_once` 才允许调用 reviewer；
+`resume_disposition` 表示 r1 已落盘，直接继续应用/升级现有 findings，禁止重审；
+`completed` 直接进入 Step 10。处置完成后真跑 `record --artifact {design.md}`，记录
+`applied|no_findings|escalated`、finding/unresolved 数量和 r1 SHA。进程在 r1 落盘后
+崩溃也只能恢复处置，不能再消耗一轮审查。
+
+**单轮硬边界（ROUND_LIMIT=1）**：每个 feature 在本阶段只允许一次 review attempt，
+独立 reviewer 与 `self-degraded` 复查二选一。零发现直接进 Step 10；
+采纳项由主执行者修正 design.md 后进 Step 10，并由后续 10.5 自检验证完整规格；分歧或
+无法机械确认的项写入摘要卡「风险点」交人裁决。**禁止 review → 修正 → 再 review**，
+也禁止换一个审查者变相开启第 2 轮；凭证只允许 `design-r1.md`，不得生成 `design-r2.md`。
+任何审查尝试（包括 `self-degraded`）均消耗唯一一轮；通道恢复后不得补审。
+（实跑教训：公共 CLI 契约的 3 轮方案复审耗时 11m59s，后两轮应由自检与人审承担。）
+未命中上述风险信号的低风险 feature 不触发，零额外负担。
+**凭证落盘**:审查原文 tee 到 `{SPECS_DIR}/.reviews/prd-{feature}-design-r1.md`——摘要卡「方案对抗审查」行必须与凭证对得上,无凭证的数字是自报(凭证教义全框架一体,规格期不豁免)。
+
+> 依据：代码有 N4 对抗、规格有 10.5 自检，唯独技术方案此前无第二模型把关——而方案错误是最贵的错误（行业重度实践的最大单笔收益正是方案期拦截架构缺陷）。
+
+### Step 10: 生成 tasks.md
+
+**按功能拆任务。** AI 执行时根据 design.md 自动判断每个任务涉及哪些层。
+
+```markdown
+# {Feature 名称} — 任务清单
+
+## 任务版本
+
+| 日期         | 版本 | 说明     |
+| ------------ | ---- | -------- |
+| {YYYY-MM-DD} | v1   | 初始任务 |
+
+## 项目信息
+
+- 项目名: {PROJECT_NAME}
+- 架构类型: {ARCH_TYPE}
+- specs 路径: {SPECS_DIR}/{N}.{feature-name}/
+
+## 任务列表
+
+### UI 还原（仅当存在 design-baseline 时生成本节）
+
+- [ ] T-001: 还原 {页面/组件} ~30min（基准: design-baseline/；本 feature 的前端功能任务依赖本任务）
+
+### 功能 1: {功能名}
+
+- [ ] T-002: {任务描述} ~{预估时间}
+- [ ] T-003: {任务描述} ~{预估时间}
+
+### 功能 2: {功能名}
+
+- [ ] T-003: {任务描述} ~{预估时间}
+
+### 集成与测试
+
+- [ ] T-010: 联调测试 ~{预估时间}
+- [ ] T-011: E2E 测试 ~{预估时间}
+- [ ] T-012: 部署 staging 并冒烟验证 ~15min（依赖本 feature 全部开发与测试任务）
+
+> 部署任务前提：项目存在部署形态（Dockerfile / CI 配置 / 部署脚本，或 0→1 项目——bootstrap 已建 CI 骨架）才生成 T-012；**纯本地工具、库等无部署形态的项目不生成**，避免执行期反复触发"无 staging 环境"上报。
+
+## 依赖关系
+
+- T-002 依赖 T-001
+
+## 风险点
+
+- {可能遇到的问题及应对}
+```
+
+**任务拆解原则：**
+
+- 按功能拆，AI 执行时读 design.md 自动识别涉及哪些层；**二开项目按 B5 锚定业务地图**（feature 沿 07 线路、任务尽量单模块）
+- 原子性，可独立完成和验证
+- **同一组件/同一文件内的行为不拆分为多个任务**（如"渲染列表项"和"列表项的删除确认"归一个任务）——拆开会导致执行时自然合并、任务标记与提交失配（实跑验证的教训）
+- 预估完成时间（5min / 15min / 30min / 1h）
+- **粒度控制**：每个子 specs（feature 目录）不宜过大，单个 tasks.md 控制在 **10-15 个任务以内**。如果需求过大，应在 Step 6 之前拆成多个独立的 feature 目录（如 `2.user-auth-login`、`3.user-auth-register`），每个 feature 有自己的 requirements/design/tasks 三件套。这样 cm:ai 执行时上下文可控，不会因为 specs 太大导致丢失关键信息。
+
+### Step 10.4: 生成 AI 测试合同（条件触发）
+
+读取 `../../runtime/test-contract.md`，按其中的生成条件为适用 feature 写
+`test-cases.json`。用户或需求源提供的用例优先且标记 `origin: "user"`；其余根据
+AC、design 和 tasks 补齐，保证 AC→TC→Task 可追踪。纯文档/注释/类型/无行为重构
+不生成空文件。写完执行 `scripts/validate-test-cases.py`。
+
+`DELIVERY_SHAPE=wechat-miniprogram` 时同时读取
+`../cm-miniprogram-engineer/references/release-checklist.md`，只为本 feature 实际使用的
+授权、平台 API、网络/云能力和真机差异生成用例；不用的能力不扩写。需要开发者工具、
+真机或后台才能证明的 expected 必须保留相应执行前提，不得改写成 Web 可替代验证。
+
+### Step 10.5: 规格自检（机器项，AI 自查自修，人不参与）
+
+读取 `references/spec-self-check.md` 并逐项执行；测试合同必须调用 `scripts/validate-test-cases.py`，不得靠目测。
+
+### Step 10.6: 独立规格审查（方案 + 任务拆分）
+
+10.5 自检是机器项，查不出「**方案是否明显错向、任务是否拆对**」。自检通过后，
+按 `runtime/review.md` 把精简的方案与拆分结果交给新上下文的独立审查者。Step 9.5
+已触发时不重复审完整方案；Step 9.5 因低风险跳过时，本步同时承担关键方案检查：
+
+- **投喂内容**：requirements.md 功能点清单 + tasks.md 全文 + design.md 的方案摘要、
+  关键技术决策、接口/数据契约与「波及面」段（二开）。不喂三件套全文；Step 9.5
+  已审过完整方案时，方案部分只用于核对任务有没有偏离已审设计。
+- **提示词要义**："这是隔壁同事整理的开发规格。先检查方案有没有明显错向、遗漏的
+  失败场景或与现有边界冲突，再检查拆分质量：①任务边界有无重叠/遗漏 ②依赖顺序
+  会不会卡死 ③粒度是否适合单任务交付验证 ④二开：波及面有没有漏掉会被牵连的
+  模块。只报有具体后果的问题，没有问题就明说。"
+- **单轮硬边界（ROUND_LIMIT=1）**：每个 feature 在本阶段只允许一次 review attempt，
+  独立 reviewer 与 `self-degraded` 复查二选一。采纳项修正 specs 后
+  重跑一次 10.5 自检；分歧或自检不能证明的项写入摘要卡「风险点」交人裁决。
+  **禁止 review → 修正 → 再 review**，也禁止换审查者变相开启第 2 轮；凭证只允许
+  `split-r1.md`，不得生成 `split-r2.md`。（实跑教训：规格修正后的再次召回复审没有
+  新增独立决策层，却继续占用主流程时间。）
+  任何审查尝试（包括 `self-degraded`）均消耗唯一一轮；通道恢复后不得补审。
+- **凭证落盘**：原始审查结果写入 `{SPECS_DIR}/.reviews/prd-{feature}-split-r1.md`，文件头使用 review contract 的 `reviewer/independent/at/scope` 字段
+- 调 reviewer 前同样真跑 `cm-prd-review-gate.py inspect --stage split`；只在
+  `dispatch_once` 调用一次，`resume_disposition` 复用已有 r1，`completed` 不再审。
+  findings 处置并重跑一次 10.5 后，真跑 `record`，artifact 传 requirements.md、
+  design.md、tasks.md 及存在的 test-cases.json，生成
+  `prd-{feature}-split-disposition.json`。回执与 r1 SHA 不一致或发现 r2 时立即 BLOCKED。
+- **降级**：无法建立独立上下文时，由主执行者对抗式复查，凭证写 `self-degraded` / `independent: false`；这是增益层，不单独因降级停车
+
+> 依据：低风险小需求不值得额外支付一轮完整方案对抗，但仍需要第二双眼睛同时检查
+> 关键方案与任务拆分；高风险需求继续保留 Step 9.5 + 本步两层审查。
+
+### Step 11: 输出总结（附规格摘要卡 + 审查清单）
+
+**先输出规格摘要卡**——人审的第一入口是这张一屏卡片，不是三个长文件（实跑教训：直接丢长文件，人审会退化成扫一眼就"通过"）：
+
+```text
+┌─ 📋 规格摘要卡 ────────────────────────────
+│ 交付形态: {Web/App/小程序…}   ← 第一分叉,看错全错
+│ Feature: {N 个}: {名称列表}
+│ 功能点: {N} 个 | AC: {N} 条 | 任务: {N} 个(预估 {x}h)
+│ 开放问题: {已答 N / 共 N}——{逐条一行: 问题→答案}
+│ 风险点: {金融/合规/破坏性操作等敏感项,无则"无"}
+│ 上下文范围: {定向 / 完整 / 定向→完整（reason_code）}
+│ 平台就绪: {就绪/待官方核验 N 项/不适用}
+│ UI 基准: {像素级/结构级/纯参考/无}
+│ 🧪 AI 测试合同: {N 条(user N/generated N) / 跳过(无可观察行为)}
+│ 🔎 规格自检: {N}/{N} 通过{（未过项已列入风险点）}
+│ 🧠 方案对抗审查: {通过 / {N}条已修 / 跳过(低风险,并入独立规格审查)}
+│ 🤖 独立规格审查(方案+拆分): {通过 / {N}条已修 / 降级自审}
+└────────────────────────────────────────────
+有疑问的行,点开对应文件细看;摘要卡没问题再走下面的审查清单。
+```
+
+完成后报告：
+
+- Feature 名称和序号、Specs 路径、涉及的技术层、总任务数和预估总时间
+
+并输出**规格审查清单**——人审规格不是"看一眼"，按此逐项检查：
+
+```text
+📋 规格审查清单（人审时逐项勾选）
+- [ ] 任务跨 feature 查重：同一产物（文件/模块）未出现在多个任务中（实跑教训：bootstrap 底座与 feature 数据层重复）
+- [ ] 依赖关系完整：每个任务的前置依赖已声明，无环
+- [ ] AC 可测试：每条验收标准都能回答"怎么验证"
+- [ ] 粒度合规：同一组件/文件的行为未拆成多任务；单 feature ≤15 个任务
+- [ ] 开放问题已全部回答，敏感决策（法域/支付/权限）有人工确认记录
+- [ ] **交付形态与需求意图一致**（要 App 别画成网页），且已写入 ADR 与 CLAUDE.md 字段
+- [ ] **原型功能点覆盖 100%**（有交互原型时）：遍历记录中每个可交互元素都有对应 [F-xxx] 或死区标注，无静默丢弃
+```
+
+**规格审批位落盘**：报告输出后真跑
+`python3 {CM_WORKFLOW_ROOT}/scripts/cm-spec-manifest.py {SPECS_DIR}`，把返回的
+`specFiles`（每个 feature 的 requirements/design/tasks 及可选 test-cases 规格语义 SHA；
+任务/AC 的运行期 `[x]` 会规范化为 `[ ]`，其余内容不忽略）
+写入 `{SPECS_DIR}/.cm-specs-status` 单行 JSON；为旧版消费者同时保留由 manifest
+筛出的 `testCases`：
+`{"status":"awaiting_review","at":"{时间}","features":["1.xxx",...],"specFiles":[{"path":"1.xxx/requirements.md","sha256":"..."}],"testCases":[]}`
+随后写 `spec_lifecycle/generated`、`spec_lifecycle/awaiting_review` 和 `run_done`，仅记录
+feature/task/case 数量、状态与 specs 路径。
+最终报告注明阶段耗时事件已记录；具体耗时由日志按 operation_id + segment 计算。
+
+**硬停车（不可违反）**：本命令的终点就是摘要卡与审查清单——**任何情况下不得在本会话顺势启动开发**，对话里的"继续"不构成开发授权。提示用户：**逐项审查通过后，运行 `$cm-ai` 开始开发**（N1 有入口闸：未审批的 specs 会先要求确认摘要卡）

package/workflows/cm/skills/cm-prd/references/brownfield.md

@@ -0,0 +1,13 @@
+# $cm-prd 模式文件 — 二开模式（B2–B5）
+
+> 由 $cm-prd Step 4 判定「存量项目且本次需求会修改存量代码」时读取本文件。B1(加载参考文档)保留在主文件 Step 4。规则内容与主文件同源拆分,语义未变。
+
+**二开模式追加规则（GREENFIELD=false 且本次需求会修改存量代码时生效）**：
+
+- **B2 波及面分析**：对每个将被修改的存量模块，基于参考文档（03-architecture 模块关系 / 04-api-routes 调用方 / 07-business-logic 线路）+ 代码搜索核实，在 design.md 写「波及面」段：改哪里 → 谁调用它 → 哪些老功能可能受影响。**波及面是 QA 回归范围的数据源**
+- **B3 防护网任务**：凡 tasks.md 中包含"修改存量模块"的 feature，第一个任务固定为**防护网基线**。**项目已有测试资产**（jest/vitest 等且可运行）→ 基线 = 跑通存量全量测试并记录结果，**不重复造快照**（实跑验证：184 用例的成熟项目直接复用，前后各跑一次）；**无测试资产** → 才写现状快照测试锁住将被修改模块的当前行为（不判断对错，只锁现状）。开发后复跑基线，变红即为碰坏老行为的信号
+- **B4 specs 只覆盖增量**：不为整个存量系统补规格；只为本次改动涉及的模块建规格，存量行为"用到哪、记到哪"（记进参考文档 07，而不是 specs）
+- **B5 拆分锚定地图**：feature 与任务的边界对齐业务地图，不凭感觉切——
+  - **feature 沿业务线路拆**（07-business-logic 的线路）：需求同时触及多条线路（如"行情展示"+"导出"）→ 按线路切成多个 feature，一条线路一个 feature
+  - **任务尽量单模块**（03-architecture 的模块关系）：一个任务的改动落在一个模块内；确需跨模块的任务，描述中显式列出涉及模块清单（审查与波及面据此聚焦）
+  - **地图盲区检测**：需求涉及的逻辑在 07 中找不到对应线路 → 说明地图有盲区，先对该区域增量补扫（scan 只读相关目录）再拆分——拆错边界的成本远高于补扫