@peterxiaoyang/superspec 0.1.1 → 0.1.3

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/self_update.d.ts

@@ -0,0 +1,14 @@
+import { runCommand } from "./util.ts";
+type RunFn = typeof runCommand;
+type CommandExistsFn = (cmd: string, meta?: {
+    cwd?: string;
+}) => boolean;
+export declare function update_self_then_rerun(opts: {
+    args: string[];
+    cwd?: string;
+    run?: RunFn;
+    commandExistsFn?: CommandExistsFn;
+    writeStdout?: (text: string) => void;
+    writeStderr?: (text: string) => void;
+}): number;
+export {};

package/dist/src/self_update.js

@@ -0,0 +1,56 @@
+import { commandExists, runCommand } from "./util.js";
+const SUPERSPEC_NPM_PACKAGE = "@peterxiaoyang/superspec";
+function renderCommand(cmd, args) {
+    return [cmd, ...args].join(" ");
+}
+function commandFailure(proc) {
+    const output = (proc.error?.message ?? (proc.stderr || proc.stdout)).trim();
+    if (output)
+        return output;
+    return proc.status === null ? "command failed" : `command exited with status ${proc.status}`;
+}
+function shouldRetrySuperSpecInstallWithForce(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 superspecBin = /\bsuperspec(?:\.(?:cmd|ps1))?\b/iu.test(output);
+    return binConflict && superspecBin;
+}
+export function update_self_then_rerun(opts) {
+    const cwd = opts.cwd ?? process.cwd();
+    const run = opts.run ?? runCommand;
+    const commandExistsFn = opts.commandExistsFn ?? ((cmd, meta) => commandExists(cmd, { cwd: meta?.cwd }));
+    const writeStdout = opts.writeStdout ?? ((text) => process.stdout.write(text));
+    const writeStderr = opts.writeStderr ?? ((text) => process.stderr.write(text));
+    if (!commandExistsFn("npm", { cwd })) {
+        writeStderr("SuperSpec update requires npm on PATH to install @peterxiaoyang/superspec@latest. Use `superspec update --local-only` to update surfaces from the currently installed package.\n");
+        return 1;
+    }
+    const installArgs = ["install", "-g", `${SUPERSPEC_NPM_PACKAGE}@latest`];
+    writeStderr(`Updating SuperSpec CLI: ${renderCommand("npm", installArgs)}\n`);
+    let install = run("npm", installArgs, { cwd, timeout: 300_000 });
+    if ((install.error || install.status !== 0) && shouldRetrySuperSpecInstallWithForce(install)) {
+        const forcedArgs = ["install", "-g", "--force", `${SUPERSPEC_NPM_PACKAGE}@latest`];
+        writeStderr(`SuperSpec CLI install hit a global bin conflict; retrying with: ${renderCommand("npm", forcedArgs)}\n`);
+        install = run("npm", forcedArgs, { cwd, timeout: 300_000 });
+    }
+    if (install.error || install.status !== 0) {
+        writeStderr(`SuperSpec CLI update failed: ${commandFailure(install)}\n`);
+        return 1;
+    }
+    if (!commandExistsFn("superspec", { cwd })) {
+        writeStderr("SuperSpec CLI update completed, but `superspec` is not resolvable from PATH. Reopen the shell or check npm global bin configuration.\n");
+        return 1;
+    }
+    const rerunArgs = ["update", ...opts.args, "--skip-self-update"];
+    const rerun = run("superspec", rerunArgs, { cwd, timeout: 300_000 });
+    if (rerun.stdout)
+        writeStdout(rerun.stdout);
+    if (rerun.stderr)
+        writeStderr(rerun.stderr);
+    if (rerun.error || rerun.status !== 0) {
+        if (rerun.error && !rerun.stderr)
+            writeStderr(`SuperSpec update rerun failed: ${rerun.error.message}\n`);
+        return rerun.status ?? 1;
+    }
+    return 0;
+}

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

@@ -78,6 +78,7 @@ export const EVIDENCE_KINDS = new Set([
 // FIX-8 (audit A-5) adds the previously anchor-less human pause points:
 // apply isolation choice, apply-phase scope expansion, and verify-failure disposition.
 export const HUMAN_CONFIRMATION_GATES = new Set([
+    "explore_complete",
     "design_complete",
     "invariants_reviewed",
     "archive_ready",
@@ -215,8 +216,8 @@ export const GATE_ALIASES = {
     "propose.invariants_reviewed": "invariants_reviewed",
     "propose.test_plan_drafted": "test_contract_drafted",
     "propose.tasks_mapped": "tasks_complete",
-    "propose.apply_ready": "propose_complete",
-    apply_ready: "propose_complete",
+    "propose.apply_ready": "apply_ready",
+    apply_ready: "apply_ready",
 };
 export const GATE_ROUTE = {
     explore_complete: "explore",
@@ -227,6 +228,7 @@ export const GATE_ROUTE = {
     test_contract_honored: "propose",
     tasks_complete: "propose",
     propose_complete: "propose",
+    apply_ready: "propose",
     review_complete: "review",
     verify_complete: "review",
     archive_ready: "archive",
@@ -287,6 +289,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 +303,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 +494,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 +508,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 +520,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/dist/superspec.d.ts

@@ -1,4 +1,6 @@
 #!/usr/bin/env node
 export * from "./src/init_cli.ts";
 export * from "./src/cli.ts";
+export * from "./src/doctor.ts";
+export * from "./src/self_update.ts";
 export declare function main_superspec(argv?: string[]): Promise<number>;

package/dist/superspec.js

@@ -3,8 +3,12 @@ import { realpathSync } from "node:fs";
 import { resolve } from "node:path";
 export * from "./src/init_cli.js";
 export * from "./src/cli.js";
+export * from "./src/doctor.js";
+export * from "./src/self_update.js";
 import { main } from "./src/cli.js";
+import { main_doctor, superspec_package_version } from "./src/doctor.js";
 import { main_init_async } from "./src/init_cli.js";
+import { update_self_then_rerun } from "./src/self_update.js";
 function realpathMaybe(filePath) {
     try {
         return realpathSync(filePath);
@@ -19,14 +23,34 @@ function help() {
         "",
         "commands:",
         "  init        install SuperSpec Codex surfaces (asks project/user; default project)",
-        "  update      update manifest-managed SuperSpec surfaces",
+        "  update      update SuperSpec CLI, then update manifest-managed surfaces",
         "  uninstall   remove manifest-managed SuperSpec surfaces",
         "  guard       run the SuperSpec guard command surface",
+        "  doctor      diagnose SuperSpec/OpenSpec/npm/PATH wiring",
+        "  version     print SuperSpec CLI version",
         "",
         "examples:",
         "  superspec init --scope project",
         "  superspec init --scope user",
         "  superspec guard check-init --change <change>",
+        "  superspec doctor",
+        "",
+    ].join("\n");
+}
+function updateHelp() {
+    return [
+        "usage: superspec update [--scope {project,user}] [--path PATH] [--codex-home PATH] [--local-only]",
+        "",
+        "updates the global SuperSpec CLI from npm, then updates manifest-managed SuperSpec surfaces.",
+        "",
+        "options:",
+        "  --scope {project,user}  update project .codex surfaces or user Codex home surfaces (default: project)",
+        "  --project               equivalent to --scope project",
+        "  --user, --global        equivalent to --scope user",
+        "  --path PATH             project root for project scope (default: current directory)",
+        "  --codex-home PATH       Codex user home for user scope (default: $CODEX_HOME or ~/.codex)",
+        "  --local-only            skip npm self-update and use the currently installed package",
+        "  -h, --help              show this help",
         "",
     ].join("\n");
 }
@@ -36,14 +60,29 @@ export async function main_superspec(argv = process.argv.slice(2)) {
         process.stdout.write(help());
         return 0;
     }
+    if (command === "-v" || command === "--version" || command === "version") {
+        process.stdout.write(`${superspec_package_version()}\n`);
+        return 0;
+    }
     if (command === "init")
         return main_init_async(rest);
-    if (command === "update")
-        return main_init_async([...rest, "--update"]);
+    if (command === "update") {
+        if (rest.includes("-h") || rest.includes("--help")) {
+            process.stdout.write(updateHelp());
+            return 0;
+        }
+        const localOnly = rest.includes("--local-only") || rest.includes("--skip-self-update");
+        const updateArgs = rest.filter((arg) => arg !== "--local-only" && arg !== "--skip-self-update");
+        if (!localOnly)
+            return update_self_then_rerun({ args: updateArgs });
+        return main_init_async([...updateArgs, "--update"]);
+    }
     if (command === "uninstall")
         return main_init_async([...rest, "--uninstall"]);
     if (command === "guard")
         return main(rest);
+    if (command === "doctor")
+        return main_doctor(rest);
     // Convenience fallback: `superspec check-init ...` behaves like `superspec guard check-init ...`.
     if (command.startsWith("check-") || command === "status" || command === "recompute" || command === "init") {
         return main(argv);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peterxiaoyang/superspec",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "SuperSpec workflow package: guard runtime, generic workflow templates, and Codex adapter payload.",
   "repository": {
     "type": "git",
@@ -51,7 +51,7 @@
   "scripts": {
     "build": "node build.js",
     "typecheck": "tsc --noEmit",
-    "test": "node --test tests/test_install_engine.test.ts tests/test_real_openspec_smoke.test.ts tests/test_superspec_guard.test.ts tests/test_superspec_skills.test.ts",
+    "test": "node --test tests/test_install_engine.test.ts tests/test_real_openspec_smoke.test.ts tests/test_superspec_cli.test.ts tests/test_superspec_guard.test.ts tests/test_superspec_skills.test.ts",
     "prepack": "npm run build",
     "prepublishOnly": "npm run build",
     "pack:dry-run": "npm pack --dry-run"

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>