@peterxiaoyang/superspec 0.1.15-alpha → 0.1.16-alpha

package/README.md

@@ -77,17 +77,16 @@ npm install -g @peterxiaoyang/superspec@latest
 进入你的项目根目录，然后运行：
 
 ```bash
-superspec init --scope project
+superspec install
 ```
 
 这条命令的意思是：把 SuperSpec 当前可用的工作流入口安装到项目里。
-
-初始化还会安装托管的 `.codex/hooks.json`。默认 manifest 只在子智能体启动和停止时调用 SuperSpec，记录 best-effort 审计信息；它不会拦截普通文件写入，也不会在测试命令后自动记录结果。
+当前 beta 会安装 `.superspec/` 引擎目录、`.codex/skills/superspec-*` 阶段入口、`.codex/prompts/*.md` 角色 prompt、`.codex/agents/*.toml` 子智能体配置，并补齐 `.codex/config.toml` 的多 agent 开关。`superspec init --scope project` 仍作为兼容别名可用。
 
 Windows PowerShell 如果拦截 npm 的 `.ps1` 脚本，请改用：
 
 ```powershell
-superspec.cmd init --scope project
+superspec.cmd install
 ```
 
 ### 3. 按步骤使用
@@ -136,6 +135,8 @@ superspec.cmd init --scope project
 
 你日常主要记住这五个入口就够了。
 
+CLI 不带 `--risk` 时默认是 `normal`；但内置的 `superspec-explore` 和 `superspec-propose` 技能默认用 `--risk strict` 驱动。探索阶段会创建 `critic` 工作项审查需求澄清记录；计划阶段会创建 `proposal-auditor`、`critic`、`architect` 和 `test-engineer` 工作项后再进入实现准备。
+
 ## 它会多保存哪些记录
 
 SuperSpec 会在每次变更下面保存一些辅助记录，方便后续追溯。
@@ -200,34 +201,24 @@ superspec --version
 安装到当前项目：
 
 ```bash
-superspec init --scope project
+superspec install
 ```
 
-更新当前项目里的 SuperSpec 入口：
+`superspec init --scope project` 是兼容别名，也会执行同一套安装逻辑。
 
-```bash
-superspec update --scope project
-```
-
-这条命令会先通过 npm 更新全局 `@peterxiaoyang/superspec`，再用新版本更新当前项目里的入口文件。只想使用当前已安装包更新项目文件时，可以运行：
+检查当前项目的 OpenSpec 探测结果：
 
 ```bash
-superspec update --scope project --local-only
+superspec status
 ```
 
-卸载当前项目里的 SuperSpec 入口：
+更新当前 beta CLI：
 
 ```bash
-superspec uninstall --scope project
+superspec update
 ```
 
-这些命令默认不会删除已经生成的 `.superspec/` 过程记录。
-
-诊断全局安装、PATH、OpenSpec 依赖和 npm bin 指向问题：
-
-```bash
-superspec doctor
-```
+这条命令只检查当前 `.superspec/changes` 运行时是否已经是新引擎布局；真正升级全局 npm 包仍需使用 `npm install -g @peterxiaoyang/superspec@<version>`。
 
 ## 进阶信息
 
@@ -235,24 +226,35 @@ superspec doctor
 
 ```text
 .codex/
-  hooks.json
   skills/superspec-explore/
   skills/superspec-propose/
   skills/superspec-apply/
   skills/superspec-review/
   skills/superspec-archive/
+  prompts/architect.md
+  prompts/code-reviewer.md
+  prompts/critic.md
+  prompts/executor.md
+  prompts/explore.md
+  prompts/final-audit.md
+  prompts/proposal-auditor.md
+  prompts/test-engineer.md
+  prompts/test-runner.md
+  prompts/verifier.md
+  agents/architect.toml
+  agents/code-reviewer.toml
+  agents/critic.toml
+  agents/executor.toml
+  agents/explore.toml
+  agents/final-audit.toml
+  agents/proposal-auditor.toml
+  agents/test-engineer.toml
+  agents/test-runner.toml
+  agents/verifier.toml
+  config.toml
 ```
 
-SuperSpec 内部还有一些检查命令，例如：
-
-```bash
-superspec check check-init --change <变更ID>
-superspec check check-apply-ready --change <变更ID>
-superspec check check-review-ready --change <变更ID>
-superspec check check-archive-ready --change <变更ID>
-```
-
-普通使用者通常不需要手动运行这些命令；对应的阶段入口会在需要时使用它们。
+当前 beta 的阶段入口由 `superspec transition next --change <变更ID>` 驱动，不再提供旧版 `superspec check ...` surface。
 
 如果你要开发 SuperSpec 本身：
 
@@ -260,14 +262,13 @@ superspec check check-archive-ready --change <变更ID>
 npm run build
 npm run typecheck
 npm test
-npm run pack:dry-run
+npm pack --dry-run
 ```
 
 更多细节见：
 
-- `docs/SPEC.md`：完整设计和规则
-- `docs/DISTRIBUTION.md`：安装、升级、卸载和分发说明
-- `.codex/skills/superspec-*/SKILL.md`：当前 Codex 适配器使用的阶段入口说明
+- `docs/plans/SUPERSPEC_TRANSITION_ENGINE_SPEC_LITE.md`：transition engine 设计
+- `templates/workflow/skills/superspec-*/SKILL.md`：当前 Codex 适配器使用的阶段入口说明
 
 ## 致谢与灵感来源
 

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 // SuperSpec 流程引擎 — CLI 入口
-import { writeFileSync, mkdirSync, existsSync } from "node:fs";
 import { join } from "node:path";
+import { installProject } from "./install.js";
 import { writeSnapshot } from "./store.js";
 import { rebuildSnapshot } from "./sync.js";
 import { next as nextCmd } from "./next.js";
@@ -44,7 +44,7 @@ function parseFlags(args) {
 async function main(argv) {
     // --help / 无参数 → 打印用法
     if (argv.length === 0 || argv.includes("--help") || argv.includes("-h")) {
-        console.log(`SuperSpec 流程引擎 0.1.15-alpha
+        console.log(`SuperSpec 流程引擎 0.1.16-alpha
 
 用法：superspec <命令> [选项]
 
@@ -53,7 +53,8 @@ async function main(argv) {
   transition <子命令> --change <C>  状态流转（见下）
   record <子命令> --change <C>      登记证据（见下）
   jobs <子命令> --change <C>        工作项管理（见下）
-  install [--global]               安装到项目或全局
+  install                           安装项目工作流入口
+  init --scope project              install 的兼容别名
   update                           更新 SuperSpec
   version                          版本号
 
@@ -74,36 +75,31 @@ jobs 子命令：
     }
     // version
     if (argv[0] === "version" || argv[0] === "--version" || argv[0] === "-v") {
-        console.log("SuperSpec 0.1.15-alpha");
+        console.log("SuperSpec 0.1.16-alpha");
         return 0;
     }
     const { command, subcommand, opts } = parseArgs(argv);
     const projectRoot = process.cwd();
-    // install / update 不需要 --change
-    if (command === "install") {
-        const { mkdirSync, writeFileSync, existsSync, readdirSync, readFileSync } = await import("node:fs");
-        const engineDir = join(projectRoot, ".superspec");
-        // 检测老版残留（0.x 的 superspec-state.json / superspec-state.lock）
-        const oldStateFiles = ["superspec-state.json", "superspec-state.lock", "ledger.jsonl"];
-        const foundOld = oldStateFiles.some(f => existsSync(join(projectRoot, "openspec", "changes")) &&
-            readdirSync(join(projectRoot, "openspec", "changes")).some(c => existsSync(join(projectRoot, "openspec", "changes", c, ".superspec", f))));
-        if (foundOld) {
+    // install / init / update 不需要 --change
+    if (command === "install" || command === "init") {
+        if (command === "init" && opts.scope && opts.scope !== "project") {
             console.log(JSON.stringify({
                 ok: false,
-                message: "检测到老版 SuperSpec (0.x) 的状态文件。\n" +
-                    "SuperSpec 0.1.15-alpha 是全新引擎，不兼容 0.x 的状态格式。\n" +
-                    "请先用老版（0.1.x）完成或归档现有 change，再安装 0.1.15-alpha。\n" +
-                    "或在全新项目目录中安装。",
+                message: "当前 beta 只支持 init --scope project",
+            }));
+            return 1;
+        }
+        try {
+            console.log(JSON.stringify(installProject(projectRoot)));
+            return 0;
+        }
+        catch (err) {
+            console.log(JSON.stringify({
+                ok: false,
+                message: err.message,
             }));
             return 1;
         }
-        if (!existsSync(engineDir))
-            mkdirSync(join(engineDir, "changes"), { recursive: true });
-        const gitignorePath = join(engineDir, ".gitignore");
-        if (!existsSync(gitignorePath))
-            writeFileSync(gitignorePath, "changes/\n*.log\n*.tmp\n");
-        console.log(JSON.stringify({ ok: true, message: "SuperSpec 0.1.15-alpha 已安装" }));
-        return 0;
     }
     if (command === "update") {
         // 检测是否从老版 update 过来
@@ -112,13 +108,13 @@ jobs 子命令：
         if (isLegacyUpdate) {
             console.log(JSON.stringify({
                 ok: false,
-                message: "SuperSpec 0.1.15-alpha 是全新引擎，不能从 0.x 直接 update。\n" +
-                    "请用 npm install -g @peterxiaoyang/superspec@0.1.15-alpha 手动安装。\n" +
+                message: "SuperSpec 0.1.16-alpha 是全新引擎，不能从 0.x 直接 update。\n" +
+                    "请用 npm install -g @peterxiaoyang/superspec@0.1.16-alpha 手动安装。\n" +
                     "现有 change 请先用 0.1.x 完成归档。",
             }));
             return 1;
         }
-        console.log(JSON.stringify({ ok: true, message: "已是最新版本 0.1.15-alpha" }));
+        console.log(JSON.stringify({ ok: true, message: "已是最新版本 0.1.16-alpha" }));
         return 0;
     }
     const change = opts.change;
@@ -156,7 +152,10 @@ jobs 子命令：
                         console.log(JSON.stringify(transitionInit(projectRoot, change, cr), null, 2));
                         return 0;
                     case "explore":
-                        console.log(JSON.stringify(transitionExplore(projectRoot, change, cr), null, 2));
+                        {
+                            const risk = opts.risk ?? "normal";
+                            console.log(JSON.stringify(transitionExplore(projectRoot, change, cr, risk), null, 2));
+                        }
                         return 0;
                     case "sync": {
                         const snapshot = rebuildSnapshot(projectRoot, change, cr, openspecStatus(projectRoot, change));
@@ -289,7 +288,7 @@ jobs 子命令：
                 }
             }
             default:
-                console.error(`未知命令：${command}。可用：status, transition, record, jobs`);
+                console.error(`未知命令：${command}。可用：status, transition, record, jobs, install, init, update, version`);
                 return 1;
         }
     }

package/dist/install.d.ts

@@ -0,0 +1,18 @@
+export declare const WORKFLOW_SKILLS: readonly ["superspec-explore", "superspec-propose", "superspec-apply", "superspec-review", "superspec-archive"];
+export declare const WORKFLOW_PROMPTS: readonly ["architect.md", "code-reviewer.md", "critic.md", "executor.md", "explore.md", "final-audit.md", "proposal-auditor.md", "test-engineer.md", "test-runner.md", "verifier.md"];
+export declare const WORKFLOW_AGENTS: readonly ["architect.toml", "code-reviewer.toml", "critic.toml", "executor.toml", "explore.toml", "final-audit.toml", "proposal-auditor.toml", "test-engineer.toml", "test-runner.toml", "verifier.toml"];
+export interface InstallResult {
+    ok: boolean;
+    message: string;
+    installed: {
+        engine_dir: string;
+        skills: string[];
+        prompts: string[];
+        agents: string[];
+        config: string;
+    };
+}
+export interface InstallOptions {
+    templateRoot?: string;
+}
+export declare function installProject(projectRoot: string, options?: InstallOptions): InstallResult;

package/dist/install.js

@@ -0,0 +1,161 @@
+import { copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+export const WORKFLOW_SKILLS = [
+    "superspec-explore",
+    "superspec-propose",
+    "superspec-apply",
+    "superspec-review",
+    "superspec-archive",
+];
+export const WORKFLOW_PROMPTS = [
+    "architect.md",
+    "code-reviewer.md",
+    "critic.md",
+    "executor.md",
+    "explore.md",
+    "final-audit.md",
+    "proposal-auditor.md",
+    "test-engineer.md",
+    "test-runner.md",
+    "verifier.md",
+];
+export const WORKFLOW_AGENTS = [
+    "architect.toml",
+    "code-reviewer.toml",
+    "critic.toml",
+    "executor.toml",
+    "explore.toml",
+    "final-audit.toml",
+    "proposal-auditor.toml",
+    "test-engineer.toml",
+    "test-runner.toml",
+    "verifier.toml",
+];
+function defaultTemplateRoot() {
+    return join(import.meta.dirname, "..", "templates", "workflow");
+}
+function legacyStateFound(projectRoot) {
+    const changesRoot = join(projectRoot, "openspec", "changes");
+    if (!existsSync(changesRoot))
+        return false;
+    const oldStateFiles = ["superspec-state.json", "superspec-state.lock", "ledger.jsonl"];
+    return oldStateFiles.some(file => readdirSync(changesRoot).some(change => existsSync(join(changesRoot, change, ".superspec", file))));
+}
+function assertWorkflowTemplates(templateRoot) {
+    const missing = [];
+    for (const skill of WORKFLOW_SKILLS) {
+        const file = join(templateRoot, "skills", skill, "SKILL.md");
+        if (!existsSync(file))
+            missing.push(file);
+    }
+    for (const prompt of WORKFLOW_PROMPTS) {
+        const file = join(templateRoot, "prompts", prompt);
+        if (!existsSync(file))
+            missing.push(file);
+    }
+    for (const agent of WORKFLOW_AGENTS) {
+        const file = join(templateRoot, "agents", agent);
+        if (!existsSync(file))
+            missing.push(file);
+    }
+    if (missing.length > 0) {
+        throw new Error(`workflow templates missing: ${missing.join(", ")}`);
+    }
+}
+function copySkills(templateRoot, projectRoot) {
+    const skillsDest = join(projectRoot, ".codex", "skills");
+    const installedSkills = [];
+    for (const skill of WORKFLOW_SKILLS) {
+        const src = join(templateRoot, "skills", skill, "SKILL.md");
+        mkdirSync(join(skillsDest, skill), { recursive: true });
+        copyFileSync(src, join(skillsDest, skill, "SKILL.md"));
+        installedSkills.push(skill);
+    }
+    return installedSkills;
+}
+function copyPrompts(templateRoot, projectRoot) {
+    const promptsDest = join(projectRoot, ".codex", "prompts");
+    const installedPrompts = [];
+    for (const prompt of WORKFLOW_PROMPTS) {
+        const src = join(templateRoot, "prompts", prompt);
+        mkdirSync(promptsDest, { recursive: true });
+        copyFileSync(src, join(promptsDest, prompt));
+        installedPrompts.push(prompt);
+    }
+    return installedPrompts;
+}
+function copyAgents(templateRoot, projectRoot) {
+    const agentsDest = join(projectRoot, ".codex", "agents");
+    const installedAgents = [];
+    for (const agent of WORKFLOW_AGENTS) {
+        const src = join(templateRoot, "agents", agent);
+        mkdirSync(agentsDest, { recursive: true });
+        copyFileSync(src, join(agentsDest, agent));
+        installedAgents.push(agent);
+    }
+    return installedAgents;
+}
+function insertMissingTableEntries(content, table, entries) {
+    const tablePattern = new RegExp(`^\\[${table}\\]\\s*$`, "m");
+    const tableMatch = tablePattern.exec(content);
+    const lines = Object.entries(entries).map(([key, value]) => `${key} = ${value}`);
+    if (!tableMatch) {
+        const separator = content.trim().length === 0 ? "" : "\n\n";
+        return `${content.trimEnd()}${separator}[${table}]\n${lines.join("\n")}\n`;
+    }
+    const tableStart = tableMatch.index;
+    const headerEnd = tableStart + tableMatch[0].length;
+    const nextTable = /^\[[^\]]+\]\s*$/m.exec(content.slice(headerEnd));
+    const tableEnd = nextTable ? headerEnd + nextTable.index : content.length;
+    const tableBody = content.slice(headerEnd, tableEnd);
+    const missing = lines.filter(line => {
+        const key = line.split(" = ", 1)[0];
+        return !new RegExp(`^\\s*${key}\\s*=`, "m").test(tableBody);
+    });
+    if (missing.length === 0)
+        return content;
+    return `${content.slice(0, headerEnd)}\n${missing.join("\n")}${content.slice(headerEnd)}`;
+}
+function ensureCodexConfig(projectRoot) {
+    const codexDir = join(projectRoot, ".codex");
+    const configPath = join(codexDir, "config.toml");
+    mkdirSync(codexDir, { recursive: true });
+    const current = existsSync(configPath) ? readFileSync(configPath, "utf8") : "";
+    let next = insertMissingTableEntries(current, "features", {
+        multi_agent: "true",
+        child_agents_md: "true",
+    });
+    next = insertMissingTableEntries(next, "agents", {
+        max_threads: "12",
+        max_depth: "1",
+    });
+    if (next !== current)
+        writeFileSync(configPath, next);
+    return ".codex/config.toml";
+}
+export function installProject(projectRoot, options = {}) {
+    if (legacyStateFound(projectRoot)) {
+        throw new Error("检测到老版 SuperSpec (0.x) 的状态文件。\n" +
+            "SuperSpec 0.1.16-alpha 是全新引擎，不兼容 0.x 的状态格式。\n" +
+            "请先用老版（0.1.x）完成或归档现有 change，再安装 0.1.16-alpha。\n" +
+            "或在全新项目目录中安装。");
+    }
+    const templateRoot = options.templateRoot ?? defaultTemplateRoot();
+    assertWorkflowTemplates(templateRoot);
+    const engineDir = join(projectRoot, ".superspec");
+    mkdirSync(join(engineDir, "changes"), { recursive: true });
+    const gitignorePath = join(engineDir, ".gitignore");
+    if (!existsSync(gitignorePath))
+        writeFileSync(gitignorePath, "changes/\n*.log\n*.tmp\n");
+    return {
+        ok: true,
+        message: "SuperSpec 0.1.16-alpha 已安装",
+        installed: {
+            engine_dir: ".superspec/",
+            skills: copySkills(templateRoot, projectRoot),
+            prompts: copyPrompts(templateRoot, projectRoot),
+            agents: copyAgents(templateRoot, projectRoot),
+            config: ensureCodexConfig(projectRoot),
+        },
+    };
+}

package/dist/next.js

@@ -46,7 +46,7 @@ export function next(projectRoot, change, changeRoot, defaultRisk = "normal") {
             return {
                 state: "explore",
                 path: "next_command",
-                next_command: transitionCommand(change, "explore"),
+                next_command: transitionCommand(change, "explore", `--risk ${defaultRisk}`),
                 reason: "探索完成，推进到计划阶段",
                 missing_inputs: [],
             };

package/dist/record.js

@@ -2,6 +2,37 @@
 import { readFileSync, existsSync } from "node:fs";
 import { join } from "node:path";
 import { ensureChangeLayout, readEvents, appendEvent, makeEvent, sha256File, withLock, } from "./store.js";
+const REVIEW_REPORT_REQUIRED_FIELDS = ["role", "verdict", "findings"];
+const REVIEW_REPORT_OPTIONAL_FIELDS = ["summary", "evidence_refs", "risks", "open_questions"];
+function recommendedAgentForRole(role) {
+    switch (role) {
+        case "proposal-auditor": return "proposal-auditor";
+        case "critic": return "critic";
+        case "architect": return "architect";
+        case "test-engineer": return "test-engineer";
+        case "final-audit": return "final-audit";
+        case "executor": return "executor";
+        case "test-run": return "test-runner";
+    }
+}
+function roleDescription(role) {
+    switch (role) {
+        case "proposal-auditor":
+            return "审查 proposal/tasks/design/discovery/business-invariants/test-contract 是否足够进入实现计划门";
+        case "critic":
+            return "从反方角度审查需求澄清或计划材料中的隐藏假设、范围漂移、验收漏洞和证据缺口";
+        case "architect":
+            return "审查架构边界、接口契约、长期维护风险和设计取舍";
+        case "test-engineer":
+            return "审查测试契约、覆盖策略、RED/GREEN 可信度和验收场景映射";
+        case "final-audit":
+            return "最终审查 proposal、实现状态、任务完成、测试契约和 SuperSpec 证据一致性";
+        case "executor":
+            return "执行受限实现工作项";
+        case "test-run":
+            return "执行受限测试工作项";
+    }
+}
 /** 从 events 中查找 job（H4 修复：job 只在 transition_commit 的 new_jobs payload 里） */
 function findJob(events, jobId) {
     for (const ev of events) {
@@ -65,15 +96,34 @@ export function recordJobSubmit(projectRoot, change, changeRoot, jobId, reportFi
         const reportDigest = sha256File(reportFile) ?? "sha256:unknown";
         // acceptance checks
         const checks = [];
-        // 0. 报告角色匹配（HIGH 5 修复）
+        // 0. 报告格式和角色匹配（最小 JSON contract）
         try {
             const report = JSON.parse(reportContent);
-            if (report.role && report.role !== job.role) {
-                checks.push(`报告角色 ${report.role} 与工作项角色 ${job.role} 不匹配`);
+            if (!report || typeof report !== "object" || Array.isArray(report)) {
+                checks.push("报告必须是 JSON object");
+            }
+            else {
+                const obj = report;
+                for (const field of REVIEW_REPORT_REQUIRED_FIELDS) {
+                    if (!(field in obj))
+                        checks.push(`报告缺少必填字段 ${field}`);
+                }
+                if (obj.role !== job.role) {
+                    checks.push(`报告角色 ${String(obj.role)} 与工作项角色 ${job.role} 不匹配`);
+                }
+                if (obj.verdict !== "pass" && obj.verdict !== "fail") {
+                    checks.push("报告 verdict 必须是 pass 或 fail");
+                }
+                if (!Array.isArray(obj.findings)) {
+                    checks.push("报告 findings 必须是数组");
+                }
+                if (obj.verdict === "fail") {
+                    checks.push("报告 verdict=fail，工作项未通过");
+                }
             }
         }
         catch {
-            // 非 JSON 报告，Phase 1 允许（Phase 2 加正式 schema）
+            checks.push("报告必须是有效 JSON");
         }
         // 1. boundFiles 仍匹配当前文档（missing 也算不匹配）
         for (const bf of job.boundFiles) {
@@ -199,10 +249,15 @@ export function jobsPacket(projectRoot, change, jobId) {
         packet: {
             job_id: job.job_id,
             role: job.role,
+            recommended_agent: recommendedAgentForRole(job.role),
             boundFiles: job.boundFiles,
             packet_digest: job.packet_digest,
-            required_output_kind: "report",
-            output_instructions: `请审查 ${job.boundFiles.map(f => f.path).join(", ")}，产出审查报告`,
+            required_output_kind: "job_report_json",
+            output_contract_fields: [...REVIEW_REPORT_REQUIRED_FIELDS],
+            output_contract_optional_fields: [...REVIEW_REPORT_OPTIONAL_FIELDS],
+            output_instructions: `${roleDescription(job.role)}。请审查 ${job.boundFiles.map(f => f.path).join(", ")}，` +
+                `产出 JSON 报告文件并通过 superspec record job-submit 登记。` +
+                `最小格式：{"role":"${job.role}","verdict":"pass|fail","findings":[]}`,
             stop_conditions: ["审查完成后提交报告，不要修改文档"],
             created_from_transition: job.created_from_transition,
         },

package/dist/transition.d.ts

@@ -24,7 +24,7 @@ export declare function commitTransition(projectRoot: string, change: string, ch
 }): TransitionResult;
 export declare function proposeReady(projectRoot: string, change: string, changeRoot: string, risk?: "minimal" | "normal" | "strict"): TransitionResult;
 export declare function transitionInit(projectRoot: string, change: string, changeRoot: string): TransitionResult;
-export declare function transitionExplore(projectRoot: string, change: string, changeRoot: string): TransitionResult;
+export declare function transitionExplore(projectRoot: string, change: string, changeRoot: string, risk?: "minimal" | "normal" | "strict"): TransitionResult;
 export declare function startApply(projectRoot: string, change: string, changeRoot: string): TransitionResult;
 export declare function taskStart(projectRoot: string, change: string, changeRoot: string, taskId: string): TransitionResult;
 export declare function reviewReady(projectRoot: string, change: string, changeRoot: string, risk?: "minimal" | "normal" | "strict"): TransitionResult;

package/dist/transition.js

@@ -12,12 +12,12 @@ const TRANSITION_REQUIREMENTS = {
     "propose-ready": {
         minimal: [],
         normal: ["proposal-auditor"],
-        strict: ["critic-review", "architect-review", "test-engineer-review"],
+        strict: ["proposal-auditor", "critic", "architect", "test-engineer"],
     },
     "explore": {
         minimal: [],
         normal: [],
-        strict: ["clarification-review"],
+        strict: ["critic"],
     },
 };
 /**
@@ -172,9 +172,9 @@ export function transitionInit(projectRoot, change, changeRoot) {
     });
 }
 // ===== explore =====
-export function transitionExplore(projectRoot, change, changeRoot) {
+export function transitionExplore(projectRoot, change, changeRoot, risk = "normal") {
     return commitTransition(projectRoot, change, changeRoot, {
-        name: "explore", idempotencyInputs: { phase: "explore" },
+        name: "explore", idempotencyInputs: { phase: "explore", risk },
         decide: (snapshot) => {
             if (snapshot.state === "init")
                 return { fromState: "init", toState: "explore", outcome: "advanced", reason: "进入探索阶段" };
@@ -182,12 +182,12 @@ export function transitionExplore(projectRoot, change, changeRoot) {
                 const discoveryPath = join(changeRoot, ".superspec", "artifacts", "discovery.md");
                 if (!existsSync(discoveryPath))
                     return { skip: true, message: "discovery.md 不存在" };
-                // explore→propose：校验 discovery + 通用 job 审查（normal+ 需 clarification-review）
+                // explore→propose：校验 discovery + strict 模式下的 critic 审查
                 const discoveryCheck = validateDiscovery(changeRoot);
                 if (!discoveryCheck.ok)
                     return { skip: true, message: discoveryCheck.message };
                 // 通用 job 审查（和 propose-ready 同一个 helper）
-                const requiredRoles = TRANSITION_REQUIREMENTS["explore"]?.["normal"] ?? [];
+                const requiredRoles = TRANSITION_REQUIREMENTS["explore"]?.[risk] ?? [];
                 const reviewResult = checkOrCreateReviewJobs(snapshot, requiredRoles, changeRoot, change, "explore", [".superspec/artifacts/discovery.md"]);
                 if (reviewResult)
                     return reviewResult;

package/dist/types.d.ts

@@ -5,7 +5,7 @@ export type Ref = {
     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 type JobRole = "proposal-auditor" | "critic" | "architect" | "test-engineer" | "executor" | "test-run" | "final-audit";
 export interface Job {
     job_id: string;
     role: JobRole;
@@ -18,9 +18,12 @@ export interface Job {
 export interface JobPacket {
     job_id: string;
     role: JobRole;
+    recommended_agent?: string;
     boundFiles: Ref[];
     packet_digest: string;
     required_output_kind: string;
+    output_contract_fields?: string[];
+    output_contract_optional_fields?: string[];
     stop_conditions: string[];
     created_from_transition: string;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peterxiaoyang/superspec",
-  "version": "0.1.15-alpha",
+  "version": "0.1.16-alpha",
   "description": "SuperSpec 流程引擎 — transition engine with lightweight fact-sync",
   "type": "module",
   "engines": { "node": ">=20.19.0" },

package/templates/workflow/agents/architect.toml

@@ -0,0 +1,13 @@
+# SuperSpec Codex agent: architect
+name = "architect"
+description = "System design, boundaries, interfaces, long-horizon tradeoffs"
+model_reasoning_effort = "high"
+developer_instructions = """
+Role: Architect. Review system boundaries, interface contracts, data flow, maintenance risk, rollback risk, and design tradeoffs.
+
+Prompt binding: load `.codex/prompts/architect.md` first, then read the provided `review-packet`, job packet, or `prompt_ref`. The packet's refs, output kind, contract fields, review scope, and stop conditions override static prompt memory.
+
+Boundary: read-only. Do not edit files or judge materials you have not opened. Report missing context upward instead of guessing.
+
+Output: concise Simplified Chinese. For `job_report_json`, submit JSON with `role:"architect"`, `verdict`, and `findings`. Otherwise put the conclusion first, cite file:line evidence, and write `无阻塞问题` when no blocking issue is found.
+"""

package/templates/workflow/agents/code-reviewer.toml

@@ -0,0 +1,13 @@
+# SuperSpec Codex agent: code-reviewer
+name = "code-reviewer"
+description = "Comprehensive review across all concerns"
+model_reasoning_effort = "high"
+developer_instructions = """
+Role: Code Reviewer. Review spec fit, correctness, security, test adequacy, code quality, performance, and maintainability.
+
+Prompt binding: load `.codex/prompts/code-reviewer.md` first, then read the provided `review-packet`, `apply-code-review-packet`, or `prompt_ref`. The packet's refs, output kind, contract fields, review scope, declared write scope, executor report refs, and stop conditions override static prompt memory.
+
+Boundary: read-only. Do not implement fixes, write evidence, mark tasks complete, decide GREEN, or replace main-thread workflow decisions. Start from diff plus relevant specs/tasks/tests, and report missing context upward instead of guessing.
+
+Output: concise Simplified Chinese. Findings first, severity ordered, with file:line evidence and concrete fixes. Write `无阻塞问题` when no blocking issue is found.
+"""