@peterxiaoyang/superspec 0.1.2 → 0.1.3

package/README.md

@@ -2,196 +2,261 @@
 
 [![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)
+[![OpenSpec](https://img.shields.io/badge/OpenSpec-compatible-6f42c1?style=flat-square)](https://github.com/Fission-AI/OpenSpec)
 
-> 面向 Codex 的 OpenSpec 增强工作流约束层。
+> SuperSpec 是一套“先想清楚，再动手”的工作流。
 
-SuperSpec 是一个已经发布的 npm 包，适合已经认可 OpenSpec，但觉得默认流程在执行层还不够严格的团队。
+它解决的是一个很常见的问题：AI 编程工具写代码很快，但有时候还没搞清楚需求、现有代码和测试边界，就已经开始改文件了。
 
-它不替换 OpenSpec，也不改 OpenSpec 的工件关系。  
-它做的是在 OpenSpec 现有变更生命周期之上，再加一层更强的执行纪律：
+SuperSpec 会把一次需求变更拆成 5 步：
 
-- 先做现状调研，再谈设计是否站得住
-- 先明确业务不变量，再做实现
-- 先写清测试约束，再避免流于表面的测试
-- 先经过多角色审查，再允许宣布“完成”
-- 先确认归档保全完整，再真正归档
+```text
+探索需求 -> 写方案 -> 做实现 -> 做审查 -> 归档收尾
+```
 
-如果你只想用最原生、最轻量的 OpenSpec，而不想增加审查、测试、归档这些额外门禁，那你大概率不需要 SuperSpec。
+这样做的目的很简单：
 
-SuperSpec 的核心定位是：
+- 改代码前先弄清楚现状
+- 写实现前先有方案和任务
+- 任务完成前先有测试或验证记录
+- 宣布完成前先经过审查
+- 归档时保留关键过程记录
 
-- **保留 OpenSpec 作为主流程**
-- **把执行约束收敛成可复用的叠加层**
-- **让阶段推进依赖证据，而不是模型一句“done”**
+## 适合谁
 
-## 为什么会有 SuperSpec
+适合已经在用 AI 编程工具或命令行代理做项目开发，并希望流程更稳一点的团队或个人。
 
-很多团队在把 OpenSpec 和编码代理结合起来之后，真正出问题的地方往往不是“没有文档”，而是“有流程形状，但没有流程纪律”。
+如果你遇到过这些情况，SuperSpec 会有帮助：
 
-常见问题是：
+- 需求还没说清楚，AI 就开始写代码
+- 方案写得很粗，后面实现时靠猜
+- 测试只跑了命令，但没人说明它证明了什么
+- 代码写完后缺少真正的审查
+- 过几天想回看当时为什么这么改，却找不到过程记录
 
-- 设计文档在，但不够细，指导不了后续实现
-- 测试在，但没有证明真正重要的东西
-- 任务打勾了，但缺少强校验
-- 主线程自己写、自己审、自己宣布通过
-- 归档做了，但辅助证据已经散了
+如果你只是想让 AI 快速改一个很小的文件，且不需要完整方案、审查和记录，那 SuperSpec 可能会显得偏重。
 
-SuperSpec 解决的不是“再造一套 OpenSpec”，而是把这些执行层的薄弱点补上。
+## 和 OpenSpec 有什么区别
 
-## SuperSpec 增加了什么
+一句话区别：
 
-### 1. 更严格的 propose 阶段
+```text
+OpenSpec 管“这次要改什么”。
+SuperSpec 管“AI 应该怎样把这次改动做稳”。
+```
 
-SuperSpec 保留 OpenSpec 的原生四件套工件：
+更具体一点：
 
-- `proposal`
-- `specs`
-- `design`
-- `tasks`
+| 问题 | OpenSpec 主要负责 | SuperSpec 额外补上 |
+|---|---|---|
+| 这次变更是什么 | 方案、规格、设计、任务和归档 | 要求 AI 在写方案前先调查现状 |
+| 方案怎么写 | 提供标准的变更文档结构 | 要求方案前后有范围、风险、业务约束和测试思路 |
+| 代码怎么做 | 记录任务清单和完成状态 | 要求按任务实现，并留下测试或验证记录 |
+| 做完怎么算稳 | 可以校验规格和归档 | 增加代码审查、架构审查、反方审查和最终验证 |
+| 以后怎么追溯 | 保留 OpenSpec 的变更文档 | 额外保留探索、测试、审查和收尾记录 |
 
-同时补三类辅助产物：
+举个例子：
 
-- `discovery.md`：记录现状调研结果、已有行为、约束边界和需要先确认的问题
-- `business-invariants.md`：整理这次变更必须守住的业务不变量，避免实现时把关键业务语义改丢
-- `test-contract.md`：把测试覆盖范围、测试编号、约束映射和验证责任提前写清楚
+OpenSpec 会帮你记录“要增加登录功能、需要哪些规格、设计和任务”。
+SuperSpec 会进一步要求 AI 先看看现有登录/权限代码在哪里、哪些业务规则不能破坏、哪些场景必须测试、实现后要经过哪些审查，最后再归档。
 
-这样 `propose` 阶段就不只是“把文档写出来”，而是真正把设计、约束和测试责任提前收拢。
+所以 SuperSpec 不是 OpenSpec 的替代品。它更像是 OpenSpec 外面的一层执行纪律，专门约束 AI 编程工具不要跳过关键步骤。
 
-### 2. 显式的多角色审查分工
+## 快速开始
 
-SuperSpec 会安装这些项目内角色：
+### 1. 安装
 
-- `architect`
-- `critic`
-- `test-engineer`
-- `code-reviewer`
-- `verifier`
+```bash
+npm install -g @peterxiaoyang/superspec@latest
+```
 
-这意味着审查在 SuperSpec 里是一个正式阶段，不是实现完成后的附带动作。
+需要 Node.js `>= 20.19.0`。
 
-### 3. 基于证据的门禁
+### 2. 初始化当前项目
 
-SuperSpec 的 guard 会检查：
+进入你的项目根目录，然后运行：
 
-- 阶段进入条件
-- 任务修改 / 任务完成 条件
-- 审查完成 条件
-- 可归档条件与归档保全条件
+```bash
+superspec init --scope project
+```
 
-目标很直接：**阶段推进必须依赖证据，而不是靠模型自述。**
+这条命令的意思是：把 SuperSpec 当前可用的工作流入口安装到项目里。
 
-### 4. 更完整的辅助目录与归档保全
+Windows PowerShell 如果拦截 npm 的 `.ps1` 脚本，请改用：
 
-每个变更下都会有 `.superspec/` 辅助运行目录，用于保存：
+```powershell
+superspec.cmd init --scope project
+```
 
-- 辅助产物：补足 OpenSpec 原生工件之外的调研、约束和测试文档
-- 证据：保存 RED/GREEN、审查、验证、确认等过程证据
-- 审查输出：保存各角色的审查结果和主线程的汇总结论
-- 状态文件：保存当前 gate、指纹和阶段状态，便于恢复和重算
-- ledger：保存关键事件记录，方便追溯流程推进过程
-- 归档保全元数据：确保归档前后能核对辅助目录是否完整保留
+### 3. 按步骤使用
 
-这让长任务恢复、阶段审计和归档后追溯更稳定。
+在你使用的 AI 编程工具或 CLI 里，按下面的阶段入口推进。不同工具的触发方式可以不同，但入口名和顺序保持一致。
 
-## 快速开始
+开始时先探索需求：
+
+```text
+使用 superspec-explore，帮我梳理这个需求：……
+```
 
-### 环境要求
+探索完成后，写正式方案：
 
-- Node.js `>= 20.19.0`
-- 本机 `PATH` 上可用兼容官方 `@fission-ai/openspec` 的 CLI，版本 `>= 1.4.1`，并支持 SuperSpec 依赖的 OpenSpec native surface
-- 目标项目准备使用 OpenSpec + Codex 工作流入口
+```text
+使用 superspec-propose，把刚才的探索结果整理成方案。
+```
 
-执行 `superspec init` 时，无论选择 `project` 还是 `user` scope，如果未检测到 `openspec`、检测到 `openspec-chinese` 或其他不兼容变体，或版本低于 `1.4.1`，SuperSpec 都会自动尝试安装 / 升级官方 OpenSpec CLI；遇到全局 bin 被不兼容变体占用时会用覆盖模式重试。
+方案确认后，开始实现：
+
+```text
+使用 superspec-apply，按任务实现。
+```
 
-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`。
+实现完成后，审查：
 
-### 安装
+```text
+使用 superspec-review，检查实现、测试和风险。
+```
 
-优先走 npm：
+审查通过后，归档：
 
-```bash
-npm install -g @peterxiaoyang/superspec
+```text
+使用 superspec-archive，归档这个变更。
 ```
 
+## 五个入口分别做什么
 
-如果你要固定到 GitHub release tarball，也可以：
+| 入口 | 什么时候用 | 它会要求做什么 |
+|---|---|---|
+| `superspec-explore` | 需求刚开始时 | 读代码、查现状、整理范围和风险；这一步不改业务代码 |
+| `superspec-propose` | 需求已经清楚后 | 写正式方案、规格、设计和任务，并提前规划测试 |
+| `superspec-apply` | 方案通过后 | 按任务实现代码，记录测试或验证结果 |
+| `superspec-review` | 实现完成后 | 做代码审查、架构审查、反方审查和最终验证 |
+| `superspec-archive` | 审查通过后 | 用 OpenSpec 完成归档，并检查关键记录是否保留 |
 
-```bash
-npm install -g https://github.com/PeterYaoYang/SuperSpec/releases/download/v0.1.0/superspec-0.1.0.tgz
+你日常主要记住这五个入口就够了。
+
+## 它会多保存哪些记录
+
+SuperSpec 会在每次变更下面保存一些辅助记录，方便后续追溯。
+
+主要包括：
+
+- 探索记录：这次需求是什么、当前代码是什么情况、有哪些风险
+- 业务约束：哪些业务规则不能被改坏
+- 测试约定：哪些场景必须验证
+- 实现记录：每个任务怎么验证通过
+- 审查记录：谁检查了什么、发现了什么、最后为什么通过或退回
+
+这些记录默认放在：
+
+```text
+openspec/changes/<变更ID>/.superspec/
 ```
 
-### 初始化
+这里的 `<变更ID>` 就是一次需求变更的名字。
+
+`.superspec/` 要不要提交到 git，由你的团队决定。
+如果不提交，删掉后就没有 git 历史可以恢复。
+
+## 重要边界
+
+SuperSpec 能让流程更规范，但它不是安全锁。
+
+它能帮助你：
+
+- 减少 AI 还没想清楚就改代码的情况
+- 让测试、审查和用户确认留下记录
+- 在进入下一步前提醒缺少什么
+- 让一次变更之后更容易回看原因
+
+它不能保证：
 
-在项目目录里执行：
+- 阻止人手动绕过流程直接改文件
+- 阻止人删除过程记录
+- 阻止恶意伪造记录
+- 替代正式的安全审计、合规审计或法律证明
+
+也就是说，SuperSpec v1 是“流程纪律工具”，不是“强制安全系统”。
+
+## 常用命令
+
+查看当前 SuperSpec CLI 版本：
 
 ```bash
-superspec init --scope project
+superspec --version
 ```
 
-如果你就在项目目录里直接运行下面这条，通常也够了：
+安装到当前项目：
 
 ```bash
-superspec init
+superspec init --scope project
 ```
 
-如果你要装到用户级目录，而不是当前项目：
+更新当前项目里的 SuperSpec 入口：
 
 ```bash
-superspec init --scope user
+superspec update --scope project
 ```
 
-`superspec init` 会安装 SuperSpec 的工作流入口，并校验主路径需要的 OpenSpec Codex 入口。  
-如果项目里还没有对应的 OpenSpec 初始化内容，且本机可用 `openspec` CLI，SuperSpec 会自动尝试执行：
+这条命令会先通过 npm 更新全局 `@peterxiaoyang/superspec`，再用新版本更新当前项目里的入口文件。只想使用当前已安装包更新项目文件时，可以运行：
 
-- `openspec init --tools codex .`
-- 必要时再执行 `openspec update --force .`
+```bash
+superspec update --scope project --local-only
+```
 
-也就是说，普通使用场景下，你不需要先手动跑一遍 `openspec init`，直接运行 `superspec init` 就可以。
+卸载当前项目里的 SuperSpec 入口：
 
-## 用户可见的工作流入口
+```bash
+superspec uninstall --scope project
+```
 
-SuperSpec 当前暴露的工作流入口是：
+这些命令默认不会删除已经生成的 `.superspec/` 过程记录。
 
-- `superspec-explore`
-- `superspec-propose`
-- `superspec-apply`
-- `superspec-review`
-- `superspec-archive`
+诊断全局安装、PATH、OpenSpec 依赖和 npm bin 指向问题：
 
-## 安装后会落什么东西
+```bash
+superspec doctor
+```
 
-项目级安装时，SuperSpec 会把项目内入口写到 `.codex/`，把变更级运行数据写到 `.superspec/`。
+## 进阶信息
 
-主要辅助目录内容包括：
+以当前内置的 Codex 适配器为例，初始化后项目里会出现这些入口文件：
+
+```text
+.codex/
+  skills/superspec-explore/
+  skills/superspec-propose/
+  skills/superspec-apply/
+  skills/superspec-review/
+  skills/superspec-archive/
+```
 
-- `.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 内部还有一些检查命令，例如：
 
-SuperSpec 支持：
+```bash
+superspec guard check-init --change <变更ID>
+superspec guard check-apply-ready --change <变更ID>
+superspec guard check-review-ready --change <变更ID>
+superspec guard check-archive-ready --change <变更ID>
+```
 
-- `project` scope
-- `user` scope
-- 基于清单的 `update`
-- 基于清单的 `uninstall`
+普通使用者通常不需要手动运行这些命令；对应的阶段入口会在需要时使用它们。
 
-## 设计原则
+如果你要开发 SuperSpec 本身：
 
-```text
-→ 叠加，不是替代
-→ 证据，不是感觉
-→ 审查，不是自我批准
-→ 保全，不是归档后失忆
-→ 更严格，但不过度做重
+```bash
+npm run build
+npm run typecheck
+npm test
+npm run pack:dry-run
 ```
 
-## 致谢与灵感来源
+更多细节见：
+
+- `docs/SPEC.md`：完整设计和规则
+- `docs/DISTRIBUTION.md`：安装、升级、卸载和分发说明
+- `.codex/skills/superspec-*/SKILL.md`：当前 Codex 适配器使用的阶段入口说明
 
-SuperSpec 的思路不是凭空长出来的。它明显受这些项目影响：
+## 致谢与灵感来源
 
 - [OpenSpec](https://github.com/Fission-AI/OpenSpec)
 - [oh-my-codex](https://github.com/Yeachan-Heo/oh-my-codex)

package/dist/src/core.js

@@ -16,12 +16,12 @@ import { relative } from "node:path";
 import { GuardError, allow, block, deepEqual, reason, runtime, toPosix, trustWarnings } from "./util.js";
 import { artifact_status_map, gate_route_phase, get_change_root, get_repo_root, openspec_status, openspec_status_shape_reasons, openspec_validate, openspec_version, repo_root_from_cwd, } from "./openspec.js";
 import { config_file, load_config, project_config_file } from "./paths.js";
-import { index_evidence, live_pass } from "./evidence.js";
+import { index_evidence, live_user_confirmations } from "./evidence.js";
 import { tasks_structure_hash } from "./tasks.js";
 import { dirty_worktree_paths, dirty_worktree_reasons, dirty_write_scope_red_reasons, file_blob_sha, git_lines, review_diff_coverage_reasons, review_diff_paths, } from "./git.js";
 import { append_ledger, load_state, compute_fingerprints, prepare_recomputed_state_write, read_ledger_text, record_supersede_ledger_events, restore_state_snapshot_locked, state_corrupt_reasons, state_file, state_file_corrupt, state_stale_reasons, force_unlock_state, with_state_lock, write_prepared_state_locked, } from "./state.js";
 import { archive_manifest_path, begin_archive_preservation_bundle, check_archived, preset_upgrade_reasons, preset_upgrade_required_from_context, write_archive_preservation_bundle, } from "./archive.js";
-import { check_archive_ready, check_artifact, check_init, check_superspec_gate, check_review_complete, check_review_ready, check_task_complete, check_task_edit, check_task_reopen, check_verify_complete, evidence_schema_guard, superspec_agent_reasons, superspec_workflow_skill_reasons, openspec_cli_capability_reasons, openspec_init_reasons, } from "./gates.js";
+import { check_archive_ready, check_apply_ready, check_artifact, check_init, check_superspec_gate, check_review_complete, check_review_ready, check_task_complete, check_task_edit, check_task_reopen, check_verify_complete, evidence_schema_guard, superspec_agent_reasons, superspec_workflow_skill_reasons, openspec_cli_capability_reasons, openspec_init_reasons, } from "./gates.js";
 const RETRY_WAIT = new Int32Array(new SharedArrayBuffer(4));
 const DEFAULT_MAX_STATE_WRITE_RETRIES = 5;
 function sleep_ms(ms) {
@@ -134,7 +134,7 @@ function dispatch_once(args) {
     if (cmd !== "recompute") {
         const changedPaths = String(config.preset ?? "full") !== "full" ? runtime.dirty_worktree_paths(repoRoot) : [];
         presetRequired = preset_upgrade_required_from_context(config, changedPaths);
-        const presetHumanConfirmed = live_pass(evidences, { gate: "preset_upgrade", kind: "human_confirmation" }).length > 0;
+        const presetHumanConfirmed = live_user_confirmations(evidences, "preset_upgrade").length > 0;
         presetProblems = preset_upgrade_reasons(config, changedPaths, presetHumanConfirmed);
         if (cmd !== "init")
             staleProblems = state_stale_reasons(changeRoot, status);
@@ -171,7 +171,7 @@ function dispatch_once(args) {
         route = gate_route_phase(args.gate ?? "");
     }
     else if (cmd === "check-apply-ready") {
-        dec = check_superspec_gate(change, status, changeRoot, evidences, "propose_complete");
+        dec = check_apply_ready(change, status, changeRoot, evidences);
         route = "propose";
     }
     else if (cmd === "check-task-edit") {
@@ -230,7 +230,7 @@ function dispatch_once(args) {
             const lockedShapeProblems = openspec_status_shape_reasons(lockedStatus);
             const lockedChangedPaths = String(lockedConfig.preset ?? "full") !== "full" ? runtime.dirty_worktree_paths(lockedRepoRoot) : [];
             const lockedPresetRequired = preset_upgrade_required_from_context(lockedConfig, lockedChangedPaths);
-            const lockedPresetHumanConfirmed = live_pass(lockedEvidences, { gate: "preset_upgrade", kind: "human_confirmation" }).length > 0;
+            const lockedPresetHumanConfirmed = live_user_confirmations(lockedEvidences, "preset_upgrade").length > 0;
             const lockedPresetProblems = preset_upgrade_reasons(lockedConfig, lockedChangedPaths, lockedPresetHumanConfirmed);
             const lockedStaleProblems = state_stale_reasons(lockedChangeRoot, lockedStatus);
             const lockedCorruptProblems = state_corrupt_reasons(lockedChangeRoot);

package/dist/src/doctor.d.ts

@@ -0,0 +1,44 @@
+import { type JsonMap } from "./util.ts";
+type RunResult = {
+    status: number | null;
+    stdout: string;
+    stderr: string;
+    error?: Error;
+};
+type RunFn = (cmd: string, args: string[], opts?: {
+    cwd?: string;
+    timeout?: number;
+    platform?: NodeJS.Platform;
+}) => RunResult;
+type CommandExistsFn = (cmd: string, meta?: {
+    cwd?: string;
+}) => boolean;
+type CheckStatus = "ok" | "warn" | "fail";
+export type DoctorCheck = {
+    status: CheckStatus;
+    name: string;
+    detail: string;
+    refs?: string[];
+};
+export type DoctorReport = {
+    ok: boolean;
+    cwd: string;
+    superspec: JsonMap;
+    node: JsonMap;
+    npm: JsonMap;
+    openspec: JsonMap;
+    checks: DoctorCheck[];
+    next_actions: string[];
+};
+export declare function superspec_package_version(packageRoot?: string): string;
+export declare function build_doctor_report(opts?: {
+    cwd?: string;
+    packageRoot?: string;
+    argv0?: string;
+    platform?: NodeJS.Platform;
+    commandExistsFn?: CommandExistsFn;
+    run?: RunFn;
+}): DoctorReport;
+export declare function render_doctor_report(report: DoctorReport): string;
+export declare function main_doctor(argv?: string[]): number;
+export {};

package/dist/src/doctor.js

@@ -0,0 +1,230 @@
+import { existsSync, lstatSync, readFileSync, readlinkSync, realpathSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { PACKAGE_ROOT } from "./install_engine.js";
+import { openspec_cli_probe } from "./openspec.js";
+import { commandExists, runCommand } from "./util.js";
+function readPackageJson(packageRoot) {
+    try {
+        const parsed = JSON.parse(readFileSync(join(packageRoot, "package.json"), "utf8"));
+        return parsed && typeof parsed === "object" ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+export function superspec_package_version(packageRoot = PACKAGE_ROOT) {
+    const version = readPackageJson(packageRoot).version;
+    return typeof version === "string" && version ? version : "0.0.0";
+}
+function realpathMaybe(filePath) {
+    try {
+        return realpathSync(filePath);
+    }
+    catch {
+        return resolve(filePath);
+    }
+}
+function pathInfo(filePath) {
+    if (!filePath)
+        return null;
+    const info = { path: filePath, exists: existsSync(filePath) };
+    if (!info.exists)
+        return info;
+    try {
+        const stat = lstatSync(filePath);
+        info.kind = stat.isSymbolicLink() ? "symlink" : stat.isDirectory() ? "directory" : stat.isFile() ? "file" : "other";
+        if (stat.isSymbolicLink())
+            info.link_target = readlinkSync(filePath);
+        info.realpath = realpathMaybe(filePath);
+    }
+    catch (err) {
+        info.error = err.message;
+    }
+    return info;
+}
+function firstNonEmptyLine(text) {
+    return text.split(/\r?\n/u).map((line) => line.trim()).find((line) => line.length > 0) ?? null;
+}
+function commandPath(cmd, opts) {
+    if (!opts.commandExistsFn(cmd, { cwd: opts.cwd }))
+        return null;
+    const proc = opts.platform === "win32"
+        ? opts.run("where.exe", [cmd], { cwd: opts.cwd, timeout: 15_000, platform: opts.platform })
+        : opts.run("sh", ["-c", `command -v ${cmd}`], { cwd: opts.cwd, timeout: 15_000, platform: opts.platform });
+    if (proc.error || proc.status !== 0)
+        return null;
+    return firstNonEmptyLine(proc.stdout);
+}
+function npmValue(args, opts) {
+    if (!opts.commandExistsFn("npm", { cwd: opts.cwd }))
+        return { available: false, value: null, error: "npm not found on PATH" };
+    const proc = opts.run("npm", args, { cwd: opts.cwd, timeout: 15_000, platform: opts.platform });
+    if (proc.error || proc.status !== 0) {
+        return {
+            available: true,
+            value: null,
+            error: (proc.error?.message ?? (proc.stderr || proc.stdout)).trim(),
+        };
+    }
+    return { available: true, value: firstNonEmptyLine(proc.stdout), error: null };
+}
+function containsUnscopedSuperspecNodeModule(value) {
+    if (!value)
+        return false;
+    return /[/\\]node_modules[/\\]superspec[/\\]/u.test(value);
+}
+function add(checks, status, name, detail, refs) {
+    checks.push({ status, name, detail, refs });
+}
+export function build_doctor_report(opts = {}) {
+    const cwd = resolve(opts.cwd ?? process.cwd());
+    const packageRoot = opts.packageRoot ?? PACKAGE_ROOT;
+    const platform = opts.platform ?? process.platform;
+    const run = opts.run ?? runCommand;
+    const commandExistsFn = opts.commandExistsFn ?? ((cmd, meta) => commandExists(cmd, { cwd: meta?.cwd, platform }));
+    const packageJson = readPackageJson(packageRoot);
+    const version = superspec_package_version(packageRoot);
+    const packageName = typeof packageJson.name === "string" ? packageJson.name : "unknown";
+    const expectedBin = join(packageRoot, "bin", "superspec.js");
+    const resolvedCommand = commandPath("superspec", { cwd, platform, commandExistsFn, run });
+    const command = pathInfo(resolvedCommand);
+    const prefix = npmValue(["prefix", "-g"], { cwd, platform, commandExistsFn, run });
+    const root = npmValue(["root", "-g"], { cwd, platform, commandExistsFn, run });
+    const npmRoot = typeof root.value === "string" ? root.value : null;
+    const scopedPackage = npmRoot ? pathInfo(join(npmRoot, "@peterxiaoyang", "superspec")) : null;
+    const unscopedPackage = npmRoot ? pathInfo(join(npmRoot, "superspec")) : null;
+    const openspecProbe = openspec_cli_probe({ cwd, commandExistsFn, run });
+    const checks = [];
+    const nextActions = [];
+    if (packageName === "@peterxiaoyang/superspec" && version !== "0.0.0") {
+        add(checks, "ok", "package metadata", `${packageName}@${version}`);
+    }
+    else {
+        add(checks, "fail", "package metadata", `could not identify @peterxiaoyang/superspec package metadata under ${packageRoot}`);
+    }
+    if (openspecProbe.ok) {
+        add(checks, "ok", "OpenSpec CLI", openspecProbe.message);
+    }
+    else {
+        add(checks, "fail", "OpenSpec CLI", openspecProbe.message);
+        nextActions.push("npm install -g @fission-ai/openspec@latest");
+    }
+    if (!command) {
+        add(checks, "warn", "superspec command", "`superspec` is not resolvable from PATH in this shell");
+    }
+    else {
+        const commandRealpath = typeof command.realpath === "string" ? command.realpath : undefined;
+        const commandTarget = typeof command.link_target === "string" ? command.link_target : undefined;
+        if (containsUnscopedSuperspecNodeModule(commandRealpath) || containsUnscopedSuperspecNodeModule(commandTarget)) {
+            add(checks, "fail", "superspec command owner", "`superspec` points at the unscoped `superspec` package, which conflicts with @peterxiaoyang/superspec", [String(command.path)]);
+            nextActions.push("npm uninstall -g superspec");
+            nextActions.push("npm install -g @peterxiaoyang/superspec@latest");
+        }
+        else if (existsSync(expectedBin) && commandRealpath && realpathMaybe(expectedBin) !== commandRealpath) {
+            add(checks, "warn", "superspec command owner", "`superspec` on PATH does not point at this package root", [String(command.path), expectedBin]);
+        }
+        else {
+            add(checks, "ok", "superspec command owner", "`superspec` resolves to this package");
+        }
+    }
+    if (root.error) {
+        add(checks, "warn", "npm global root", String(root.error));
+    }
+    else if (npmRoot) {
+        add(checks, "ok", "npm global root", npmRoot);
+    }
+    if (unscopedPackage?.exists) {
+        add(checks, "warn", "unscoped superspec package", "global package `superspec` is installed and can claim the same `superspec` binary", [String(unscopedPackage.path)]);
+        nextActions.push("npm uninstall -g superspec");
+    }
+    if (scopedPackage && !scopedPackage.exists) {
+        add(checks, "warn", "scoped superspec package", "@peterxiaoyang/superspec is not present under npm global root", [String(scopedPackage.path)]);
+    }
+    const dedupedNextActions = [...new Set(nextActions)];
+    return {
+        ok: !checks.some((check) => check.status === "fail"),
+        cwd,
+        superspec: {
+            name: packageName,
+            version,
+            package_root: packageRoot,
+            expected_bin: expectedBin,
+            entry: opts.argv0 ?? process.argv[1] ?? null,
+            command,
+            scoped_global_package: scopedPackage,
+            unscoped_global_package: unscopedPackage,
+        },
+        node: {
+            version: process.versions.node,
+            exec_path: process.execPath,
+            platform,
+        },
+        npm: {
+            prefix,
+            root,
+        },
+        openspec: {
+            ok: openspecProbe.ok,
+            state: openspecProbe.state,
+            version: openspecProbe.version,
+            message: openspecProbe.message,
+        },
+        checks,
+        next_actions: dedupedNextActions,
+    };
+}
+export function render_doctor_report(report) {
+    const lines = [
+        "SuperSpec doctor",
+        "",
+        `SuperSpec: ${report.superspec.name}@${report.superspec.version}`,
+        `Package root: ${report.superspec.package_root}`,
+        `Command path: ${report.superspec.command?.path ?? "not found"}`,
+        `OpenSpec: ${report.openspec.message}`,
+        `Node: ${report.node.version} (${report.node.platform})`,
+        `npm prefix: ${report.npm.prefix.value ?? "unknown"}`,
+        `npm root: ${report.npm.root.value ?? "unknown"}`,
+        "",
+        "Checks:",
+        ...report.checks.map((check) => {
+            const refs = check.refs && check.refs.length > 0 ? ` (${check.refs.join(", ")})` : "";
+            return `  [${check.status}] ${check.name}: ${check.detail}${refs}`;
+        }),
+    ];
+    if (report.next_actions.length > 0) {
+        lines.push("", "Next actions:", ...report.next_actions.map((action) => `  ${action}`));
+    }
+    lines.push("");
+    return lines.join("\n");
+}
+function doctorHelp() {
+    return [
+        "usage: superspec doctor [--json]",
+        "",
+        "diagnoses SuperSpec, OpenSpec, npm global package, and PATH wiring.",
+        "",
+        "options:",
+        "  --json      print machine-readable JSON",
+        "  -h, --help  show this help",
+        "",
+    ].join("\n");
+}
+export function main_doctor(argv = process.argv.slice(2)) {
+    if (argv.includes("-h") || argv.includes("--help")) {
+        process.stdout.write(doctorHelp());
+        return 0;
+    }
+    const unknown = argv.filter((arg) => arg !== "--json");
+    if (unknown.length > 0) {
+        process.stderr.write(`superspec doctor: unknown option ${JSON.stringify(unknown[0])}\n\n${doctorHelp()}`);
+        return 2;
+    }
+    const report = build_doctor_report();
+    if (argv.includes("--json")) {
+        process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+    }
+    else {
+        process.stdout.write(render_doctor_report(report));
+    }
+    return report.ok ? 0 : 1;
+}

package/dist/src/evidence.d.ts

@@ -26,3 +26,4 @@ export declare function live_pass(evidences: JsonMap[], filters?: {
     kind?: string | null;
     task_id?: string | null;
 }): JsonMap[];
+export declare function live_user_confirmations(evidences: JsonMap[], gate: string): JsonMap[];

package/dist/src/evidence.js

@@ -272,6 +272,9 @@ function finding_string_list_reasons(ev, finding, field, opts = {}) {
 function human_confirmation_reasons(ev) {
     const problems = [];
     const gate = normalize_gate(String(ev.gate ?? ""));
+    if (String(ev.created_by ?? "") !== "user") {
+        problems.push(reason("human_confirmation_invalid", `${ev._path}: human_confirmation must be created_by user`));
+    }
     if (!HUMAN_CONFIRMATION_GATES.has(gate)) {
         problems.push(reason("human_confirmation_invalid", `${ev._path}: human_confirmation gate=${repr(ev.gate)} is not consumed by any guard gate; expected one of ${renderList([...HUMAN_CONFIRMATION_GATES].sort())}`));
     }
@@ -847,3 +850,7 @@ export function live_pass(evidences, filters = {}) {
     const dead = superseded_ids(evidences);
     return find_pass(evidences, filters).filter((ev) => !dead.has(ev.evidence_id));
 }
+export function live_user_confirmations(evidences, gate) {
+    return live_pass(evidences, { gate, kind: "human_confirmation" })
+        .filter((ev) => String(ev.created_by ?? "") === "user");
+}

package/dist/src/gates.d.ts

@@ -8,6 +8,7 @@ export declare function check_init(change: string, status: JsonMap, repoRoot: st
 export declare function check_superspec_gate(change: string, status: JsonMap, changeRoot: string, evidences: JsonMap[], gateRaw: string): Decision;
 export declare function check_artifact(change: string, status: JsonMap, changeRoot: string, evidences: JsonMap[], artifact: string): Decision;
 export declare function check_task_reopen(change: string, status: JsonMap, changeRoot: string, evidences: JsonMap[], taskId: string): Decision;
+export declare function check_apply_ready(change: string, status: JsonMap, changeRoot: string, evidences: JsonMap[]): Decision;
 export declare function check_task_edit(change: string, status: JsonMap, changeRoot: string, evidences: JsonMap[], taskId: string): Decision;
 export declare function check_task_complete(change: string, status: JsonMap, changeRoot: string, evidences: JsonMap[], taskId: string): Decision;
 export declare function check_review_ready(change: string, status: JsonMap, changeRoot: string, evidences: JsonMap[]): Decision;

package/dist/src/gates.js

@@ -5,7 +5,7 @@ import { all_done, artifact_status_map, get_repo_root, is_done, normalize_gate,
 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";
-import { duplicate_evidence_id_reasons, dangling_evidence_ref_reasons, final_verification_evidences, live_task_reopens, live_task_reopen_resolutions, live_pass, pass_task_reopens, supersede_reasons, unresolved_live_task_reopens, validate_evidence_schema, verify_reference_reasons, } from "./evidence.js";
+import { duplicate_evidence_id_reasons, dangling_evidence_ref_reasons, final_verification_evidences, live_task_reopens, live_task_reopen_resolutions, live_pass, live_user_confirmations, pass_task_reopens, supersede_reasons, unresolved_live_task_reopens, validate_evidence_schema, verify_reference_reasons, } from "./evidence.js";
 import { review_disclosure_reasons } from "./disclosure.js";
 import { archive_manifest_path } from "./archive.js";
 function action_list(...items) {
@@ -311,7 +311,7 @@ function archive_ready_actions(change, reasons, review) {
 function default_gate_next_actions(gate) {
     switch (gate) {
         case "explore_complete":
-            return ["write .superspec/artifacts/discovery.md and record native_subagent critic evidence"];
+            return ["write .superspec/artifacts/discovery.md, record native_subagent critic evidence, and record explore_complete human confirmation"];
         case "proposal_reviewed":
             return ["run the proposal critic review (round-tagged, findings[]) and record a main_review_digest disclosing every finding"];
         case "design_complete":
@@ -478,6 +478,9 @@ export function check_superspec_gate(change, status, changeRoot, evidences, gate
                 reasons.push(reason("missing_native_subagent_evidence", `explore_complete requires native_subagent ${role} report`));
         }
         reasons.push(...stale_artifact_review_reasons(exploreReviews, changeRoot, ".superspec/artifacts/discovery.md", "stale_explore_review", "explore_complete"));
+        if (live_user_confirmations(evidences, "explore_complete").length === 0) {
+            reasons.push(reason("missing_human_confirmation", "explore_complete requires human confirmation before entering propose"));
+        }
         // DISC Phase 1: material findings raised by explore reviews must be disclosed to the user
         // (main_review_digest + user_review_decision) before the gate can pass.
         reasons.push(...review_disclosure_reasons("explore_complete", changeRoot, evidences));
@@ -510,7 +513,7 @@ export function check_superspec_gate(change, status, changeRoot, evidences, gate
             if (!designReviews.some((ev) => ev.agent_role === role))
                 reasons.push(reason(`missing_${role}_review`, `design_complete requires native_subagent ${role} report`));
         }
-        if (live_pass(evidences, { kind: "human_confirmation", gate: "design_complete" }).length === 0)
+        if (live_user_confirmations(evidences, "design_complete").length === 0)
             reasons.push(reason("missing_human_confirmation", "design_complete requires human confirmation"));
         reasons.push(...stale_artifact_review_reasons(designReviews, changeRoot, "design.md", "stale_design_review", "design_complete"));
         // DISC Phase 2: design reviews carrying round-tagged findings enter the disclosure loop
@@ -536,7 +539,7 @@ export function check_superspec_gate(change, status, changeRoot, evidences, gate
         const humanRequired = human_confirmation_business_invariant_ids(changeRoot);
         if (humanRequired.size > 0) {
             const confirmed = new Set();
-            for (const ev of live_pass(evidences, { gate: "invariants_reviewed", kind: "human_confirmation" })) {
+            for (const ev of live_user_confirmations(evidences, "invariants_reviewed")) {
                 for (const id of evidence_invariant_refs(ev))
                     confirmed.add(id);
             }
@@ -654,6 +657,9 @@ export function check_superspec_gate(change, status, changeRoot, evidences, gate
             }
         }
     }
+    else if (gate === "apply_ready") {
+        return check_apply_ready(change, status, changeRoot, evidences);
+    }
     else {
         return block(change, gate, [reason("unknown_gate", `unknown superspec gate: ${gate}`)]);
     }
@@ -1029,6 +1035,7 @@ export function check_task_reopen(change, status, changeRoot, evidences, taskId)
         reasons.push(reason("propose_not_complete", "task_reopen requires propose_complete"));
         reasons.push(...propose.block_reasons);
     }
+    reasons.push(...apply_scope_confirmation_reasons(changeRoot, evidences));
     const tasks = parse_tasks(changeRoot);
     const task = tasks[taskId];
     if (!task)
@@ -1038,8 +1045,13 @@ export function check_task_reopen(change, status, changeRoot, evidences, taskId)
     reasons.push(...request_changes_round_reasons(evidences));
     const reopenCheck = active_task_reopen_reasons(changeRoot, evidences, task, taskId, "pre_revert");
     reasons.push(...reopenCheck.reasons);
-    if (reasons.length > 0)
-        return block(change, gate, reasons, { task_id: taskId, next_actions: [`keep ${taskId} checked, fix task_reopen evidence / supersedes, then rerun check-task-reopen`] });
+    if (reasons.length > 0) {
+        const reasonSet = reason_codes(reasons);
+        return block(change, gate, reasons, {
+            task_id: taskId,
+            next_actions: action_list(reasonSet.has("apply_isolation_unconfirmed") ? "AskUserQuestion for apply isolation/execution mode and record gate=\"apply_isolation\" human_confirmation" : null, reasonSet.has("scope_expansion_unconfirmed") ? "stop: redesign/split the change or record gate=\"scope_expansion\" human_confirmation re-approving tasks.md structure" : null, `keep ${taskId} checked, fix task_reopen evidence / supersedes, then rerun check-task-reopen`),
+        });
+    }
     return allow(change, gate, { task_id: taskId });
 }
 // FIX-8 (audit A-5): apply work requires the user's explicit isolation/execution-mode choice,
@@ -1048,7 +1060,7 @@ export function check_task_reopen(change, status, changeRoot, evidences, taskId)
 // apply-phase scope expansion (SPEC §14.7) and demands explicit user re-approval — redesign,
 // split into a new change, or record a scope_expansion confirmation re-pinning the structure.
 function apply_scope_confirmation_reasons(changeRoot, evidences) {
-    const isolation = live_pass(evidences, { gate: "apply_isolation", kind: "human_confirmation" });
+    const isolation = live_user_confirmations(evidences, "apply_isolation");
     const currentHash = tasks_structure_hash(changeRoot);
     if (isolation.length === 0) {
         const hashHint = currentHash ? ` with tasks_structure_hash=${currentHash}` : "";
@@ -1056,11 +1068,28 @@ function apply_scope_confirmation_reasons(changeRoot, evidences) {
     }
     if (currentHash === null)
         return [];
-    const approvals = [...isolation, ...live_pass(evidences, { gate: "scope_expansion", kind: "human_confirmation" })];
+    const approvals = [...isolation, ...live_user_confirmations(evidences, "scope_expansion")];
     if (approvals.some((ev) => String(ev.tasks_structure_hash ?? "") === currentHash))
         return [];
     return [reason("scope_expansion_unconfirmed", `tasks.md structure changed after the last user-approved apply scope; ask the user to redesign/split the change or re-approve by recording gate="scope_expansion" human_confirmation with tasks_structure_hash=${currentHash}`)];
 }
+export function check_apply_ready(change, status, changeRoot, evidences) {
+    const gate = "apply_ready";
+    const reasons = [];
+    const propose = check_superspec_gate(change, status, changeRoot, evidences, "propose_complete");
+    if (!propose.allowed) {
+        reasons.push(reason("propose_not_complete", "apply_ready requires propose_complete"));
+        reasons.push(...propose.block_reasons);
+    }
+    reasons.push(...apply_scope_confirmation_reasons(changeRoot, evidences));
+    if (reasons.length > 0) {
+        const reasonSet = reason_codes(reasons);
+        return block(change, gate, reasons, {
+            next_actions: action_list(!propose.allowed ? "pass propose_complete before apply" : null, reasonSet.has("apply_isolation_unconfirmed") ? "AskUserQuestion for apply isolation/execution mode and record gate=\"apply_isolation\" human_confirmation" : null, reasonSet.has("scope_expansion_unconfirmed") ? "stop: redesign/split the change or record gate=\"scope_expansion\" human_confirmation re-approving tasks.md structure" : null),
+        });
+    }
+    return allow(change, gate, { openspec_summary: artifact_status_map(status) });
+}
 export function check_task_edit(change, status, changeRoot, evidences, taskId) {
     const gate = "task_edit";
     const reasons = [];
@@ -1378,7 +1407,7 @@ export function check_review_complete(change, status, changeRoot, evidences) {
         && (ev.kind === "verification_review" || ev.kind === "final_test")
         && ev.status === "fail");
     if (failedVerifications.length > 0) {
-        const dispositions = new Set(live_pass(evidences, { gate: "verify_failure_handling", kind: "human_confirmation" })
+        const dispositions = new Set(live_user_confirmations(evidences, "verify_failure_handling")
             .flatMap((ev) => (Array.isArray(ev.confirmed_refs) ? ev.confirmed_refs.map((item) => String(item)) : [])));
         const unhandled = failedVerifications
             .map((ev) => String(ev.evidence_id ?? ev._path ?? "unknown"))
@@ -1456,7 +1485,7 @@ export function check_archive_ready(change, status, changeRoot, evidences) {
     if (!ok && !reviewCodes.has("validate_failed")) {
         reasons.push(reason("validate_failed", "openspec validate did not pass"));
     }
-    if (live_pass(evidences, { gate: "archive_ready", kind: "human_confirmation" }).length === 0) {
+    if (live_user_confirmations(evidences, "archive_ready").length === 0) {
         reasons.push(reason("missing_final_confirmation", "archive_ready requires human confirmation evidence"));
     }
     if (reasons.length > 0)

package/dist/src/git.js

@@ -2,7 +2,7 @@ import { existsSync, statSync } from "node:fs";
 import { dirname, isAbsolute, relative } from "node:path";
 import { GuardError, reason, renderList, runCommand, runtime } from "./util.js";
 import { splitList, task_test_evidence } from "./tasks.js";
-import { live_pass } from "./evidence.js";
+import { live_user_confirmations } from "./evidence.js";
 export function file_blob_sha(filePath) {
     if (!existsSync(filePath) || !statSync(filePath).isFile())
         throw new GuardError(`git_blob_inspection_failure: reviewed target missing: ${filePath}`);
@@ -50,7 +50,7 @@ export function dirty_worktree_reasons(repoRoot, changeRoot, evidences) {
     const unknown = dirty.filter((item) => !(changeRel && item.startsWith(`${changeRel}/`)));
     if (unknown.length === 0)
         return [];
-    const confirmations = live_pass(evidences, { gate: "branch_handling", kind: "human_confirmation" });
+    const confirmations = live_user_confirmations(evidences, "branch_handling");
     const confirmedScopes = confirmations.flatMap((ev) => (Array.isArray(ev.confirmed_paths) ? ev.confirmed_paths.map((item) => String(item)).filter(Boolean) : []));
     const unconfirmed = unknown.filter((item) => !confirmedScopes.some((scope) => pathInScope(item, scope)));
     if (unconfirmed.length === 0)

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.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",

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.2",
+  "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/skills/superspec-apply/SKILL.md

@@ -23,6 +23,14 @@ metadata:
 - Windows PowerShell 中执行 npm 全局 bin 时，必须显式使用 `.cmd` shim：`superspec.cmd ...`、`openspec.cmd ...`；不要运行 `superspec.ps1` 或 `openspec.ps1`。
 - macOS、Linux、Git Bash、cmd.exe 或其他不会优先拦截 `.ps1` 的 shell 中，继续使用文档中的 `superspec ...`、`openspec ...` 命令。
 
+## 上下文读取纪律 / Context Budget
+
+- guard 可以在本地读取完整 `.superspec/evidence/**/*.json` 并重算判定；主流程默认不要打开完整 evidence JSON，除非正在排查 guard block、修复 schema，或用户明确要求诊断原文。
+- 主流程默认只读取 guard decision、当前 task 必要 artifact、OpenSpec instructions apply 返回的 `contextFiles`、native subagent `output_ref` 的摘要/结论段，以及 task RED/GREEN 所需的最小测试摘要。
+- raw log、长报告和历史 superseded evidence 默认只作为引用、hash 或摘要保留；不要把全文复制进对话上下文或新的 evidence。
+- RED/GREEN 仍按 task 的 `test_refs` 记录 gate-driving evidence；同一次命令输出可以作为共享 raw log 被引用，但不要仅凭聚合日志替代每个 task/test 所需的 RED/GREEN 证据字段。
+- 使用按运行合并建档的 `test_ids[]` 清单时，每个 claimed id 都必须出现在引用的 raw log 中；若当前 task gate 需要单个 `test_id` 覆盖，仍要补齐对应 gate-driving evidence。
+
 在 propose package 完成后使用本 skill 执行实现任务。**Task context、ordering 和 progress 来自 OpenSpec native apply instructions**（`openspec instructions apply`）；SuperSpec 为每个 task 包上一层 RED/GREEN guard checks。
 
 ## 边界 / Boundaries
@@ -41,7 +49,7 @@ metadata:
 
 ## 步骤 / Steps
 
-1. 对实现隔离（apply isolation）和执行模式（execution mode）使用 AskUserQuestion，并等待明确选择。
+1. 对实现隔离（apply isolation）和执行模式（execution mode）使用 AskUserQuestion，并等待明确选择；记录 `gate:"apply_isolation"` 的 `human_confirmation` evidence，必须包含 `confirmation_text`、`confirmed_refs` 和当前 `tasks_structure_hash`。
 2. 当 dirty worktree、untracked files 或 branch state 需要确认时，使用 AskUserQuestion 处理分支状态。
 3. 验证 apply readiness：
    ```text
@@ -68,7 +76,7 @@ metadata:
    ```
 7. 在 runtime/business implementation edits 前产出 RED evidence，除非有允许的 `no_tdd_reason` 或处于现状锁定测试模式（`characterization mode`）。这里的 `characterization` 指“先把当前真实行为测出来并锁住，重构后保持一致”。RED/GREEN evidence 必须引用 task 的 `test_refs`，并在 task 声明 `invariant_refs` 时同步记录 `invariant_refs`。若 task 来自 reopen，本轮 successor GREEN / alternative verification / manual verification 必须携带同一 `reopen_id`。
 8. 按 native dynamic instruction 和 `contextFiles` 指引，实现最小 task scope。
-9. 产出 GREEN evidence，保留 `test_id`、`invariant_refs`、命令、输出摘要和 raw log ref。
+9. 产出 GREEN evidence，保留 `test_id`、`invariant_refs`、命令、输出摘要和 raw log ref；raw log ref 指向原始输出文件，evidence 中只写必要摘要，不复制完整日志。
 10. 勾选 task 前执行任务完成检查（`check-task-complete`）：
    ```text
    superspec guard check-task-complete --change "<change>" --task-id "<task-id>"

package/templates/workflow/skills/superspec-archive/SKILL.md

@@ -23,6 +23,12 @@ metadata:
 - Windows PowerShell 中执行 npm 全局 bin 时，必须显式使用 `.cmd` shim：`superspec.cmd ...`、`openspec.cmd ...`；不要运行 `superspec.ps1` 或 `openspec.ps1`。
 - macOS、Linux、Git Bash、cmd.exe 或其他不会优先拦截 `.ps1` 的 shell 中，继续使用文档中的 `superspec ...`、`openspec ...` 命令。
 
+## 上下文读取纪律 / Context Budget
+
+- guard 可以在本地读取完整 `.superspec/evidence/**/*.json` 并重算 archive 判定；主流程默认不要打开完整 evidence JSON，除非正在排查 guard block、修复 preservation manifest，或用户明确要求诊断原文。
+- 主流程默认只读取 guard decision、archive preservation 摘要、OpenSpec archive 输出摘要，以及最终验证 archive 结果所需的最小 manifest 信息。
+- raw log、长报告和历史 superseded evidence 默认只作为引用、hash 或摘要保留；不要把全文复制进对话上下文或新的 evidence。
+
 仅在 `review_complete` passes（其中已经包含 final verification）后使用本 skill。
 
 ## 边界 / Boundaries

package/templates/workflow/skills/superspec-explore/SKILL.md

@@ -23,6 +23,14 @@ metadata:
 - Windows PowerShell 中执行 npm 全局 bin 时，必须显式使用 `.cmd` shim：`superspec.cmd ...`、`openspec.cmd ...`；不要运行 `superspec.ps1` 或 `openspec.ps1`。
 - macOS、Linux、Git Bash、cmd.exe 或其他不会优先拦截 `.ps1` 的 shell 中，继续使用文档中的 `superspec ...`、`openspec ...` 命令。
 
+## 上下文读取纪律 / Context Budget
+
+- guard 可以在本地读取完整 `.superspec/evidence/**/*.json` 并重算判定；主流程默认不要打开完整 evidence JSON，除非正在排查 guard block、修复 schema，或用户明确要求诊断原文。
+- 主流程默认只读取 guard decision、当前 gate 必要 artifact、OpenSpec instructions 返回的必要 context、native subagent `output_ref` 的摘要/结论段，以及用户确认所需的最小原文。
+- 当前轮披露循环所需的最小结构化字段必须读取，不能只看 `output_ref` 摘要；包括 role evidence 的 `findings[]`、`finding_uid`、`decision_scope_key`、逐字 `summary`、`target_refs`，以及本轮 digest 需要引用的 evidence id。
+- raw log、长报告和历史 superseded evidence 默认只作为引用、hash 或摘要保留；不要把全文复制进对话上下文或新的 evidence。
+- native subagent 的 `output_ref` 应指向简洁审查报告；原始命令输出或长日志放在 raw/report 文件中被引用，不作为默认阅读材料。
+
 在 init 之后、编写 OpenSpec proposal package 之前使用本 skill。
 
 ## 边界 / Boundaries
@@ -74,7 +82,8 @@ metadata:
    ```
 7. 在 `.superspec/evidence/discovery/` 记录 critic evidence，包含 `execution_mode:"native_subagent"`、`agent_role`、`agent_id`、`output_ref`、`source_anchors` 和 `target_refs`。
 8. 按确认循环处理 findings：写本轮审查问题记录；存在关键问题时**停下来向用户说明并等待用户确认**，再按用户确认更新探索记录 / 重跑 critic / 写新一轮记录，直到最新轮 clean 且问题清单里没有未处理完的问题。
-9. 运行进入阶段前检查（`check-enter`），验证 explore completion：
+9. 对探索结论、范围边界和进入 propose 的授权使用 AskUserQuestion，并等待明确选择；记录探索阶段人工确认 evidence（JSON 中为 `gate:"explore_complete"`、`kind:"human_confirmation"`、`created_by:"user"`），`confirmed_refs` 固定记录用户确认过的探索记录。
+10. 运行进入阶段前检查（`check-enter`），验证 explore completion：
    ```text
    superspec guard check-enter --change "<change>" --gate explore_complete
    ```

package/templates/workflow/skills/superspec-propose/SKILL.md

@@ -23,6 +23,14 @@ metadata:
 - Windows PowerShell 中执行 npm 全局 bin 时，必须显式使用 `.cmd` shim：`superspec.cmd ...`、`openspec.cmd ...`；不要运行 `superspec.ps1` 或 `openspec.ps1`。
 - macOS、Linux、Git Bash、cmd.exe 或其他不会优先拦截 `.ps1` 的 shell 中，继续使用文档中的 `superspec ...`、`openspec ...` 命令。
 
+## 上下文读取纪律 / Context Budget
+
+- guard 可以在本地读取完整 `.superspec/evidence/**/*.json` 并重算判定；主流程默认不要打开完整 evidence JSON，除非正在排查 guard block、修复 schema，或用户明确要求诊断原文。
+- 主流程默认只读取 guard decision、当前 gate 必要 artifact、OpenSpec instructions 返回的必要 context、native subagent `output_ref` 的摘要/结论段，以及用户确认所需的最小原文。
+- 当前轮披露循环所需的最小结构化字段必须读取，不能只看 `output_ref` 摘要；包括 role evidence 的 `findings[]`、`finding_uid`、`decision_scope_key`、逐字 `summary`、`target_refs`，以及本轮 digest 需要引用的 evidence id。
+- raw log、长报告和历史 superseded evidence 默认只作为引用、hash 或摘要保留；不要把全文复制进对话上下文或新的 evidence。
+- native subagent 的 `output_ref` 应指向简洁审查报告；原始命令输出或长日志放在 raw/report 文件中被引用，不作为默认阅读材料。
+
 在 explore 完成后使用本 skill，用于把探索记录整理成可执行的正式方案包。OpenSpec 负责生成标准方案文件，具体写法必须通过它自带的指令（`openspec instructions`）获取；SuperSpec 负责在外层增加审查门禁（gates）、业务约束（`business-invariants.md`）、测试契约（`test-contract.md`）和任务元数据。
 
 ## 边界 / Boundaries
@@ -43,7 +51,7 @@ metadata:
 
 ## 步骤 / Steps
 
-1. 运行前置门禁检查（`check-enter`），确认探索阶段已经完成：
+1. 运行前置门禁检查（`check-enter`），确认探索阶段已经完成；该 gate 必须包含用户对探索结论和进入 propose 的明确确认，若 guard block 则停止并回到 explore 补确认：
    ```text
    superspec guard check-enter --change "<change>" --gate explore_complete
    ```
@@ -79,7 +87,7 @@ metadata:
    ```text
    superspec guard check-enter --change "<change>" --gate propose.test_plan_drafted
    ```
-8. 通过 `openspec instructions tasks` 编写任务清单 `tasks.md` 时：为每个 task 补充 `requirement_refs`、`invariant_refs`（必须是 business-invariants `INV-*` ids 的子集）、`test_refs`（必须是 test-contract TEST ids 的子集）、`read_scope`、`write_scope`、dependencies、TDD metadata，以及需要时的 parallel group。若 reviewer 对 task 映射提出 round-tagged findings，走 `tasks_complete-r<N>` 确认循环（pinned target：tasks + test-contract + invariants + design + specs glob）；验收标准问题 route 用 `return_test_contract_drafted`，映射问题用 `stay_same_gate_fix`。对于任务审查确认，使用 AskUserQuestion 并等待明确选择；记录 human-confirmation evidence，然后验证：
+8. 通过 `openspec instructions tasks` 编写任务清单 `tasks.md` 时：为每个 task 补充 `requirement_refs`、`invariant_refs`（必须是 business-invariants `INV-*` ids 的子集）、`test_refs`（必须是 test-contract TEST ids 的子集）、`read_scope`、`write_scope`、dependencies、TDD metadata，以及需要时的 parallel group。若 reviewer 对 task 映射提出 round-tagged findings，走 `tasks_complete-r<N>` 确认循环（pinned target：tasks + test-contract + invariants + design + specs glob）；验收标准问题 route 用 `return_test_contract_drafted`，映射问题用 `stay_same_gate_fix`。对于任务审查确认，使用 AskUserQuestion 并等待明确选择；按披露循环记录用户裁决和审查问题处理结果，然后验证：
    ```text
    superspec guard check-enter --change "<change>" --gate propose.tasks_mapped
    ```

package/templates/workflow/skills/superspec-review/SKILL.md

@@ -25,6 +25,14 @@ metadata:
 - Windows PowerShell 中执行 npm 全局 bin 时，必须显式使用 `.cmd` shim：`superspec.cmd ...`、`openspec.cmd ...`；不要运行 `superspec.ps1` 或 `openspec.ps1`。
 - macOS、Linux、Git Bash、cmd.exe 或其他不会优先拦截 `.ps1` 的 shell 中，继续使用文档中的 `superspec ...`、`openspec ...` 命令。
 
+## 上下文读取纪律 / Context Budget
+
+- guard 可以在本地读取完整 `.superspec/evidence/**/*.json` 并重算判定；主流程默认不要打开完整 evidence JSON，除非正在排查 guard block、修复 schema，或用户明确要求诊断原文。
+- 主流程默认只读取 guard decision、当前 review 必要 artifact、native subagent `output_ref` 的摘要/结论段、`required_load_refs` 指向的关键 source，以及 final verification 的摘要。
+- `source_refs` 只是可追溯来源，不等于必须读取；只有 `required_load_refs` 是主流程必须亲自读取并写入 `loaded_refs` 的内容。
+- raw log、长报告和历史 superseded evidence 默认只作为引用、hash 或摘要保留；不要把全文复制进对话上下文或新的 evidence。
+- guard-only read 不能替代主流程的 `loaded_refs`：凡进入 `required_load_refs` 的材料，主流程必须真实读取后再写 `main_adjudication`。
+
 ## 硬边界
 
 - `review_complete` 是 allow-only gate。只有 `main_adjudication.review_decision:"allow"` 才允许进入 `check-review-complete` / `archive_ready`。
@@ -58,13 +66,13 @@ Required project-scope files: `.codex/agents/code-reviewer.toml`、`.codex/promp
    ```text
    superspec guard check-review-ready --change "<change>"
    ```
-2. 从 `git diff`、OpenSpec artifacts、tasks、business invariants、test contract、red/green evidence 和 `.superspec` evidence 构建审查范围。
+2. 从 guard decision、`git diff`、OpenSpec artifacts、tasks、business invariants、test contract、RED/GREEN 摘要和 live role output 摘要构建审查范围；不要默认打开完整 `.superspec/evidence/**/*.json`。
 3. 运行 repo-local review guidance：
    - 启动 repo-local `code-reviewer` native subagent，记录审查指导证据（内部 JSON kind 为 `source_guidance`）。
    - 启动 repo-local `architect` native subagent，记录审查指导证据（内部 JSON kind 为 `source_guidance`）。
    - 启动独立 repo-local `critic` native subagent，审查 superspec-specific scope drift、隐藏假设、业务不变量是否被测试/实现扭曲、遗漏的 rollback targets 和 evidence 充分性，并记录审查指导证据（内部 JSON kind 为 `source_guidance`）。
 4. 主流程读取关键 source，准备 `main_adjudication` 输入：
-   - 从每条 `source_guidance.source_refs` 中判断哪些内容需要亲自加载。
+   - 从每条 `source_guidance.source_refs` 中判断哪些内容确实需要亲自加载，不要把所有来源自动升级为必须读取。
    - `source_refs` / `required_load_refs` 使用 `pinned_ref = {path, blob_sha}`；其中 `pinned_ref.path` 一律是 repo-root relative path。`required_load_refs` 必须按 `(path, blob_sha)` 精确包含于 `source_refs`。
    - 对所有 `required_load_refs` 做真实读取，并在 `loaded_refs` 中记录同样的 `pinned_ref`；`loaded_refs` 必须按 `(path, blob_sha)` 精确覆盖全部 `required_load_refs`，同一路径不同 blob 不算已加载。
    - 对所有 `required_claim_ids` 写出结构化 `claim_adjudications[] = {claim_id, decision, rationale}`。