@peterxiaoyang/superspec 0.1.1 → 0.1.2

package/README.md

@@ -99,10 +99,12 @@ SuperSpec 的 guard 会检查：
 ### 环境要求
 
 - Node.js `>= 20.19.0`
-- 本机 `PATH` 上可用 `openspec`
+- 本机 `PATH` 上可用兼容官方 `@fission-ai/openspec` 的 CLI，版本 `>= 1.4.1`，并支持 SuperSpec 依赖的 OpenSpec native surface
 - 目标项目准备使用 OpenSpec + Codex 工作流入口
 
-如果交互式执行 `superspec init --scope project` 时未检测到 `openspec`，SuperSpec 会主动询问是否现在代为安装 OpenSpec CLI。
+执行 `superspec init` 时，无论选择 `project` 还是 `user` scope，如果未检测到 `openspec`、检测到 `openspec-chinese` 或其他不兼容变体，或版本低于 `1.4.1`，SuperSpec 都会自动尝试安装 / 升级官方 OpenSpec CLI；遇到全局 bin 被不兼容变体占用时会用覆盖模式重试。
+
+Windows PowerShell 中如果遇到 npm 全局 bin 的 `.ps1` 执行策略报错，请显式使用 `.cmd` shim，例如 `superspec.cmd init --scope project`、`superspec.cmd guard check-init --change <change>`、`openspec.cmd status --change <change> --json`。
 
 ### 安装
 

package/dist/src/gates.js

@@ -1,7 +1,7 @@
 import { existsSync, readFileSync, statSync } from "node:fs";
 import { join, relative } from "node:path";
-import { ARTIFACT_ENTER_GATE, MAIN_ADJUDICATION_DECISIONS, REQUEST_CHANGES_ROUTES, NO_TDD_REASONS, OPENSPEC_ARTIFACTS, FINAL_VERIFICATION_ROLES, REQUIRED_SUPERSPEC_AGENT_ROLES, REQUIRED_SUPERSPEC_WORKFLOW_SKILLS, REQUIRED_OPENSPEC_CLI_SURFACES, REQUIRED_OPENSPEC_CODEX_SKILLS, REVIEW_GUIDANCE_ROLES, REVIEW_EVIDENCE_REQUIRED_FIELDS, TDD_MODES, VERIFY_EVIDENCE_REQUIRED_FIELDS, allow, block, commandExists, isObject, reason, renderList, repr, pinned_ref_key, safe_within, runCommand, sha256_text, runtime, toPosix, } from "./util.js";
-import { all_done, artifact_status_map, get_repo_root, is_done, normalize_gate } from "./openspec.js";
+import { ARTIFACT_ENTER_GATE, MAIN_ADJUDICATION_DECISIONS, REQUEST_CHANGES_ROUTES, NO_TDD_REASONS, OPENSPEC_ARTIFACTS, FINAL_VERIFICATION_ROLES, REQUIRED_SUPERSPEC_AGENT_ROLES, REQUIRED_SUPERSPEC_WORKFLOW_SKILLS, REQUIRED_OPENSPEC_CODEX_SKILLS, REVIEW_GUIDANCE_ROLES, REVIEW_EVIDENCE_REQUIRED_FIELDS, TDD_MODES, VERIFY_EVIDENCE_REQUIRED_FIELDS, allow, block, isObject, reason, renderList, repr, pinned_ref_key, safe_within, sha256_text, runtime, toPosix, } from "./util.js";
+import { all_done, artifact_status_map, get_repo_root, is_done, normalize_gate, openspec_cli_probe } from "./openspec.js";
 import { read_agent_toml_name, read_skill_frontmatter_name, sidecar_business_invariants_path, sidecar_discovery_path, sidecar_test_contract_path } from "./paths.js";
 import { business_invariant_ids, business_invariant_validation_reasons, automated_hard_business_invariant_ids, evidence_invariant_refs, evidence_invariant_ref_reasons, evidence_test_contract_invariant_reasons, human_confirmation_business_invariant_ids, invariant_matrix_coverage_reasons, post_implementation_business_invariant_ids, red_green_invariant_ids, test_contract_invariant_ids, } from "./invariants.js";
 import { evidence_test_id_reasons, declared_test_evidence_reasons, parse_spec_scenarios, parse_tasks, parse_test_contract_ids, parse_test_contract_records, red_green_test_ids, splitList, tasks_structure_hash, task_alternative_verification, task_test_evidence, task_test_refs, test_contract_covers_scenario, test_contract_invariant_refs_by_test, write_scope_conflict_reasons, } from "./tasks.js";
@@ -356,7 +356,7 @@ export function superspec_workflow_skill_reasons(repoRoot) {
     const skillsRoot = join(repoRoot, ".codex", "skills");
     const missing = REQUIRED_SUPERSPEC_WORKFLOW_SKILLS.filter((name) => !existsSync(join(skillsRoot, name, "SKILL.md")));
     if (missing.length > 0) {
-        reasons.push(reason("superspec_init_missing", "SuperSpec workflow skills are missing; run superspec init --scope project to (re)install them", missing));
+        reasons.push(reason("superspec_init_missing", "SuperSpec workflow skills are missing; run `superspec init --scope project` to (re)install them", missing));
     }
     for (const name of REQUIRED_SUPERSPEC_WORKFLOW_SKILLS) {
         const skillPath = join(skillsRoot, name, "SKILL.md");
@@ -401,19 +401,14 @@ export function superspec_agent_reasons(repoRoot) {
     return reasons;
 }
 export function openspec_cli_capability_reasons() {
-    if (!commandExists("openspec"))
-        return [reason("openspec_cli_unavailable", "openspec CLI is not available in PATH")];
-    const problems = [];
-    for (const args of REQUIRED_OPENSPEC_CLI_SURFACES) {
-        const proc = runCommand("openspec", [...args], { timeout: 15_000 });
-        if (proc.error) {
-            problems.push(reason("openspec_native_surface_missing", `\`openspec ${args.join(" ")}\` failed: ${proc.error.message}`));
-        }
-        else if (proc.status !== 0) {
-            problems.push(reason("openspec_native_surface_missing", `\`openspec ${args.join(" ")}\` failed: ${(proc.stderr || proc.stdout).trim()}`));
-        }
-    }
-    return problems;
+    const probe = openspec_cli_probe();
+    if (probe.ok)
+        return [];
+    if (probe.state === "missing")
+        return [reason("openspec_cli_unavailable", probe.message)];
+    if (probe.state === "too_old")
+        return [reason("openspec_cli_too_old", probe.message)];
+    return [reason("openspec_native_surface_missing", probe.message)];
 }
 export function evidence_schema_guard(change, changeRoot, repoRoot, evidences) {
     return [

package/dist/src/i18n.js

@@ -1,68 +1,69 @@
 const COMMAND_ZH = {
-    init: { label_zh: "初始化", hint_zh: "初始化 SuperSpec 工作流所需的目录和受管内容。" },
-    status: { label_zh: "状态检查", hint_zh: "查看当前变更的守卫状态与摘要。" },
-    recompute: { label_zh: "状态重算", hint_zh: "重新计算守卫状态指纹与阶段摘要。" },
+    init: { label_zh: "初始化", hint_zh: "初始化 SuperSpec 工作流所需的目录和文件。" },
+    status: { label_zh: "状态检查", hint_zh: "查看当前变更的检查状态和摘要。" },
+    recompute: { label_zh: "重新计算状态", hint_zh: "重新计算检查状态指纹和阶段摘要。" },
     "check-init": { label_zh: "初始化前置检查", hint_zh: "检查项目是否具备运行 SuperSpec 的基础内容。" },
     "check-artifact": { label_zh: "工件前置检查", hint_zh: "检查某个 OpenSpec 工件是否允许开始编写。" },
-    "check-enter": { label_zh: "前置门禁检查", hint_zh: "检查某个流程关卡是否允许进入。" },
-    "check-apply-ready": { label_zh: "进入实现前检查", hint_zh: "检查提案阶段是否已经完整收口，可以进入实现阶段。" },
+    "check-enter": { label_zh: "进入阶段前检查", hint_zh: "检查是否可以进入指定流程阶段。" },
+    "check-apply-ready": { label_zh: "进入实现前检查", hint_zh: "检查提案阶段是否已经处理完成，可以进入实现阶段。" },
     "check-task-reopen": { label_zh: "任务重开检查", hint_zh: "检查被审查打回的任务是否满足重开条件。" },
     "check-task-edit": { label_zh: "任务编辑前检查", hint_zh: "检查任务在开始实现前是否满足测试与范围前置条件。" },
     "check-task-complete": { label_zh: "任务完成检查", hint_zh: "检查任务在勾完成前是否满足 GREEN 或替代验证要求。" },
-    "check-review-ready": { label_zh: "进入审查前检查", hint_zh: "检查实现阶段是否完整收口，可以进入审查阶段。" },
+    "check-review-ready": { label_zh: "进入审查前检查", hint_zh: "检查实现阶段是否已经处理完成，可以进入审查阶段。" },
     "check-review-complete": { label_zh: "审查完成检查", hint_zh: "检查审查阶段证据是否齐备并允许通过。" },
     "check-verify-ready": { label_zh: "验证完成检查", hint_zh: "检查最终验证证据是否完整。" },
     "check-archive-ready": { label_zh: "归档前检查", hint_zh: "检查是否满足 archive 前的确认与保全要求。" },
     "check-archived": { label_zh: "归档结果检查", hint_zh: "检查 change 是否已经被正确归档。" },
 };
 const GATE_ZH = {
-    status: { label_zh: "状态", hint_zh: "当前变更的总览状态，不对应单个关卡。" },
+    status: { label_zh: "状态", hint_zh: "当前变更的总览状态，不对应单个阶段。" },
     init: { label_zh: "初始化", hint_zh: "项目或 change 级别的初始化检查。" },
-    recompute: { label_zh: "状态重算", hint_zh: "重新计算 state 与守卫指纹的辅助关卡。" },
-    project_init: { label_zh: "项目初始化", hint_zh: "为当前仓库安装或修复 SuperSpec 项目级受管内容。" },
-    project_update: { label_zh: "项目级更新", hint_zh: "更新当前仓库中的 SuperSpec 项目级受管内容。" },
-    project_uninstall: { label_zh: "项目级卸载", hint_zh: "卸载当前仓库中的 SuperSpec 项目级受管内容。" },
-    user_install: { label_zh: "用户级安装", hint_zh: "在用户级 Codex 目录安装 SuperSpec 受管内容。" },
-    user_update: { label_zh: "用户级更新", hint_zh: "更新用户级 Codex 目录中的 SuperSpec 受管内容。" },
-    user_uninstall: { label_zh: "用户级卸载", hint_zh: "卸载用户级 Codex 目录中的 SuperSpec 受管内容。" },
-    guard_error: { label_zh: "命令执行异常", hint_zh: "当前 guard 或 init 命令在执行过程中返回了错误。" },
+    recompute: { label_zh: "重新计算状态", hint_zh: "重新计算 state 与检查指纹的辅助步骤。" },
+    openspec_preflight: { label_zh: "OpenSpec 前置检查", hint_zh: "确认 OpenSpec CLI 已满足 SuperSpec 运行要求。" },
+    project_init: { label_zh: "项目初始化", hint_zh: "为当前仓库安装或修复 SuperSpec 项目文件。" },
+    project_update: { label_zh: "项目级更新", hint_zh: "更新当前仓库中的 SuperSpec 项目文件。" },
+    project_uninstall: { label_zh: "项目级卸载", hint_zh: "卸载当前仓库中的 SuperSpec 项目文件。" },
+    user_install: { label_zh: "用户级安装", hint_zh: "在用户级 Codex 目录安装 SuperSpec 文件。" },
+    user_update: { label_zh: "用户级更新", hint_zh: "更新用户级 Codex 目录中的 SuperSpec 文件。" },
+    user_uninstall: { label_zh: "用户级卸载", hint_zh: "卸载用户级 Codex 目录中的 SuperSpec 文件。" },
+    guard_error: { label_zh: "命令执行异常", hint_zh: "当前检查或初始化命令在执行过程中返回了错误。" },
     preset_upgrade: { label_zh: "预设升级确认", hint_zh: "需要先确认是否接受更高强度的流程预设。" },
     branch_handling: { label_zh: "分支处理确认", hint_zh: "需要先确认当前分支与工作区的处理方式。" },
     apply_isolation: { label_zh: "实现隔离确认", hint_zh: "需要先确认实现阶段允许写入的隔离范围。" },
     scope_expansion: { label_zh: "范围扩张确认", hint_zh: "需要先确认本次变更是否允许扩大范围。" },
-    verify_failure_handling: { label_zh: "失败验证处置确认", hint_zh: "需要先确认失败验证是继续修复还是接受偏差。" },
-    explore_complete: { label_zh: "探索完成", hint_zh: "探索记录与探索期审查披露闭环已完成。" },
-    proposal_reviewed: { label_zh: "提案审查完成", hint_zh: "提案已经完成对抗审查，并完成必要披露或用户裁决。" },
-    design_complete: { label_zh: "设计完成", hint_zh: "设计与规格的审查闭环已完成。" },
-    invariants_reviewed: { label_zh: "业务不变量审查完成", hint_zh: "业务不变量文档已完成审查与披露闭环。" },
-    test_contract_drafted: { label_zh: "测试契约起草完成", hint_zh: "测试契约已完成审查与披露闭环。" },
-    tasks_complete: { label_zh: "任务映射完成", hint_zh: "任务映射、测试引用与上游约束已经收口。" },
+    verify_failure_handling: { label_zh: "失败验证处理确认", hint_zh: "需要先确认失败验证是继续修复还是接受偏差。" },
+    explore_complete: { label_zh: "探索完成", hint_zh: "探索记录、审查问题说明和必要的用户确认都已完成。" },
+    proposal_reviewed: { label_zh: "提案审查完成", hint_zh: "提案已经完成严格审查，并完成必要的问题说明或用户确认。" },
+    design_complete: { label_zh: "设计完成", hint_zh: "设计与规格审查已经完成。" },
+    invariants_reviewed: { label_zh: "业务不变量审查完成", hint_zh: "业务不变量文档已经完成审查和必要的问题说明。" },
+    test_contract_drafted: { label_zh: "测试契约起草完成", hint_zh: "测试契约已经完成审查和必要的问题说明。" },
+    tasks_complete: { label_zh: "任务映射完成", hint_zh: "任务映射、测试引用和上游约束已经处理完成。" },
     propose_complete: { label_zh: "提案阶段完成", hint_zh: "从探索到任务映射的提案链路已经全部通过。" },
     task_reopen: { label_zh: "任务重开", hint_zh: "审查打回后的任务重开流程。" },
     task_edit: { label_zh: "任务编辑", hint_zh: "实现前检查 RED 或现状锁定测试等前置条件。" },
     task_complete: { label_zh: "任务完成", hint_zh: "任务勾完成前的证据检查。" },
     review_ready: { label_zh: "进入审查前准备完成", hint_zh: "可以开始审查阶段。" },
-    review_complete: { label_zh: "审查完成", hint_zh: "审查与最终验证证据已经收口。" },
-    verify_complete: { label_zh: "验证完成", hint_zh: "最终验证闭环已完成。" },
+    review_complete: { label_zh: "审查完成", hint_zh: "审查和最终验证证据都已经处理完成。" },
+    verify_complete: { label_zh: "验证完成", hint_zh: "最终验证已完成。" },
     archive_ready: { label_zh: "归档准备完成", hint_zh: "满足 archive 之前的所有保全与确认要求。" },
     archived: { label_zh: "已归档", hint_zh: "change 已完成 archive。" },
 };
 const REASON_ZH = {
-    missing_review_digest: { label_zh: "缺少审查披露记录", hint_zh: "当前轮次的审查问题还没有被主线程整理成披露记录。" },
-    needs_user_decision_pending: { label_zh: "等待用户裁决", hint_zh: "当前问题已经进入用户检查点，必须先由用户在 A/B/C/D 中拍板。" },
-    finding_unresolved: { label_zh: "历史问题未收口", hint_zh: "旧问题还没有终态处置，不能靠新一轮无问题审查抹掉历史问题。" },
-    finding_undisclosed: { label_zh: "本轮问题未披露", hint_zh: "审查角色提出的问题没有被写进本轮披露记录并展示给用户。" },
-    user_decision_unbound: { label_zh: "用户裁决未绑定", hint_zh: "关键问题的终态处置没有正确绑定到用户裁决或有效授权。" },
-    standing_authorization_unbound: { label_zh: "常设授权不适用", hint_zh: "当前问题不能被现有常设授权合法覆盖。" },
-    review_round_stale: { label_zh: "审查轮次已过期", hint_zh: "审查轮次钉住的工件版本已经不是当前版本，需要重审。" },
-    review_digest_stale: { label_zh: "披露记录已过期", hint_zh: "披露记录钉住的工件集合已过期，需要按当前版本重做披露。" },
-    review_round_discontinuous: { label_zh: "审查轮次断档", hint_zh: "review_round_id 必须连续编号，不能跳过中间轮次。" },
-    digest_chain_broken: { label_zh: "披露链断裂", hint_zh: "后一轮披露记录没有正确引用前一轮披露记录。" },
-    finding_identity_mismatch: { label_zh: "问题身份不一致", hint_zh: "主线程在披露记录里改写了审查方原始问题的分类或身份字段。" },
-    finding_summary_not_verbatim: { label_zh: "问题原文未逐字保留", hint_zh: "用户可见披露没有逐字保留审查方的原始摘要。" },
+    missing_review_digest: { label_zh: "缺少审查问题记录", hint_zh: "当前轮次的审查问题还没有整理成给用户看的记录。" },
+    needs_user_decision_pending: { label_zh: "等待用户确认", hint_zh: "当前问题需要用户确认，请先选择 A/B/C/D 中的一项。" },
+    finding_unresolved: { label_zh: "历史问题未处理完", hint_zh: "旧问题还没有最终处理结果，不能靠新一轮无问题审查把它忽略掉。" },
+    finding_undisclosed: { label_zh: "本轮问题未说明", hint_zh: "审查角色提出的问题还没有写进本轮审查问题记录并展示给用户。" },
+    user_decision_unbound: { label_zh: "用户确认未绑定", hint_zh: "关键问题的最终处理结果没有正确关联到用户确认或有效授权。" },
+    standing_authorization_unbound: { label_zh: "长期授权不适用", hint_zh: "当前问题不能被现有长期授权覆盖。" },
+    review_round_stale: { label_zh: "审查轮次已过期", hint_zh: "审查轮次记录的工件版本已经不是当前版本，需要重新审查。" },
+    review_digest_stale: { label_zh: "审查问题记录已过期", hint_zh: "审查问题记录对应的工件集合已过期，需要按当前版本重新整理。" },
+    review_round_discontinuous: { label_zh: "审查轮次断档", hint_zh: "审查轮次编号必须连续，不能跳过中间轮次。" },
+    digest_chain_broken: { label_zh: "审查问题记录链不完整", hint_zh: "后一轮审查问题记录没有正确引用前一轮记录。" },
+    finding_identity_mismatch: { label_zh: "问题身份不一致", hint_zh: "主流程在审查问题记录里改写了审查方原始问题的分类或身份字段。" },
+    finding_summary_not_verbatim: { label_zh: "问题原文未逐字保留", hint_zh: "展示给用户的问题说明没有逐字保留审查方的原始摘要。" },
     accepted_deviation_unacknowledged: { label_zh: "已接受偏差未被重审确认", hint_zh: "新一轮无问题审查没有明确确认已接受的偏差。" },
-    ledger_injection_missing: { label_zh: "缺少问题台账注入", hint_zh: "增量重审输入中缺少工具生成的问题台账。" },
-    round_budget_exhausted: { label_zh: "审查轮次预算耗尽", hint_zh: "同一流程关卡超过预算轮次仍未收敛，需要升级给用户。" },
+    ledger_injection_missing: { label_zh: "缺少问题清单", hint_zh: "增量重审输入中缺少工具生成的问题清单。" },
+    round_budget_exhausted: { label_zh: "审查轮次已达上限", hint_zh: "同一流程阶段超过预算轮次仍未处理完成，需要升级给用户。" },
     missing_characterization: { label_zh: "缺少现状锁定测试", hint_zh: "行为保持重构在动代码前，必须先用 GREEN 测试锁住当前行为。" },
     missing_red_evidence: { label_zh: "缺少 RED 证据", hint_zh: "新增行为或修 bug 的任务在实现前需要先有失败测试证据。" },
     missing_green_evidence: { label_zh: "缺少 GREEN 证据", hint_zh: "任务完成前需要通过成功测试或等价验证。" },
@@ -70,29 +71,34 @@ const REASON_ZH = {
     invalid_no_tdd_reason: { label_zh: "免 TDD 理由无效", hint_zh: "task 上声明的 no_tdd_reason 不在允许枚举里。" },
     missing_discovery: { label_zh: "缺少探索记录", hint_zh: "探索阶段缺少 discovery.md，或者该文件内容为空。" },
     missing_proposal: { label_zh: "缺少提案工件", hint_zh: "提案工件还没有完成。" },
-    missing_proposal_review: { label_zh: "缺少提案审查", hint_zh: "提案审查关卡还没有收集到对抗审查证据。" },
-    explore_complete_failed: { label_zh: "探索阶段未通过", hint_zh: "下游关卡依赖的探索完成检查还没有通过。" },
-    proposal_reviewed_failed: { label_zh: "提案审查阶段未通过", hint_zh: "下游关卡依赖的提案审查完成还没有通过。" },
+    missing_proposal_review: { label_zh: "缺少提案审查", hint_zh: "提案审查阶段还没有收集到严格审查证据。" },
+    explore_complete_failed: { label_zh: "探索阶段未通过", hint_zh: "后续阶段依赖的探索完成检查还没有通过。" },
+    proposal_reviewed_failed: { label_zh: "提案审查阶段未通过", hint_zh: "后续阶段依赖的提案审查完成还没有通过。" },
     validate_failed: { label_zh: "OpenSpec 校验失败", hint_zh: "openspec validate 还没有通过。" },
-    review_not_ready: { label_zh: "尚未达到审查条件", hint_zh: "进入审查阶段之前的前置关卡还没有全部通过。" },
+    review_not_ready: { label_zh: "尚未达到审查条件", hint_zh: "进入审查阶段之前的检查还没有全部通过。" },
     apply_isolation_unconfirmed: { label_zh: "实现隔离尚未确认", hint_zh: "实现阶段缺少用户对写入隔离范围的确认。" },
     scope_expansion_unconfirmed: { label_zh: "范围扩张尚未确认", hint_zh: "tasks 结构变化扩大了范围，但还没有新的用户确认。" },
     state_concurrent_update: { label_zh: "状态写入发生并发变更", hint_zh: "决策和写入之间输入发生变化，需要等变更稳定后重新运行。" },
     project_init_failed: { label_zh: "项目初始化失败", hint_zh: "项目级 SuperSpec 初始化没有成功完成。" },
-    project_update_failed: { label_zh: "项目级更新失败", hint_zh: "项目级受管内容更新失败。" },
-    project_uninstall_failed: { label_zh: "项目级卸载失败", hint_zh: "项目级受管内容卸载失败。" },
+    openspec_cli_too_old: { label_zh: "OpenSpec 版本过低", hint_zh: "当前 openspec CLI 低于 SuperSpec 要求的最低版本。" },
+    openspec_cli_unavailable: { label_zh: "OpenSpec CLI 不可用", hint_zh: "PATH 中没有可执行的 openspec CLI。" },
+    openspec_native_surface_missing: { label_zh: "OpenSpec 原生能力缺失", hint_zh: "当前 openspec CLI 不是受支持版本，或缺少 SuperSpec 依赖的子命令。" },
+    openspec_auto_install_unavailable: { label_zh: "OpenSpec 无法自动安装", hint_zh: "当前环境没有可用包管理器完成 OpenSpec 自动安装或升级。" },
+    openspec_auto_install_failed: { label_zh: "OpenSpec 自动安装失败", hint_zh: "OpenSpec 自动安装或升级命令没有成功完成。" },
+    project_update_failed: { label_zh: "项目级更新失败", hint_zh: "项目级 SuperSpec 文件更新失败。" },
+    project_uninstall_failed: { label_zh: "项目级卸载失败", hint_zh: "项目级 SuperSpec 文件卸载失败。" },
     user_install_failed: { label_zh: "用户级安装失败", hint_zh: "用户级 SuperSpec 安装失败。" },
     user_update_failed: { label_zh: "用户级更新失败", hint_zh: "用户级 SuperSpec 更新失败。" },
     user_uninstall_failed: { label_zh: "用户级卸载失败", hint_zh: "用户级 SuperSpec 卸载失败。" },
-    guard_error: { label_zh: "Guard 执行失败", hint_zh: "guard 命令执行过程中发生了可报告错误。" },
-    guard_internal_error: { label_zh: "Guard 内部错误", hint_zh: "guard 内部抛出了异常，需要查看错误信息排查。" },
+    guard_error: { label_zh: "检查执行失败", hint_zh: "guard 命令执行过程中发生了可报告错误。" },
+    guard_internal_error: { label_zh: "检查器内部错误", hint_zh: "guard 内部抛出了异常，需要查看错误信息排查。" },
 };
 const WORKFLOW_TERMS_ZH = {
-    "check-enter": { term: "check-enter", label_zh: "前置门禁检查", hint_zh: "进入某个 gate 前先跑的守门检查命令。" },
-    acceptance: { term: "acceptance", label_zh: "验收口径", hint_zh: "这个 change 交付后必须满足的结果和边界。" },
+    "check-enter": { term: "check-enter", label_zh: "进入阶段前检查", hint_zh: "进入某个流程阶段前先运行的检查命令。" },
+    acceptance: { term: "acceptance", label_zh: "验收标准", hint_zh: "这个 change 交付后必须满足的结果和边界。" },
     characterization: { term: "characterization", label_zh: "现状锁定测试", hint_zh: "先把当前真实行为测出来并锁住，重构后保持一致。" },
-    main_review_digest: { term: "main_review_digest", label_zh: "主线程审查披露记录", hint_zh: "主线程把本轮审查问题整理给用户看的记录。" },
-    user_review_decision: { term: "user_review_decision", label_zh: "用户裁决记录", hint_zh: "用户对 A/B/C/D 选项做出的正式决定记录。" },
+    main_review_digest: { term: "main_review_digest", label_zh: "审查问题记录", hint_zh: "主流程把本轮审查问题整理给用户看的记录。" },
+    user_review_decision: { term: "user_review_decision", label_zh: "用户确认记录", hint_zh: "用户对 A/B/C/D 选项做出的正式确认记录。" },
 };
 const TRUST_WARNING_ZH = {
     "v1 evidence is audit-only/self-reported unless explicitly backed by OpenSpec facts": "v1 证据默认只作审计参考或自报信息；除非另有 OpenSpec 事实支撑，否则不能单独当作强证明。",
@@ -103,9 +109,9 @@ const TRUST_WARNING_ZH = {
 const ACTION_ZH_EXACT = {
     "continue with superspec-explore/propose/apply guard checks": "继续执行探索、提案和实现阶段的前置检查。",
     "create/select a change during superspec-explore, then run change-scoped guard checks": "先在探索阶段创建或选择一个变更，然后运行该变更范围内的前置检查。",
-    "review *.new files for user-modified surfaces, then rerun superspec guard check-init": "先检查因用户改动而生成的 *.new 文件，然后重新运行初始化前置检查。",
+    "review *.new files for user-modified surfaces, then rerun superspec guard check-init": "先检查因用户改动而生成的 *.new 文件，然后重新运行初始化前置检查；Windows PowerShell 中使用 superspec.cmd guard check-init。",
     "review *.new files for user-modified user-level surfaces": "先检查用户级内容对应的 *.new 文件。",
-    "user-level SuperSpec Codex surfaces installed; use superspec init --scope project inside a repo when project-local surfaces are needed": "用户级 SuperSpec 配套内容已安装；如果仓库里还需要项目级内容，请在仓库内运行 superspec init --scope project。",
+    "user-level SuperSpec Codex surfaces installed; use superspec init --scope project inside a repo when project-local surfaces are needed": "用户级 SuperSpec 配套内容已安装；如果仓库里还需要项目级内容，请在仓库内运行 superspec init --scope project；Windows PowerShell 中使用 superspec.cmd init --scope project。",
     "finish remaining unchecked tasks and mark them complete only after check-task-complete passes": "先完成剩余未勾选任务，并且仅在任务完成检查通过后再标记完成。",
     "record final_test pass evidence and reference it from verification_review": "记录最终测试通过证据，并在验证审查证据中引用它。",
 };
@@ -120,7 +126,7 @@ const ACTION_STATUS_ZH = {
 };
 const ROLE_ZH = {
     architect: "架构审查",
-    critic: "对抗审查",
+    critic: "严格审查",
     "test-engineer": "测试审查",
     "code-reviewer": "代码审查",
     verifier: "验证审查",
@@ -129,9 +135,9 @@ const EVIDENCE_KIND_ZH = {
     source_guidance: "审查指导证据",
     verification_review: "验证审查证据",
     final_test: "最终测试通过证据",
-    main_adjudication: "主线程裁决记录",
-    main_review_digest: "主线程审查披露记录",
-    user_review_decision: "用户裁决记录",
+    main_adjudication: "主流程最终判断记录",
+    main_review_digest: "审查问题记录",
+    user_review_decision: "用户确认记录",
     human_confirmation: "人工确认证据",
     test_run: "测试运行证据",
     alternative_verification: "替代验证证据",
@@ -147,8 +153,8 @@ const FIELD_ZH = {
     blocking_source_evidence_refs: "阻塞来源证据引用",
     required_claim_ids: "必需结论项",
     required_load_refs: "必需加载引用",
-    claim_adjudications: "结论项裁决",
-    finding_adjudications: "问题项裁决",
+    claim_adjudications: "结论项判断",
+    finding_adjudications: "问题处理判断",
     request_changes_route: "打回路由",
     reopen_task_ids: "需重开任务列表",
     output_ref: "输出引用",
@@ -169,9 +175,9 @@ const NOUN_ZH = {
     source_guidance: "审查指导证据",
     verification_review: "验证审查证据",
     final_test: "最终测试通过证据",
-    main_adjudication: "主线程裁决记录",
-    main_review_digest: "主线程审查披露记录",
-    review_digest: "审查披露记录",
+    main_adjudication: "主流程最终判断记录",
+    main_review_digest: "审查问题记录",
+    review_digest: "审查问题记录",
     review_round: "审查轮次",
     final_verification_review: "最终验证审查",
     business_invariants: "业务不变量",
@@ -193,9 +199,9 @@ const NOUN_ZH = {
     review_evidence: "审查证据",
     task_evidence: "任务证据",
     native_subagent_evidence: "本地子代理证据",
-    claim_adjudication: "结论项裁决",
-    claim_adjudications: "结论项裁决",
-    finding_adjudication: "问题项裁决",
+    claim_adjudication: "结论项判断",
+    claim_adjudications: "结论项判断",
+    finding_adjudication: "问题处理判断",
     test_contract_review: "测试契约审查",
     invariant_review: "不变量审查",
     missing_roles: "缺失角色",
@@ -203,7 +209,7 @@ const NOUN_ZH = {
     reviewed_files: "审查文件列表",
     required_loads: "必需加载项",
     claims: "结论项",
-    blocking_findings: "阻塞问题项",
+    blocking_findings: "阻塞问题",
     human_confirmation: "人工确认",
     scope_drift: "范围漂移",
     openspec_cli: "OpenSpec CLI",
@@ -229,11 +235,11 @@ const TOKEN_ZH = {
     unknown: "未知",
     unexpected: "非预期",
     ambiguous: "不唯一",
-    unresolved: "未收口",
+    unresolved: "未处理完",
     stale: "已过期",
     failed: "失败",
     incomplete: "不完整",
-    blocked: "被阻塞",
+    blocked: "未通过",
     unavailable: "不可用",
     mismatch: "不匹配",
     duplicate: "重复",
@@ -274,15 +280,15 @@ const TOKEN_ZH = {
     native: "本地",
     subagent: "子代理",
     evidence: "证据",
-    adjudication: "裁决",
+    adjudication: "最终判断",
     claim: "结论项",
     claims: "结论项",
-    finding: "问题项",
-    findings: "问题项",
+    finding: "问题",
+    findings: "问题",
     complete: "完成",
     propose: "提案",
     apply: "实现",
-    gate: "关卡",
+    gate: "阶段",
     rereview: "重新审查",
     rollback: "回滚",
     target: "目标",
@@ -309,7 +315,7 @@ export function command_zh(command) {
     return COMMAND_ZH[command] ?? { label_zh: noun_phrase_zh(command) ?? "内部命令", hint_zh: "这是内部命令标识；界面层应优先展示对应的中文说明。" };
 }
 export function gate_zh(gate) {
-    return GATE_ZH[gate] ?? { label_zh: noun_phrase_zh(gate) ?? "内部流程关卡", hint_zh: "这是内部流程关卡标识；界面层应优先展示对应的中文说明。" };
+    return GATE_ZH[gate] ?? { label_zh: noun_phrase_zh(gate) ?? "内部流程阶段", hint_zh: "这是内部流程阶段标识；界面层应优先展示对应的中文说明。" };
 }
 export function reason_zh(code) {
     return REASON_ZH[code] ?? auto_reason_zh(code);
@@ -318,10 +324,10 @@ export function decision_zh(decision) {
     if (decision === "allow")
         return "通过";
     if (decision === "block")
-        return "阻塞";
+        return "未通过";
     if (decision === "status")
         return "状态";
-    return "内部决策";
+    return "内部结果";
 }
 function hasHan(text) {
     return /[\u3400-\u9fff]/u.test(text);
@@ -371,7 +377,7 @@ function auto_reason_zh(code) {
         [/^unknown_(.+)$/u, (subject) => render(subject, "未知", "无法被当前流程识别。")],
         [/^unexpected_(.+)$/u, (subject) => render(subject, "出现非预期的", "超出了当前流程允许范围。")],
         [/^ambiguous_(.+)$/u, (subject) => render(subject, "", "不唯一，需要先消歧。")],
-        [/^unresolved_(.+)$/u, (subject) => render(subject, "", "尚未收口，需要先处理。")],
+        [/^unresolved_(.+)$/u, (subject) => render(subject, "", "尚未处理完成，需要先处理。")],
         [/^stale_(.+)$/u, (subject) => render(subject, "", "已经过期，需要基于最新内容重做。")],
         [/^(.+)_failed$/u, (subject) => render(subject, "", "未通过当前检查。")],
         [/^(.+)_invalid$/u, (subject) => render(subject, "", "不符合预期格式或约束。")],
@@ -382,7 +388,7 @@ function auto_reason_zh(code) {
         [/^(.+)_unloaded$/u, (subject) => render(subject, "", "尚未被正确加载。")],
         [/^(.+)_mismatch$/u, (subject) => render(subject, "", "与预期不一致。")],
         [/^(.+)_duplicate$/u, (subject) => render(subject, "", "出现重复。")],
-        [/^(.+)_blocked$/u, (subject) => render(subject, "", "当前被阻塞。")],
+        [/^(.+)_blocked$/u, (subject) => render(subject, "", "当前未通过。")],
         [/^(.+)_required$/u, (subject) => render(subject, "需要", "是当前流程的必需项。")],
         [/^(.+)_not_honored$/u, (subject) => render(subject, "", "尚未被满足。")],
         [/^(.+)_not_ready$/u, (subject) => render(subject, "", "尚未就绪。")],
@@ -397,12 +403,25 @@ function auto_reason_zh(code) {
     }
     const label = noun_phrase_zh(code);
     if (label)
-        return { label_zh: label, hint_zh: "当前流程触发了这条阻塞原因，请结合上下文继续排查。" };
-    return fallbackZh("阻塞原因");
+        return { label_zh: label, hint_zh: "当前流程触发了这条未通过原因，请结合上下文继续排查。" };
+    return fallbackZh("未通过原因");
 }
 function translate_message_tokens_zh(raw) {
     let out = raw;
     const phraseReplacements = [
+        [/main_review_digest/giu, "审查问题记录"],
+        [/user_review_decision/giu, "用户确认记录"],
+        [/review_standing_authorization/giu, "长期授权记录"],
+        [/review_round_id/giu, "审查轮次编号"],
+        [/finding_uid/giu, "问题唯一标识"],
+        [/decision_scope_key/giu, "确认范围标识"],
+        [/confirmed_refs/giu, "已确认内容引用"],
+        [/source_review_evidence_refs/giu, "来源审查证据引用"],
+        [/previous_digest_refs/giu, "上一轮审查问题记录引用"],
+        [/finding_dispositions/giu, "问题处理结果"],
+        [/needs_user_decision/giu, "等待用户确认"],
+        [/ledger_injection_missing/giu, "缺少问题清单"],
+        [/round_budget_exhausted/giu, "审查轮次已达上限"],
         [/source_guidance evidence/giu, "审查指导证据"],
         [/verification_review evidence/giu, "验证审查证据"],
         [/final_test pass evidence/giu, "最终测试通过证据"],
@@ -501,7 +520,8 @@ export function translate_action_zh(action) {
     if (exact)
         return exact;
     const patterns = [
-        [/^managed SuperSpec surfaces removed; run superspec init --scope (.+) to reinstall$/u, (scope) => `受管 SuperSpec 内容已移除；如需重新安装，请运行 superspec init --scope ${scope}。`],
+        [/^managed SuperSpec surfaces removed; run superspec init --scope (.+) to reinstall$/u, (scope) => `SuperSpec 管理的文件已移除；如需重新安装，请运行 superspec init --scope ${scope}；Windows PowerShell 中使用 superspec.cmd init --scope ${scope}。`],
+        [/^install or upgrade @fission-ai\/openspec >= ([0-9.]+), then rerun `superspec init --scope (.+)`$/u, (version, scope) => `先安装或升级 @fission-ai/openspec 到 ${version} 或更高版本，然后重新运行 superspec init --scope ${scope}；Windows PowerShell 中使用 superspec.cmd init --scope ${scope}。`],
         [/^fix ([A-Za-z0-9_.-]+) reasons, then rerun(?: (.+))?$/u, (problem, cmd) => {
                 const label = display_term_zh(problem);
                 return cmd ? `先处理${label}对应问题，然后重新运行相关命令。` : `先处理${label}对应问题，然后重新运行相关检查。`;
@@ -510,42 +530,42 @@ export function translate_action_zh(action) {
         [/^collect ([A-Za-z0-9_.-]+) source_guidance from missing roles: (.+)$/u, (gate, roles) => `补齐${display_term_zh(gate)}所缺的审查指导证据（角色：${render_roles_zh(roles)}）。`],
         [/^collect verification_review evidence from missing roles: (.+)$/u, (roles) => `补齐验证审查证据（角色：${render_roles_zh(roles)}）。`],
         [/^repair source_guidance evidence fields so every review lane has base\/head refs, reviewed_files, and rollback_targets$/u, () => "修复审查指导证据字段，确保每条审查线都包含基线/当前提交引用、审查文件列表和回滚目标。"],
-        [/^write exactly one live main_adjudication referencing every live source_guidance and final verification evidence$/u, () => "补写且仅保留一条有效的主线程裁决记录，并引用全部有效的审查指导证据和最终验证证据。"],
-        [/^repair main_adjudication so it references all source_guidance\/final verification evidence and explicitly covers required loads, claims, and blocking findings$/u, () => "修复主线程裁决记录，确保它引用全部审查指导证据与最终验证证据，并明确覆盖必需加载项、结论项和阻塞问题项。"],
+        [/^write exactly one live main_adjudication referencing every live source_guidance and final verification evidence$/u, () => "补写且仅保留一条有效的主流程最终判断记录，并引用全部有效的审查指导证据和最终验证证据。"],
+        [/^repair main_adjudication so it references all source_guidance\/final verification evidence and explicitly covers required loads, claims, and blocking findings$/u, () => "修复主流程最终判断记录，确保它引用全部审查指导证据与最终验证证据，并明确覆盖必需加载项、结论项和阻塞问题。"],
         [/^repair verification_review references so openspec_validate_ref, matrices, scope drift report, and test evidence refs are readable$/u, () => "修复验证审查证据引用，确保 OpenSpec 校验引用、各类矩阵、范围漂移报告和测试证据引用都可读取。"],
         [/^resolve scope drift before review close: narrow the change or record accepted\/none with evidence$/u, () => "先处理范围漂移，再结束审查：要么收窄本次变更范围，要么补充证据后明确记录为已接受或无漂移。"],
         [/^record ([A-Za-z0-9_.-]+) pass evidence and reference it from ([A-Za-z0-9_.-]+)$/u, (kind, target) => `记录${display_term_zh(kind)}，并在${display_term_zh(target)}中引用它。`],
         [/^AskUserQuestion for apply isolation\/execution mode and record gate="apply_isolation" human_confirmation$/u, () => "请先让用户确认实现隔离范围或执行方式，并记录对应的人工确认证据。"],
-        [/^run the proposal critic review \(round-tagged, findings\[\]\) and record a main_review_digest disclosing every finding$/u, () => "先完成提案的对抗审查，并记录一条向用户完整披露所有问题的主线程审查披露记录。"],
+        [/^run the proposal critic review \(round-tagged, findings\[\]\) and record a main_review_digest disclosing every finding$/u, () => "先完成提案的严格审查，并记录一条向用户说明所有问题的审查问题记录。"],
         [/^pass (.+) before entering (.+)$/u, (name, stage) => `进入${display_term_zh(stage)}之前先通过${display_term_zh(name)}。`],
         [/^pass (.+) first$/u, (name) => `先通过${display_term_zh(name)}。`],
         [/^pass (.+)$/u, (name) => `先通过${display_term_zh(name)}。`],
         [/^rerun (.+)$/u, (cmd) => `重新运行${display_term_zh(cmd)}。`],
         [/^run (.+)$/u, (cmd) => `运行${display_term_zh(cmd)}。`],
         [/^fix (.+), then rerun (.+)$/u, (_problem, cmd) => `先修复相关问题，然后重新运行 ${cmd}。`],
-        [/^fix (.+)$/u, (problem) => hasHan(problem) ? `修复 ${problem}。` : "先修复当前阻塞项。"],
+        [/^fix (.+)$/u, (problem) => hasHan(problem) ? `修复 ${problem}。` : "先修复当前未通过项。"],
         [/^inspect (.+), then rerun (.+)$/u, (target, cmd) => `先检查 ${target}，然后重新运行 ${cmd}。`],
         [/^keep (.+) checked, fix (.+), then rerun (.+)$/u, (target, _problem, cmd) => `保持 ${target} 处于已勾选状态，修复当前问题，然后重新运行 ${cmd}。`],
         [/^continue with (.+)$/u, (what) => `继续执行 ${what}。`],
         [/^record (.+) human_confirmation evidence, then rerun (.+)$/u, (kind, cmd) => `记录${display_term_zh(kind)}对应的人工确认证据，然后重新运行${display_term_zh(cmd)}。`],
-        [/^stop review completion and hand off to apply task_reopen for (.+)$/u, (taskIds) => `停止当前审查收口，转回实现阶段处理任务重开：${taskIds}。`],
-        [/^stop review completion and hand off to apply task_reopen$/u, () => "停止当前审查收口，转回实现阶段处理任务重开。"],
-        [/^stop review completion and hand off to propose\/change update$/u, () => "停止当前审查收口，转回提案阶段处理变更回改。"],
-        [/^do not add allow-path verification_review\/final_test evidence to this request_changes round$/u, () => "本轮打回处理中不要补写仅用于放行路径的验证审查证据或最终测试通过证据。"],
+        [/^stop review completion and hand off to apply task_reopen for (.+)$/u, (taskIds) => `停止当前审查完成流程，转回实现阶段处理任务重开：${taskIds}。`],
+        [/^stop review completion and hand off to apply task_reopen$/u, () => "停止当前审查完成流程，转回实现阶段处理任务重开。"],
+        [/^stop review completion and hand off to propose\/change update$/u, () => "停止当前审查完成流程，转回提案阶段处理变更回改。"],
+        [/^do not add allow-path verification_review\/final_test evidence to this request_changes round$/u, () => "本轮打回处理中不要补写仅用于通过审查的验证审查证据或最终测试通过证据。"],
         [/^repair request_changes_route and hand off the review round before retrying review_complete$/u, () => "先修复打回路由并完成当前审查轮次交接，再重新尝试审查完成检查。"],
-        [/^AskUserQuestion for the failed-verification disposition \(fix or accept deviation\) and record gate="verify_failure_handling" human_confirmation referencing the failed evidence ids$/u, () => "把失败验证的处置交给用户拍板：选择继续修复还是接受偏差，并补记引用失败证据的人工确认。"],
+        [/^AskUserQuestion for the failed-verification disposition \(fix or accept deviation\) and record gate="verify_failure_handling" human_confirmation referencing the failed evidence ids$/u, () => "请用户确认失败验证的处理方式：继续修复，或接受这次偏差；并补记引用失败证据的人工确认。"],
     ];
     for (const [pattern, render] of patterns) {
         const match = action.match(pattern);
         if (match)
             return render(...match.slice(1));
     }
-    return "先处理当前阻塞项，再重新运行相关检查。";
+    return "先处理当前未通过项，再重新运行相关检查。";
 }
 export function reason_message_zh(code, rawMessage, refs = []) {
     const zh = reason_zh(code);
     if (hasHan(rawMessage))
-        return `${rawMessage}${refs_suffix_zh(refs)}`;
+        return `${translate_message_tokens_zh(rawMessage)}${refs_suffix_zh(refs)}`;
     if (Object.prototype.hasOwnProperty.call(REASON_ZH, code) && zh.hint_zh)
         return `${zh.label_zh}：${zh.hint_zh}${refs_suffix_zh(refs)}`;
     const translated = translate_message_tokens_zh(rawMessage);
@@ -581,7 +601,7 @@ export function action_label_zh(action) {
         if (match)
             return render(...match.slice(1));
     }
-    return "执行受管文件操作";
+    return "执行由 SuperSpec 管理的文件操作";
 }
 export function action_detail_zh(detail) {
     const patterns = [
@@ -589,9 +609,9 @@ export function action_detail_zh(detail) {
         [/^pre-existing file with different content kept; rerun with --force to overwrite \(backs up \*\.bak\)$/u, () => "已有不同内容文件已保留；如需覆盖，请使用 --force，覆盖前会备份为 *.bak。"],
         [/^preexisting file is never touched$/u, () => "既有文件不会被改动。"],
         [/^user-modified file kept; new version written to (.+)$/u, (target) => `已保留用户修改版本；新版本写入 ${target}。`],
-        [/^managed file no longer shipped$/u, () => "该受管文件在当前版本中已不再分发。"],
+        [/^managed file no longer shipped$/u, () => "该文件在当前版本中已不再分发。"],
         [/^no longer shipped but user-modified; kept$/u, () => "该文件在当前版本中已不再分发，但因存在用户修改而被保留。"],
-        [/^preexisting\/unmanaged file is never touched$/u, () => "既有或非受管文件不会被改动。"],
+        [/^preexisting\/unmanaged file is never touched$/u, () => "既有文件或非 SuperSpec 管理的文件不会被改动。"],
         [/^already absent$/u, () => "该文件原本就不存在。"],
         [/^user-modified since install; kept$/u, () => "该文件在安装后已被用户修改，因此会被保留。"],
     ];

package/dist/src/init_cli.d.ts

@@ -1,4 +1,4 @@
-import { runCommand } from "./core.ts";
+import { runCommand, type OpenspecCliProbe } from "./core.ts";
 import { type InstallScope } from "./install_engine.ts";
 type InitArgs = {
     path: string;
@@ -16,10 +16,12 @@ export declare function maybe_install_missing_openspec(opts: {
     commandExistsFn?: (cmd: string, meta?: {
         cwd?: string;
     }) => boolean;
-    confirm?: (question: string) => Promise<boolean>;
+    probeOpenspecFn?: (meta?: {
+        cwd?: string;
+    }) => OpenspecCliProbe;
     run?: typeof runCommand;
     writeStderr?: (text: string) => void;
-}): Promise<"not-needed" | "installed" | "skipped" | "failed">;
+}): "not-needed" | "installed" | "skipped" | "failed";
 export declare function main_init(argv?: string[]): number;
 export declare function main_init_async(argv?: string[]): Promise<number>;
 export {};