@peterxiaoyang/superspec 0.1.0 → 0.1.2

package/README.md

@@ -1,47 +1,198 @@
 # SuperSpec
 
-SuperSpec 是基于 OpenSpec 的 agent 工作流叠加层。本仓库是独立的
-SuperSpec 项目，包根目录、工作流模板、Codex 适配文件、设计文档和
-CI 配置都放在仓库根目录。
+[![npm version](https://img.shields.io/npm/v/@peterxiaoyang/superspec?style=flat-square)](https://www.npmjs.com/package/@peterxiaoyang/superspec)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D20.19.0-brightgreen?style=flat-square)](https://nodejs.org)
+[![OpenSpec overlay](https://img.shields.io/badge/OpenSpec-overlay-6f42c1?style=flat-square)](https://github.com/Fission-AI/OpenSpec)
 
-本包开发时使用 TypeScript；执行 `npm run build` 后生成 `dist/*.js`。
-发布包里的命令行入口会运行编译后的 JavaScript。
+> 面向 Codex 的 OpenSpec 增强工作流约束层。
 
-使用者需要 Node.js 20.19.0 或更高版本。仓库开发和测试当前使用
-Node.js 24，因为测试会直接执行 `.ts` 文件。
+SuperSpec 是一个已经发布的 npm 包，适合已经认可 OpenSpec，但觉得默认流程在执行层还不够严格的团队。
 
-## 安装
+它不替换 OpenSpec，也不改 OpenSpec 的工件关系。  
+它做的是在 OpenSpec 现有变更生命周期之上，再加一层更强的执行纪律：
 
-从 GitHub 发布附件全局安装命令行工具：
+- 先做现状调研，再谈设计是否站得住
+- 先明确业务不变量，再做实现
+- 先写清测试约束，再避免流于表面的测试
+- 先经过多角色审查，再允许宣布“完成”
+- 先确认归档保全完整，再真正归档
 
-```text
+如果你只想用最原生、最轻量的 OpenSpec，而不想增加审查、测试、归档这些额外门禁，那你大概率不需要 SuperSpec。
+
+SuperSpec 的核心定位是：
+
+- **保留 OpenSpec 作为主流程**
+- **把执行约束收敛成可复用的叠加层**
+- **让阶段推进依赖证据，而不是模型一句“done”**
+
+## 为什么会有 SuperSpec
+
+很多团队在把 OpenSpec 和编码代理结合起来之后，真正出问题的地方往往不是“没有文档”，而是“有流程形状，但没有流程纪律”。
+
+常见问题是：
+
+- 设计文档在，但不够细，指导不了后续实现
+- 测试在，但没有证明真正重要的东西
+- 任务打勾了，但缺少强校验
+- 主线程自己写、自己审、自己宣布通过
+- 归档做了，但辅助证据已经散了
+
+SuperSpec 解决的不是“再造一套 OpenSpec”，而是把这些执行层的薄弱点补上。
+
+## SuperSpec 增加了什么
+
+### 1. 更严格的 propose 阶段
+
+SuperSpec 保留 OpenSpec 的原生四件套工件：
+
+- `proposal`
+- `specs`
+- `design`
+- `tasks`
+
+同时补三类辅助产物：
+
+- `discovery.md`：记录现状调研结果、已有行为、约束边界和需要先确认的问题
+- `business-invariants.md`：整理这次变更必须守住的业务不变量，避免实现时把关键业务语义改丢
+- `test-contract.md`：把测试覆盖范围、测试编号、约束映射和验证责任提前写清楚
+
+这样 `propose` 阶段就不只是“把文档写出来”，而是真正把设计、约束和测试责任提前收拢。
+
+### 2. 显式的多角色审查分工
+
+SuperSpec 会安装这些项目内角色：
+
+- `architect`
+- `critic`
+- `test-engineer`
+- `code-reviewer`
+- `verifier`
+
+这意味着审查在 SuperSpec 里是一个正式阶段，不是实现完成后的附带动作。
+
+### 3. 基于证据的门禁
+
+SuperSpec 的 guard 会检查：
+
+- 阶段进入条件
+- 任务修改 / 任务完成 条件
+- 审查完成 条件
+- 可归档条件与归档保全条件
+
+目标很直接：**阶段推进必须依赖证据，而不是靠模型自述。**
+
+### 4. 更完整的辅助目录与归档保全
+
+每个变更下都会有 `.superspec/` 辅助运行目录，用于保存：
+
+- 辅助产物：补足 OpenSpec 原生工件之外的调研、约束和测试文档
+- 证据：保存 RED/GREEN、审查、验证、确认等过程证据
+- 审查输出：保存各角色的审查结果和主线程的汇总结论
+- 状态文件：保存当前 gate、指纹和阶段状态，便于恢复和重算
+- ledger：保存关键事件记录，方便追溯流程推进过程
+- 归档保全元数据：确保归档前后能核对辅助目录是否完整保留
+
+这让长任务恢复、阶段审计和归档后追溯更稳定。
+
+## 快速开始
+
+### 环境要求
+
+- Node.js `>= 20.19.0`
+- 本机 `PATH` 上可用兼容官方 `@fission-ai/openspec` 的 CLI，版本 `>= 1.4.1`，并支持 SuperSpec 依赖的 OpenSpec native surface
+- 目标项目准备使用 OpenSpec + Codex 工作流入口
+
+执行 `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`。
+
+### 安装
+
+优先走 npm：
+
+```bash
+npm install -g @peterxiaoyang/superspec
+```
+
+
+如果你要固定到 GitHub release tarball，也可以：
+
+```bash
 npm install -g https://github.com/PeterYaoYang/SuperSpec/releases/download/v0.1.0/superspec-0.1.0.tgz
 ```
 
-这个发布包由 `npm pack` 生成，里面包含已经编译好的 `dist/*.js`。
-源码仓库本身不提交 `dist/`。
+### 初始化
 
-安装完成后初始化 SuperSpec：
+在项目目录里执行：
 
-```text
+```bash
+superspec init --scope project
+```
+
+如果你就在项目目录里直接运行下面这条，通常也够了：
+
+```bash
 superspec init
 ```
 
-`init` 会询问安装范围：当前项目（`project`）或 Codex 用户目录
-（`user`）。直接回车默认选择 `project`；非交互运行时也默认选择
-`project`。脚本里建议显式传入范围：
+如果你要装到用户级目录，而不是当前项目：
 
-```text
-superspec init --scope project
+```bash
 superspec init --scope user
 ```
 
-以后发布到 npm 公共仓库后，安装命令会变成：
+`superspec init` 会安装 SuperSpec 的工作流入口，并校验主路径需要的 OpenSpec Codex 入口。  
+如果项目里还没有对应的 OpenSpec 初始化内容，且本机可用 `openspec` CLI，SuperSpec 会自动尝试执行：
+
+- `openspec init --tools codex .`
+- 必要时再执行 `openspec update --force .`
+
+也就是说，普通使用场景下，你不需要先手动跑一遍 `openspec init`，直接运行 `superspec init` 就可以。
+
+## 用户可见的工作流入口
+
+SuperSpec 当前暴露的工作流入口是：
+
+- `superspec-explore`
+- `superspec-propose`
+- `superspec-apply`
+- `superspec-review`
+- `superspec-archive`
+
+## 安装后会落什么东西
+
+项目级安装时，SuperSpec 会把项目内入口写到 `.codex/`，把变更级运行数据写到 `.superspec/`。
+
+主要辅助目录内容包括：
+
+- `.superspec/artifacts/discovery.md`：记录现状调研、边界澄清和上游事实
+- `.superspec/artifacts/business-invariants.md`：记录本次变更必须守住的业务不变量
+- `.superspec/artifacts/test-contract.md`：记录测试覆盖矩阵、测试编号和约束映射
+- `.superspec/evidence/...`：保存测试、审查、验证、用户确认等证据文件
+- `.superspec/superspec-state.json`：保存 guard 重算后的状态摘要和指纹
+- `.superspec/ledger.jsonl`：保存关键流程事件，便于审计和追溯
+
+SuperSpec 支持：
+
+- `project` scope
+- `user` scope
+- 基于清单的 `update`
+- 基于清单的 `uninstall`
+
+## 设计原则
 
 ```text
-npm install -g @peterxiaoyang/superspec
+→ 叠加，不是替代
+→ 证据，不是感觉
+→ 审查，不是自我批准
+→ 保全，不是归档后失忆
+→ 更严格，但不过度做重
 ```
 
-不推荐普通使用者直接通过源码地址安装，例如
-`npm install -g github:PeterYaoYang/SuperSpec#main`。除非仓库提交了
-`dist/`，或者安装时的构建环境完全可控，否则应使用 GitHub 发布附件。
+## 致谢与灵感来源
+
+SuperSpec 的思路不是凭空长出来的。它明显受这些项目影响：
+
+- [OpenSpec](https://github.com/Fission-AI/OpenSpec)
+- [oh-my-codex](https://github.com/Yeachan-Heo/oh-my-codex)
+- [Superpowers](https://github.com/obra/superpowers)

package/dist/src/cli.js

@@ -8,13 +8,13 @@ export function main(argv = process.argv.slice(2)) {
             return argparseExit;
         args = parse_argv(argv);
         const [decision] = dispatch(args);
-        printDecision(decision);
+        printDecision(decision, { command: args.command });
         return decision.allowed ? 0 : 1;
     }
     catch (err) {
         const change = args?.change ?? "?";
         const errReason = err instanceof GuardError ? reason("guard_error", err.message) : reason("guard_internal_error", `${err.name}: ${err.message}`);
-        printDecision(block(change, "guard_error", [errReason]));
+        printDecision(block(change, "guard_error", [errReason]), { command: args?.command });
         return 2;
     }
 }

package/dist/src/cli_args.js

@@ -1,3 +1,4 @@
+import { command_zh } from "./i18n.js";
 const SIMPLE_COMMANDS = [
     "status",
     "recompute",
@@ -40,7 +41,11 @@ function rootUsage() {
     return `usage: superspec_guard [-h]\n                     {${COMMAND_LIST}}\n                     ...\n`;
 }
 function rootHelp() {
-    return `${rootUsage()}\nsuperspec Sync Guard (v1)\n\npositional arguments:\n  {${COMMAND_LIST}}\n\noptional arguments:\n  -h, --help            show this help message and exit\n`;
+    const commandLines = COMMANDS.map((command) => {
+        const zh = command_zh(command);
+        return `  ${command.padEnd(22, " ")} ${zh.label_zh} / ${zh.hint_zh}\n`;
+    }).join("");
+    return `${rootUsage()}\nSuperSpec 守护检查（v1）\n\n位置参数：\n  {${COMMAND_LIST}}\n\n命令：\n${commandLines}\n可选参数：\n  -h, --help            显示帮助并退出\n`;
 }
 function commandUsage(command) {
     const usageFlags = [
@@ -52,7 +57,8 @@ function commandUsage(command) {
     return `usage: superspec_guard ${command} ${usageFlags.join(" ")}\n`;
 }
 function commandHelp(command) {
-    const lines = [commandUsage(command), "\noptional arguments:\n", "  -h, --help           show this help message and exit\n"];
+    const zh = command_zh(command);
+    const lines = [commandUsage(command), `\n${zh.label_zh}：${zh.hint_zh}\n`, "\n可选参数：\n", "  -h, --help           显示帮助并退出\n"];
     for (const flag of requiredValueFlags(command)) {
         const metavariable = flag.slice(2).replace(/-/g, "_").toUpperCase();
         lines.push(`  ${flag} ${metavariable}\n`);
@@ -73,7 +79,7 @@ function missingRequiredFlags(command, args) {
 }
 export function emitArgparsePreamble(argv) {
     if (argv.length === 0) {
-        process.stderr.write(`${rootUsage()}superspec_guard: error: the following arguments are required: command\n`);
+        process.stderr.write(`${rootUsage()}superspec_guard：错误：缺少必填参数：command\n`);
         return 2;
     }
     const command = argv[0];
@@ -82,7 +88,7 @@ export function emitArgparsePreamble(argv) {
         return 0;
     }
     if (!COMMANDS.includes(command)) {
-        process.stderr.write(`${rootUsage()}superspec_guard: error: argument command: invalid choice: '${command}' (choose from ${COMMAND_CHOICES})\n`);
+        process.stderr.write(`${rootUsage()}superspec_guard：错误：命令无效：'${command}'；可选值：${COMMAND_CHOICES}\n`);
         return 2;
     }
     const args = argv.slice(1);
@@ -92,14 +98,14 @@ export function emitArgparsePreamble(argv) {
     }
     const missing = missingRequiredFlags(command, args);
     if (missing.length > 0) {
-        process.stderr.write(`${commandUsage(command)}superspec_guard ${command}: error: the following arguments are required: ${missing.join(", ")}\n`);
+        process.stderr.write(`${commandUsage(command)}superspec_guard ${command}：错误：缺少必填参数：${missing.join(", ")}\n`);
         return 2;
     }
     return null;
 }
 export function parse_argv(argv) {
     if (argv.length === 0)
-        throw new Error("missing command");
+        throw new Error("缺少命令");
     const command = argv[0];
     const args = argv.slice(1);
     const getValue = (flag) => {
@@ -110,33 +116,33 @@ export function parse_argv(argv) {
     };
     const change = getValue("--change");
     if (!change)
-        throw new Error("missing required --change");
+        throw new Error("缺少必填参数 --change");
     if (command === "init") {
         if (!hasFlag(args, "--create"))
-            throw new Error("missing required --create");
+            throw new Error("缺少必填参数 --create");
         return { command, change, create: true };
     }
     if (command === "check-artifact") {
         const artifact = getValue("--artifact");
         if (!artifact)
-            throw new Error("missing required --artifact");
+            throw new Error("缺少必填参数 --artifact");
         return { command, change, artifact };
     }
     if (command === "check-enter") {
         const gate = getValue("--gate");
         if (!gate)
-            throw new Error("missing required --gate");
+            throw new Error("缺少必填参数 --gate");
         return { command, change, gate };
     }
     if (command === "check-task-reopen" || command === "check-task-edit" || command === "check-task-complete") {
         const taskId = getValue("--task-id");
         if (!taskId)
-            throw new Error("missing required --task-id");
+            throw new Error("缺少必填参数 --task-id");
         return { command, change, task_id: taskId };
     }
     const simple = new Set(SIMPLE_COMMANDS);
     if (!simple.has(command))
-        throw new Error(`unknown command: ${command}`);
+        throw new Error(`未知命令：${command}`);
     return {
         command,
         change,

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

@@ -0,0 +1,21 @@
+export type ZhHint = {
+    label_zh: string;
+    hint_zh: string;
+};
+export type WorkflowTermHint = {
+    term: string;
+    label_zh: string;
+    hint_zh: string;
+};
+export declare function command_zh(command: string): ZhHint;
+export declare function gate_zh(gate: string): ZhHint;
+export declare function reason_zh(code: string): ZhHint;
+export declare function decision_zh(decision: string): string;
+export declare function translate_action_zh(action: string): string;
+export declare function reason_message_zh(code: string, rawMessage: string, refs?: string[]): string;
+export declare function trust_warning_zh(warning: string): string;
+export declare function action_status_zh(status: string): string;
+export declare function action_label_zh(action: string): string;
+export declare function action_detail_zh(detail: string): string;
+export declare function system_failure_zh(raw: string, fallback?: string): string;
+export declare function workflow_terms_zh_for(command: string | undefined, _gate: string, reasonCodes: string[]): WorkflowTermHint[];