@peterxiaoyang/superspec 0.1.53 → 0.1.55

package/README.md

@@ -33,14 +33,14 @@ superspec status
 
 ## 工作流入口
 
-在 Codex 中显式调用对应 Skill。新需求通常从 `$superspec-explore` 开始；已有 change 则从当前阶段继续。
+在 Codex 中显式调用对应 Skill。新需求通常从 `superspec-explore` 开始；已有 change 则从当前阶段继续。
 
 | Skill | 作用 |
 | --- | --- |
-| `$superspec-explore` | 调查现状，确认事实和待决策事项 |
-| `$superspec-propose` | 生成规格、设计和可执行任务 |
-| `$superspec-apply` | 按已批准任务修改代码并验证 |
-| `$superspec-review` | 审查实现并完成最终验证 |
+| `superspec-explore` | 调查现状，确认事实和待决策事项 |
+| `superspec-propose` | 生成规格、设计和可执行任务 |
+| `superspec-apply` | 按已批准任务修改代码并验证 |
+| `superspec-review` | 审查实现并完成最终验证 |
 
 工作流会根据问题性质留在当前阶段修复，或回到计划阶段重新确认需求、验收和技术取舍。
 
@@ -51,7 +51,8 @@ superspec status
 ```json
 {
   "workflow": {
-    "mode": "normal"
+    "mode": "normal",
+    "hosts": ["codex"]
   }
 }
 ```

package/dist/cli.js

@@ -13,7 +13,7 @@ import { recordTestRun, recordTestRunContent } from "./task.js";
 import { RecordInputDecodingError, decodeRecordInput } from "./record_input.js";
 import { probeOpenSpec, openspecStatus, changeRoot } from "./openspec.js";
 import { SUPERSPEC_VERSION } from "./version.js";
-import { WorkflowConfigError, workflowRiskForProject } from "./workflow_config.js";
+import { DEFAULT_WORKFLOW_HOSTS, parseWorkflowHostsFlag, WorkflowConfigError, workflowHostsDeclared, workflowHostsForProject, workflowRiskForProject, } from "./workflow_config.js";
 const PACKAGE_NAME = "@peterxiaoyang/superspec";
 const OPENSPEC_PACKAGE_NAME = "@fission-ai/openspec";
 const OPENSPEC_REQUIRED_VERSION = "1.4.1";
@@ -490,6 +490,55 @@ async function askToUpdateSelfIfNeeded(projectRoot, rerunArgs) {
         throw attachSelfUpdateLatest(err, "rerun", latest);
     }
 }
+function parseSelectedHosts(raw) {
+    if (!raw)
+        return DEFAULT_WORKFLOW_HOSTS;
+    return parseWorkflowHostsFlag(raw);
+}
+function parseHostPromptAnswer(raw) {
+    const tokens = raw.toLowerCase().split(/[,\s]+/).filter(Boolean);
+    if (tokens.length === 0)
+        return DEFAULT_WORKFLOW_HOSTS;
+    const selected = [];
+    for (const token of tokens) {
+        if (token === "1" || token === "codex")
+            selected.push("codex");
+        else if (token === "2" || token === "omp")
+            selected.push("omp");
+        else if (token === "both" || token === "all")
+            selected.push("codex", "omp");
+        else
+            throw new WorkflowConfigError(`无法识别的宿主选项：${token}。可用 1/codex、2/omp，或 both`);
+    }
+    return parseWorkflowHostsFlag(selected.join(","));
+}
+async function resolveInstallHosts(projectRoot, opts, mode) {
+    if (opts.hosts)
+        return parseSelectedHosts(opts.hosts);
+    if (mode === "update" || workflowHostsDeclared(projectRoot))
+        return workflowHostsForProject(projectRoot);
+    const assumeTty = testEnv("SUPERSPEC_TEST_ASSUME_TTY") === "1";
+    if (!assumeTty && (!process.stdin.isTTY || !process.stdout.isTTY))
+        return DEFAULT_WORKFLOW_HOSTS;
+    const testAnswer = testEnv("SUPERSPEC_TEST_HOSTS_ANSWER");
+    if (testAnswer !== undefined)
+        return parseHostPromptAnswer(testAnswer);
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        const answer = await rl.question("选择 SuperSpec 入口宿主：1) Codex  2) OMP。可多选，例如 1,2；直接回车默认 Codex。 ");
+        return parseHostPromptAnswer(answer);
+    }
+    finally {
+        rl.close();
+    }
+}
+function installOptionsFromCli(opts, hosts, allowLegacyState = false) {
+    return {
+        hosts,
+        allowLegacyState,
+        ...(opts["omp-home"] ? { ompHome: opts["omp-home"] } : {}),
+    };
+}
 // ===== 初始化 transition init =====
 // ===== init/explore 现在在 transition.ts 中（走统一锁内路径）=====
 // ===== 主分发 =====
@@ -503,9 +552,9 @@ function topLevelHelp() {
   transition <子命令> --change <C>  状态流转（见下）
   record <子命令> --change <C>      登记证据（见下）
   jobs <子命令> --change <C>        工作项管理（见下）
-  install                           安装项目工作流入口
+  install [--hosts codex,omp]       安装项目工作流入口
   init --scope project              install 的兼容别名
-  update                            升级 CLI 到 npm latest 并同步项目工作流模板
+  update [--hosts codex,omp]        升级 CLI 到 npm latest 并同步已选宿主入口
   version                           版本号
 
 transition 子命令：
@@ -589,10 +638,14 @@ async function main(argv) {
             return 1;
         }
         try {
+            const hosts = await resolveInstallHosts(projectRoot, opts, "install");
             if (opts["skip-self-update"] !== "true") {
+                const hostArgs = ["--hosts", hosts.join(",")];
+                if (opts["omp-home"])
+                    hostArgs.push("--omp-home", opts["omp-home"]);
                 const rerunArgs = command === "init"
-                    ? ["init", "--scope", "project", "--skip-self-update"]
-                    : ["install", "--skip-self-update"];
+                    ? ["init", "--scope", "project", "--skip-self-update", ...hostArgs]
+                    : ["install", "--skip-self-update", ...hostArgs];
                 const selfUpdate = await askToUpdateSelfIfNeeded(projectRoot, rerunArgs);
                 if (selfUpdate.updated) {
                     const rerun = updatedCliOutput(selfUpdate.output, selfUpdate.latest);
@@ -602,7 +655,7 @@ async function main(argv) {
             }
             const openspec = ensureOpenSpecCli();
             console.log(JSON.stringify({
-                ...installProject(projectRoot),
+                ...installProject(projectRoot, installOptionsFromCli(opts, hosts)),
                 openspec,
             }));
             return 0;
@@ -612,14 +665,20 @@ async function main(argv) {
                 ? selfUpdateFailurePayload(err)
                 : err instanceof OpenSpecDependencyError
                     ? openSpecDependencyFailurePayload(err)
-                    : { ok: false, message: commandErrorMessage(err) }));
+                    : err instanceof WorkflowConfigError
+                        ? { ok: false, message: err.message }
+                        : { ok: false, message: commandErrorMessage(err) }));
             return 1;
         }
     }
     if (command === "update") {
         try {
+            const hosts = await resolveInstallHosts(projectRoot, opts, "update");
             if (opts["skip-self-update"] !== "true") {
-                const selfUpdate = updateSelfIfNeeded(projectRoot, ["update", "--skip-self-update"]);
+                const hostArgs = ["--hosts", hosts.join(",")];
+                if (opts["omp-home"])
+                    hostArgs.push("--omp-home", opts["omp-home"]);
+                const selfUpdate = updateSelfIfNeeded(projectRoot, ["update", "--skip-self-update", ...hostArgs]);
                 if (selfUpdate.updated) {
                     const rerun = updatedCliOutput(selfUpdate.output, selfUpdate.latest);
                     console.log(rerun.text);
@@ -627,7 +686,7 @@ async function main(argv) {
                 }
             }
             const openspec = ensureOpenSpecCli();
-            const result = installProject(projectRoot, { allowLegacyState: true });
+            const result = installProject(projectRoot, installOptionsFromCli(opts, hosts, true));
             console.log(JSON.stringify({
                 ...result,
                 openspec,
@@ -640,7 +699,9 @@ async function main(argv) {
                 ? selfUpdateFailurePayload(err)
                 : err instanceof OpenSpecDependencyError
                     ? openSpecDependencyFailurePayload(err)
-                    : { ok: false, message: commandErrorMessage(err) }));
+                    : err instanceof WorkflowConfigError
+                        ? { ok: false, message: err.message }
+                        : { ok: false, message: commandErrorMessage(err) }));
             return 1;
         }
     }

package/dist/install.d.ts

@@ -1,14 +1,23 @@
+import { type WorkflowHost } from "./workflow_config.ts";
 export declare const WORKFLOW_SKILLS: readonly ["superspec-explore", "superspec-propose", "superspec-apply", "superspec-review"];
 export declare const WORKFLOW_PROMPTS: readonly ["architect.md", "code-reviewer.md", "critic.md", "executor.md", "explore.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", "test-engineer.toml", "test-runner.toml", "verifier.toml"];
+export declare const WORKFLOW_MARKDOWN_AGENTS: readonly ["architect.md", "code-reviewer.md", "critic.md", "executor.md", "explore.md", "test-engineer.md", "test-runner.md", "verifier.md"];
+export interface OmpInstallResult {
+    dest: string | null;
+    agents: string[];
+    skipped: string | null;
+}
 export interface InstallResult {
     ok: boolean;
     message: string;
     installed: {
         engine_dir: string;
+        hosts: WorkflowHost[];
         skills: string[];
         prompts: string[];
         agents: string[];
+        omp: OmpInstallResult;
         config: string;
         workflow_config: string;
         agents_md: string;
@@ -18,5 +27,7 @@ export interface InstallResult {
 export interface InstallOptions {
     templateRoot?: string;
     allowLegacyState?: boolean;
+    hosts?: WorkflowHost[];
+    ompHome?: string;
 }
 export declare function installProject(projectRoot: string, options?: InstallOptions): InstallResult;

package/dist/install.js

@@ -1,7 +1,8 @@
-import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { SUPERSPEC_VERSION } from "./version.js";
-import { DEFAULT_WORKFLOW_RISK, WORKFLOW_CONFIG_PATH } from "./workflow_config.js";
+import { DEFAULT_WORKFLOW_HOSTS, persistWorkflowHosts, workflowHostsDeclared, workflowHostsForProject, } from "./workflow_config.js";
 export const WORKFLOW_SKILLS = [
     "superspec-explore",
     "superspec-propose",
@@ -29,6 +30,16 @@ export const WORKFLOW_AGENTS = [
     "test-runner.toml",
     "verifier.toml",
 ];
+export const WORKFLOW_MARKDOWN_AGENTS = [
+    "architect.md",
+    "code-reviewer.md",
+    "critic.md",
+    "executor.md",
+    "explore.md",
+    "test-engineer.md",
+    "test-runner.md",
+    "verifier.md",
+];
 function defaultTemplateRoot() {
     return join(import.meta.dirname, "..", "templates", "workflow");
 }
@@ -56,6 +67,11 @@ function assertWorkflowTemplates(templateRoot) {
         if (!existsSync(file))
             missing.push(file);
     }
+    for (const agent of WORKFLOW_MARKDOWN_AGENTS) {
+        const file = join(templateRoot, "agents-md", agent);
+        if (!existsSync(file))
+            missing.push(file);
+    }
     const agentsMdTemplate = join(templateRoot, "AGENTS.md");
     if (!existsSync(agentsMdTemplate))
         missing.push(agentsMdTemplate);
@@ -248,14 +264,44 @@ function ensureOpenSpecChineseContext(projectRoot) {
     writeFileSync(configPath, next);
     return OPENSPEC_CONFIG_PATH;
 }
-function ensureWorkflowConfig(projectRoot) {
-    const configPath = join(projectRoot, WORKFLOW_CONFIG_PATH);
-    mkdirSync(dirname(configPath), { recursive: true });
-    if (!existsSync(configPath)) {
-        // install/update 是显式迁移动作：为以后各轮写入 normal 默认值。
-        writeFileSync(configPath, JSON.stringify({ workflow: { mode: DEFAULT_WORKFLOW_RISK } }, null, 2) + "\n");
+function copyOmpAgents(templateRoot, dest) {
+    const agentsDest = join(dest, "agents");
+    const installedAgents = [];
+    for (const agent of WORKFLOW_MARKDOWN_AGENTS) {
+        const src = join(templateRoot, "agents-md", agent);
+        writeBundledFile(src, join(agentsDest, agent));
+        installedAgents.push(agent);
     }
-    return WORKFLOW_CONFIG_PATH;
+    return installedAgents;
+}
+function existingDirectory(path) {
+    try {
+        return statSync(path).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function resolveOmpAgentHome(explicitHome) {
+    if (explicitHome) {
+        return existingDirectory(explicitHome)
+            ? { dest: explicitHome, skipped: null }
+            : { dest: null, skipped: `OMP 用户目录不存在：${explicitHome}` };
+    }
+    const profile = (process.env.OMP_PROFILE ?? process.env.PI_PROFILE ?? "").trim();
+    const dest = profile && profile !== "default"
+        ? join(homedir(), ".omp", "profiles", profile, "agent")
+        : join(homedir(), ".omp", "agent");
+    if (!existingDirectory(dest)) {
+        return { dest: null, skipped: `OMP 用户目录不存在：${dest}。先启动一次 omp，或用 --omp-home 指定已有目录。` };
+    }
+    return { dest, skipped: null };
+}
+function installOmpAgents(templateRoot, ompHome) {
+    const resolved = resolveOmpAgentHome(ompHome);
+    if (!resolved.dest)
+        return { dest: null, agents: [], skipped: resolved.skipped };
+    return { dest: resolved.dest, agents: copyOmpAgents(templateRoot, resolved.dest), skipped: null };
 }
 const AGENTS_MD_PATH = "AGENTS.md";
 const SUPERSPEC_AGENTS_START = "<!-- SUPERSPEC:AGENTS:START -->";
@@ -299,22 +345,31 @@ export function installProject(projectRoot, options = {}) {
     const templateRoot = options.templateRoot ?? defaultTemplateRoot();
     assertWorkflowTemplates(templateRoot);
     const agentsMdTemplate = readAgentsMdTemplate(templateRoot);
+    const hosts = options.hosts
+        ?? (workflowHostsDeclared(projectRoot) ? workflowHostsForProject(projectRoot) : DEFAULT_WORKFLOW_HOSTS);
+    const wantsCodex = hosts.includes("codex");
+    const wantsOmp = hosts.includes("omp");
     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");
     migrateLegacyManagedHooks(projectRoot);
+    const omp = wantsOmp
+        ? installOmpAgents(templateRoot, options.ompHome)
+        : { dest: null, agents: [], skipped: null };
     return {
         ok: true,
         message: `SuperSpec ${SUPERSPEC_VERSION} 已安装`,
         installed: {
             engine_dir: ".superspec/",
+            hosts,
             skills: copySkills(templateRoot, projectRoot),
-            prompts: copyPrompts(templateRoot, projectRoot),
-            agents: copyAgents(templateRoot, projectRoot),
-            config: ensureCodexConfig(projectRoot),
-            workflow_config: ensureWorkflowConfig(projectRoot),
+            prompts: wantsCodex ? copyPrompts(templateRoot, projectRoot) : [],
+            agents: wantsCodex ? copyAgents(templateRoot, projectRoot) : [],
+            omp,
+            config: wantsCodex ? ensureCodexConfig(projectRoot) : "",
+            workflow_config: persistWorkflowHosts(projectRoot, hosts),
             agents_md: ensureAgentsMd(projectRoot, agentsMdTemplate),
             openspec_config: ensureOpenSpecChineseContext(projectRoot),
         },

package/dist/record.js

@@ -16,7 +16,7 @@ import { currentProposeOpenQuestion, currentProposeQuestionContent, currentPropo
 import { discoveryOpenQuestionDisplayText, discoveryQuestionContextFingerprint, discoveryQuestionDecisionBasisDigest, discoveryOpenQuestionScope, legacyDiscoveryOpenQuestionScope, EXPLORE_OPEN_QUESTION_SCOPE_PREFIX, parseDiscoveryOpenQuestions, proposeOpenQuestionDisplayText, proposeOpenQuestionScope, proposeQuestionContextFingerprint, proposeQuestionDecisionBasisDigest, legacyProposeOpenQuestionScope, PROPOSE_OPEN_QUESTION_SCOPE_PREFIX, } from "./format.js";
 const REVIEW_REPORT_REQUIRED_FIELDS = ["role", "verdict", "findings"];
 const REVIEW_REPORT_OPTIONAL_FIELDS = ["summary", "evidence_refs", "risks", "open_questions"];
-const REVIEWER_KINDS = new Set(["codex-subagent", "human", "external-agent"]);
+const REVIEWER_KINDS = new Set(["subagent", "codex-subagent", "human", "external-agent"]);
 const CODE_REVIEW_FINDING_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._:-]*$/;
 function isReviewRole(role) {
     return role === "critic" || role === "architect" || role === "test-engineer" || role === "code-reviewer" || role === "verifier";
@@ -1234,7 +1234,7 @@ export function jobsPacket(projectRoot, change, jobId) {
                 (requiresReviewer(job.role) ? `必须由独立 ${recommendedAgentForRole(job.role)} 审查角色执行，并在审查者来源字段（reviewer.kind/id）中记录来源，` : "") +
                 `产出 JSON 报告内容并优先通过 --report - 从 stdin 登记；文件路径模式仅作备用。${recordInputInstruction(job)}协议字段含义见 packet 顶层“字段说明”，普通对话不要原样复述 JSON。` +
                 (isCodeReviewer
-                    ? `格式骨架：{"role":"code-reviewer","verdict":"pass","review_scope":{"job_id":"${job.job_id}","packet_digest":"${job.packet_digest}","checked_paths":[],"checked_docs":[],"unchecked":[]},"findings":[],"reviewer":{"kind":"codex-subagent","id":"<thread-or-agent-id>"}}。提交前按真实审查结果填写数组；不得从 boundFiles 自动复制 checked_paths。verdict 只能为 pass 或 fail；审查覆盖范围（review_scope）用来说明本次审查覆盖了哪些文件和文档，已检查路径（checked_paths）与未检查项（unchecked）必须合起来覆盖全部绑定文件（boundFiles），unchecked 条目格式为 {"path":"<path>","reason":"<reason>"}；pass 不允许仍有未检查的绑定文件。`
+                    ? `格式骨架：{"role":"code-reviewer","verdict":"pass","review_scope":{"job_id":"${job.job_id}","packet_digest":"${job.packet_digest}","checked_paths":[],"checked_docs":[],"unchecked":[]},"findings":[],"reviewer":{"kind":"subagent","id":"<thread-or-agent-id>"}}。提交前按真实审查结果填写数组；不得从 boundFiles 自动复制 checked_paths。verdict 只能为 pass 或 fail；审查覆盖范围（review_scope）用来说明本次审查覆盖了哪些文件和文档，已检查路径（checked_paths）与未检查项（unchecked）必须合起来覆盖全部绑定文件（boundFiles），unchecked 条目格式为 {"path":"<path>","reason":"<reason>"}；pass 不允许仍有未检查的绑定文件。`
                         + `报告结论为 fail 时，问题列表（findings）至少包含一个可处理、可追溯的阻塞问题，字段为 {"id":"<stable-id>","blocking":true,"type":"implementation|spec|mixed","description":"<what>","evidence":"<why>","source_refs":["<path:line>"],"impact":"<impact>","suggested_action":"apply|propose"}。问题类型（type）中 implementation 表示纯代码实现问题，spec 表示方案/需求文档问题，mixed 表示需要使用者判断的混合问题。`
                         + (packetContext?.task_execution_index
                             ? `本工作项带任务执行索引（task_execution_index）：按 task 对照其执行依据快照（contract）审查——实现路线对照 design 引用原文、累计 diff 对照 guard 边界、测试断言对照 tests 声明的 scenario；每项的 required_evidence 是 task-start 冻结的证据口径，red_required/green_required 分别说明是否需要 RED/GREEN；fix 非空表示状态机创建的实现修复，source、parent_task_id 和 reason 说明其归属，code_review 来源还需核对 review_finding；scope_note 既可能解释必要的范围扩大，也可能说明代码审查修复为何保留原实现，均需结合 Diff、调用链和验证证据独立判断；changed_paths 是归属线索不是结论（null 表示未知）；unattributed_paths 中的无主改动逐个判断合理性；coverage_exemption_refs 解释未绑定 task 的 TEST 豁免。当前 packet 的 boundFiles 是本轮冻结的审查范围；若它来自前一轮审查后的增量，只复核本轮变化及其直接影响链路，不要求重复审查未变化文件，但仍要判断批准行为是否完整闭合。`
@@ -1245,7 +1245,7 @@ export function jobsPacket(projectRoot, change, jobId) {
                                 ? `本工作项带代码状态检查（code_state_check），它是创建 packet 时的快照：验证期间若代码状态已变化，不要提交该报告；主流程会通过 next 创建携带最新事实的验证工作项。`
                                 : "")
                         : isReviewer
-                            ? `最小格式：{"role":"${job.role}","verdict":"pass","findings":[]${hasReviewScope ? `,"review_scope":{"checked_paths":${JSON.stringify(job.boundFiles.map(file => file.path))}}` : ""},"reviewer":{"kind":"codex-subagent","id":"<thread-or-agent-id>"}}。verdict 只能为 pass 或 fail。`
+                            ? `最小格式：{"role":"${job.role}","verdict":"pass","findings":[]${hasReviewScope ? `,"review_scope":{"checked_paths":${JSON.stringify(job.boundFiles.map(file => file.path))}}` : ""},"reviewer":{"kind":"subagent","id":"<thread-or-agent-id>"}}。verdict 只能为 pass 或 fail。`
                             : `最小格式：{"role":"${job.role}","verdict":"pass","findings":[]}。verdict 只能为 pass 或 fail。`),
             stop_conditions: isReviewer
                 ? ["完成审查后提交报告，不要修改文档"]

package/dist/transition.js

@@ -1016,6 +1016,24 @@ function applyPlanningMaterialsChanged(changeRoot, events) {
     const baseline = latestApplyPlanningBaseline(events);
     return baseline != null && applyPlanningDocsChangedSinceBaseline(changeRoot, baseline);
 }
+/**
+ * self-test-fix 由使用者明确指定已完成的父 task；它可以修复早于当前
+ * Apply round 的实现问题。普通 Apply 仍只消费当前轮完成事件，这个查询
+ * 只用于自测修复的人工关联，不改变任务完成判定。
+ */
+function hasHistoricalTaskCompletion(events, taskId) {
+    return events.some(event => {
+        if (event.event_type !== "task_completed")
+            return false;
+        const payload = event.payload;
+        if (payload.task_id !== taskId || typeof payload.attempt_id !== "string")
+            return false;
+        const checkboxUpdate = payload.checkbox_update;
+        if (!checkboxUpdate || typeof checkboxUpdate !== "object" || Array.isArray(checkboxUpdate))
+            return true;
+        return checkboxUpdate.status !== "failed";
+    });
+}
 function proposalReopenBaseline(changeRoot, events, source) {
     const applyBaseline = ["apply", "apply_done", "review"].includes(source)
         ? latestApplyPlanningBaseline(events)
@@ -1154,7 +1172,9 @@ export function reopen(projectRoot, change, changeRoot, to, reason, opts = {}) {
                 if (pendingStatus.pending.length > 0 || snapshot.active_task_attempts.some(attempt => attempt.state === "active")) {
                     return { skip: true, message: "自测修复只允许在当前 task 全部完成且没有活跃执行尝试后创建" };
                 }
-                if (pendingStatus.mode === "contract" && !pendingStatus.completedByEvent.includes(parentTaskId)) {
+                if (pendingStatus.mode === "contract" &&
+                    !pendingStatus.completedByEvent.includes(parentTaskId) &&
+                    !hasHistoricalTaskCompletion(events, parentTaskId)) {
                     return { skip: true, message: `自测修复关联的 task ${parentTaskId} 缺少完成事件，不能只依赖 checkbox` };
                 }
                 if (pendingStatus.mode === "legacy" && !parentTask.done) {

package/dist/workflow_config.d.ts

@@ -3,9 +3,19 @@ import type { Event, State } from "./types.ts";
 export declare const WORKFLOW_CONFIG_PATH = ".superspec/config.json";
 /** 项目未声明 workflow.mode 时采用的默认档位。 */
 export declare const DEFAULT_WORKFLOW_RISK: ReviewRisk;
+export declare const WORKFLOW_HOSTS: readonly ["codex", "omp"];
+export type WorkflowHost = (typeof WORKFLOW_HOSTS)[number];
+/** 未声明 hosts 的旧项目按 Codex 入口处理。 */
+export declare const DEFAULT_WORKFLOW_HOSTS: WorkflowHost[];
 export declare class WorkflowConfigError extends Error {
     constructor(message: string);
 }
+export declare function normalizeWorkflowHosts(values: readonly string[]): WorkflowHost[];
+export declare function parseWorkflowHostsFlag(raw: string): WorkflowHost[];
+/** 读取项目已选宿主。缺少配置或缺少 workflow.hosts 时默认 Codex。 */
+export declare function workflowHostsForProject(projectRoot: string): WorkflowHost[];
+export declare function persistWorkflowHosts(projectRoot: string, hosts: WorkflowHost[]): string;
+export declare function workflowHostsDeclared(projectRoot: string): boolean;
 /**
  * Propose-ready 是一个 planning round 的冻结点。配置只影响尚未冻结的计划；
  * 已就绪计划必须沿用当时的 mode，直到 reopen 回到 propose 后创建新 round。

package/dist/workflow_config.js

@@ -1,10 +1,13 @@
 // SuperSpec 项目级工作流配置。所有阶段从同一位置解析默认 mode，
 // 避免 CLI、Explore、Propose、Review 各自保留不同默认值。
-import { existsSync, readFileSync } from "node:fs";
-import { join } from "node:path";
+import { existsSync, readFileSync, mkdirSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
 export const WORKFLOW_CONFIG_PATH = ".superspec/config.json";
 /** 项目未声明 workflow.mode 时采用的默认档位。 */
 export const DEFAULT_WORKFLOW_RISK = "normal";
+export const WORKFLOW_HOSTS = ["codex", "omp"];
+/** 未声明 hosts 的旧项目按 Codex 入口处理。 */
+export const DEFAULT_WORKFLOW_HOSTS = ["codex"];
 export class WorkflowConfigError extends Error {
     constructor(message) {
         super(message);
@@ -14,6 +17,77 @@ export class WorkflowConfigError extends Error {
 function isReviewRisk(value) {
     return value === "minimal" || value === "normal" || value === "strict";
 }
+function isWorkflowHost(value) {
+    return value === "codex" || value === "omp";
+}
+export function normalizeWorkflowHosts(values) {
+    const hosts = [...new Set(values.filter(isWorkflowHost))];
+    hosts.sort((left, right) => WORKFLOW_HOSTS.indexOf(left) - WORKFLOW_HOSTS.indexOf(right));
+    return hosts;
+}
+export function parseWorkflowHostsFlag(raw) {
+    const hosts = normalizeWorkflowHosts(raw.split(/[,\s]+/).filter(Boolean));
+    if (hosts.length === 0) {
+        throw new WorkflowConfigError(`hosts 只能是 ${WORKFLOW_HOSTS.join("、")}，至少选一个`);
+    }
+    return hosts;
+}
+function readWorkflowConfigObject(projectRoot) {
+    const configPath = join(projectRoot, WORKFLOW_CONFIG_PATH);
+    if (!existsSync(configPath))
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(configPath, "utf8"));
+    }
+    catch {
+        throw new WorkflowConfigError(`${WORKFLOW_CONFIG_PATH} 必须是有效 JSON`);
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new WorkflowConfigError(`${WORKFLOW_CONFIG_PATH} 顶层必须是 JSON object`);
+    }
+    return parsed;
+}
+function workflowObject(parsed) {
+    if (!parsed || parsed.workflow === undefined)
+        return undefined;
+    if (parsed.workflow === null || typeof parsed.workflow !== "object" || Array.isArray(parsed.workflow)) {
+        throw new WorkflowConfigError(`${WORKFLOW_CONFIG_PATH} 的 workflow 必须是 object`);
+    }
+    return parsed.workflow;
+}
+function hostsFromWorkflow(workflow) {
+    if (!workflow || workflow.hosts === undefined)
+        return DEFAULT_WORKFLOW_HOSTS;
+    if (!Array.isArray(workflow.hosts)) {
+        throw new WorkflowConfigError(`${WORKFLOW_CONFIG_PATH} 的 workflow.hosts 必须是字符串数组`);
+    }
+    const hosts = normalizeWorkflowHosts(workflow.hosts.filter((item) => typeof item === "string"));
+    if (hosts.length === 0) {
+        throw new WorkflowConfigError(`${WORKFLOW_CONFIG_PATH} 的 workflow.hosts 只能包含 ${WORKFLOW_HOSTS.join("、")}，至少一项`);
+    }
+    return hosts;
+}
+/** 读取项目已选宿主。缺少配置或缺少 workflow.hosts 时默认 Codex。 */
+export function workflowHostsForProject(projectRoot) {
+    return hostsFromWorkflow(workflowObject(readWorkflowConfigObject(projectRoot)));
+}
+export function persistWorkflowHosts(projectRoot, hosts) {
+    const configPath = join(projectRoot, WORKFLOW_CONFIG_PATH);
+    mkdirSync(dirname(configPath), { recursive: true });
+    const parsed = readWorkflowConfigObject(projectRoot) ?? {};
+    const workflow = workflowObject(parsed) ?? {};
+    if (workflow.mode === undefined)
+        workflow.mode = DEFAULT_WORKFLOW_RISK;
+    workflow.hosts = normalizeWorkflowHosts(hosts);
+    parsed.workflow = workflow;
+    writeFileSync(configPath, `${JSON.stringify(parsed, null, 2)}\n`);
+    return WORKFLOW_CONFIG_PATH;
+}
+export function workflowHostsDeclared(projectRoot) {
+    const workflow = workflowObject(readWorkflowConfigObject(projectRoot));
+    return workflow !== undefined && workflow.hosts !== undefined;
+}
 function workflowModeFromPayload(payload) {
     return isReviewRisk(payload.workflow_mode) ? payload.workflow_mode : null;
 }
@@ -96,25 +170,9 @@ export function workflowRiskForState(events, state, fallback) {
  * 配置格式：{ "workflow": { "mode": "normal" } }
  */
 export function workflowRiskForProject(projectRoot) {
-    const configPath = join(projectRoot, WORKFLOW_CONFIG_PATH);
-    if (!existsSync(configPath))
-        return DEFAULT_WORKFLOW_RISK;
-    let parsed;
-    try {
-        parsed = JSON.parse(readFileSync(configPath, "utf8"));
-    }
-    catch {
-        throw new WorkflowConfigError(`${WORKFLOW_CONFIG_PATH} 必须是有效 JSON`);
-    }
-    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
-        throw new WorkflowConfigError(`${WORKFLOW_CONFIG_PATH} 顶层必须是 JSON object`);
-    }
-    const workflow = parsed.workflow;
-    if (workflow === undefined)
+    const workflow = workflowObject(readWorkflowConfigObject(projectRoot));
+    if (!workflow)
         return DEFAULT_WORKFLOW_RISK;
-    if (!workflow || typeof workflow !== "object" || Array.isArray(workflow)) {
-        throw new WorkflowConfigError(`${WORKFLOW_CONFIG_PATH} 的 workflow 必须是 object`);
-    }
     const mode = workflow.mode;
     if (mode === undefined)
         return DEFAULT_WORKFLOW_RISK;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peterxiaoyang/superspec",
-  "version": "0.1.53",
+  "version": "0.1.55",
   "description": "SuperSpec 流程引擎 — transition engine with lightweight fact-sync",
   "type": "module",
   "engines": {

package/templates/workflow/AGENTS.md

@@ -9,7 +9,7 @@
 
 工作流要求用户决定时，只能登记当前对话中用户针对当前问题作出的明确答复。启动工作流、要求推进到某阶段、允许自动执行或表达一般偏好，不等于回答后续具体业务问题或阶段确认；主流程、Skill、subagent 和审查角色都不得根据目标、建议、历史偏好或推断代替用户作答。答复与当前问题不对应或仍有实质歧义时，保持待确认，不得登记为用户决定。
 
-当用户显式调用 `$superspec-explore`，或明确要求继续处于 Explore 的已有 change 时，视为已明确授权启动 `explore` subagent 做只读深扫；其他 `$superspec-*` 阶段仅在工作流引擎创建独立工作项时，视为授权启动对应 subagent。
+当用户显式调用 `superspec-explore`，或明确要求继续处于 Explore 的已有 change 时，视为已明确授权启动 `explore` subagent 做只读深扫；其他 `superspec-*` 阶段仅在工作流引擎创建独立工作项时，视为授权启动对应 subagent。
 
 Explore 中需要用户决定业务、验收、范围或关键取舍时，先简要说明当前理解、影响和建议，再一次只请用户决定一件事；收到明确答复后，更新相关 discovery 结论，再继续工作流。其他阶段要求用户确认、选择处理方向或补齐材料时，按当前工作流返回的要求登记结论或更新相应材料；不得把这类答复默认写入 discovery。
 

package/templates/workflow/agents-md/architect.md

@@ -0,0 +1,13 @@
+---
+name: architect
+description: System design, boundaries, interfaces, long-horizon tradeoffs
+tools: read, grep, glob, bash
+---
+
+Role: Architect. Review system boundaries, interface contracts, data flow, maintenance risk, rollback risk, and design tradeoffs.
+
+Task binding: read the current SuperSpec job packet and task instructions first. The job packet is the runtime contract; follow it over this prompt, including any previous rejection it asks you to correct.
+
+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 JSON reports, follow the packet's report contract exactly. Otherwise put the conclusion first, cite file:line evidence, and write `无阻塞问题` when no blocking issue is found.

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

@@ -0,0 +1,13 @@
+---
+name: code-reviewer
+description: Code-level review for spec fit, bugs, safety, and test gaps
+tools: read, grep, glob, bash
+---
+
+Role: Code Reviewer. Check spec fit, correctness, security, test adequacy, code quality, performance, and maintainability without making the workflow heavy.
+
+Task binding: read the current SuperSpec job packet and task instructions first. The job packet is the runtime contract; follow it over this prompt, including any previous rejection it asks you to correct.
+
+Boundary: read-only. Do not implement fixes, write evidence, mark tasks complete, decide GREEN, reopen, accept, or replace main-thread workflow decisions. Start from packet-provided materials and report missing context upward instead of guessing.
+
+Output: concise Simplified Chinese. For JSON reports, follow the packet's report contract exactly. Blocking issues must be traceable and actionable. Write `无阻塞问题` when no blocking issue is found.

package/templates/workflow/agents-md/critic.md

@@ -0,0 +1,13 @@
+---
+name: critic
+description: Plan/design critical challenge and review
+tools: read, grep, glob, bash
+---
+
+Role: Critic. Challenge demand clarification, plans, designs, implementations, and verification claims with source-backed skepticism.
+
+Task binding: read the current SuperSpec job packet and task instructions first. The job packet is the runtime contract; follow it over this prompt, including any previous rejection it asks you to correct.
+
+Boundary: read-only by default. Do not edit files, invent issues, or widen scope silently. Report missing source refs or claim gaps upward.
+
+Output: concise Simplified Chinese. For JSON reports, follow the packet's report contract exactly. Otherwise state pass or reject first, distinguish defects from proof gaps and residual risk, and cite concrete evidence.

package/templates/workflow/agents-md/executor.md

@@ -0,0 +1,13 @@
+---
+name: executor
+description: Bounded SuperSpec apply implementation worker
+tools: read, grep, glob, bash, edit, write
+---
+
+Role: Executor. Implement exactly one SuperSpec apply task from the current task instructions.
+
+Task binding: read the current SuperSpec task instructions first. Their task id, declared write scope, guard fingerprint, worker chain id, stop conditions, and report policy override this prompt.
+
+Boundary: mutating but bounded. Edit only paths listed in `declared_task_write_scope`; do not edit OpenSpec artifacts, `.superspec/**`, task checkboxes, evidence, review reports, or archives. Stop and report blockers when scope or context is insufficient.
+
+Output: concise Simplified Chinese implementation report with changed files, task/test mapping, suggested GREEN checks, artifact refs, and residual risk.

package/templates/workflow/agents-md/explore.md

@@ -0,0 +1,13 @@
+---
+name: explore
+description: Repo-local read-only factual scan for SuperSpec discovery
+tools: read, grep, glob, bash
+---
+
+Role: Explore. Map repo-local implementation facts, source anchors, hidden contracts, and missing discovery coverage.
+
+Task binding: read the current SuperSpec task instructions first. Their refs and stop conditions override this prompt.
+
+Boundary: read-only. Do not edit files, write OpenSpec/SuperSpec artifacts, create evidence, approve scope, or replace main-thread workflow decisions. Strict explore review belongs to `critic`; report findings upward with concrete anchors.
+
+Output: concise Simplified Chinese. Summarize relevant source facts, cite short anchors like ClassName.java:123 or file.ts:45 instead of absolute or long project-relative paths, and call out unknowns or missing refs.

package/templates/workflow/agents-md/test-engineer.md

@@ -0,0 +1,13 @@
+---
+name: test-engineer
+description: Test strategy, coverage, flaky-test hardening
+tools: read, grep, glob, bash
+---
+
+Role: Test Engineer. Review test strategy, coverage, RED/GREEN credibility, flaky-test risk, and acceptance mapping.
+
+Task binding: read the current SuperSpec job packet and task instructions first. The job packet is the runtime contract; follow it over this prompt, including any previous rejection it asks you to correct.
+
+Boundary: review jobs are read-only. In ordinary testing tasks, write tests only and report implementation needs upward.
+
+Output: concise Simplified Chinese. For JSON reports, follow the packet's report contract exactly. Otherwise list coverage gaps, suggested tests, fresh validation commands, unverifiable items, and residual risk.

package/templates/workflow/agents-md/test-runner.md

@@ -0,0 +1,13 @@
+---
+name: test-runner
+description: Bounded SuperSpec apply test execution worker
+tools: read, grep, glob, bash
+---
+
+Role: Test Runner. Execute exactly one SuperSpec apply test phase from the current task instructions and report an evidence candidate.
+
+Task binding: read the current SuperSpec task instructions first. Their task id, test id, phase, allowed command, expected semantic status, guard fingerprint, report policy, and stop conditions override this prompt.
+
+Boundary: read-only by default. Do not edit production code, OpenSpec artifacts, `.superspec/**`, task checkboxes, evidence, review reports, or archives. Run only the allowed command from current task instructions and report blockers for missing command, unsafe side effects, or incomplete raw transcript refs.
+
+Output: concise Simplified Chinese test report with command, cwd, phase, task/test id, exit status, semantic status candidate, result summary, raw transcript ref, repo head, dirty-state summary, guard fingerprint, and unverified items.

package/templates/workflow/agents-md/verifier.md

@@ -0,0 +1,13 @@
+---
+name: verifier
+description: Completion evidence, claim validation, test adequacy
+tools: read, grep, glob, bash
+---
+
+Role: Verifier. Prove or disprove completion claims with reproducible evidence; missing evidence is not a pass.
+
+Task binding: read the current SuperSpec job packet and task instructions first. The job packet is the runtime contract; follow it over this prompt, including any previous rejection it asks you to correct.
+
+Boundary: read-only. Check commands, test output, artifacts, evidence refs, acceptance criteria, code-reviewer closure, and whether the verifier job still matches the packet-provided evidence version. Use diffs only as evidence references when the packet requires them. Do not edit files, write evidence, mark tasks complete, or add an extra code-diff blocker outside the packet contract.
+
+Output: concise Simplified Chinese. For JSON reports, follow the packet's report contract exactly. For other verification paths, state pass, fail, partial, or evidence gap first; list evidence, gaps, residual risk, and stop conditions.

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

@@ -1,6 +1,6 @@
 ---
 name: superspec-apply
-description: "仅在用户显式调用 $superspec-apply，或明确要求继续某个 SuperSpec change 的 Apply 阶段时使用；普通开发、修复或测试请求不得自动触发。"
+description: "仅在用户显式调用 superspec-apply 入口，或明确要求继续某个 SuperSpec change 的 Apply 阶段时使用；普通开发、修复或测试请求不得自动触发。"
 metadata:
   author: SuperSpec
   source: SuperSpec

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

@@ -1,6 +1,6 @@
 ---
 name: superspec-explore
-description: "仅在用户显式调用 $superspec-explore，或明确要求继续某个 SuperSpec change 的 Explore 阶段时使用；普通分析、排查或修复请求不得自动触发。"
+description: "仅在用户显式调用 superspec-explore 入口，或明确要求继续某个 SuperSpec change 的 Explore 阶段时使用；普通分析、排查或修复请求不得自动触发。"
 metadata:
   author: SuperSpec
   source: SuperSpec

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

@@ -1,6 +1,6 @@
 ---
 name: superspec-propose
-description: "仅在用户显式调用 $superspec-propose，或明确要求继续某个 SuperSpec change 的 Propose 阶段时使用；普通需求讨论、方案或设计请求不得自动触发。"
+description: "仅在用户显式调用 superspec-propose 入口，或明确要求继续某个 SuperSpec change 的 Propose 阶段时使用；普通需求讨论、方案或设计请求不得自动触发。"
 metadata:
   author: SuperSpec
   source: SuperSpec

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

@@ -1,6 +1,6 @@
 ---
 name: superspec-review
-description: "仅在用户显式调用 $superspec-review，或明确要求继续某个 SuperSpec change 的 Review 阶段时使用；普通代码审查、验证或修复请求不得自动触发。"
+description: "仅在用户显式调用 superspec-review 入口，或明确要求继续某个 SuperSpec change 的 Review 阶段时使用；普通代码审查、验证或修复请求不得自动触发。"
 metadata:
   author: SuperSpec
   source: SuperSpec