@peterxiaoyang/superspec 0.1.1 → 0.1.2

package/dist/src/init_cli.js

@@ -1,5 +1,5 @@
-import { block, commandExists, GuardError, printDecision, reason, runCommand } from "./core.js";
-import { project_init, recommended_openspec_install_plan } from "./project_init.js";
+import { block, commandExists, GuardError, printDecision, reason, runCommand, openspec_cli_probe, REQUIRED_OPENSPEC_MIN_VERSION, } from "./core.js";
+import { forced_openspec_install_plan, project_init, recommended_openspec_install_plan } from "./project_init.js";
 import { install_workflow, uninstall_workflow, update_workflow } from "./install_engine.js";
 import { homedir } from "node:os";
 import { resolve } from "node:path";
@@ -9,7 +9,7 @@ function usage() {
     return "usage: superspec init [-h] [--scope {project,user}] [--path PATH] [--codex-home PATH] [--create] [--update] [--uninstall] [--dry-run] [--force]\n";
 }
 function help() {
-    return `${usage()}\n可选参数：\n  -h, --help             显示帮助并退出\n  --scope {project,user} 安装到当前项目的 .codex 目录，或安装到用户级 Codex 目录（默认：project）\n  --project              等价于 --scope project\n  --user                 等价于 --scope user\n  --global               兼容别名，等价于 --user\n  --path PATH            --scope project 时使用的项目根目录（默认：当前目录）\n  --codex-home PATH      --scope user 时使用的 Codex 用户目录（默认：$CODEX_HOME 或 ~/.codex）\n  --create               兼容参数；init 默认就会创建缺失内容\n  --update               按 manifest 更新受管 SuperSpec 内容；用户改动文件保留，新的版本写入 *.new\n  --uninstall            按 manifest 卸载受管 SuperSpec 内容；.superspec 数据与既有/用户改动文件会保留\n  --dry-run              配合 --uninstall 时只预览将删除的文件，不实际修改\n  --force                安装时覆盖已有且内容不同的文件，并保留 *.bak 备份\n`;
+    return `${usage()}\n可选参数：\n  -h, --help             显示帮助并退出\n  --scope {project,user} 安装到当前项目的 .codex 目录，或安装到用户级 Codex 目录（默认：project）\n  --project              等价于 --scope project\n  --user                 等价于 --scope user\n  --global               兼容别名，等价于 --user\n  --path PATH            --scope project 时使用的项目根目录（默认：当前目录）\n  --codex-home PATH      --scope user 时使用的 Codex 用户目录（默认：$CODEX_HOME 或 ~/.codex）\n  --create               兼容参数；init 默认就会创建缺失内容\n  --update               按 manifest 更新 SuperSpec 管理的文件；用户改动文件保留，新的版本写入 *.new\n  --uninstall            按 manifest 卸载 SuperSpec 管理的文件；.superspec 数据与既有/用户改动文件会保留\n  --dry-run              配合 --uninstall 时只预览将删除的文件，不实际修改\n  --force                安装时覆盖已有且内容不同的文件，并保留 *.bak 备份\n`;
 }
 function parse_init_argv(argv) {
     const getValue = (flag) => {
@@ -56,6 +56,12 @@ function commandFailure(proc) {
         return `安装命令执行失败（退出状态码 ${proc.status}）。`;
     return "安装命令执行失败，请查看终端日志后重试。";
 }
+function shouldRetryOpenSpecInstallWithForce(proc) {
+    const output = `${proc.error?.message ?? ""}\n${proc.stderr}\n${proc.stdout}`;
+    const binConflict = /\bEEXIST\b|already exists|file exists|Refusing to delete|will not overwrite|would overwrite/iu.test(output);
+    const openspecBin = /\bopenspec(?:\.(?:cmd|ps1))?\b/iu.test(output);
+    return binConflict && openspecBin;
+}
 function engineDecision(gate, projectRoot, result, nextActions) {
     if (result.problems.length > 0) {
         const decision = block("project", gate, result.problems.map((item) => reason(`${gate}_failed`, item)));
@@ -92,56 +98,60 @@ async function promptInstallScope() {
 function canPrompt() {
     return Boolean(process.stdin.isTTY && process.stderr.isTTY);
 }
-async function promptYesNo(question, defaultYes = true) {
-    const rl = createInterface({ input: process.stdin, output: process.stderr });
-    const suffix = defaultYes ? "[Y/n]" : "[y/N]";
-    try {
-        for (;;) {
-            const answer = (await rl.question(`${question} ${suffix} `)).trim().toLowerCase();
-            if (answer === "")
-                return defaultYes;
-            if (["y", "yes", "是", "好", "确认"].includes(answer))
-                return true;
-            if (["n", "no", "否", "不", "取消"].includes(answer))
-                return false;
-            process.stderr.write("请输入 y / n，或输入 是 / 否。\n");
-        }
-    }
-    finally {
-        rl.close();
-    }
-}
-export async function maybe_install_missing_openspec(opts) {
+export function maybe_install_missing_openspec(opts) {
     const commandExistsFn = opts.commandExistsFn ?? ((cmd, meta) => commandExists(cmd, { cwd: meta?.cwd }));
-    if (opts.scope !== "project" || opts.mode !== "install")
+    if (opts.mode !== "install")
         return "not-needed";
-    if (commandExistsFn("openspec", { cwd: opts.cwd }))
+    const run = opts.run ?? runCommand;
+    const probeOpenspecFn = opts.probeOpenspecFn ?? ((meta) => openspec_cli_probe({ cwd: meta?.cwd, commandExistsFn, run }));
+    const before = probeOpenspecFn({ cwd: opts.cwd });
+    if (before.ok)
         return "not-needed";
-    if (!(opts.interactive ?? canPrompt()))
-        return "skipped";
-    const plan = recommended_openspec_install_plan({ cwd: opts.cwd, commandExistsFn });
-    if (plan === null)
-        return "skipped";
-    const confirm = opts.confirm ?? ((question) => promptYesNo(question));
-    const accepted = await confirm(`未检测到 openspec CLI。是否现在尝试自动安装？\n将执行：${plan.rendered}`);
-    if (!accepted)
-        return "skipped";
     const writeStderr = opts.writeStderr ?? ((text) => {
         process.stderr.write(text);
     });
+    const plan = recommended_openspec_install_plan({ cwd: opts.cwd, commandExistsFn });
+    if (plan === null) {
+        writeStderr(`${before.message}。SuperSpec 需要 @fission-ai/openspec >= ${REQUIRED_OPENSPEC_MIN_VERSION}，但未找到 npm、pnpm、yarn 或 bun，无法自动安装。\n`);
+        return "skipped";
+    }
+    writeStderr(`${before.message}。SuperSpec 需要 @fission-ai/openspec >= ${REQUIRED_OPENSPEC_MIN_VERSION}，将自动安装或升级。\n`);
     writeStderr(`正在安装 OpenSpec CLI：${plan.rendered}\n`);
-    const proc = (opts.run ?? runCommand)(plan.cmd, plan.args, { cwd: opts.cwd, timeout: 300_000 });
+    let proc = run(plan.cmd, plan.args, { cwd: opts.cwd, timeout: 300_000 });
+    if ((proc.error || proc.status !== 0) && shouldRetryOpenSpecInstallWithForce(proc)) {
+        const forcedPlan = forced_openspec_install_plan(plan);
+        writeStderr(`OpenSpec CLI 安装遇到全局 bin 冲突，正在覆盖重试：${forcedPlan.rendered}\n`);
+        proc = run(forcedPlan.cmd, forcedPlan.args, { cwd: opts.cwd, timeout: 300_000 });
+    }
     if (proc.error || proc.status !== 0) {
         writeStderr(`自动安装 OpenSpec CLI 失败：${commandFailure(proc)}\n`);
         return "failed";
     }
-    if (!commandExistsFn("openspec", { cwd: opts.cwd })) {
-        writeStderr("安装命令已完成，但当前 PATH 里仍未检测到 `openspec`。请重新打开终端或确认全局 bin 已在 PATH 中，然后重新运行 superspec init。\n");
+    const after = probeOpenspecFn({ cwd: opts.cwd });
+    if (!after.ok) {
+        writeStderr(`安装命令已完成，但当前 PATH 里的 openspec 仍不可用：${after.message}。请重新打开终端或确认全局 bin 已在 PATH 中，然后重新运行 superspec init；Windows PowerShell 请运行 superspec.cmd init。\n`);
         return "failed";
     }
-    writeStderr("OpenSpec CLI 安装完成，继续执行 superspec init。\n");
+    writeStderr("OpenSpec CLI 安装或升级完成，继续执行 superspec init。\n");
     return "installed";
 }
+function openspecPreflightBlocked(args, scope, installResult) {
+    const targetRoot = scope === "user" ? args.codexHome : args.path;
+    const code = installResult === "skipped" ? "openspec_auto_install_unavailable" : "openspec_auto_install_failed";
+    const message = installResult === "skipped"
+        ? `OpenSpec CLI 不满足 SuperSpec 要求，且未找到可用包管理器自动安装 @fission-ai/openspec >= ${REQUIRED_OPENSPEC_MIN_VERSION}。`
+        : `OpenSpec CLI 自动安装或升级 @fission-ai/openspec >= ${REQUIRED_OPENSPEC_MIN_VERSION} 未完成。`;
+    const decision = block("project", "openspec_preflight", [reason(code, message)], {
+        next_actions: [`install or upgrade @fission-ai/openspec >= ${REQUIRED_OPENSPEC_MIN_VERSION}, then rerun \`superspec init --scope ${scope}\``],
+    });
+    printDecision({
+        ...decision,
+        project_root: args.path,
+        install_scope: scope,
+        install_root: targetRoot,
+    }, { command: "init" });
+    return 1;
+}
 function run_init(args, scope) {
     const targetRoot = scope === "user" ? args.codexHome : args.path;
     const gatePrefix = scope === "user" ? "user" : "project";
@@ -176,7 +186,11 @@ export function main_init(argv = process.argv.slice(2)) {
             return 0;
         }
         const args = parse_init_argv(argv);
-        return run_init(args, args.scope ?? "project");
+        const scope = args.scope ?? "project";
+        const openspecInstall = maybe_install_missing_openspec({ cwd: args.path, scope, mode: args.mode });
+        if (openspecInstall === "failed" || openspecInstall === "skipped")
+            return openspecPreflightBlocked(args, scope, openspecInstall);
+        return run_init(args, scope);
     }
     catch (err) {
         const change = "project";
@@ -193,7 +207,9 @@ export async function main_init_async(argv = process.argv.slice(2)) {
         }
         const args = parse_init_argv(argv);
         const scope = args.scope ?? (canPrompt() ? await promptInstallScope() : "project");
-        await maybe_install_missing_openspec({ cwd: args.path, scope, mode: args.mode });
+        const openspecInstall = maybe_install_missing_openspec({ cwd: args.path, scope, mode: args.mode });
+        if (openspecInstall === "failed" || openspecInstall === "skipped")
+            return openspecPreflightBlocked(args, scope, openspecInstall);
         return run_init(args, scope);
     }
     catch (err) {

package/dist/src/openspec.d.ts

@@ -1,4 +1,21 @@
 import type { JsonMap, Reason } from "./util.ts";
+import { runCommand } from "./util.ts";
+export declare const REQUIRED_OPENSPEC_MIN_VERSION = "1.4.1";
+export type OpenspecCliProbe = {
+    ok: boolean;
+    state: "ok" | "missing" | "invalid" | "too_old";
+    version: string | null;
+    message: string;
+};
+export declare function parse_openspec_version(raw: string): string | null;
+export declare function compare_versions(actual: string, required: string): number;
+export declare function openspec_cli_probe(opts?: {
+    cwd?: string;
+    commandExistsFn?: (cmd: string, meta?: {
+        cwd?: string;
+    }) => boolean;
+    run?: typeof runCommand;
+}): OpenspecCliProbe;
 export declare function openspec_status(change: string): JsonMap;
 export declare function openspec_validate(change: string): [boolean, string];
 export declare function openspec_version(): string;

package/dist/src/openspec.js

@@ -1,6 +1,93 @@
 import { dirname, join, resolve, sep } from "node:path";
 import { existsSync } from "node:fs";
-import { GATE_ALIASES, GATE_ROUTE, GuardError, ROUTE_ALIASES, ROUTE_ORDER, fingerprint_obj, isObject, reason, repr, runCommand, } from "./util.js";
+import { REQUIRED_OPENSPEC_CLI_SURFACES, GATE_ALIASES, GATE_ROUTE, GuardError, ROUTE_ALIASES, ROUTE_ORDER, commandExists, fingerprint_obj, isObject, reason, repr, runCommand, } from "./util.js";
+export const REQUIRED_OPENSPEC_MIN_VERSION = "1.4.1";
+export function parse_openspec_version(raw) {
+    const match = raw.match(/\b(\d+)\.(\d+)\.(\d+)(?:[-+][0-9A-Za-z.-]+)?\b/);
+    return match ? `${match[1]}.${match[2]}.${match[3]}` : null;
+}
+export function compare_versions(actual, required) {
+    const actualParts = actual.split(".").map((part) => Number.parseInt(part, 10));
+    const requiredParts = required.split(".").map((part) => Number.parseInt(part, 10));
+    for (let index = 0; index < Math.max(actualParts.length, requiredParts.length); index += 1) {
+        const actualPart = actualParts[index] ?? 0;
+        const requiredPart = requiredParts[index] ?? 0;
+        if (!Number.isFinite(actualPart))
+            return -1;
+        if (!Number.isFinite(requiredPart))
+            return 1;
+        if (actualPart > requiredPart)
+            return 1;
+        if (actualPart < requiredPart)
+            return -1;
+    }
+    return 0;
+}
+export function openspec_cli_probe(opts = {}) {
+    const commandExistsFn = opts.commandExistsFn ?? ((cmd, meta) => commandExists(cmd, { cwd: meta?.cwd }));
+    const run = opts.run ?? runCommand;
+    if (!commandExistsFn("openspec", { cwd: opts.cwd })) {
+        return {
+            ok: false,
+            state: "missing",
+            version: null,
+            message: "PATH 中缺少 OpenSpec CLI（openspec）",
+        };
+    }
+    const versionProc = run("openspec", ["--version"], { cwd: opts.cwd, timeout: 15_000 });
+    if (versionProc.error || versionProc.status !== 0) {
+        const output = (versionProc.error?.message ?? (versionProc.stderr || versionProc.stdout)).trim();
+        return {
+            ok: false,
+            state: "invalid",
+            version: null,
+            message: `\`openspec --version\` 执行失败：${output}`,
+        };
+    }
+    const rawVersion = `${versionProc.stdout}${versionProc.stderr}`.trim();
+    if (/openspec[-_\s]*chinese/iu.test(rawVersion)) {
+        return {
+            ok: false,
+            state: "invalid",
+            version: null,
+            message: "PATH 上的 openspec 来自 openspec-chinese，不是受支持的 @fission-ai/openspec CLI",
+        };
+    }
+    const version = parse_openspec_version(rawVersion);
+    if (version === null) {
+        return {
+            ok: false,
+            state: "invalid",
+            version: null,
+            message: "PATH 上的 OpenSpec CLI（openspec）无法报告语义版本，可能不是受支持的 @fission-ai/openspec",
+        };
+    }
+    if (compare_versions(version, REQUIRED_OPENSPEC_MIN_VERSION) < 0) {
+        return {
+            ok: false,
+            state: "too_old",
+            version,
+            message: `openspec ${version} 低于 SuperSpec 要求的最低版本 ${REQUIRED_OPENSPEC_MIN_VERSION}`,
+        };
+    }
+    for (const args of REQUIRED_OPENSPEC_CLI_SURFACES) {
+        const proc = run("openspec", [...args], { cwd: opts.cwd, timeout: 15_000 });
+        if (proc.error || proc.status !== 0) {
+            return {
+                ok: false,
+                state: "invalid",
+                version,
+                message: `openspec ${version} 缺少必需的原生能力：\`openspec ${args.join(" ")}\` 执行失败`,
+            };
+        }
+    }
+    return {
+        ok: true,
+        state: "ok",
+        version,
+        message: `openspec ${version} satisfies SuperSpec requirements`,
+    };
+}
 export function openspec_status(change) {
     const proc = runCommand("openspec", ["status", "--change", change, "--json"], { timeout: 30_000 });
     if (proc.error) {
@@ -28,8 +115,7 @@ export function openspec_version() {
     if (proc.error || proc.status !== 0)
         return "unknown";
     const raw = (proc.stdout || proc.stderr).trim();
-    const match = raw.match(/\d+\.\d+\.\d+/);
-    return match ? match[0] : raw || "unknown";
+    return (parse_openspec_version(raw) ?? raw) || "unknown";
 }
 export function openspec_status_shape_reasons(status) {
     const problems = [];

package/dist/src/project_init.d.ts

@@ -1,4 +1,4 @@
-import { type JsonMap } from "./core.ts";
+import { type JsonMap, type OpenspecCliProbe } from "./core.ts";
 export declare const OPENSPEC_NPM_PACKAGE = "@fission-ai/openspec";
 export declare const OPENSPEC_INSTALL_DOC_URL = "https://github.com/Fission-AI/OpenSpec#readme";
 export type OpenspecInstallPlan = {
@@ -13,12 +13,19 @@ export declare function recommended_openspec_install_plan(opts?: {
         cwd?: string;
     }) => boolean;
 }): OpenspecInstallPlan | null;
+export declare function forced_openspec_install_plan(plan: OpenspecInstallPlan): OpenspecInstallPlan;
 export declare function missing_openspec_cli_message(opts?: {
     cwd?: string;
     commandExistsFn?: (cmd: string, meta?: {
         cwd?: string;
     }) => boolean;
 }): string;
+export declare function openspec_cli_requirement_message(probe: OpenspecCliProbe, opts?: {
+    cwd?: string;
+    commandExistsFn?: (cmd: string, meta?: {
+        cwd?: string;
+    }) => boolean;
+}): string;
 export declare function project_init(repoRootRaw?: string, opts?: {
     force?: boolean;
 }): JsonMap;

package/dist/src/project_init.js

@@ -1,13 +1,13 @@
 import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import { join, resolve } from "node:path";
-import { REQUIRED_SUPERSPEC_AGENT_ROLES, REQUIRED_OPENSPEC_CODEX_SKILLS, block, reason, read_agent_toml_name, read_skill_frontmatter_name, commandExists, runCommand, } from "./core.js";
+import { REQUIRED_SUPERSPEC_AGENT_ROLES, REQUIRED_OPENSPEC_CODEX_SKILLS, REQUIRED_OPENSPEC_MIN_VERSION, block, commandExists, openspec_cli_probe, reason, read_agent_toml_name, read_skill_frontmatter_name, runCommand, } from "./core.js";
 import { install_workflow } from "./install_engine.js";
 import { system_failure_zh } from "./i18n.js";
 export const OPENSPEC_NPM_PACKAGE = "@fission-ai/openspec";
 export const OPENSPEC_INSTALL_DOC_URL = "https://github.com/Fission-AI/OpenSpec#readme";
 const ROLE_DESCRIPTIONS = {
     architect: "系统设计、边界、接口与长期取舍",
-    critic: "对计划、证据、假设与范围漂移做对抗审查",
+    critic: "严格审查计划、证据、假设与范围漂移",
     "test-engineer": "测试策略、覆盖率与 RED/GREEN 证据审查",
     "code-reviewer": "代码 / 规格 / 安全审查",
     verifier: "最终完成证据与验证审查",
@@ -34,12 +34,30 @@ export function recommended_openspec_install_plan(opts = {}) {
     }
     return null;
 }
+export function forced_openspec_install_plan(plan) {
+    const versionedPackage = `${OPENSPEC_NPM_PACKAGE}@latest`;
+    const forced = {
+        npm: ["install", "-g", "--force", versionedPackage],
+        pnpm: ["add", "-g", "--force", versionedPackage],
+        yarn: ["global", "add", versionedPackage, "--force"],
+        bun: ["add", "-g", "--force", versionedPackage],
+    };
+    return { ...plan, args: forced[plan.manager], rendered: renderCommand(plan.cmd, forced[plan.manager]) };
+}
 export function missing_openspec_cli_message(opts = {}) {
+    return openspec_cli_requirement_message({
+        ok: false,
+        state: "missing",
+        version: null,
+        message: "PATH 中缺少 OpenSpec CLI（openspec）",
+    }, opts);
+}
+export function openspec_cli_requirement_message(probe, opts = {}) {
     const plan = recommended_openspec_install_plan(opts);
     if (plan) {
-        return `PATH 中缺少 openspec CLI。可先运行 \`${plan.rendered}\` 安装，然后重新运行 superspec init --scope project。`;
+        return `${probe.message}。需要 @fission-ai/openspec >= ${REQUIRED_OPENSPEC_MIN_VERSION}。可先运行 \`${plan.rendered}\` 安装或升级，然后重新运行 \`superspec init --scope project\`。`;
     }
-    return `PATH 中缺少 openspec CLI。请先安装 OpenSpec CLI（${OPENSPEC_INSTALL_DOC_URL}），然后重新运行 superspec init --scope project。`;
+    return `${probe.message}。请先安装或升级 @fission-ai/openspec >= ${REQUIRED_OPENSPEC_MIN_VERSION}（${OPENSPEC_INSTALL_DOC_URL}），然后重新运行 \`superspec init --scope project\`。`;
 }
 function openspecSkillProblems(repoRoot) {
     const skillsRoot = join(repoRoot, ".codex", "skills");
@@ -64,8 +82,8 @@ function writeSuperSpecAgent(repoRoot, name) {
         'model_reasoning_effort = "high"',
         'developer_instructions = """',
         `你是仓库本地的 superspec ${name} native subagent。`,
-        "遵循分配给你的 superspec gate 证据任务，引用具体文件，并把阻塞点上报主线程。",
-        "不要用主线程自审替代必须的角色证据。",
+        "遵循分配给你的 superspec gate 证据任务，引用具体文件，并把未通过的问题上报主流程。",
+        "不要用主流程自审替代必须的角色证据。",
         '"""',
         "",
     ].join("\n"), "utf8");
@@ -82,14 +100,15 @@ function writeSuperSpecPrompt(repoRoot, name) {
         "",
         `你是仓库本地的 superspec ${name} 角色。`,
         "",
-        "请基于具体文件证据审查提供的 superspec gate 上下文，输出简洁的通过 / 阻塞报告，引用 source anchors 与 target refs，并且不要用主线程自审替代必须的 native-subagent 证据。",
+        "请基于具体文件证据审查提供的 superspec gate 上下文，输出简洁的通过 / 未通过报告，引用 source anchors 与 target refs，并且不要用主流程自审替代必须的 native-subagent 证据。",
         "",
     ].join("\n"), "utf8");
     return filePath;
 }
 function ensureOpenSpecCodex(repoRoot, actions) {
-    if (!commandExists("openspec", { cwd: repoRoot }))
-        return [missing_openspec_cli_message({ cwd: repoRoot })];
+    const probe = openspec_cli_probe({ cwd: repoRoot });
+    if (!probe.ok)
+        return [openspec_cli_requirement_message(probe, { cwd: repoRoot })];
     let problems = openspecSkillProblems(repoRoot);
     if (problems.length === 0) {
         actions.push({ action: "openspec_codex_skills", status: "ok" });

package/dist/src/util.d.ts

@@ -127,6 +127,7 @@ export declare function commandLookupInvocation(cmd: string, platform?: NodeJS.P
     args: string[];
     shell: boolean;
 };
+export declare function selectWindowsCommandCandidate(cmd: string, whereStdout: string): string;
 export declare function windowsShellEscapeArg(arg: string): string;
 export declare function windowsCmdShimInvocation(cmdPath: string, args: string[], comspec?: string): {
     cmd: string;

package/dist/src/util.js

@@ -287,6 +287,10 @@ export function decorateDecision(decision, opts = {}) {
         })
         : [];
     const nextActions = Array.isArray(decision.next_allowed_actions) ? decision.next_allowed_actions.map((item) => String(item)) : [];
+    const windowsPowerShellHints = windowsPowerShellCommandHints([
+        ...nextActions,
+        ...reasons.map((item) => String(item.message ?? "")),
+    ]);
     return {
         ...decision,
         command: command || decision.command,
@@ -297,10 +301,23 @@ export function decorateDecision(decision, opts = {}) {
         command_hint_zh: commandInfo?.hint_zh,
         block_reasons: reasons,
         next_allowed_actions_zh: nextActions.map((item) => translate_action_zh(item)),
+        windows_powershell_command_hints: windowsPowerShellHints.length > 0 ? windowsPowerShellHints : undefined,
         trust_warnings_zh: Array.isArray(decision.trust_warnings) ? decision.trust_warnings.map((item) => trust_warning_zh(String(item))) : [],
         workflow_terms_zh: workflow_terms_zh_for(command || undefined, String(decision.gate ?? ""), reasons.map((item) => String(item.code ?? ""))),
     };
 }
+function windowsPowerShellCommandHints(texts) {
+    const hints = new Set();
+    for (const text of texts) {
+        for (const match of text.matchAll(/`((?:superspec|openspec)\s+[^`]+)`/giu)) {
+            const command = match[1]?.trim();
+            if (!command)
+                continue;
+            hints.add(`Windows PowerShell: use \`${command.replace(/^(superspec|openspec)\b/iu, "$1.cmd")}\``);
+        }
+    }
+    return [...hints];
+}
 function sanitizeReasonForOutput(item) {
     const refs = Array.isArray(item.refs) ? item.refs.map((ref) => String(ref)) : [];
     return {
@@ -475,6 +492,10 @@ export function commandLookupInvocation(cmd, platform = process.platform) {
         return { cmd: "where.exe", args: [cmd], shell: false };
     return { cmd: "sh", args: ["-c", `command -v ${cmd}`], shell: false };
 }
+export function selectWindowsCommandCandidate(cmd, whereStdout) {
+    const candidates = whereStdout.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+    return candidates.find((candidate) => /\.(?:cmd|bat)$/i.test(candidate)) ?? candidates[0] ?? cmd;
+}
 function resolveWindowsCommand(cmd, cwd) {
     if (cmd.includes("\\") || cmd.includes("/") || extname(cmd))
         return cmd;
@@ -485,7 +506,7 @@ function resolveWindowsCommand(cmd, cwd) {
     });
     if (lookup.status !== 0 || typeof lookup.stdout !== "string")
         return cmd;
-    return lookup.stdout.split(/\r?\n/).map((line) => line.trim()).find(Boolean) ?? cmd;
+    return selectWindowsCommandCandidate(cmd, lookup.stdout);
 }
 export function windowsShellEscapeArg(arg) {
     let escaped = String(arg);
@@ -497,7 +518,7 @@ export function windowsShellEscapeArg(arg) {
 export function windowsCmdShimInvocation(cmdPath, args, comspec = "cmd.exe") {
     return {
         cmd: comspec,
-        args: ["/d", "/s", "/c", [windowsShellEscapeArg(cmdPath), ...args.map(windowsShellEscapeArg)].join(" ")],
+        args: ["/d", "/c", cmdPath, ...args],
     };
 }
 function windowsCommandInvocation(cmd, args, cwd) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peterxiaoyang/superspec",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "SuperSpec workflow package: guard runtime, generic workflow templates, and Codex adapter payload.",
   "repository": {
     "type": "git",

package/templates/workflow/prompts/architect.md

@@ -40,7 +40,7 @@ argument-hint: "任务说明"
 - 建议必须具体且可执行。
 - 必须说明取舍。
 - 在 ralplan 共识审查中，要包含反论、张力和综合方案。
-- 在 `superspec-review` 中，要输出基于来源证据的架构 guidance 和升级点；最终裁决由主线程完成，不由本角色直接下判。
+- 在 `superspec-review` 中，要输出基于来源证据的架构 guidance 和升级点；最终判断由主流程完成，不由本角色直接下判。
 </success_criteria>
 
 <verification_loop>
@@ -78,7 +78,7 @@ argument-hint: "任务说明"
 1. [最高优先级] - [工作量] - [影响]
 2. [下一优先级] - [工作量] - [影响]
 
-## 主线程裁决建议
+## 主流程判断建议
 - 关键架构判断
 - 建议直接加载的 source refs
 - 建议升级或后续动作

package/templates/workflow/prompts/code-reviewer.md

@@ -6,7 +6,7 @@ argument-hint: "任务说明"
 你是 Code Reviewer。你的任务是通过系统化、带严重级别的审查来保障代码质量与安全性。
 你负责规格符合性验证、安全检查、代码质量评估、性能审视和最佳实践约束。
 你不负责直接实现修复（executor）、架构设计（architect）或编写测试（test-engineer）。
-当你在 `superspec-review` 中与 `architect` / `critic` 配合时，你负责代码 / 规格 / 安全这一条审查线，需要产出带证据的 guidance 供主线程裁决，而不是自己充当最终判官。
+当你在 `superspec-review` 中与 `architect` / `critic` 配合时，你负责代码 / 规格 / 安全这一条审查线，需要产出带证据的 guidance，供主流程做最终判断，而不是自己充当最终判官。
 
 代码审查是缺陷和漏洞进入生产前的最后一道防线。之所以强调这些规则，是因为漏掉安全问题会造成真实损害，而只盯格式细枝末节会浪费所有人的时间。
 </identity>
@@ -39,8 +39,8 @@ argument-hint: "任务说明"
 <explore>
 1) 先跑 `git diff` 看最近改动，重点关注被修改的文件。
 2) 阶段 1：规格符合性（必须先通过）。检查实现是否覆盖全部要求，是否解决了正确的问题，是否有缺漏或多做，需求提出者会不会认得这是他要的东西。
-3) 根因守卫（在正常质量放行前必须通过）：如果新引入的 fallback / workaround 会掩盖故障、压掉证据、增加宽泛绕路，或回避修主合同，就直接驳回。要求作者回到根因修复：保留失败证据、收紧主合同、删除掩盖分支，并补上真正故障的回归覆盖。
-4) 阶段 2：代码质量（只有阶段 1 和根因守卫都通过后才做）。对每个修改文件运行 `lsp_diagnostics`。使用 `ast_grep_search` 检查高风险模式，例如 `console.log`、空 `catch`、硬编码密钥、宽泛 `try/catch` fallback、静默默认值、尽力而为式绕路。然后按安全、质量、性能、最佳实践清单审查。
+3) 根因检查（在正常质量放行前必须通过）：如果新引入的 fallback / workaround 会掩盖故障、压掉证据、增加宽泛绕路，或回避修主合同，就直接驳回。要求作者回到根因修复：保留失败证据、收紧主合同、删除掩盖分支，并补上真正故障的回归覆盖。
+4) 阶段 2：代码质量（只有阶段 1 和根因检查都通过后才做）。对每个修改文件运行 `lsp_diagnostics`。使用 `ast_grep_search` 检查高风险模式，例如 `console.log`、空 `catch`、硬编码密钥、宽泛 `try/catch` fallback、静默默认值、尽力而为式绕路。然后按安全、质量、性能、最佳实践清单审查。
 5) 给每个问题评严重级别，并给出修复建议。
 6) 根据最高严重级别得出总体结论。
 </explore>
@@ -53,7 +53,7 @@ argument-hint: "任务说明"
 - 每个问题都包含明确修复建议。
 - 所有修改文件都已运行 `lsp_diagnostics`，不能在有类型错误时放行。
 - guidance 包必须清晰：包括 findings、source refs、required claim ids 和建议的下一步。
-- 在 superspec review 中，架构问题要向 `architect` 上抛，最终裁决留给主线程。
+- 在 superspec review 中，架构问题要向 `architect` 上抛，最终判断留给主流程。
 </success_criteria>
 
 <verification_loop>
@@ -71,7 +71,7 @@ argument-hint: "任务说明"
 
 <root_cause_fallback_policy>
 - 当 fallback / workaround 会掩盖真实缺陷时，要把它当成审查阻塞项：比如吞错、降级诊断、静默默认值、宽泛兼容垫片、重复的备用执行路径、绕开损坏主路径的功能开关，或没有证明主合同被修好却让故障“消失”的尽力分支。
-- 对这类掩盖式补丁，即使测试通过也要给出 REQUEST CHANGES。要明确说明：只要补丁压掉证据或绕开失败合同，单纯“能跑通”就不够；要求最小化的根因修复、明确的失败行为，以及没有真实修复就会失败的回归测试。
+- 对这类掩盖式问题，即使测试通过也要给出 REQUEST CHANGES。要明确说明：只要问题压掉证据或绕开失败合同，单纯“能跑通”就不够；要求最小化的根因修复、明确的失败行为，以及没有真实修复就会失败的回归测试。
 - 不要无差别否定所有 fallback。若 fallback 明确说明为不可避免、被限制在已知外部/版本边界内、主路径与 fallback 路径都经过测试、失败证据仍然可见，并且没有替代可控主合同的修复，那么窄范围兼容 fallback 可以接受。
 - 需要细腻判断时，要把条件写清楚：例如“只有当这个 fallback 始终限制在 [boundary]、保持 [evidence/error] 可见，并且同时覆盖 [primary] 与 [compatibility] 行为测试时，才可以接受。”否则就建议删除 fallback / workaround，回到根因修复。
 </root_cause_fallback_policy>
@@ -114,7 +114,7 @@ argument-hint: "任务说明"
 
 ### 主线程建议
 - 推荐下一步
-- 需要主线程裁决的 claims
+- 需要主流程判断的 claims
 - 建议主线程直接加载的 source refs
 </output_contract>
 
@@ -124,7 +124,7 @@ argument-hint: "任务说明"
 - 没有证据：没跑 `lsp_diagnostics` 就说 “looks good”。必须对修改文件跑诊断。
 - 问题描述含糊：比如只说“这里可以更好”。应改成类似：`[MEDIUM] utils.ts:42 - 函数超过 50 行，建议把 42-65 行的校验逻辑提取到 validateInput()。`
 - 严重级别膨胀：把缺失 JSDoc 评成 CRITICAL。CRITICAL 只留给安全漏洞和数据损坏风险。
-- 纵容掩盖式补丁：看到用 fallback、静默默认值、宽泛绕路去掩盖主路径故障却仍然放行。应要求回到根因修复，并补回归证据。
+- 纵容掩盖式问题：看到用 fallback、静默默认值、宽泛绕路去掩盖主路径故障却仍然放行。应要求回到根因修复，并补回归证据。
 </anti_patterns>
 
 <scenario_handling>
@@ -142,7 +142,7 @@ argument-hint: "任务说明"
 - 我是否拦下了会掩盖故障或绕开根因修复的 fallback / workaround？
 - 我是否对所有修改文件都运行了 lsp_diagnostics？
 - 每个问题是否都有 file:line、严重级别和修复建议？
-- 我是否给主线程留下了足够证据，使其无需盲信我也能裁决？
+- 我是否给主流程留下了足够证据，使其无需盲信我也能判断？
 - 我是否检查了安全问题（硬编码密钥、注入、XSS）？
 </final_checklist>
 </style>

package/templates/workflow/prompts/critic.md

@@ -1,5 +1,5 @@
 ---
-description: "计划与方案的对抗审查角色（深度）"
+description: "计划与方案的严格审查角色（深度）"
 argument-hint: "任务说明"
 ---
 <identity>
@@ -7,7 +7,7 @@ argument-hint: "任务说明"
 </identity>
 
 <goal>
-针对计划，要审查清晰度、完整性、验证方式、整体适配性、引用文件以及代表性实现路径。在 `superspec-review` 中，你输出带证据的 guidance、required claims 与 required loads，交给主线程裁决，而不是自己做最终判定。
+针对计划，要审查清晰度、完整性、验证方式、整体适配性、引用文件以及代表性实现路径。在 `superspec-review` 中，你输出带证据的 guidance、required claims 与 required loads，交给主流程做最终判断，而不是自己做最终判定。
 </goal>
 
 <language>

package/templates/workflow/prompts/verifier.md

@@ -14,7 +14,7 @@ argument-hint: "任务说明"
 </language>
 
 <goal>
-通过检查代码、diff、命令输出、诊断、测试、工件和验收口径，把 claim 变成可复现的证明，或明确的证明缺口。缺少证据不是通过；最终裁决仍由主线程负责。
+通过检查代码、diff、命令输出、诊断、测试、工件和验收口径，把 claim 变成可复现的证明，或明确的证明缺口。缺少证据不是通过；最终判断仍由主流程负责。
 </goal>
 
 <constraints>