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

package/README.md

@@ -124,7 +124,7 @@ npm install -g @gordon.gan/specflow
 npm install -g github:Gordon-Gan-Jiang/specflow
 
 # 验证
-specflow --version   # 以 npm / package.json 为准（当前 1.3.1-beta）
+specflow --version   # 以 npm / package.json 为准（当前 1.3.3-beta）
 specflow --help
 ```
 

package/dist/core/artifact-language.js

@@ -21,7 +21,9 @@ export function renderArtifactLanguageGuidance(language) {
     return [
         '## Artifact language policy',
         '',
-        `Write human-readable artifact content in ${narrativeLanguage}.`,
+        `Write all non-protocol business content in ${narrativeLanguage}.`,
+        'This includes proposal narrative, requirement and scenario descriptions, text after WHEN/THEN, design rationale, and task descriptions.',
+        'Do not mix narrative languages in the same artifact.',
         '',
         'Keep SpecFlow protocol markers unchanged, including:',
         '- `ADDED Requirements`, `MODIFIED Requirements`, `REMOVED Requirements`, and `RENAMED Requirements`',

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

@@ -5,14 +5,15 @@ export interface OpenerSpawnPlan {
     readonly args: string[];
     readonly options: SpawnSyncOptions;
 }
+export declare function selectWindowsOpenerPath(output: string): string | null;
 /**
  * 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.
+ * On Windows, Cursor/VS Code normally ship as `*.cmd` shims. Resolve the shim
+ * to an absolute path first: invoking a bare command while cwd is a project
+ * can make the shim resolve its own relative Cursor.exe path from the project.
+ * Batch shims run through cmd.exe; native executables run directly.
  */
-export declare function buildOpenerSpawn(opener: OpenerDefinition, workspacePath: string, primaryPath: string, platform?: NodeJS.Platform, comSpec?: string): OpenerSpawnPlan;
+export declare function buildOpenerSpawn(opener: OpenerDefinition, workspacePath: string, primaryPath: string, platform?: NodeJS.Platform, comSpec?: string, resolvedPath?: 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,13 +1,36 @@
 import { spawnSync } from 'node:child_process';
+import path from 'node:path';
+export function selectWindowsOpenerPath(output) {
+    return (output
+        .split(/\r?\n/)
+        .map((candidate) => candidate.trim())
+        .find((candidate) => /\.(?:cmd|bat|exe)$/i.test(candidate)) ?? null);
+}
+function resolveWindowsOpenerPath(opener) {
+    for (const suffix of ['.cmd', '.bat', '.exe']) {
+        const result = spawnSync('where.exe', [`${opener.command}${suffix}`], {
+            encoding: 'utf8',
+            shell: false,
+            stdio: ['ignore', 'pipe', 'ignore'],
+        });
+        if (result.status === 0) {
+            const executablePath = selectWindowsOpenerPath(result.stdout ?? '');
+            if (executablePath) {
+                return executablePath;
+            }
+        }
+    }
+    return null;
+}
 /**
  * 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.
+ * On Windows, Cursor/VS Code normally ship as `*.cmd` shims. Resolve the shim
+ * to an absolute path first: invoking a bare command while cwd is a project
+ * can make the shim resolve its own relative Cursor.exe path from the project.
+ * Batch shims run through cmd.exe; native executables run directly.
  */
-export function buildOpenerSpawn(opener, workspacePath, primaryPath, platform = process.platform, comSpec = process.env.ComSpec || 'cmd.exe') {
+export function buildOpenerSpawn(opener, workspacePath, primaryPath, platform = process.platform, comSpec = process.env.ComSpec || 'cmd.exe', resolvedPath) {
     const baseOptions = {
         cwd: primaryPath,
         shell: false,
@@ -20,27 +43,48 @@ export function buildOpenerSpawn(opener, workspacePath, primaryPath, platform =
             options: baseOptions,
         };
     }
-    // Escape " for cmd.exe by doubling; wrap each token so spaces are preserved.
-    const quote = (value) => `"${value.replace(/"/g, '""')}"`;
+    if (!resolvedPath) {
+        throw new Error(`Could not resolve '${opener.command}.cmd' or '${opener.command}.exe' on PATH.`);
+    }
+    const executablePath = path.win32.normalize(resolvedPath);
+    const extension = path.win32.extname(executablePath).toLowerCase();
+    const shimOptions = {
+        ...baseOptions,
+        // Cursor's .cmd shim derives Cursor.exe from its own directory.
+        cwd: path.win32.dirname(executablePath),
+    };
+    if (extension === '.exe') {
+        return {
+            command: executablePath,
+            args: [workspacePath],
+            options: shimOptions,
+        };
+    }
+    // cmd.exe's /s removes the outer pair of quotes. Supply that pair explicitly
+    // so the batch-file path and workspace path retain their independent quotes.
+    const commandLine = `""${executablePath.replace(/"/g, '""')}" "${workspacePath.replace(/"/g, '""')}""`;
     return {
         command: comSpec,
-        args: ['/d', '/s', '/c', `${quote(opener.command)} ${quote(workspacePath)}`],
+        args: ['/d', '/s', '/c', commandLine],
         options: {
-            ...baseOptions,
+            ...shimOptions,
             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], {
+    if (process.platform === 'win32') {
+        return resolveWindowsOpenerPath(opener) !== null;
+    }
+    const result = spawnSync('which', [opener.command], {
         stdio: 'ignore',
         shell: false,
     });
     return result.status === 0;
 }
 export function launchOpener(opener, workspacePath, primaryPath) {
-    const plan = buildOpenerSpawn(opener, workspacePath, primaryPath);
+    const resolvedPath = process.platform === 'win32' ? resolveWindowsOpenerPath(opener) : undefined;
+    const plan = buildOpenerSpawn(opener, workspacePath, primaryPath, process.platform, process.env.ComSpec || 'cmd.exe', resolvedPath ?? undefined);
     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.1-beta",
+  "version": "1.3.3-beta",
   "type": "module",
   "description": "SpecFlow — unified spec-driven development: OpenSpec planning + Superpowers execution in one CLI and cross-IDE workflow",
   "keywords": [

package/prompts/apply/phase-a-plan.md

@@ -16,6 +16,10 @@
 **Plan location (input and output):** `specflow/changes/<change-name>/tasks.md`
 - (User preferences for propose location override this default)
 
+## Artifact Language
+
+Before rewriting, resolve `artifacts.language` from the active planning root's `specflow/config.yaml` (see shared `artifact-language.md`). Rewrite **group titles and task description prose** in that language (`zh-CN` → Simplified Chinese; `en` → English). Keep file paths, commands, code blocks, symbols, and Verify command text unchanged. Do not switch business narrative to English when `zh-CN` is configured.
+
 ## Input Order
 
 Phase A MUST read inputs in the following order before making any analysis decisions:

package/prompts/propose/design-draft.md

@@ -6,6 +6,8 @@
 
 Generate a substantive `design.md` representing your **first round of deep thinking** on this change. This is v1 of the design — refine will produce v2 by challenging assumptions, proposing alternative options, probing edge cases, and questioning scope. Your job here is to give refine something real to work with.
 
+**Narrative language:** Follow the resolved `artifacts.language` for Context, Goals / Non-Goals, Decisions, Risks, and Open Questions. Keep paths, commands, code, symbols, and technical identifiers unchanged.
+
 ## Inputs You Must Read
 
 - `specflow/changes/<change-name>/proposal.md` — the approved proposal

package/prompts/propose/proposal.md

@@ -4,6 +4,8 @@
 
 Generate a proposal document following the SpecFlow format. The proposal establishes WHY a change is needed and WHAT it affects.
 
+**Narrative language:** Follow the resolved `artifacts.language` for Why, What Changes, Impact, Capabilities prose, and success criteria. Keep change IDs, capability IDs, paths, commands, and code symbols unchanged.
+
 ## Process
 
 ### Step 1: Baseline Awareness

package/prompts/propose/specs.md

@@ -27,6 +27,8 @@ Create one spec file per capability at `specflow/changes/<change-name>/specs/<ca
 
 **CRITICAL FORMAT — the specflow CLI parses this exact structure. Deviations will cause validation and archive failures.**
 
+**Narrative language:** Follow the resolved `artifacts.language` for all business content — requirement descriptions, scenario titles, and the text after `WHEN` / `THEN`. Protocol markers below stay exactly English. Do not emit English narrative when `zh-CN` is configured.
+
 Use `##` headers for delta operation sections. Use `###` for requirements. Use `####` for scenarios. Use `- **WHEN**` and `- **THEN**` bullet format for scenario steps.
 
 ```markdown
@@ -66,9 +68,9 @@ TO: <new requirement name>
 
 **Format rules:**
 - Each requirement: `### Requirement: <name>` followed by description
-- Use SHALL/MUST for normative requirements (avoid should/may)
+- Use SHALL/MUST (or 必须/应当 under zh-CN) for normative requirements (avoid should/may)
 - Each scenario: `#### Scenario: <name>` — **MUST use exactly 4 hashtags (`####`)**. Using 3 hashtags will fail validation silently.
-- Scenario steps: `- **WHEN** <condition>` and `- **THEN** <outcome>` — **MUST use bullet dash + bold format**
+- Scenario steps: `- **WHEN** <condition>` and `- **THEN** <outcome>` — **MUST use bullet dash + bold format**; `<condition>` / `<outcome>` use the resolved artifact language
 - Every requirement MUST have at least one scenario
 - Only include the sections you need (e.g., only `## ADDED Requirements` for new capabilities)
 

package/prompts/propose/tasks-draft.md

@@ -30,15 +30,15 @@ This marker tells future readers (and the Apply Phase A prompt) that this docume
    - Group names are capability- or layer-oriented, not generic ("Core artifact management" — not "Phase 1")
 
 2. **Each group contains 2 to 6 concrete checkbox items**
-   - Format: `- [ ] N.M <动作短语>` where N is the group number and M is the item index within the group
-   - Mixed Chinese and English is acceptable (project convention); pick the language the action verb flows in
+   - Format: `- [ ] N.M <action phrase>` where N is the group number and M is the item index within the group
+   - Group titles and task descriptions MUST follow the resolved `artifacts.language` from Artifact Language Setup (zh-CN → Simplified Chinese; en → English). Keep paths, commands, code, and symbols unchanged. Do not default to English when `zh-CN` is configured, and do not mix narrative languages inside the same tasks.md.
 
 3. **Items are concrete actions, not topics**
-   - "实现 searchNotes 纯函数" (good — specific function)
-   - "添加 CLI --verbose 标志并接入 logger" (good — specific change)
-   - "处理搜索逻辑" (bad — vague topic, not an action)
-   - "handle searching" (bad — same problem in English)
-   - "完善测试" (bad — improvement verb without a subject)
+   - zh-CN good: "实现 searchNotes 纯函数"
+   - zh-CN good: "添加 CLI --verbose 标志并接入 logger"
+   - en good: "Implement searchNotes pure function"
+   - bad: "处理搜索逻辑" / "handle searching" (vague topic, not an action)
+   - bad: "完善测试" / "improve tests" (improvement verb without a subject)
 
 4. **Each item should be a coherent unit of work** — roughly the size that Apply Phase A will later expand into a handful of bite-sized TDD steps. If an item feels like it's really 5 unrelated actions, split it.
 
@@ -55,7 +55,7 @@ If the change has both parallel capabilities and deep layering, a two-level grou
 
 ## Example — Good Granularity
 
-Below is a short worked example for a hypothetical "add search to notes CLI" change. Study the **granularity and verb concreteness**, not the specific content.
+Below is a short worked example for a hypothetical "add search to notes CLI" change when `artifacts.language` is `zh-CN`. Study the **granularity and verb concreteness**, not the specific content. If the active language is `en`, write the same structure entirely in English.
 
 ```markdown
 <!-- Plan-phase first-iteration tasks. Will be rewritten to writing-plans precision in /specflow:apply Phase A. -->
@@ -119,5 +119,6 @@ specflow/changes/<change-name>/tasks.md
 - Substantive, not placeholder
 - 3 to 8 groups, 2 to 6 items each
 - Concrete verbs on concrete subjects
+- Business narrative language follows `artifacts.language`; protocol/tech tokens stay unchanged
 - Top-of-file marker comment is mandatory
 - Writing-plans precision comes in Apply Phase A — do not pre-write it here

package/prompts/shared/artifact-language.md

@@ -8,7 +8,13 @@ Before creating or rewriting any SpecFlow artifact:
    - `zh-CN` → write human-readable artifact content in Simplified Chinese.
    - Missing → default to `en`.
    - Invalid → report the invalid value and use `en`; do not invent another language.
-3. Apply the selected language consistently to narrative prose, requirement and scenario descriptions, design rationale, and task descriptions.
+3. Apply the selected language to **all non-protocol business content**, including:
+   - proposal Why / What / Impact / success criteria
+   - requirement descriptions and scenario titles
+   - text after protected `WHEN` / `THEN` markers
+   - design Context, Goals, Decisions, Risks, Open Questions
+   - task group titles and task descriptions (including Apply Phase A rewrites)
+4. Do **not** mix languages for that business content. Protocol markers and technical identifiers stay as written below; everything else follows the resolved language.
 
 ## Protected Protocol