sdd-flow-kit 1.0.27 → 1.1.0

package/dist/steps/startFlow.js

@@ -10,6 +10,8 @@ const utils_1 = require("../core/utils");
 const fs_1 = require("../core/fs");
 const templates_1 = require("../core/templates");
 const inferProject_1 = require("../core/inferProject");
+const sessionState_1 = require("../core/sessionState");
+const writeNext_1 = require("../core/writeNext");
 function renderTemplate(template, vars) {
     let out = template;
     for (const [k, v] of Object.entries(vars)) {
@@ -76,17 +78,14 @@ async function startFlowScaffold(options) {
     await (0, fs_1.writeTextFileEnsuredDir)(path_1.default.join(outputRoot, "05-openspec-提案草稿.md"), openspecEntryTemplate);
     const opsxAutoChainTemplate = await (0, templates_1.loadTemplateText)("artifacts/06-opsx-auto-chain.template.md");
     await (0, fs_1.writeTextFileEnsuredDir)(path_1.default.join(outputRoot, "06-opsx-自动串联指引.md"), opsxAutoChainTemplate);
-    await (0, fs_1.writeTextFileEnsuredDir)(path_1.default.join(outputRoot, ".session-state.json"), JSON.stringify({
+    const session = (0, sessionState_1.defaultSession)({
         product: options.product,
         version: options.version,
         runId,
         outputRoot,
-        status: "awaiting_user_confirmation",
-        docModeOnly: true,
-        autoChainOpsx: true,
-        phase: "A_or_B",
-        createdAtISO: new Date().toISOString(),
-    }, null, 2));
+    });
+    await (0, sessionState_1.writeSession)(outputRoot, session);
+    await (0, writeNext_1.writeInitialNext)(outputRoot, options.projectRoot, runId);
     // runDir 自述
     await (0, fs_1.writeTextFileEnsuredDir)(path_1.default.join(outputRoot, "RUNME.md"), [
         "# RUNME（SDD 流程执行说明）",
@@ -113,16 +112,11 @@ async function startFlowScaffold(options) {
         "- `02-改动点清单.md`",
         "- `04-技术文档草稿.md`",
         "",
-        "## Step 5–6：自动串联 OPSX（默认）",
-        "03 闭环且 01/02/04 完成后，**同一 AI 回合**读 `06-opsx-自动串联指引.md`：",
-        "1. `/opsx-propose`（输入 01、02、UI；UI 默认读 `source/PRD.md` 原型目录）",
-        "2. 提案 apply-ready 后立即 `/opsx-apply` + `pnpm run opsx:delivery-pipeline`（exit 0）",
-        "勿停下来问「是否继续」。仅当用户说「只提案」或 `.session-state.json` 中 `autoChainOpsx: false` 时暂停。",
+        "## Step 5–6：脚本门禁（禁止仅靠自然语言跳步）",
+        "每一步必须先执行 `NEXT.md` 中的 `npx sdd-flow-kit gate` / `phase advance` / `propose` / `deliver`。",
+        "命令失败 (exit≠0) 时 **不得** 改 `src/` 或宣称完成。",
         "",
-        "## Step 6 明细：Apply + TDD + Playwright（阶段 D）",
-        "依次执行 skill：`openspec-apply-change` → `tdd-script` → `openspec-superpowers-pipeline` → `opsx-dev-delivery-pipeline`。",
-        "仓库根执行：`pnpm run opsx:delivery-pipeline -- <change-name>`（须 exit 0）。",
-        "禁止跳过 TDD / Playwright 裸写代码收尾。详见 `.cursor/skills/sdd-flow-kit/SKILL.md` 阶段 D。",
+        "详见：`NEXT.md`、`06-opsx-自动串联指引.md`、`.cursor/skills/sdd-flow-kit/SKILL.md`。",
     ].join("\n"));
     return {
         runId,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sdd-flow-kit",
-  "version": "1.0.27",
+  "version": "1.1.0",
   "private": false,
   "description": "Cross-agent SDD automated development workflow kit (ADI/ADI-like).",
   "license": "MIT",

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

@@ -1,148 +1,73 @@
 ---
 name: sdd-flow-kit-trigger
-description: 开发某版本需求、SDD 流程、待确认问题澄清、用户回复确认点/矛盾点结论时触发。阶段 A/B 仅文档；阶段 B 闭环后**自动** /opsx-propose → /opsx-apply（除非用户说只提案或 autoChainOpsx=false）。
+description: 开发某版本需求、SDD 流程、用户回复确认点时触发。**必须**按 openspec/PRD/<runId>/NEXT.md 执行 `npx sdd-flow-kit gate|phase|propose|deliver`；命令 exit≠0 时禁止进入下一阶段或改 src/。
 ---
 
-# SDD Flow Trigger Skill
+# SDD Flow（脚本门禁版 — 不依赖自然语言跳步）
 
-## 触发条件（仅这些场景触发）
-- 用户说法包含类似：
-  - `开发 XXX 1.2 需求`
-  - `开发 XXX 1.2.3 版本`
-  - `开发 XXX-V1.2.3 版本`
-  - `开发XXX-V1.2.3版本`（无空格连写）
-  - `开发 XXX PRD`
-- 或明确要求“按 SDD 流程”推进某版本需求
-- **用户回复待确认点 / 粘贴确认结论 / 说「按上面确认继续」**（即使未再说「开发 XX 需求」也视为 SDD 流程续跑）
+## 铁律
 
-## ⚠️ 最高优先级：文档模式 vs 实现模式
+1. 每步开始前读 `openspec/PRD/<runId>/NEXT.md` 与 `.session-state.json`。
+2. **必须**在终端执行其中的 `npx sdd-flow-kit ...`；根据 **exit code** 判断是否可继续（0=通过，非0=停止）。
+3. `docModeOnly: true` 时 **禁止** 修改 `src/`、`e2e/`、`frontend/src/` 等实现路径。
+4. 只有 `gate --expect impl-allowed` 通过后才允许改业务代码。
+5. 只有 `deliver` 成功且 `phase advance --to shipped` 通过后才可宣称「开发完成」。
 
-| 模式 | 何时 | 允许改动的路径 | 禁止 |
-|------|------|----------------|------|
-| **文档模式** | 阶段 A/B/C，含「用户发来确认点」 | 仅 `openspec/PRD/**`（及阶段 C 的 `openspec/changes/**`） | 任何 `src/`、`pages/`、`components/` 等业务代码 |
-| **实现模式** | 阶段 D（提案 apply-ready 后**自动进入**，无需用户再说「开始 apply」） | 按 openspec change 与 pipeline 要求 | 跳过 propose / 跳过 pipeline |
+## 准备
 
-**常见错误**：用户粘贴确认点后，你一边更新 `03` 一边改 `.tsx` —— **绝对禁止**。确认回复 = 只做文档，同一回合不得 touch 业务代码。
+```bash
+npx sdd-flow-kit run --product <PRODUCT> --version <VERSION> -y
+```
 
-### 用户侧：零口令（不要要求加前缀）
-- 用户**直接粘贴**确认点、编号结论、「按 1/2/3 继续」即可；**禁止**要求用户输入【仅文档模式】等固定话术。
-- 你须在收到后**自动**判定为阶段 B 的文档模式；先读 `openspec/PRD/<runId>/.session-state.json`（`docModeOnly: true` 时严禁写业务代码）与 `03-待确认问题清单.md`。
-- **默认自动串联**（`openspec/PRD/<runId>/.session-state.json` 中 `autoChainOpsx !== false`）：
-  - 阶段 B 产出 01/02/闭环03/04 后，**同一回合**继续阶段 C→D，**不要**停下来问「是否继续」。
-  - 读 `06-opsx-自动串联指引.md` 与 `.cursor/skills/opsx-superpowers-workflow/SKILL.md`。
-- **仅当用户说**「只提案」「先别写代码」时：阶段 C 结束后停止，等待 `/opsx-apply`。
-- 口语仍可用：`继续` / `做提案` / `开始 apply`（用于断点续跑）。
+工作目录：`openspec/PRD/<runId>/`（已生成 `NEXT.md`）。
 
-## 触发后执行规则（分阶段，禁止跳步）
+## 标准命令序列（复制 NEXT.md，按序执行）
 
-### 准备
-1. 从用户输入提取 `product`、`version`
-2. 执行：`npx sdd-flow-kit run --product <product> --version <version> -y`
-3. 工作目录：`openspec/PRD/<runId>/`（见 `RUNME.md`）
+| 阶段 | 门禁 / 推进 |
+|------|-------------|
+| PRD 已拉取 | `gate --expect prd-fetched` → `phase advance --to after-prd` |
+| 提问模式 | `gate --expect questions-open` |
+| 用户确认后（仅文档） | 更新 01/02/03/04 → `gate --expect docs-closed` → `phase advance --to docs-done` |
+| 提案 | `propose --change <name>` →（AI 生成 openspec artifacts）→ `gate --expect propose-ready` → `phase advance --to propose-done` |
+| 实现 | `phase advance --to impl --change <name>` → `gate --expect impl-allowed` → 按 tasks 改代码 |
+| 交付 | `deliver --change <name>` → `phase advance --to shipped` |
 
----
-
-### 阶段 A — Step1 + Step2（必须可停顿）
-1. **Step1**：打开 `01-获取需求文档指引.md`，**在终端执行其中的 `confluence-doc.py` 命令**（不要跳过）。
-   - ADI 必须用 `docs/adi-doc-skill` 或上级 `../docs/adi-doc-skill`，**禁止**用 `docs/oms-doc-skill`。
-   - 用户说「开发 ADI_V2.3.2」时，脚本参数传 `2.3.2` 或 `ADI_V2.3.2` 均可。
-   - 将下载的 markdown 回填 `source/PRD.md`。
-2. **Step2**：执行 `02-需求分析提示词.md`（引用 `docs/` 下已下载的 PRD）
+统一参数（示例）：
 
-**门禁（Step2）**
-- 若矛盾点池**未闭合**（提问模式）：
-  - **仅允许** 输出/更新 `03-待确认问题清单.md`
-  - **禁止** 生成 `01-需求分析报告.md`、`02-改动点清单.md`、`04-技术文档草稿.md`
-  - **必须停止**，请用户补充/确认待确认项
-- **不得** 进入阶段 B/C/D
+```bash
+export PR=<项目根目录>
+export RID=<runId>
+export CH=<change-name>
 
----
+npx sdd-flow-kit gate --project-root "$PR" --run-id "$RID" --expect docs-closed
+npx sdd-flow-kit phase advance --project-root "$PR" --run-id "$RID" --to docs-done
+```
 
-### 阶段 B — 用户确认后（仅文档 01/02/03/04）
-**触发条件**：用户已回复待确认点，或明确表示“矛盾点池已闭合 / 按确认点继续”。
-
-**「用户发来确认点」专用指令（本回合严格执行）**
-1. 先读 `openspec/PRD/<runId>/03-待确认问题清单.md`，把用户消息逐条写入「用户确认结论」列。
-2. 将状态改为 **矛盾点池状态：已闭合**。
-3. 再生成 `01`、`02`、`04`（路径均在 `openspec/PRD/<runId>/`）。
-4. **本回合禁止**：`StrReplace`/`Write` 任何业务源码；禁止「顺手实现一版」。
-5. 更新 `.session-state.json`：`status: ready_for_propose`，`phase: B_done`。
-6. **若 `autoChainOpsx !== false` 且用户未说「只提案」**：**不要结束回合**——立即打开 `06-opsx-自动串联指引.md` 执行阶段 C→D（见下文）。
-7. 若 `autoChainOpsx === false`：简短说明 01/02/03/04 已就绪，等待用户说「继续」。
-
-**本阶段只允许产出：**
-1. 更新 `03-待确认问题清单.md`（标注 **矛盾点池状态：已闭合**，写入用户确认结论）
-2. 生成最终版 `01-需求分析报告.md`
-3. 生成最终版 `02-改动点清单.md`（仅代码文件改动）
-4. 生成 `04-技术文档草稿.md`
-
-**本阶段禁止：**
-- 修改 `src/`、`pages/`、`components/`、`api/` 等实现代码（`02-改动点清单` 只是**计划**，不是实施许可）
-- 在 **未闭合 03** 时执行 `/opsx-propose` 或 `/opsx-apply`
-- 在 `autoChainOpsx === false` 时未经用户同意就进入阶段 C/D
-
----
+## 各阶段说明（辅助，不可替代脚本）
 
-### 阶段 C — `/opsx-propose`（生成提案，对应 Step5）
-**触发条件**：
-- 阶段 B 已完成（03 已闭合，01/02/04 已生成），**且**
-- `autoChainOpsx !== false`（默认）→ **与用户确认同一回合内自动执行**；或用户说「继续/做提案」；或 `status` 为 `ready_for_propose` 且用户未说「只提案」。
+### 阶段 A
+- Step1：`01-获取需求文档指引.md` → 回填 `source/PRD.md`
+- Step2：`02-需求分析提示词.md`；未闭合时 **只** 改 `03`
 
-**必须执行：**
-1. 先读当前仓库 `.opsx/config.json` 与本地 OPSX skills（禁止跨项目 fallback）
-2. 执行 **`/opsx-propose`**（遵循 `.cursor/commands/opsx-propose.md` 与 `openspec-propose` skill），输入至少包含：
-   - `openspec/PRD/<runId>/01-需求分析报告.md`
-   - `openspec/PRD/<runId>/02-改动点清单.md`
-   - **UI 图/交互参考**（按 `06-opsx-自动串联指引.md` 解析；无则注明缺失并继续）
-3. 一次性生成 openspec change（`proposal.md`、`design.md`、`specs/`、`tasks.md` 等）
-4. 更新 `05-openspec-提案草稿.md`；`.session-state.json` → `status: propose_done`
+### 阶段 B
+- 用户确认后：生成 01/02/04，**然后必须** `gate docs-closed`（会检测 git 是否误改 src）
 
-**本阶段交付物 = openspec 提案产物**。  
-**本阶段禁止**：写 `src/`、跑 delivery-pipeline。
+### 阶段 C
+- `propose` 创建 change；AI 按 openspec-propose 写 artifacts；`gate propose-ready` 校验 apply-ready
 
-**默认**：提案 apply-ready 后 **立即** 进入阶段 D（勿问用户「是否 apply」），除非用户说了「只提案」。
+### 阶段 D
+- `phase advance --to impl` 将 `docModeOnly` 设为 false
+- 实现后 `deliver` 跑 `ensure-opsx` + `pnpm run opsx:delivery-pipeline`
 
----
-
-### 阶段 D — Apply + TDD + Playwright 交付（禁止裸写代码收尾）
-**触发条件**：阶段 C 的 openspec 提案已 apply-ready（`autoChainOpsx` 默认下与阶段 C **同一连续执行**）。
-
-**严禁**：跳过 skill 链、不按 `tasks.md` TDD、不跑 delivery-pipeline 就改 `src/` 并宣称完成。
-
-**必须按顺序执行（以仓库根 `AGENTS.md` 与 `.cursor/skills/` 为准）：**
-
-0. **环境门禁（缺则自动安装，不可跳过）** — 在仓库根执行：
-   ```bash
-   npx sdd-flow-kit ensure-opsx --agent cursor -y
-   ```
-   - 检测：openspec、TDD/Playwright skills、`opsx:delivery-pipeline` 脚本、`AGENTS.md` 等。
-   - 若 FAIL：上述命令会运行 `npx @lixin5257xxx/opsx-workflow setup ...` 安装工作流；**exit 0 前不得开始改 `src/`**。
-1. 读取 `AGENTS.md`、`docs/agent-workflow.md`、`.opsx/config.json`。
-2. 绑定 change 名：写入 `.opsx-active-change`（一行 kebab-case），或 `export OPSX_ACTIVE_CHANGE=<name>`。
-3. **依次读取并执行**（不可省略）：
-   - `.cursor/skills/openspec-apply-change/SKILL.md` — `openspec instructions apply --change "<name>" --json`
-   - `.cursor/skills/tdd-script/SKILL.md` — **每项 task 先测后实现**，并勾选 `tasks.md` 的 `- [x]`
-   - `.cursor/skills/openspec-superpowers-pipeline/SKILL.md` — Delta Spec / 代码质量审查门控
-   - `.cursor/skills/opsx-dev-delivery-pipeline/SKILL.md` — 机械交付脚本（TDD 门禁 → validate → **Playwright** → archive）
-4. 在**仓库根**（含 `package.json` 的目录）执行：
-   ```bash
-   pnpm run opsx:delivery-pipeline -- <change-name>
-   ```
-   脚本路径须为：`.cursor/skills/opsx-dev-delivery-pipeline/scripts/opsx-delivery-pipeline.sh`（若 `package.json` 仍指向 `poquan-*`，先运行 `npx sdd-flow-kit install -y` 修复）。
-5. **完成判定**：`tasks.md` 全部 `- [x]` **且** 上一条命令 **exit 0**。否则不得宣称 SDD 流程结束。
-
----
+## 严禁
 
-## 严禁（全局）
-- 澄清/确认阶段写业务代码（最常见违规）
-- 未闭合时一次性生成 `01~05` 或直接进入提案/实现
-- 把 `02-改动点清单.md` 当作可以立刻改文件的指令
-- 跳过用户确认点
-- 在错误仓库执行 OPSX（如 fallback 到其它项目的 poquan-web 路径）
+- 跳过 `gate` / `phase` 直接改代码或宣称完成
+- `docs-closed` 未通过时修改 `src/`
+- 手写 `tasks.md` 全勾 `[x]` 而不跑 `deliver`
+- 用自然语言代替 exit code 判断
 
-## 非触发场景
-- 非“开发某版本需求”类对话 → 按普通问答处理
+## 环境
 
-## 当前环境
 - agent: {{AGENT_NAME}}
-- 安装: `npx sdd-flow-kit install`
+- 安装: `npx sdd-flow-kit install -y`
+- 脚本帮助: `npx sdd-flow-kit --help`

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

@@ -1,46 +1,45 @@
 ---
-description: SDD 门禁：存在 openspec/PRD 待确认或用户回复澄清结论时自动文档模式，禁止改业务代码；仅 /opsx-apply 后可实现
+description: SDD 脚本门禁：必须执行 sdd-flow-kit gate/phase；docModeOnly 时禁止改 src；交付前必须 deliver 成功
 alwaysApply: true
 ---
 
-# SDD 流程：禁止提前写代码
+# SDD 流程：脚本门禁（非自然语言）
 
-## 自动进入「文档模式」（用户无需加任何前缀）
+## 强制行为
 
-**不要要求用户粘贴【仅文档模式】等口令。** 满足以下任一条件时，你必须默认文档模式，即使用户只发了编号列表或「确认了」：
+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 phase advance --to impl` + `gate --expect impl-allowed`（阶段 D 前）
+4. **禁止**在未执行 `npx sdd-flow-kit deliver` 成功前宣称需求开发完成。
 
-1. 仓库存在 `openspec/PRD/*/03-待确认问题清单.md`，且其中 **矛盾点池状态：未闭合**（或用户本条消息明显是在回答其中的待确认项）。
-2. 上一轮你刚输出过待确认问题 / 请用户确认 / 矛盾点池未闭合。
-3. 用户消息为：编号结论、选用方案、是/否、补充业务规则、粘贴 PRD 片段说明——且当前对话上下文在 SDD/`openspec/PRD` 需求流程中。
-4. `openspec/PRD/*/.session-state.json` 中 `docModeOnly` 为 `true`（若存在则必读）。
+## docModeOnly
 
-**识别到上述情况后**：在本回合**内部**执行文档模式，不要要求用户改说法。
+当 `openspec/PRD/*/.session-state.json` 中 `docModeOnly: true`：
 
-当用户处于 **需求澄清 / 待确认回复 / 矛盾点确认** 时，你必须遵守：
+- **仅允许** 修改 `openspec/PRD/**`、`openspec/changes/**`（提案阶段）
+- **禁止** 修改 `src/`、`e2e/`、`frontend/src/` 等
+- 用户粘贴确认点后：先 `gate docs-closed`，通过后再 `phase advance --to docs-done`；**不得**同回合改 ts/vue
 
-## 本回合只允许（文档模式）
-- 读写 `openspec/PRD/**` 下的 markdown（`01`~`05`、`source/`、`RUNME.md`）
-- 只读扫描 `src/`、`pages/`、`components/` 等用于分析，**不得修改**
+## 用户确认点（无需口令）
 
-## 本回合严禁
-- 修改或新建任何业务实现代码：`src/**`、`app/**`、`pages/**`、`components/**`、`api/**`、`store/**`、`hooks/**` 等
-- 运行会改动业务代码的 refactor / fix / feature 实现
-- 在未执行 `/opsx-propose` 前创建 `openspec/changes/**`（除非用户明确要求进入提案阶段）
-- 在用户未明确同意前执行 `/opsx-apply`
+1. 更新 `03` → 生成 `01/02/04`
+2. 执行：
+   ```bash
+   npx sdd-flow-kit gate --project-root <repo> --run-id <runId> --expect docs-closed
+   npx sdd-flow-kit phase advance --project-root <repo> --run-id <runId> --to docs-done
+   ```
+3. 失败则停止，不得进入 propose/实现
 
-## 用户直接粘贴确认点（最常见误触，勿要求用户加前缀）
-1. 定位最新或对话相关的 `openspec/PRD/<runId>/`（读 `RUNME.md` 或 `.session-state.json`）。
-2. **仅**更新 `03`（写入用户结论，标为已闭合）。
-3. 再生成/更新 `01`、`02`、`04`。
-4. 生成 `01`、`02`、`04` 后更新 `.session-state.json`：`status: ready_for_propose`，`phase: B_done`。
-5. **默认自动串联**（`autoChainOpsx !== false`，且用户未说「只提案」「先别写代码」）：
-   - **同一回合**读 `06-opsx-自动串联指引.md`，执行 `/opsx-propose` → `/opsx-apply`。
-   - UI 参考优先：`source/PRD.md` 中的原型目录（如 `docs/adi-v232/`），其次用户本条消息给出的路径。
-   - **不要**停下来问「是否继续」或「是否 apply」。
-6. 仅当 `autoChainOpsx === false` 时：文档更新后停止，等用户说「继续」再 propose。
+## 实现与交付
 
-## 唯一允许写业务代码的时机
-- 阶段 D：`/opsx-propose` 已完成且 change **apply-ready** 后执行 `/opsx-apply`（SDD 默认与用户确认后**自动**进入，无需再等「开始 apply」）。
-- 用户明确「只提案」时：在 apply-ready 之前**禁止**写业务代码。
-
-路径 B（03 已闭合、01/02/04 已生成）中：**禁止**仅更新文档就结束回合而不进入 propose（除非 `autoChainOpsx === false` 或用户说只提案）。
+```bash
+npx sdd-flow-kit propose --project-root <repo> --run-id <runId> --change <name>
+# … AI 生成 openspec artifacts …
+npx sdd-flow-kit gate --project-root <repo> --run-id <runId> --expect propose-ready --change <name>
+npx sdd-flow-kit phase advance --project-root <repo> --run-id <runId> --to impl --change <name>
+# … 实现 …
+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>
+```