@gordon.gan/specflow 1.3.0-beta → 1.3.1-beta

package/README.md

@@ -8,17 +8,19 @@
 
 SpecFlow 把 **OpenSpec**（结构化需求规划）和 **Superpowers**（TDD、调试、代码审查等工程纪律）合并为一个工具：一个 CLI 负责确定性操作，一套跨 IDE 工作流技能负责 AI 编排，覆盖从探索需求到归档合并的完整生命周期。
 
-| 环境 | 命令形式 | 详细指南 |
-|------|----------|----------|
-| Claude Code | `/specflow:propose` 等斜杠命令 | 本文 |
-| Cursor | `specflow:propose` 等命令 | [Cursor 指南](./CURSOR_PACKAGING_AND_USAGE_GUIDE.md) |
-| OpenAI Codex | `$specflow-propose` 等技能 | [Codex 指南](./CODEX_PACKAGING_AND_USAGE_GUIDE.md) |
+| 场景 | 入口 | 详细指南 |
+|------|------|----------|
+| **单仓（默认）** | Claude `/specflow:*` · Cursor `specflow:*` · Codex `$specflow-*` | **本文**（含中文产物、`apply --yes`） |
+| Cursor 打包与安装 | Cursor 命令与资产 | [Cursor 指南](./CURSOR_PACKAGING_AND_USAGE_GUIDE.md) |
+| Codex 打包与安装 | Codex 技能与资产 | [Codex 指南](./CODEX_PACKAGING_AND_USAGE_GUIDE.md) |
 | 多语言 / Go Profile | SpecFlow + 语言专项 skills | [语言 Profile 指南](./LANGUAGE_PROFILE_USAGE_GUIDE.md) |
-| 多仓 / 前后端一体需求（**权威**） | Contract Hub + Spokes + 产物与 CLI | [多仓完整指南](./MULTI_REPO_GUIDE.md) |
-| 多仓原生能力（设计） | Store / References / Workset | [多仓技术方案](./MULTI_REPO_TECHNICAL_DESIGN.md) |
-| 多仓场景示例（TALOS） | contracts + api + web 实操路径 | [TALOS 多仓教程](./TALOS_MULTI_REPO_TUTORIAL.md) |
-| TALOS 公共需求详例 | 工作区邀请成员（Hub→BE→FE→联调） | [公共需求 Walkthrough](./docs/TALOS_SHARED_REQUIREMENT_WALKTHROUGH.md) |
-| 产物与作用 | explore / proposal / delta / design / tasks / 主 specs | [产物说明](./SPECFLOW_ARTIFACTS.md) |
+| 多仓（**权威**） | Contract Hub + Spokes | [多仓完整指南](./MULTI_REPO_GUIDE.md) |
+| 多仓技术方案 | Store / References / Workset | [多仓技术方案](./MULTI_REPO_TECHNICAL_DESIGN.md) |
+| 多仓场景示例（TALOS） | contracts + api + web | [TALOS 多仓教程](./TALOS_MULTI_REPO_TUTORIAL.md) |
+| TALOS 公共需求详例 | Hub→BE→FE→联调 | [公共需求 Walkthrough](./docs/TALOS_SHARED_REQUIREMENT_WALKTHROUGH.md) |
+| 产物与作用 | explore / proposal / delta / design / tasks | [产物说明](./SPECFLOW_ARTIFACTS.md) |
+
+未配置 `store` / `references` / `workflow.profile` 时，行为就是**单仓 SpecFlow**（`standalone`）；多仓为可选增强。
 
 ---
 
@@ -44,12 +46,16 @@ explore（可选）→ propose → refine → apply → review → test → veri
 | 能力 | 说明 |
 |------|------|
 | **结构化规划** | 一次 propose 产出 proposal、delta specs、design、tasks 四个 artifact |
+| **中文 / 英文产物** | `specflow init --artifact-language zh-CN`（别名 `zh`）写入 `artifacts.language`；叙述可中文，协议标记保持英文 |
 | **多轮精化** | refine 内部循环（≥2 轮），攻击性审查假设、边界与 scope |
 | **纪律化构建** | apply 先重写 tasks.md，再逐任务 TDD；design 有漏则回 refine |
+| **`apply --yes`** | 当前调用内自动放行成功确认门禁，构建成功后串行 review → test → verify；不绕过 Block / 失败，不自动 archive |
+| **语言感知审查** | apply 按 `go.mod` / `package.json` 等路由到 ECC reviewer（TS / Python / Go / Rust / Kotlin / Java） |
 | **双重验收** | verify 对照 delta specs 与主 specs 做回归检查 |
 | **变更归档** | archive 自动 merge delta、移入 archive、可做 git 分支清理 |
 | **跨 IDE 一致** | Claude / Cursor / Codex 共享同一套技能与 prompt，parity 可校验 |
 | **确定性 CLI** | 校验、合并、状态追踪、资产同步 — 不依赖 AI 猜 |
+| **可选语言 Profile** | SpecFlow 管流程门禁；Go/TS 等专项 skills 按仓库挂载，见 [语言 Profile 指南](./LANGUAGE_PROFILE_USAGE_GUIDE.md) |
 
 ---
 
@@ -67,6 +73,7 @@ explore（可选）→ propose → refine → apply → review → test → veri
 │  refine           ≥2 轮精化：挑战假设 / 新方案 / 探边界 / 质疑 scope     │
 │       ↓                                                                 │
 │  apply            Phase A 重写 tasks.md → Phase B 逐任务 TDD 执行         │
+│                   （可选 /specflow:apply --yes：少打断，成功后串行验收）   │
 │       ↓                                                                 │
 │  review → test → verify                                                 │
 │       ↓                                                                 │
@@ -117,7 +124,7 @@ npm install -g @gordon.gan/specflow
 npm install -g github:Gordon-Gan-Jiang/specflow
 
 # 验证
-specflow --version   # 以 npm / package.json 为准（开发中可见 1.2.0-beta）
+specflow --version   # 以 npm / package.json 为准（当前 1.3.1-beta）
 specflow --help
 ```
 
@@ -160,23 +167,45 @@ artifacts:
 
 ### 跑通第一个变更
 
-**需求已清晰：**
+**需求已清晰（交互确认，默认）：**
 
 ```
 /specflow:propose "给用户管理模块加批量导入"
 /specflow:refine
 /specflow:apply
+/specflow:review
+/specflow:test
 /specflow:verify
 /specflow:archive
 ```
 
-需要少打断确认时，可用 `/specflow:apply --yes`：自动接受成功的 Gate A/B 确认，并在构建成功后串行执行 review → test → verify；失败、Block、设计缺口仍会停下，且不会自动 archive。
+**少打断（`apply --yes`）：**
+
+```
+/specflow:propose "给用户管理模块加批量导入"
+/specflow:refine
+/specflow:apply --yes
+# 构建成功后自动串行：review → test → verify
+# 全部通过后你再手动：
+/specflow:archive
+```
+
+`/specflow:apply --yes` 只影响**当前这一次**调用：
+
+| 会自动做 | 不会自动做 / 仍会停下 |
+|----------|------------------------|
+| 接受成功的 Phase A 重写确认（Gate A） | 设计缺口、重组选项需人决策 |
+| 任务审查为 `Approve` / `Warning` 时进入下一任务 | 审查 `Block`、测试失败、前置 phase 不对 |
+| Phase B 成功后串行 review → test → verify | 自动 `/specflow:archive` |
+| | CRITICAL / HIGH review、test 红、verify `FAIL` 时中断序列 |
+
+Cursor：`specflow:apply --yes`；Codex：`$specflow-apply --yes`。
 
 **需求模糊：**
 
 ```
 /specflow:explore "不确定用 CSV 还是 Excel，也不清楚现有用户表结构"
-# 确认 explore.md 后：
+# 确认 explore.md 的 Status 为 confirmed 后：
 /specflow:propose
 /specflow:refine
 ...
@@ -248,14 +277,14 @@ specflow init
 | 命令 | 做什么 |
 |------|--------|
 | **explore** | 读代码、比方案、定边界；产出 `explore.md`，confirmed 后 handoff 到 propose |
-| **propose** | 一次产出 proposal、delta specs、design、tasks（第一轮深度思考，非占位骨架） |
+| **propose** | 一次产出 proposal、delta specs、design、tasks（第一轮深度思考，非占位骨架）；叙述语言跟 `artifacts.language` |
 | **refine** | 内部多轮循环（≥2 轮，AI 判断收敛）；可更新任意 artifact |
-| **apply** | Phase A 用 writing-plans 规则重写 tasks.md；Phase B subagent TDD 逐任务执行 |
+| **apply** | Phase A 重写 tasks.md；Phase B 按语言路由 ECC 审查 + TDD 逐任务执行；可选 `--yes` |
 | **review** | 代码审查，对照 specs 检查回归 |
 | **test** | 单元 + 集成 + E2E + 回归测试 |
-| **verify** | Pass 1：delta specs 验收；Pass 2：主 specs 回归（无基线时显式 skipped） |
-| **archive** | 归档变更、delta merge、git 分支清理；默认要求 phase=apply |
-| **fix** | 修 Bug 一条龙 |
+| **verify** | Pass 1：delta specs 验收；Pass 2：主 specs 回归（无基线时显式 skipped）；Web 另有安全 Pass |
+| **archive** | 归档变更、delta merge、git 分支清理；单仓默认要求 phase=`apply` |
+| **fix** | 修 Bug 一条龙（可加 `--urgent` 跳过审查） |
 | **snap** | 从 git 历史反推变更并归档 |
 
 > **v1.0.1 起命令已重命名**（对齐 OpenSpec 术语）：`plan→propose`、`build→apply`、`done→archive`。`.specflow.yaml` 的 phase 枚举同步为 `propose/refined/apply/archived`（读取时兼容旧值 `plan`/`built`）。
@@ -290,7 +319,46 @@ CLI 从当前目录**向上查找**项目根（识别 `specflow/config.yaml`）
 | 命令 | 说明 |
 |------|------|
 | `specflow validate <文件>` | 校验 spec 文件格式（WHEN/THEN scenario 等） |
-| `specflow instructions <artifact> <change>` | 查看某 artifact 的创建指令 |
+| `specflow instructions <artifact> <change>` | 查看某 artifact 的创建指令（含 `artifactLanguage` / `languageGuidance`） |
+
+---
+
+## 单仓常用能力速查
+
+### 产物语言（中文 / 英文）
+
+```bash
+specflow init --artifact-language zh-CN   # 推荐国内团队
+# 已有项目：直接改 specflow/config.yaml → artifacts.language（init 不覆盖已有 config）
+```
+
+| 会本地化 | 保持英文 / 不变 |
+|----------|-----------------|
+| Why / What、场景叙述、design 说明、tasks 描述 | `ADDED Requirements`、`WHEN` / `THEN`、`Requirement:` / `Scenario:` |
+| | Change ID、capability id、路径、命令、代码符号 |
+
+切换语言只影响**之后新建或主动重写**的内容，不会自动翻译历史产物。
+
+### `apply --yes`（非交互确认）
+
+```text
+/specflow:apply --yes
+```
+
+适合任务清单已确认、希望少打断连续落地的场景。质量门禁仍在：Block / 失败 / 设计缺口会停；通过后需你手动 archive。
+
+### 语言感知代码审查（内置）
+
+apply Phase B 在项目根检测语言信号（如 `go.mod`、`tsconfig.json`、`pyproject.toml`），选用对应 ECC reviewer；无匹配时用通用 reviewer。更深的语言惯用法可再挂 [语言 Profile](./LANGUAGE_PROFILE_USAGE_GUIDE.md)。
+
+### 升级与健康检查
+
+```bash
+npm install -g @gordon.gan/specflow@beta   # 或指定版本
+specflow sync --ide all
+specflow doctor --parity
+specflow parity-report
+```
 
 ---
 

package/dist/core/opener-launch.d.ts

@@ -1,3 +1,18 @@
+import { type SpawnSyncOptions } from 'node:child_process';
 import type { OpenerDefinition } from './openers.js';
+export interface OpenerSpawnPlan {
+    readonly command: string;
+    readonly args: string[];
+    readonly options: SpawnSyncOptions;
+}
+/**
+ * Build spawn argv for launching a workspace-file opener.
+ *
+ * On Windows, Cursor/VS Code ship as `*.cmd` shims. Node's spawn with
+ * `shell: false` cannot execute those directly (ENOENT). Follow Node's
+ * recommended pattern: `cmd.exe /d /s /c` with a single quoted command line
+ * and `windowsVerbatimArguments`, without enabling shell interpolation.
+ */
+export declare function buildOpenerSpawn(opener: OpenerDefinition, workspacePath: string, primaryPath: string, platform?: NodeJS.Platform, comSpec?: string): OpenerSpawnPlan;
 export declare function isOpenerAvailable(opener: OpenerDefinition): boolean;
 export declare function launchOpener(opener: OpenerDefinition, workspacePath: string, primaryPath: string): void;

package/dist/core/opener-launch.js

@@ -1,16 +1,47 @@
 import { spawnSync } from 'node:child_process';
+/**
+ * Build spawn argv for launching a workspace-file opener.
+ *
+ * On Windows, Cursor/VS Code ship as `*.cmd` shims. Node's spawn with
+ * `shell: false` cannot execute those directly (ENOENT). Follow Node's
+ * recommended pattern: `cmd.exe /d /s /c` with a single quoted command line
+ * and `windowsVerbatimArguments`, without enabling shell interpolation.
+ */
+export function buildOpenerSpawn(opener, workspacePath, primaryPath, platform = process.platform, comSpec = process.env.ComSpec || 'cmd.exe') {
+    const baseOptions = {
+        cwd: primaryPath,
+        shell: false,
+        stdio: 'inherit',
+    };
+    if (platform !== 'win32') {
+        return {
+            command: opener.command,
+            args: [workspacePath],
+            options: baseOptions,
+        };
+    }
+    // Escape " for cmd.exe by doubling; wrap each token so spaces are preserved.
+    const quote = (value) => `"${value.replace(/"/g, '""')}"`;
+    return {
+        command: comSpec,
+        args: ['/d', '/s', '/c', `${quote(opener.command)} ${quote(workspacePath)}`],
+        options: {
+            ...baseOptions,
+            windowsVerbatimArguments: true,
+        },
+    };
+}
 export function isOpenerAvailable(opener) {
+    // `where.exe` resolves .cmd/.bat shims the same way cmd does.
     const result = spawnSync(process.platform === 'win32' ? 'where' : 'which', [opener.command], {
         stdio: 'ignore',
+        shell: false,
     });
     return result.status === 0;
 }
 export function launchOpener(opener, workspacePath, primaryPath) {
-    const child = spawnSync(opener.command, [workspacePath], {
-        cwd: primaryPath,
-        shell: false,
-        stdio: 'inherit',
-    });
+    const plan = buildOpenerSpawn(opener, workspacePath, primaryPath);
+    const child = spawnSync(plan.command, plan.args, plan.options);
     if (child.error) {
         throw child.error;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gordon.gan/specflow",
-  "version": "1.3.0-beta",
+  "version": "1.3.1-beta",
   "type": "module",
   "description": "SpecFlow — unified spec-driven development: OpenSpec planning + Superpowers execution in one CLI and cross-IDE workflow",
   "keywords": [