sdd-flow-kit 1.2.2 → 1.3.0

package/src/templates/artifacts/04-/346/212/200/346/234/257/346/226/207/346/241/243.template.md

@@ -1,21 +1,282 @@
-# 04-技术文档草稿（由第 2/3 步产物生成）
+# 04-前端技术文档（由第 2/3 步产物生成）
 
 > 使用输入：
-> - `01-需求分析报告.md`
+> - `05-验收清单.md`（**验收 SSOT，技术方案须引用 AC-ID**）
+> - `01-需求分析报告.md`（业务概述）
 > - `02-改动点清单.md`
 > - `03-待确认问题清单.md`
 >
-> 说明：请先把第 3 步“提问/待确认”闭环，否则技术设计可能缺失关键约束。
+> 说明：
+> - 本文档用于产出“可开发、可联调、可测试、可回滚”的前端实现方案。
+> - 若 `03-待确认问题清单.md` 仍有未闭环问题，请先补齐约束后再冻结本文档。
+> - 建议结论优先写“明确规则”，避免“待定/看情况”。
 
-## 总体方案
-- （架构改动概述）
+## 文档元信息
 
-## 模块/页面/接口改动
-- （按 `02-改动点清单.md` 列表逐条描述）
+- 需求名称：
+- 版本号：
+- 业务域/模块：
+- 适用工程与分支：
+- 文档作者/评审人：
+- 最后更新时间：
+- 关联文档：
+  - PRD：
+  - 接口文档：
+  - 原型/Figma：
+  - 自测用例：
 
-## 关键数据流与状态治理
-- （说明前端状态/服务端状态边界）
+## 1. 改造范围
 
-## 风险与回滚预案
-- （列出关键风险点与回滚方式）
+### 1.1 改造目标
+
+- 本次改造要解决的问题：
+- 预期业务收益/体验收益：
+- 成功标准（量化）：
+
+### 1.2 In Scope（本次必须完成）
+
+- 页面/路由：
+- 组件/弹窗：
+- 状态管理：
+- 接口联调：
+- 校验与提交流程：
+- 埋点/日志：
+
+### 1.3 Out of Scope（明确不做）
+
+- 不在本次交付内的能力：
+- 依赖他方排期、暂不落地的能力：
+- 后续迭代建议：
+
+### 1.4 影响面评估
+
+- 受影响角色（运营/销售/管理员等）：
+- 受影响流程（创建/编辑/审批/导出等）：
+- 向后兼容性说明：
+
+## 2. 页面与交互设计
+
+### 2.1 页面显隐/可用性矩阵
+
+| 模块/控件 | 场景A | 场景B | 场景C | 说明 |
+| --- | --- | --- | --- | --- |
+| 示例：高级筛选 | 显示 | 隐藏 | 显示但置灰 | 写明触发条件 |
+
+### 2.2 核心交互流程（按用户路径）
+
+#### 流程A：创建
+
+- Step1：
+- Step2：
+- Step3：
+- 成功态：
+- 失败态：
+
+#### 流程B：编辑
+
+- 可编辑字段：
+- 不可编辑字段：
+- 字段变更引发的联动重置：
+
+#### 流程C：列表/详情查看
+
+- 列表展示规则：
+- 超长/空值/异常值展示策略：
+- hover、tooltip、展开收起规则：
+
+### 2.3 交互细节约束
+
+- 防重复点击：
+- loading 态（按钮、局部、全局）：
+- 空态文案：
+- 错误态提示口径（toast/inline）：
+- 权限不足提示：
+
+## 3. 前端状态与数据模型设计
+
+### 3.1 领域模型（TypeScript）
+
+```ts
+type ExampleEntity = {
+  id: string;
+  name: string;
+  status: "init" | "ready" | "failed";
+};
+```
+
+### 3.2 页面状态拆分
+
+- 服务端状态（remote state）：
+- 本地状态（ui state）：
+- 派生状态（computed/selector）：
+- 临时状态（草稿、弹窗输入）：
+
+### 3.3 状态流转图（文字化）
+
+- 初始进入：
+- 用户输入中：
+- 触发请求中：
+- 请求成功：
+- 请求失败：
+- 离开页面清理：
+
+### 3.4 数据一致性策略
+
+- 多请求并发防抖/竞态处理：
+- 旧响应覆盖新响应的保护：
+- 列表与详情一致性：
+- 缓存命中与失效策略：
+
+## 4. 接口与数据交互设计
+
+### 4.1 接口清单
+
+| 接口 | Method | 用途 | 请求关键字段 | 响应关键字段 | 异常码处理 |
+| --- | --- | --- | --- | --- | --- |
+| `/example/path` | `POST` | 示例说明 | `xxx` | `yyy` | `code != 0` |
+
+### 4.2 请求参数映射（UI -> API）
+
+- 字段映射关系：
+- 枚举值转换关系：
+- 默认值补齐逻辑：
+- 过滤空值策略：
+
+### 4.3 响应数据映射（API -> UI）
+
+- 展示字段组装规则：
+- 兜底值处理：
+- 时间/金额/百分比格式化规则：
+- 兼容旧字段方案：
+
+### 4.4 提交 payload 结构
+
+```json
+{
+  "biz_id": "xxx",
+  "items": [
+    {
+      "id": "1",
+      "source": "system"
+    }
+  ]
+}
+```
+
+### 4.5 重试与容错
+
+- 超时重试策略：
+- 可重试与不可重试错误划分：
+- 用户可感知提示文案：
+
+## 5. 表单与校验设计
+
+### 5.1 字段校验矩阵
+
+| 字段 | 必填 | 格式/范围 | 触发时机 | 错误文案 |
+| --- | --- | --- | --- | --- |
+| 示例字段 | 是 | 1-50字符 | blur + submit | `示例字段不能为空` |
+
+### 5.2 前后端口径对齐
+
+- 前端预校验规则：
+- 后端兜底校验规则：
+- 冲突时以前/后端哪方为准：
+
+### 5.3 默认值与自动填充
+
+- 默认值来源：
+- 自动更新条件：
+- 用户手动修改后的保护策略：
+
+## 6. 异常、边界与降级方案
+
+### 6.1 边界场景
+
+- 无权限用户：
+- 脏数据/历史数据不完整：
+- 数据量过大（分页、截断、懒加载）：
+- 网络抖动与弱网：
+
+### 6.2 降级与兜底
+
+- 功能开关（feature flag）策略：
+- 接口失败时的兜底展示：
+- 关键流程失败时的替代路径：
+
+### 6.3 可观测性
+
+- 错误日志埋点：
+- 关键操作埋点：
+- 性能指标采集（FMP/TTI/接口耗时）：
+
+## 7. 改造清单（到文件级）
+
+### 7.1 新增文件
+
+- `src/...`：用途说明
+
+### 7.2 修改文件
+
+- `src/...`：改造点说明
+- `src/...`：改造点说明
+
+### 7.3 删除/废弃文件（如有）
+
+- `src/...`：废弃原因与迁移说明
+
+## 8. 风险点与应对策略
+
+| 风险 | 触发条件 | 影响范围 | 等级 | 应对策略 | 负责人 |
+| --- | --- | --- | --- | --- | --- |
+| 示例：接口字段变更 | 后端上线未通知 | 创建/编辑流程 | 高 | 增加兼容解析 + 监控告警 | FE |
+
+- 高风险项必须包含：预警信号、止损动作、回滚判定条件。
+
+## 9. 发布、灰度与回滚
+
+### 9.1 发布前检查
+
+- 联调完成：
+- 用例通过：
+- 监控/埋点已验证：
+- feature flag 配置已确认：
+
+### 9.2 灰度策略
+
+- 灰度范围（账号/租户/流量比例）：
+- 观察指标：
+- 放量节奏：
+
+### 9.3 回滚方案
+
+- 回滚入口（配置回滚/代码回滚）：
+- 数据是否需要回滚：
+- 回滚后验证清单：
+
+## 10. 测试与验收要点
+
+### 10.1 功能测试
+
+- 主流程：
+- 分支流程：
+- 异常流程：
+
+### 10.2 回归测试
+
+- 受影响历史能力：
+- 跨模块联动能力：
+
+### 10.3 验收标准（DoD）
+
+- 需求项全部可追溯到实现点与测试点；
+- 无 P0/P1 阻塞问题；
+- 文档、埋点、告警、回滚方案齐备。
+
+## 11. 待确认事项（若仍存在）
+
+> 若此节不为空，文档状态不得标记为“可开发”。
+
+- [ ] 待确认项1（责任人 + 截止时间）
+- [ ] 待确认项2（责任人 + 截止时间）
 

package/src/templates/artifacts/05-/351/252/214/346/224/266/346/270/205/345/215/225.template.md

@@ -0,0 +1,38 @@
+# 05-验收清单（AC Matrix）
+
+> **implement 与 deliver 的唯一验收 SSOT**。`01-需求分析报告.md` 仅为业务概述，**不**承担完整验收职责。  
+> 每条 AC 须从 `source/PRD.md` **逐条抽取**（禁止仅从 01 摘要归纳）。
+
+## 清单状态
+
+- **定义状态**：未定义（AI 从 PRD 填表后改为 `已定义`）
+- **签收状态**：未签收（交付前改为 `已签收`）
+
+## 填写规则
+
+1. **ID**：`AC-01`、`AC-02`… 全局唯一。
+2. **验收标准**：必须可观测（DOM 顺序、完整 toast/tooltip 文案、E2E 路径、截图对比等）。
+3. **测试类型**：`unit` | `component` | `e2e` | `visual` | `manual`（可组合，如 `unit+e2e`）。
+4. **优先级**：`P0`（交付阻断）/ `P1` / `P2`。
+5. **映射**：propose 后在 `openspec/changes/<change>/tasks.md` 或 `spec.md` 中引用 `[AC-XX]`。
+6. **Intentional 偏差**：与 PRD 有意不一致时，必须同步记入 `03-待确认问题清单.md` 并在下文登记。
+
+## 验收项
+
+| ID | PRD 出处 | 验收标准（可测试） | 测试类型 | 优先级 | 映射（spec/tasks） | 验收状态 |
+|----|---------|-------------------|---------|--------|-------------------|---------|
+| AC-01 | PRD §（填写） | （填写可观测断言，toast/tooltip 须一字不差） | unit | P0 | 待映射 | 待验收 |
+| AC-02 | PRD §（填写） | （填写） | e2e | P1 | 待映射 | 待验收 |
+
+## Intentional 偏差登记
+
+| AC-ID | 偏差说明（相对 PRD） | 确认来源（03 条目或用户原话） |
+|-------|---------------------|------------------------------|
+| （无则留空） | | |
+
+## 签收检查（deliver 前人工/AI 勾选）
+
+- [ ] 全部 P0 行的「验收状态」已改为 `已验收`
+- [ ] 每条 P0 在 `tasks.md` 或 `spec.md` 中有 `[AC-XX]` 映射且对应测试已通过
+- [ ] Intentional 偏差已记入 `03` 且上表已登记
+- [ ] 已将「签收状态」改为 `已签收`

package/src/templates/artifacts/06-agent-skill.template.md

@@ -1,6 +1,6 @@
 ---
 name: sdd-flow-kit
-description: 用户说「开发/进行 {{DEFAULT_PRODUCT}} x.x.x 版本/需求」「ADI_2.3.2」等时触发。**禁止**未过 gate 直接改 src。必须先 invoke/run，确认点闭合后走 OpenSpec+Superpowers（gate→propose→apply→deliver）。
+description: 用户说「开发/进行 {{DEFAULT_PRODUCT}} x.x.x 版本/需求」「ADI_2.3.2」等时触发。**禁止**未过 gate 直接改 src。必须先 invoke/run，确认点闭合后走 OpenSpec+Superpowers（gate→05 AC→propose→ac-ready→apply→ac-signed→deliver）。
 ---
 
 # SDD Flow Kit（{{PROJECT_KIND}} — 脚本门禁）
@@ -21,19 +21,31 @@ npx sdd-flow-kit run --product {{DEFAULT_PRODUCT}} --version <版本号> -y --ag
 
 然后 **只读** `openspec/PRD/<runId>/NEXT.md` 与 `.session-state.json`，按其中命令顺序执行；**exit code ≠ 0 必须停止**。
 
+## 文档职责（SSOT）
+
+| 文档 | 职责 |
+|------|------|
+| `01` | 业务概述、风险（**非**完整验收） |
+| `05` | **唯一验收 SSOT** — 从 `source/PRD.md` 逐条抽 AC |
+| `04` | 技术方案，须引用 `[AC-XX]` |
+| `tasks.md` | 每条任务标题含 `[AC-XX]` |
+
 ## 铁律（防 vibe coding）
 
 1. `docModeOnly: true` 时 **禁止** 修改 `src/`、`frontend/src/`、`e2e/`。
-2. 用户粘贴确认点、更新 03 后：先产出 01/02/04，再 **必须**：
+2. 用户粘贴确认点后：先生成 **`05 → 04 → 01/02`**，再 **必须**：
    ```bash
    npx sdd-flow-kit gate --project-root <安装根> --run-id <runId> --expect docs-closed
    npx sdd-flow-kit phase advance --project-root <安装根> --run-id <runId> --to docs-done
    ```
-3. **仅当** `gate --expect impl-allowed` 通过后，才允许按 `openspec/changes/<change>/tasks.md` 改业务代码。
-4. 提案/实现 **必须** 读并执行：
-   - `.cursor/skills/opsx-superpowers-workflow/SKILL.md`（总编排）
+3. propose 后 **必须** `gate ac-ready`（P0 映射到 spec/tasks）才能 `phase impl`。
+4. **仅当** `gate --expect impl-allowed` 通过后，才允许按 `tasks.md` 改业务代码。
+5. **Apply 前必读**：`source/PRD.md` 对应章节 + `05-验收清单.md`（tasks 是子集，不能替代 PRD）。
+6. **deliver 前必须** `gate ac-signed`（05 中 P0 已验收且已签收）。
+7. 提案/实现 **必须** 读并执行：
+   - `.cursor/skills/opsx-superpowers-workflow/SKILL.md`
    - `openspec-propose` → `openspec-apply-change` → `pnpm run opsx:delivery-pipeline -- <change>`
-5. **禁止** 跳过 `propose` / `deliver` 或手写 tasks 全勾 `[x]` 宣称完成。
+8. TDD/Playwright 遵循 `LAYERED-TESTING.md`（L2 交互契约、L3 每页 E2E）。
 
 ## 阶段摘要
 
@@ -41,12 +53,14 @@ npx sdd-flow-kit run --product {{DEFAULT_PRODUCT}} --version <版本号> -y --ag
 |------|------|
 | A | Step1 PRD → `gate prd-fetched` → `phase after-prd` |
 | A2 | 提问模式仅 03 → `gate questions-open` |
-| B | 用户确认后 01/02/04 → `gate docs-closed` → `phase docs-done` |
-| C | `propose` + OpenSpec artifacts → `gate propose-ready` → `phase propose-done` |
-| D | `phase impl` → `gate impl-allowed` → 改代码 → `deliver` → `phase shipped` |
+| B | 用户确认后 **05→04→01/02** → `gate docs-closed` → `phase docs-done` |
+| C | `propose` + artifacts → `gate propose-ready` + **`gate ac-ready`** → `phase propose-done` |
+| D | `phase impl` → `gate impl-allowed` → `/opsx-apply`（读 PRD+05） |
+| E | `validate` → **05 签收** → `gate ac-signed` → `deliver` → `phase shipped` |
 
 ## 环境
 
 - agent: {{AGENT_NAME}}
 - 全量安装: `npx sdd-flow-kit install --project {{PROJECT_KIND}} -y`
+- 分层测试: `.cursor/skills/sdd-flow-kit/LAYERED-TESTING.md`
 - 本地 OPSX: `SDD_OPSX_WORKFLOW_PACKAGE=file:../../opsx-workflow`

package/src/templates/artifacts/{05-openspec- → 06-openspec-}/346/217/220/346/241/210/350/215/211/347/250/277.template.md

@@ -1,24 +1,33 @@
-# 05-openspec 提案阶段指引（阶段 C 完成后填写）
+# 06-openspec 提案阶段指引（阶段 C 完成后填写）
 
 > 本文件不是最终提案正文，而是 **/opsx-propose 执行后的索引与交接记录**。  
 > 真正提案产物在 `openspec/changes/<change-name>/`。
 
 ## 前置条件（必须全部满足）
+
 - [ ] `03-待确认问题清单.md` 已标注 **矛盾点池状态：已闭合**
-- [ ] `01-需求分析报告.md`、`02-改动点清单.md`、`04-技术文档草稿.md` 已生成
+- [ ] `05-验收清单.md` 已标注 **定义状态：已定义**，且 P0 项齐全
+- [ ] `01-需求分析报告.md`、`02-改动点清单.md`、`04-技术文档草稿.md` 已生成（04 须引用 AC-ID）
+- [ ] `gate ac-ready` 通过（P0 已映射到 spec/tasks）
 - [ ] 用户已确认可进入提案阶段（阶段 B 闭环）
 - [ ] `autoChainOpsx` 为 true（默认）→ 与用户确认后**同一回合**自动 propose，无需再等「继续」
 
 ## /opsx-propose 输入清单
-- 需求分析：`01-需求分析报告.md`
+
+- 需求分析：`01-需求分析报告.md`（概述）
+- **验收 SSOT**：`05-验收清单.md`（**必须**）
 - 改动清单：`02-改动点清单.md`
+- 技术方案：`04-技术文档草稿.md`（引用 AC-ID）
 - UI/交互参考：（填写用户提供的路径，例如原型页面或设计稿目录）
 
 ## 执行命令（在 AI 工具中）
+
 - `/opsx-propose`
-- 说明需基于上述 01/02 + UI 参考一次性生成 change
+- 说明需基于 **05 + 04 + 02** + UI 参考一次性生成 change
+- **tasks.md 每条任务须含 `[AC-XX]`**（与 05 中 P0 一一映射）
 
 ## 产出记录（执行后填写）
+
 - change 名称：
 - change 路径：`openspec/changes/<change-name>/`
 - 主要文件：
@@ -27,7 +36,10 @@
   - `specs/`
   - `tasks.md`
 - openspec status：（如 4/4 apply-ready）
+- AC 映射自检：（列出 P0 → tasks 行号）
 
 ## 下一步
+
 - 阶段 D：执行 `/opsx-apply`（或 `pnpm run opsx:delivery-pipeline -- <change-name>`）
+- Apply 前须读 `source/PRD.md` 对应章节 + `05-验收清单.md`（tasks 是子集，不能替代 PRD）
 - 禁止在 pipeline 未成功前宣称“需求开发完成”

package/src/templates/artifacts/{06-opsx-auto-chain.template.md → 07-opsx-auto-chain.template.md}

@@ -1,17 +1,20 @@
-# 06 OPSX 自动串联（阶段 B 完成后立即执行）
+# 07 OPSX 自动串联（阶段 B 完成后立即执行）
 
 > **不要**在阶段 B 结束后停下来问用户「是否继续」或「是否 apply」。  
 > 除非用户明确说「只提案」「先别写代码」，或 `.session-state.json` 中 `autoChainOpsx: false`。
 
 ## 输入（本 runId）
+
 | 文件 | 路径 |
 |------|------|
+| 验收 SSOT | `05-验收清单.md` |
 | 需求分析 | `01-需求分析报告.md` |
 | 改动清单 | `02-改动点清单.md` |
 | 技术草稿 | `04-技术文档草稿.md` |
 | UI 参考 | 见下方「UI 路径解析」 |
 
 ## UI 路径解析（按优先级）
+
 1. 用户本条消息给出的路径
 2. `source/PRD.md` 中的「原型图片目录」行（如 `docs/adi-v232/`）
 3. `docs/<product>-v<version无点>/` 或 `docs/<product>-<version>/` 目录（只读扫描）
@@ -19,20 +22,31 @@
 缺失 UI 时：**仍继续** propose，在 `proposal.md` / `design.md` 注明「UI 待补」。
 
 ## 阶段 C — `/opsx-propose`（同一对话回合内）
+
 1. 读仓库根 `.cursor/skills/opsx-superpowers-workflow/SKILL.md` 与 `openspec-propose/SKILL.md`
-2. 执行 `/opsx-propose`（或等价的 openspec CLI 全流程），输入 = 上表 01 + 02 + UI
+2. 执行 `/opsx-propose`，输入 = **05 + 04 + 02** + UI
 3. change 名建议：`{{PRODUCT}}-v{{VERSION}}-<short-topic>`（kebab-case）
-4. 更新 `05-openspec-提案草稿.md` 与 `.session-state.json`：`status: propose_done`
-5. **禁止**在本阶段写 `src/` 或跑 delivery-pipeline
+4. `tasks.md` 每条须含 `[AC-XX]`；完成后执行：
+   ```bash
+   npx sdd-flow-kit gate --project-root <repo> --run-id <runId> --expect ac-ready --change <name>
+   ```
+5. 更新 `06-openspec-提案草稿.md` 与 `.session-state.json`：`status: propose_done`
+6. **禁止**在本阶段写 `src/` 或跑 delivery-pipeline
+
+## 阶段 D — `/opsx-apply`（ac-ready 后**立即**执行，无需再等用户）
 
-## 阶段 D — `/opsx-apply`（提案 apply-ready 后**立即**执行，无需再等用户）
 1. `npx sdd-flow-kit ensure-opsx --agent cursor -y`（仓库根）
 2. 写 `.opsx-active-change` = change 名
-3. 读并执行：`openspec-apply-change` → `tdd-script` → `openspec-superpowers-pipeline` → `opsx-dev-delivery-pipeline`
-4. `pnpm run opsx:delivery-pipeline -- <change-name>` 直至 **exit 0**
-5. 更新 `.session-state.json`：`status: complete`，`docModeOnly: false`
+3. **Apply 前必读**：`source/PRD.md` 对应章节 + `05-验收清单.md`
+4. 读并执行：`openspec-apply-change` → `tdd-script`（分层测试策略）→ `openspec-superpowers-pipeline` → `opsx-dev-delivery-pipeline`
+5. Red 断言须写死 PRD/05 原文（toast、tooltip、列序等）
+6. `pnpm run opsx:delivery-pipeline -- <change-name>` 直至 **exit 0**
+7. deliver 前执行 `gate ac-signed`，再 `deliver`
 
 ## 完成判定
+
+- [ ] `gate ac-ready` 通过（P0 已映射）
 - [ ] `openspec/changes/<name>/` 下 applyRequires 全部 done
-- [ ] `tasks.md` 全部 `- [x]`
+- [ ] `tasks.md` 全部 `- [x]` 且含 `[AC-XX]`
+- [ ] `gate ac-signed` 通过
 - [ ] delivery-pipeline exit 0

package/src/templates/prompts/02-sdd-loop-prompt.md

@@ -38,16 +38,32 @@
 
 #### 1. 文件命名规则
 *   `[时间戳]` 建议使用 `YYYYMMDD` 格式。
-*   文件名：`01-需求分析报告.md`, `02-改动点清单.md`, `03-待确认问题清单.md`
+*   文件名：`01-需求分析报告.md`, `02-改动点清单.md`, `03-待确认问题清单.md`, **`05-验收清单.md`**
 
-#### 2. 文档模板要求
+#### 2. 文档职责（重要）
+
+| 文档 | 职责 |
+|------|------|
+| `01` | 业务概述、范围、风险（**不承担**完整验收） |
+| `05` | **唯一验收 SSOT**（从 `source/PRD.md` 逐条抽 AC） |
+| `04` | 技术方案（引用 AC-ID） |
+| `02` | 代码改动计划表 |
+
+#### 3. 文档模板要求
 
 **📄 01-需求分析报告.md**
-*   **业务概述**：PRD 核心目标摘要。
+*   **业务概述**：PRD 核心目标摘要（粗粒度，不替代 05）。
 *   **现状映射**：现有系统中对应的模块描述（引用 `openspec` 中的现有定义）。
 *   **差异分析**：PRD 与现状的具体差异（新增/修改/删除）。
 *   **风险评估**：技术风险、兼容性问题、副作用分析。
 
+**📄 05-验收清单.md（AC Matrix）**
+*   **必须从 `source/PRD.md` 逐条抽取**，禁止仅从 01 摘要归纳。
+*   **格式**：表格 — ID | PRD 出处 | 验收标准（可测试） | 测试类型 | 优先级 | 映射 | 验收状态
+*   **ID**：`AC-01`、`AC-02`…；P0 为交付阻断项。
+*   填完后标注：**定义状态：已定义**
+*   Intentional 偏差须同步记入 `03` 与 05 偏差表。
+
 **📄 02-改动点清单.md**
 *   **格式**：表格形式。
 *   **字段**：文件路径 | 改动类型 (Add/Modify/Delete) | 模块类型 (Component/Store/API) | 依赖关系 | 预估影响。
@@ -84,12 +100,13 @@
 
 **任务（本路径仅文档，不含 openspec，不含写代码）**：
 1.  更新 `03-待确认问题清单.md`，标注“**矛盾点池状态：已闭合**”，写入用户确认结论。
-2.  生成最终版 `01-需求分析报告.md` 和 `02-改动点清单.md`（清单中的路径是**计划**，不得在本回合修改这些文件）。
-3.  确认 `02-改动点清单.md` 中仅包含代码文件改动，不涉及 `openspec/spec/` 内容。
-4.  **禁止** 在阶段 B 内修改 `src/` 等业务代码。
-5.  更新 `.session-state.json`：`status: ready_for_propose`，`phase: B_done`。
-6.  **若 `autoChainOpsx !== false`（默认）且用户未说「只提案」**：同一回合继续读 `06-opsx-自动串联指引.md`，执行 `/opsx-propose`（输入 01+02+UI）→ `/opsx-apply`；**不要**要求用户再说「继续」。
-7.  仅当 `autoChainOpsx === false` 时输出：`01/02/03/04 已更新。回复「继续」进入提案。`
+2.  **从 `source/PRD.md` 生成 `05-验收清单.md`**（标注「定义状态：已定义」），再生成 `04-技术文档草稿.md`（引用 AC-ID）。
+3.  生成最终版 `01-需求分析报告.md` 和 `02-改动点清单.md`（清单中的路径是**计划**，不得在本回合修改这些文件）。
+4.  确认 `02-改动点清单.md` 中仅包含代码文件改动，不涉及 `openspec/spec/` 内容。
+5.  **禁止** 在阶段 B 内修改 `src/` 等业务代码。
+6.  更新 `.session-state.json`：`status: ready_for_propose`，`phase: B_done`。
+7.  **若 `autoChainOpsx !== false`（默认）且用户未说「只提案」**：同一回合继续读 `07-opsx-自动串联指引.md`，执行 `/opsx-propose`（输入 **05+04+02**+UI）→ `/opsx-apply`；**不要**要求用户再说「继续」。
+8.  仅当 `autoChainOpsx === false` 时输出：`05/01/02/03/04 已更新。回复「继续」进入提案。`
 
 ---
 

package/src/templates/rules/sdd-no-implement-until-apply.mdc.template

@@ -1,18 +1,28 @@
 ---
-description: SDD 脚本门禁：必须执行 sdd-flow-kit gate/phase；docModeOnly 时禁止改 src；交付前必须 deliver 成功
+description: SDD 脚本门禁：必须执行 sdd-flow-kit gate/phase；docModeOnly 时禁止改 src；交付前必须 ac-signed + deliver 成功
 alwaysApply: true
 ---
 
 # SDD 流程：脚本门禁（非自然语言）
 
+## 文档 SSOT
+
+| 文档 | 职责 |
+|------|------|
+| `01` | 业务概述（**非**完整验收） |
+| `05` | **唯一验收 SSOT**（AC Matrix） |
+| `04` | 技术方案（引用 AC-ID） |
+| `tasks.md` | `[AC-XX]` 可执行映射 |
+
 ## 强制行为
 
 1. 存在活跃 `openspec/PRD/<runId>/` 时，**每步**先读 `NEXT.md` 与 `.session-state.json`。
 2. **必须**运行 `npx sdd-flow-kit gate ...` / `phase advance` / `propose` / `deliver`，以 **命令 exit code** 为准（0 才继续）。
 3. **禁止**在未执行下列命令前修改业务代码：
-   - `npx sdd-flow-kit gate --expect docs-closed`（阶段 B 后）
+   - `npx sdd-flow-kit gate --expect docs-closed`（含 `05-验收清单.md` 已定义）
+   - `npx sdd-flow-kit gate --expect ac-ready --change <name>`（P0 已映射到 spec/tasks）
    - `npx sdd-flow-kit phase advance --to impl` + `gate --expect impl-allowed`（阶段 D 前）
-4. **禁止**在未执行 `npx sdd-flow-kit deliver` 成功前宣称需求开发完成。
+4. **禁止**在未执行 `gate ac-signed` 与 `npx sdd-flow-kit deliver` 成功前宣称需求开发完成。
 
 ## docModeOnly
 
@@ -20,9 +30,9 @@ alwaysApply: true
 
 - **仅允许** 修改 `openspec/PRD/**`、`openspec/changes/**`（提案阶段）
 - **禁止** 修改 `src/`、`e2e/`、`frontend/src/` 等
-- 用户粘贴确认点后：先 `gate docs-closed`，通过后再 `phase advance --to docs-done`；**不得**同回合改 ts/vue
+- 用户粘贴确认点后：生成 **05 → 04 → 01/02**，再 `gate docs-closed`；**不得**同回合改 ts/vue
 
-## 自然语言触发（ADI / OMS 等）
+## 自然语言触发（ADI / OMS / BreakX 等）
 
 用户说「开发/进行 ADI 2.3.2 版本」「ADI_2.3.2」等时：
 
@@ -31,7 +41,7 @@ alwaysApply: true
 
 ## 用户确认点（无需口令）
 
-1. 更新 `03` → 生成 `01/02/04`
+1. 更新 `03` → 从 `source/PRD.md` 生成 `05` → `04` → `01`/`02`
 2. 执行：
    ```bash
    npx sdd-flow-kit gate --project-root <repo> --run-id <runId> --expect docs-closed
@@ -39,14 +49,23 @@ alwaysApply: true
    ```
 3. 失败则停止，不得进入 propose/实现
 
-## 实现与交付
+## 提案 / 实现 / 签收 / 交付
 
 ```bash
 npx sdd-flow-kit propose --project-root <repo> --run-id <runId> --change <name>
-# … AI 生成 openspec artifacts …
+# … AI 生成 openspec artifacts；tasks.md 须含 [AC-XX] …
 npx sdd-flow-kit gate --project-root <repo> --run-id <runId> --expect propose-ready --change <name>
+npx sdd-flow-kit gate --project-root <repo> --run-id <runId> --expect ac-ready --change <name>
 npx sdd-flow-kit phase advance --project-root <repo> --run-id <runId> --to impl --change <name>
+# Apply 前必读 source/PRD.md + 05-验收清单.md
 # … 实现 …
+npx sdd-flow-kit validate --project-root <repo> --run-id <runId> --change <name>
+# 05 签收：P0 已验收 + 签收状态已签收
+npx sdd-flow-kit gate --project-root <repo> --run-id <runId> --expect ac-signed
 npx sdd-flow-kit deliver --project-root <repo> --run-id <runId> --change <name>
 npx sdd-flow-kit phase advance --project-root <repo> --run-id <runId> --to shipped --change <name>
 ```
+
+## 分层测试（L1–L4）
+
+见 `.cursor/skills/sdd-flow-kit/LAYERED-TESTING.md`（由 sdd-flow-kit 安装）。