@peterxiaoyang/superspec 0.1.14 → 0.1.15-alpha

package/dist/types.d.ts

@@ -0,0 +1,138 @@
+export type State = "init" | "explore" | "propose" | "propose_ready" | "apply" | "apply_done" | "review" | "accepted" | "archive" | "abandoned";
+export declare const PHASE1_STATES: ReadonlySet<State>;
+export type Ref = {
+    path: string;
+    sha: string;
+};
+export type JobState = "requested" | "accepted" | "rejected";
+export type JobRole = "proposal-auditor" | "clarification-review" | "critic-review" | "architect-review" | "test-engineer-review" | "executor" | "test-run" | "final-audit";
+export interface Job {
+    job_id: string;
+    role: JobRole;
+    state: JobState;
+    boundFiles: Ref[];
+    packet_digest: string;
+    created_from_transition: string;
+    created_at: string;
+}
+export interface JobPacket {
+    job_id: string;
+    role: JobRole;
+    boundFiles: Ref[];
+    packet_digest: string;
+    required_output_kind: string;
+    stop_conditions: string[];
+    created_from_transition: string;
+}
+export type EventType = "transition_prepare" | "transition_commit" | "job_requested" | "job_invalidated" | "reopen" | "abandon" | "task_started" | "task_completed" | "task_abandoned" | "job_accepted" | "job_rejected" | "user_decision_recorded" | "test_run_recorded" | "task_activation_recorded" | "artifact_recorded";
+export interface Event {
+    event_id: string;
+    event_type: EventType;
+    change_id: string;
+    transition_id: string | null;
+    idempotency_key: string | null;
+    created_at: string;
+    actor: string;
+    prev_snapshot_digest: string | null;
+    input_refs: Ref[];
+    output_refs: Ref[];
+    payload: Record<string, unknown>;
+    event_digest: string;
+}
+export interface TransitionCommitPayload {
+    transition: string;
+    from_state: State;
+    to_state: State;
+    outcome: "advanced" | "job_created";
+    created_job_ids: string[];
+    reason: string;
+}
+export interface Snapshot {
+    change_id: string;
+    state: State;
+    openspec_status_digest: string;
+    events_digest: string;
+    document_digests: Record<string, string>;
+    tasks_structure_digest: string | null;
+    task_statuses: Record<string, "todo" | "doing" | "done">;
+    open_jobs: Job[];
+    accepted_jobs: Job[];
+    active_task_attempts: TaskAttempt[];
+    pending_user_decisions: AskUser[];
+    last_transition: string | null;
+    computed_at: string;
+}
+export type AttemptState = "active" | "closed" | "abandoned";
+export interface TaskAttempt {
+    attempt_id: string;
+    task_id: string;
+    state: AttemptState;
+    task_structure_digest: string;
+    declared_write_scope: string[];
+    pre_edit_source_fingerprint: string | null;
+    pre_edit_red_ref: string | null;
+    executor_packet_digest: string | null;
+    executor_result_ref: string | null;
+    post_edit_green_ref: string | null;
+    created_at: string;
+}
+export interface TestRun {
+    test_id: string;
+    attempt_id?: string | null;
+    task_structure_digest: string;
+    command: string;
+    cwd: string;
+    exit_code: number;
+    semantic_status: "expected_failure" | "expected_success" | "characterization_pass" | "unknown";
+    target_fingerprint: string | null;
+    raw_log_ref: string | null;
+    created_at: string;
+}
+export interface MissingInput {
+    field: string;
+    expected: string;
+    command_to_fix: string;
+}
+export interface AskUser {
+    question: string;
+    allowed_answers: string[];
+    scope: string;
+}
+export type NextOutput = {
+    state: State;
+} & ({
+    path: "next_command";
+    next_command: string;
+    reason: string;
+    missing_inputs: MissingInput[];
+} | {
+    path: "required_job";
+    required_jobs: {
+        job_id: string;
+        role: JobRole;
+        packet_command: string;
+    }[];
+    reason: string;
+} | {
+    path: "ask_user";
+    ask_user: AskUser;
+    reason: string;
+} | {
+    path: "done";
+    reason: string;
+});
+export interface TransitionResult {
+    transition: string;
+    outcome: "advanced" | "job_created";
+    from_state: State;
+    to_state: State;
+    created_jobs: string[];
+    message: string;
+    events_written: number;
+}
+export interface RecordResult {
+    event_type: EventType;
+    accepted: boolean;
+    message: string;
+    job_state?: JobState;
+}

package/dist/types.js

@@ -0,0 +1,3 @@
+// SuperSpec 流程引擎 — 核心类型定义
+// Phase 1 只实现前 4 个
+export const PHASE1_STATES = new Set(["init", "explore", "propose", "propose_ready"]);

package/package.json

@@ -1,65 +1,20 @@
 {
   "name": "@peterxiaoyang/superspec",
-  "version": "0.1.14",
-  "description": "SuperSpec workflow package: guard runtime, generic workflow templates, and Codex adapter payload.",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/PeterYaoYang/SuperSpec.git"
-  },
-  "bugs": {
-    "url": "https://github.com/PeterYaoYang/SuperSpec/issues"
-  },
-  "homepage": "https://github.com/PeterYaoYang/SuperSpec#readme",
-  "private": false,
+  "version": "0.1.15-alpha",
+  "description": "SuperSpec 流程引擎 — transition engine with lightweight fact-sync",
   "type": "module",
-  "publishConfig": {
-    "access": "public"
-  },
-  "engines": {
-    "node": ">=20.19.0"
-  },
-  "bin": {
-    "superspec": "bin/superspec.js",
-    "superspec-check": "bin/superspec-check.js",
-    "superspec-hook": "bin/superspec-hook.js",
-    "superspec-init": "bin/superspec-init.js"
-  },
+  "engines": { "node": ">=20.19.0" },
+  "bin": { "superspec": "dist/cli.js" },
   "exports": {
-    ".": {
-      "types": "./dist/superspec.d.ts",
-      "default": "./dist/superspec.js"
-    },
-    "./superspec_guard": {
-      "types": "./dist/superspec_guard.d.ts",
-      "default": "./dist/superspec_guard.js"
-    },
-    "./superspec_hook": {
-      "types": "./dist/superspec_hook.d.ts",
-      "default": "./dist/superspec_hook.js"
-    },
-    "./superspec_init": {
-      "types": "./dist/superspec_init.d.ts",
-      "default": "./dist/superspec_init.js"
-    },
-    "./templates/*": "./templates/*",
-    "./adapters/*": "./adapters/*",
-    "./schemas/*": "./schemas/*"
+    ".": { "types": "./dist/types.d.ts", "default": "./dist/cli.js" }
   },
-  "files": [
-    "README.md",
-    "bin",
-    "dist",
-    "templates",
-    "adapters",
-    "schemas"
-  ],
+  "files": ["README.md", "dist", "templates"],
   "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_cli.test.ts tests/test_superspec_guard_output.test.ts tests/test_superspec_guard_core.test.ts tests/test_superspec_guard_review.test.ts tests/test_superspec_guard_request_reopen.test.ts tests/test_superspec_guard_archive.test.ts tests/test_superspec_guard_packet.test.ts tests/test_superspec_guard_disclosure.test.ts tests/test_superspec_hooks.test.ts tests/test_superspec_i18n.test.ts tests/test_superspec_skills.test.ts",
+    "test": "node --test tests/*.ts",
     "prepack": "npm run build",
-    "prepublishOnly": "npm run build",
-    "pack:dry-run": "npm pack --dry-run"
+    "prepublishOnly": "npm run build"
   },
   "devDependencies": {
     "@types/node": "^20.19.0",

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

@@ -1,6 +1,6 @@
 ---
 name: superspec-apply
-description: "3.方案通过后用：按 tasks 一项项写代码、跑测试、记录证据；每个任务都要先证明测试会失败，再实现到测试通过。"
+description: "按 tasks.md 逐任务实现代码，记录 RED/GREEN 证据，推进 task-complete。"
 metadata:
   author: SuperSpec
   source: SuperSpec
@@ -8,136 +8,64 @@ metadata:
 
 # SuperSpec Apply
 
-## 语言规则 / Language
+你是执行阶段。职责：按 tasks.md 的任务逐个实现——先 RED（测试会失败），再 GREEN（实现到测试通过），然后 task-complete 勾选。
 
-- 默认使用简体中文写人类可读内容；命令、路径、字段名、阶段门名、task/test id、代码标识符保留原文。
-- 用户可见文案不得使用“裁决”描述用户动作；统一说“确认”“范围取舍”“处理方式选择”或“用户确认记录”。
-- 不把内部证据种类、reason code、JSON 字段大全直接转述给用户；需要诊断时才引用原文。
-- 普通 workflow 命令使用 `--format agent`；`--format json` 只用于诊断，不作为默认上下文。
+## 驱动方式
 
-## 命令执行 / Shell
+所有状态由 transition engine 管理。循环：
 
-- Windows PowerShell 中使用 `.cmd` shim：`superspec.cmd ...`、`openspec.cmd ...`；不要运行 `superspec.ps1` 或 `openspec.ps1`。
-- 其他 shell 使用文档中的 `superspec ...`、`openspec ...` 命令。
+1. `superspec transition next --change "<change>"` 获取下一步
+2. 执行返回的命令
+3. 登记结果
+4. 回到 1
 
-## 阶段职责
+## 本阶段做什么
 
-Apply 按 OpenSpec tasks 实现，负责 RED/GREEN 证据、任务勾选和 review request-changes 后的 reopen 修复；不扩大范围，不改 proposal package 语义。
+进入执行前，先用 `openspec instructions apply --change "<change>" --json` 读取 apply 阶段约束，再执行 `superspec transition start-apply --change "<change>"`。
 
-## 第一条必跑命令
+每个任务的循环：
 
-```text
-superspec check workflow-packet --change "<change>" --gate apply_ready --format agent
-```
-
-遇到任何返回状态为 `block` 就停止；未 allowed 前不要编辑实现。
-
-## OpenSpec 边界
-
-- 直接使用 OpenSpec CLI surface，不读取 repo-local `openspec-*` skill 文本。
-- task list、`contextFiles`、progress、dynamic instruction 来自：
-
-```text
-openspec instructions apply --change "<change>" --json
-```
-
-不要发明 task list，也不要跳过 OpenSpec 返回的 context files。
-
-## Task Guard 边界
-
-实现编辑前读取 `task_edit` 检查结果；勾选 task 前读取 `task_complete` 检查结果：
-
-```text
-superspec check workflow-packet --change "<change>" --gate task_edit --task-id "<task-id>" --format agent
-superspec check workflow-packet --change "<change>" --gate task_complete --task-id "<task-id>" --format agent
-```
-
-`task_edit` 未 allowed 不得编辑实现；`task_complete` 未 allowed 不得把 checkbox 改成 done。
-
-## Reopen 边界
-
-review 给出 `request_changes_route:"reopen_tasks"` 时，先生成完整 reopen package，再检查：
-
-```text
-superspec check workflow-packet --change "<change>" --gate task_reopen --task-id "<task-id>" --format agent
-```
-
-只有 `task_reopen` allowed 后，才允许把目标 task 从 checked 改回 unchecked 并重新 RED/GREEN。修完写 `task_reopen_resolved`，再进 review。若 route 是 `change_update`，停止 apply 并回 propose/change update。
-
-## 用户确认边界
-
-- apply isolation 和 execution mode 必须等待明确选择。
-- 分支状态、dirty worktree、scope expands 或需要改变 task scope 时必须停止并确认。
-- 不要使用默认值、历史偏好或沉默作为确认。
-
-## 专用代理边界
-
-主线程只负责用检查命令生成各角色提示、分派专用代理、审核代理报告、登记证据、推进任务勾选。专用代理来自 `.codex/agents/*.toml` 与 `.codex/prompts/*.md`，不能由主线程自审替代。代理报告只是候选材料，通过检查的才是正式证据。当前 CLI 没有登记证据的命令；代理报告返回后，由主线程按检查命令的 output contract 字段手动写入 `.superspec/evidence/` 对应目录。
-
-RED/characterization/GREEN 测试必须由 `.codex/agents/test-runner.toml` + `.codex/prompts/test-runner.md` 执行；主线程不得代跑或伪造 formal `test_run` evidence。新增或修改测试文件时用 `test-engineer` 专用代理。
-
-```text
-superspec check apply-test-packet --change "<change>" --task-id "<task-id>" --test-id "<test-id>" --phase red --format prompt
-```
-
-用 test-runner 执行检查命令指定的测试命令；主线程审核报告/原始日志并登记为证据后，才写正式 `test_run` 证据。
-
-测试证据语义（框架无关，审核 worker report 时用）：只有 `target test identity executed` 才算有效运行；`command exit code alone is not proof`，退出码 0 不证明目标测试真正跑过/通过；命令在到达测试 runner 之前失败属于 `blocked before the target test runner`，不算 RED/GREEN；`do not classify environment/build failures as RED or GREEN`。
-
-`apply_execution_surface`：缺省有 `write_scope` 为 `implementation`，无 `write_scope` 为 `no_code`；显式允许 `implementation`、`runtime_config`、`docs_generated`、`no_code`。`implementation` / `runtime_config` 必须走 executor-worker chain；`tdd_required:false` 也只能用 closed `apply_worker_chain` 的 `completion_proof_kind:"alternative_verification"` 完成。`docs_generated` / `no_code` 可用 direct alternative/manual verification。
-
-编码实现必须由 `.codex/agents/executor.toml` + `.codex/prompts/executor.md` 执行，并通过 active -> closed `apply_worker_chain` 收敛；主线程不得直接改实现代码来完成 task。
-
-```text
-superspec check apply-executor-packet --change "<change>" --task-id "<task-id>" --apply-worker-chain-ref "<active-chain-ref>" --format prompt
-```
-
-使用 `.codex/agents/executor.toml` / `.codex/prompts/executor.md`。先把检查命令给出的激活模板登记为工作链证据；缺激活标记不能启动 executor。TDD 与 no-TDD 的激活标记不同（具体字段以检查命令输出为准）。executor 只能改检查命令声明的实现写范围（implementation/runtime_config write scope），不能写正式 evidence，不能改 task checkbox，不能做 review/verification。
-
-executor 返回后把报告登记为证据，再生成任务级审查：
+1. **task-start**：`superspec transition task-start --change "<change>" --task "<TASK-ID>"`
+2. **拿到 attempt_id**：从 task-start 的返回结果或 `snapshot.json` 中读取当前活跃 attempt 的 `attempt_id`
+3. **RED**：写测试，跑测试确认失败，`superspec record test-run --change "<change>" --input <red.json>`
+4. **实现**：写代码让测试通过
+5. **GREEN**：跑测试确认通过，`superspec record test-run --change "<change>" --input <FILE>`
+6. **task-complete**：`superspec transition task-complete --change "<change>" --task "<TASK-ID>"`
 
-```text
-superspec check apply-code-review-packet --change "<change>" --task-id "<task-id>" --executor-report-ref "<ref>" --format prompt
-```
-
-用 `.codex/agents/code-reviewer.toml` 检查 scope/protected paths、executor report 与 diff、test/invariant mapping 和 suggested GREEN checks。
+no-TDD 任务（tdd_required:false + no_tdd_reason）跳过 RED/GREEN。
 
-code-review 通过后，GREEN 只走同一 executor-worker chain：
+## test-run 输入格式
 
-```text
-superspec check apply-test-packet --change "<change>" --task-id "<task-id>" --test-id "<test-id>" --phase green --task-code-review-report-ref "<ref>" --format prompt
+```json
+{
+  "test_id": "TEST-XXX",
+  "attempt_id": "ATT-TASK-XXX-...",
+  "task_structure_digest": "<从 tasks.md 派生的结构指纹>",
+  "command": "npm test",
+  "cwd": "<工作目录>",
+  "exit_code": 1,
+  "semantic_status": "expected_failure",
+  "target_fingerprint": "<被测文件的 sha256>"
+}
 ```
 
-GREEN report 审核并登记为 evidence 后，生成 GREEN verification：
+- `attempt_id`：从 task-start 结果获取，确保 RED/GREEN 绑定到正确的执行尝试
+- `semantic_status`：`expected_failure`（RED）/ `expected_success`（GREEN）/ `characterization_pass`
+- `task_structure_digest`：tasks.md 复选框归一化后的 sha256（引擎计算，你不需要手动算）
 
-```text
-superspec check apply-verify-packet --change "<change>" --task-id "<task-id>" --executor-report-ref "<ref>" --task-code-review-report-ref "<ref>" --green-test-run-evidence-ref "<ref>" --red-test-run-evidence-ref "<ref>" --format prompt
-```
+当前限制：
 
-no-TDD implementation/runtime_config 先登记 live/pass `alternative_verification` 或 `manual_verification`，再生成 alternative verification：
+- 不要同时保留多个 active attempt；同一任务必须先完成或明确失败当前 attempt。
+- 测试证据不按 `task_id` 或 `attempt_id` 绑定时，不要拿来完成任务。
+- RED/GREEN 是流程纪律，不是引擎校验项；引擎只登记你提交的测试记录。
+- 当前 CLI 没有 return-to-propose / reopen surface；不要假装存在回退到 propose 的命令。
 
-```text
-superspec check apply-verify-packet --change "<change>" --task-id "<task-id>" --executor-report-ref "<ref>" --task-code-review-report-ref "<ref>" --alternative-verification-evidence-ref "<ref>" --format prompt
-```
-
-用 `.codex/agents/verifier.toml` 检查完成方式分支：GREEN 绑定 RED/characterization、GREEN 和当前工作区；alternative 绑定 no-TDD 激活标记、实际替代/人工验证引用、surface/no-TDD 元数据和当前工作区。审核 verifier 报告后写关闭的工作链证据，再跑 `task_complete`。异常终止只取消旧工作链，不授权完成。
-
-## 完成检查
-
-每个 task 的证据链（RED/characterization → executor → code-review → GREEN 或替代验证 → verifier）齐全后，运行任务完成检查：
-
-```text
-superspec check workflow-packet --change "<change>" --gate task_complete --task-id "<task-id>" --format agent
-```
-
-只有检查结果显示通过后，才把该 task 的 checkbox 改为 done。所有 task 完成后进入 `superspec-review`。
-
-## 异常恢复
-
-状态文件损坏时重建：
-
-```text
-superspec check recompute --change "<change>" --rebuild-corrupt
-```
+## Guardrails
 
-状态指纹过期时，重跑对应检查命令即可（检查命令会自动重算并刷新指纹）；不要手写状态文件。
+- 只改 tasks.md 里本任务范围相关的文件
+- 不跳过 RED 直接写 GREEN
+- 退出码 0 ≠ 测试通过——semantic_status 才是证据
+- 环境错误 / 构建失败不算 RED 或 GREEN
+- 不手改 tasks.md 复选框——task-complete 会自动补丁
+- 不跳过 transition
+- 不要发明当前分支没有的 `superspec check` / `apply_worker_chain` / `apply_isolation`

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

@@ -1,6 +1,6 @@
 ---
 name: superspec-archive
-description: "5.所有审查和验证通过后用：把完成的 change 归档到 specs，并确认关键证据和历史没有丢失；这一步是流程收尾。"
+description: "归档保全：验证文档完整性，提交 archive。"
 metadata:
   author: SuperSpec
   source: SuperSpec
@@ -8,58 +8,33 @@ metadata:
 
 # SuperSpec Archive
 
-## 语言规则 / Language
+你是归档阶段。职责：确认审查通过后，执行归档——保全清单记录当前文档指纹。
 
-- 默认使用简体中文写人类可读内容；命令、路径、字段名、阶段门名、task/test id、代码标识符保留原文。
-- 用户可见文案不得使用“裁决”描述用户动作；统一说“确认”“范围取舍”“处理方式选择”或“用户确认记录”。
-- 不把内部证据种类、reason code、JSON 字段大全直接转述给用户；需要诊断时才引用原文。
-- 普通 workflow 命令使用 `--format agent`；`--format json` 只用于诊断，不作为默认上下文。
+## 驱动方式
 
-## 命令执行 / Shell
+所有状态由 transition engine 管理。循环：
 
-- Windows PowerShell 中使用 `.cmd` shim：`superspec.cmd ...`、`openspec.cmd ...`；不要运行 `superspec.ps1` 或 `openspec.ps1`。
-- 其他 shell 使用文档中的 `superspec ...`、`openspec ...` 命令。
+1. `superspec transition next --change "<change>"` 获取下一步
+2. 执行返回的命令
+3. 回到 1
 
-## 阶段职责
+## 本阶段做什么
 
-Archive 在 `review_complete` allowed 后收尾：确认 archive readiness、保全 `.superspec` 证据快照、运行 OpenSpec archive，并验证归档后的 preservation。
+1. **确认状态为 accepted**：next 会检查
+2. **archive**：`superspec transition archive --change "<change>"`
+   - 引擎记录当前文档指纹（proposal/tasks/design/discovery/bi/test-contract/specs）作为保全清单
+   - 归档事件写入 `events.jsonl`，并包含 `artifact_recorded`
+   - 缺失 artifact 会以 `sha256:missing` 表达
+   - 状态推进到 archive（终态）
 
-## 第一条必跑命令
+当前限制：
 
-```text
-superspec check workflow-packet --change "<change>" --gate archive_ready --format agent
-```
+- 这一步没有执行物理 OpenSpec archive；只是记录 SuperSpec 保全事件。
+- 当前 CLI 没有 archive rollback / retry surface。
 
-遇到 `block` 就停止，不归档。
+## Guardrails
 
-## OpenSpec 边界
-
-- 直接使用 OpenSpec CLI surface，不读取 repo-local `openspec-*` skill 文本。
-- 归档动作使用 native OpenSpec CLI；SuperSpec 不重新实现移动、spec sync 或 validation。
-- 当前 v1 固定使用 `openspec archive -y "<change>"`，不暴露 `--no-validate` 或 skip-specs 分支。
-
-## 用户确认边界
-
-`archive_ready` 最终确认必须等待明确选择。若 change 不应同步 specs，先回 propose/change update 调整方案，不在 archive 阶段跳过。
-
-## 执行步骤
-
-确认后运行会写 preservation manifest 的 readiness check：
-
-```text
-superspec check check-archive-ready --change "<change>" --format agent
-```
-
-然后运行 OpenSpec archive：
-
-```text
-openspec archive -y "<change>"
-```
-
-最后验证 archived sidecar preservation：
-
-```text
-superspec check check-archived --change "<change>" --format agent
-```
-
-`.superspec/artifacts/business-invariants.md`、`.superspec/artifacts/test-contract.md`、review/verification evidence、RED/GREEN evidence 和 archive evidence 必须能从 preservation manifest 追溯。
+- 不改文档内容（归档前应已定稿）
+- 不跳过 accept 直接 archive
+- archive 后不可逆——确认无误再提交
+- 不跳过 transition

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

@@ -1,6 +1,6 @@
 ---
 name: superspec-explore
-description: "1.新需求刚开始时用：先把目标、范围、风险和现有代码事实弄清楚，产出探索记录（`discovery.md`）；这一步只探索，不写正式方案，也不改代码。"
+description: "探索现状、澄清范围、维护 discovery.md；通过 transition/record 把 change 从 init 推进到 propose。"
 metadata:
   author: SuperSpec
   source: SuperSpec
@@ -8,90 +8,59 @@ metadata:
 
 # SuperSpec Explore
 
-## 语言规则 / Language
+你是探索阶段。职责：调查现状、梳理范围、识别风险，把结果沉淀到 `discovery.md`。不写业务代码，不提前写 proposal/specs/design/tasks。
 
-- 默认使用简体中文写人类可读内容；命令、路径、字段名、阶段门名、task/test id、代码标识符保留原文。
-- 用户可见文案不得使用“裁决”描述用户动作；统一说“确认”“范围取舍”“处理方式选择”或“用户确认记录”。
-- 不把内部证据种类、reason code、JSON 字段大全直接转述给用户；需要诊断时才引用原文。
-- 普通 workflow 命令使用 `--format agent`；`--format json` 只用于诊断，不作为默认上下文。
+## 驱动方式
 
-## 命令执行 / Shell
+所有状态由 transition engine 管理。循环：
 
-- Windows PowerShell 中使用 `.cmd` shim：`superspec.cmd ...`、`openspec.cmd ...`；不要运行 `superspec.ps1` 或 `openspec.ps1`。
-- 其他 shell 使用文档中的 `superspec ...`、`openspec ...` 命令。
+1. `superspec transition next --change "<change>"` 获取下一步
+2. 执行返回的命令
+3. 登记结果
+4. 回到 1
 
-## 阶段职责
+next 返回 `ask_user` 说明 discovery 不完整或有未确认问题——向用户提问，收到回答后 `superspec record user-decision --change "<change>" --input <FILE>`。
 
-Explore 只做需求澄清、代码事实调查、范围边界和风险记录。产物是 `openspec/changes/<change>/.superspec/artifacts/discovery.md`；不写 `proposal.md`、`specs/**`、`design.md`、`tasks.md`，也不改实现代码。
+当前 CLI surface：
 
-## 产物格式
+- 用 `openspec list --json` 和 `openspec status --change "<change>" --json` 建立 OpenSpec 事实基线。
+- 用 `superspec transition explore --change "<change>"` 从 init 进入探索阶段。
+- 用户回答阻塞问题后，写入决策文件并执行 `superspec record user-decision --change "<change>" --input <decision.json>`。
+- 不要把 `superspec status` 的 job 计数当成权威事实；阶段推进以 transition / record 返回值和 OpenSpec 文档为准。
 
-- discovery.md 必须按 SuperSpec discovery 模板的结构填写，保留全部段落：`调查范围` / `现有实现事实` / `隐性合约` / `风险与歧义` / `待确认问题` / `Subagent Evidence`；不得自创或删减段落骨架。
-- 第一条必跑命令 `superspec check workflow-packet --change "<change>" --gate explore_complete --format agent` 的返回里带 `discovery_template` 与 `discovery_rules`：按其中的模板骨架和填写规则产出，而不是自由发挥，这样无论哪个模型产物结构都一致。
+## 本阶段做什么
 
-## 第一条必跑命令
+1. **建立事实基线**：读代码、查架构、理解当前系统行为（只读）
+2. **写 discovery.md**：
+3. **澄清歧义**：有阻塞歧义时向用户提问
 
-```text
-superspec init --scope project --format agent
-```
+## discovery.md 格式
 
-随后用 `openspec list --json` 查找匹配 change；若已有则复用，若没有则直接创建，不要先跑 `openspec --help` / `openspec change --help` / `openspec new --help` 探测语法（命令失败或版本报错时才查 help 诊断）。
+写入 `openspec/changes/<change>/.superspec/artifacts/discovery.md`：
 
-```text
-openspec list --json
-```
+```markdown
+# Discovery
 
-仅当 `openspec list --json` 没有匹配 change 时运行：
+## 现状
+（当前系统怎么工作）
 
-```text
-openspec new change "<change>" --description "<用户需求摘要>"
-```
+## 需要改什么
+（要实现的需求）
 
-然后读取当前上下文：
+## 风险和边界
+（技术风险、依赖、兼容性）
 
-```text
-openspec status --change "<change>" --json
-superspec check check-init --change "<change>" --format agent
-superspec check workflow-packet --change "<change>" --gate explore_complete --format agent
+## 待确认问题
+- [ ] 问题1的描述
+- [ ] 问题2的描述
 ```
 
-遇到 `block` 就停止，按检查结果的下一步提示处理；不要绕过检查。
-
-## OpenSpec 边界
-
-- 直接使用 OpenSpec CLI surface，不读取 repo-local `openspec-*` skill 文本。
-- 用 `openspec list --json` 和 `openspec status --change "<change>" --json` 确认 change 结构、artifactPaths 和当前状态。
-- OpenSpec 负责 change 结构和后续 artifact 语义；本阶段只补 SuperSpec discovery 证据。
-- 如果发现需要正式方案、规格、设计或任务，先写入 discovery，再交给 `superspec-propose`。
-- 代码事实扫描可由主线程直接完成；若并行创建只读子代理，使用 repo-local `.codex/agents/explore.toml`。该角色只辅助 discovery 覆盖，不能替代 `critic` 审查证据。
-
-## 专用代理边界
-
-需求审查由本仓库的 `critic` 专用代理完成。生成审查提示时使用检查命令的输出，而不是把披露协议常驻在 skill 正文：
-
-```text
-superspec check review-packet --change "<change>" --gate explore_complete --role critic --round 1 --format prompt
-```
+**重要**：`- [ ]` 标记的待确认问题必须全部解决。收到用户确认后，把对应未决项从 `- [ ]` 改成 `- [x]` 或删除；只留档、不回写 `discovery.md`，阶段还是过不去。
 
-主流程整理审查问题时读取主线程提示信息：
-
-```text
-superspec check review-packet --change "<change>" --gate explore_complete --role main-thread --round 1 --format agent
-```
-
-第二轮及以后的审查，必须由检查命令把上一轮的问题注入提示；不要手写历史问题清单。
-
-## 用户确认边界
-
-- 关键范围、非目标、验收标准、业务语义或设计边界问题必须面向用户说明并等待明确确认。
-- 探索结论、范围边界和进入 propose 的授权必须等待用户确认后再记录 evidence。
-- discovery.md 必须含 `## 待确认问题` 段（标题含「确认」字样即可，如「待确认问题」「需要用户确认的问题」）。每条问题用 `- [ ]`（未决）或 `- [x]`（已确认）标记；也可在已确认项写「已确认：」。**该段只要还有 `- [ ]` 或「仍需确认/待确认」项，`explore_complete` 检查就不会通过**，不得记录人工确认，也不得进入 propose。
-- 用户看到的文字要用中文业务语言；内部 JSON 名只写进证据、命令输出或诊断片段。
-
-## 完成检查
-
-```text
-superspec check workflow-packet --change "<change>" --gate explore_complete --format agent
-```
+## Guardrails
 
-只有检查结果显示通过后，才进入 `superspec-propose`。
+- 不改业务代码
+- 不写 proposal/specs/design/tasks
+- 不跳过 transition 直接编辑状态文件
+- 用户未确认的决策不自行推断
+- 不要伪造当前分支没有的 `superspec check`