@peterxiaoyang/superspec 0.1.54 → 0.1.56

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

@@ -0,0 +1,26 @@
+import type { CodeReviewClaimKind } from "./types.ts";
+export declare const CODE_REVIEW_CLAIM_KINDS: readonly ["missing_approved", "breaks_existing", "unjustified_addition"];
+export type ApprovedRefKind = "test" | "requirement" | "task" | "design" | "proposal";
+export interface ResolvedApprovedRef {
+    raw: string;
+    kind: ApprovedRefKind;
+    short: string;
+}
+export declare function isCodeReviewClaimKind(value: unknown): value is CodeReviewClaimKind;
+export declare function shortApprovedRef(raw: string): string;
+export declare function resolveApprovedRef(changeRoot: string, raw: unknown): {
+    ok: true;
+    value: ResolvedApprovedRef;
+} | {
+    ok: false;
+    reason: string;
+};
+export declare function resolveApprovedRefs(changeRoot: string, refs: unknown): {
+    ok: true;
+    values: ResolvedApprovedRef[];
+} | {
+    ok: false;
+    reasons: string[];
+};
+export declare function hasBehaviorAnchor(values: readonly ResolvedApprovedRef[]): boolean;
+export declare function reviewFixReason(claimKind: CodeReviewClaimKind, refs: readonly string[]): string;

package/dist/approved_ref.js

@@ -0,0 +1,158 @@
+// SuperSpec 代码审查 approved_refs：只做存在性解析，不做语义匹配。
+import { readFileSync, statSync } from "node:fs";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
+import { parseTasksMd, parseTestContractEntries } from "./format.js";
+export const CODE_REVIEW_CLAIM_KINDS = [
+    "missing_approved",
+    "breaks_existing",
+    "unjustified_addition",
+];
+const TEST_ID_RE = /^TEST-[A-Za-z0-9_-]+$/;
+const TEST_CONTRACT_REL = join(".superspec", "artifacts", "test-contract.md");
+function escapeRegex(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function isPathInside(root, target) {
+    const rel = relative(root, target);
+    return rel !== "" && !rel.startsWith(`..${sep}`) && rel !== ".." && !isAbsolute(rel);
+}
+function headingExists(content, title) {
+    const heading = new RegExp(`^#{1,6}[\\t ]+${escapeRegex(title)}(?:[\\t ]+#+)?[\\t ]*$`, "m");
+    return heading.test(content);
+}
+function shortTestId(raw) {
+    const trimmed = raw.trim();
+    if (TEST_ID_RE.test(trimmed))
+        return trimmed;
+    const hash = trimmed.lastIndexOf("#");
+    if (hash >= 0) {
+        const id = trimmed.slice(hash + 1).trim();
+        if (TEST_ID_RE.test(id))
+            return id;
+    }
+    return null;
+}
+function readChangeFile(changeRoot, relPath) {
+    const target = resolve(changeRoot, relPath);
+    if (!isPathInside(resolve(changeRoot), target) && resolve(changeRoot) !== target)
+        return null;
+    try {
+        if (!statSync(target).isFile())
+            return null;
+        return readFileSync(target, "utf8");
+    }
+    catch {
+        return null;
+    }
+}
+export function isCodeReviewClaimKind(value) {
+    return typeof value === "string" && CODE_REVIEW_CLAIM_KINDS.includes(value);
+}
+export function shortApprovedRef(raw) {
+    const testId = shortTestId(raw);
+    if (testId)
+        return testId;
+    const req = /#Requirement:\s*(.+)$/.exec(raw.trim());
+    if (req)
+        return `Requirement: ${req[1].trim()}`;
+    const hash = raw.lastIndexOf("#");
+    if (hash >= 0 && hash < raw.length - 1)
+        return raw.slice(hash + 1).trim();
+    return raw.trim();
+}
+export function resolveApprovedRef(changeRoot, raw) {
+    if (typeof raw !== "string" || raw.trim() === "") {
+        return { ok: false, reason: "approved_refs 条目必须是非空字符串" };
+    }
+    const ref = raw.trim();
+    if (/[\u0000-\u001f\u007f]/.test(ref)) {
+        return { ok: false, reason: `approved_refs 条目不能包含换行等控制字符：${JSON.stringify(ref)}` };
+    }
+    const testId = shortTestId(ref);
+    if (testId) {
+        if (ref.includes("#") && !ref.endsWith(`#${testId}`)) {
+            return { ok: false, reason: `TEST 引用只能是裸 TEST-ID 或以 #TEST-ID 结尾指向 test-contract.md：${ref}` };
+        }
+        if (ref.includes("#")) {
+            const path = ref.slice(0, ref.lastIndexOf("#")).replace(/\\/g, "/");
+            const allowed = path === TEST_CONTRACT_REL.replace(/\\/g, "/")
+                || path === "test-contract.md"
+                || path.endsWith("/test-contract.md");
+            if (!allowed)
+                return { ok: false, reason: `TEST 引用只能指向 test-contract.md：${ref}` };
+        }
+        const content = readChangeFile(changeRoot, TEST_CONTRACT_REL);
+        if (content == null)
+            return { ok: false, reason: `无法读取 ${TEST_CONTRACT_REL.replace(/\\/g, "/")}，无法校验 TEST 引用：${ref}` };
+        const parsed = parseTestContractEntries(content);
+        if (!parsed.ok || !parsed.entries.some(entry => entry.test_id === testId)) {
+            return { ok: false, reason: `${TEST_CONTRACT_REL.replace(/\\/g, "/")} 中不存在 ${testId}` };
+        }
+        return { ok: true, value: { raw: ref, kind: "test", short: testId } };
+    }
+    const separator = ref.indexOf("#");
+    if (separator <= 0 || separator === ref.length - 1) {
+        return { ok: false, reason: `锚点格式无法解析，应为 文件#标题 或 TEST-ID：${ref}` };
+    }
+    const path = ref.slice(0, separator).replace(/\\/g, "/");
+    const anchor = ref.slice(separator + 1).trim();
+    const content = readChangeFile(changeRoot, path);
+    if (content == null)
+        return { ok: false, reason: `${path} 在当前 change 中不存在` };
+    if (path === "tasks.md") {
+        const tasks = parseTasksMd(content);
+        if (!tasks.some(task => task.taskId === anchor))
+            return { ok: false, reason: `tasks.md 中不存在任务 ${anchor}` };
+        return { ok: true, value: { raw: ref, kind: "task", short: anchor } };
+    }
+    if (path === "design.md") {
+        if (!headingExists(content, anchor))
+            return { ok: false, reason: `design.md 中不存在标题「${anchor}」` };
+        return { ok: true, value: { raw: ref, kind: "design", short: anchor } };
+    }
+    if (path === "proposal.md") {
+        if (!headingExists(content, anchor))
+            return { ok: false, reason: `proposal.md 中不存在标题「${anchor}」` };
+        return { ok: true, value: { raw: ref, kind: "proposal", short: anchor } };
+    }
+    if (/^specs\/[^/]+\/spec\.md$/.test(path)) {
+        const requirementTitle = anchor.startsWith("Requirement:")
+            ? anchor.slice("Requirement:".length).trim()
+            : "";
+        if (!requirementTitle)
+            return { ok: false, reason: `spec 锚点必须以 Requirement: 开头：${ref}` };
+        if (!headingExists(content, `Requirement: ${requirementTitle}`)) {
+            return { ok: false, reason: `${path} 中不存在 Requirement「${requirementTitle}」` };
+        }
+        return {
+            ok: true,
+            value: { raw: ref, kind: "requirement", short: `Requirement: ${requirementTitle}` },
+        };
+    }
+    return { ok: false, reason: `只支持 tasks.md、design.md、proposal.md、specs/*/spec.md 与 test-contract.md 的锚点：${ref}` };
+}
+export function resolveApprovedRefs(changeRoot, refs) {
+    if (!Array.isArray(refs) || refs.length === 0) {
+        return { ok: false, reasons: ["approved_refs 必须是非空字符串数组"] };
+    }
+    const values = [];
+    const reasons = [];
+    for (const raw of refs) {
+        const resolved = resolveApprovedRef(changeRoot, raw);
+        if (!resolved.ok)
+            reasons.push(resolved.reason);
+        else
+            values.push(resolved.value);
+    }
+    if (reasons.length > 0)
+        return { ok: false, reasons };
+    return { ok: true, values };
+}
+export function hasBehaviorAnchor(values) {
+    return values.some(value => value.kind === "test" || value.kind === "requirement");
+}
+export function reviewFixReason(claimKind, refs) {
+    const shorts = refs.map(shortApprovedRef).filter(Boolean);
+    const target = shorts.length > 0 ? shorts.join("、") : "已批准行为";
+    return `兑现 ${target}（${claimKind}）`;
+}

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

@@ -69,6 +69,7 @@ export declare function codeReviewPacketDigest(input: {
     packet_context?: JobPacketContext;
     previous_rejection?: ReviewPreviousRejection;
 }): string;
+export declare function addedCodePathsForScope(projectRoot: string, scope: CodeReviewScope): string[];
 export declare function codeReviewPacketContext(changeRoot: string, projectRoot: string, scope: CodeReviewScope, events: Event[]): JobPacketContext;
 export declare function effectiveCoverageExemptionRefsFromEvents(events: Event[]): CoverageExemptionRef[];
 export declare function missingCoverageExemptionTestIds(changeRoot: string, events: Event[]): string[];

package/dist/code_review.js

@@ -360,6 +360,41 @@ export function codeReviewJobStaleReason(projectRoot, job, currentPaths, events,
 export function codeReviewPacketDigest(input) {
     return sha256Text(JSON.stringify(input));
 }
+export function addedCodePathsForScope(projectRoot, scope) {
+    if (!scope.scope_reliable)
+        return [];
+    const added = new Set();
+    let baseHead = scope.base_head;
+    if (!baseHead && scope.current_head) {
+        // 首轮 start-apply 前仓库还没有提交：以空树为基点，让 Apply 期间产生的首个提交也进入新增清单。
+        const emptyTree = gitLines(projectRoot, ["hash-object", "-t", "tree", "/dev/null"]);
+        if (emptyTree.ok)
+            baseHead = emptyTree.lines[0] ?? null;
+    }
+    if (baseHead && scope.current_head) {
+        const committed = gitLines(projectRoot, [
+            "diff", "--no-renames", "--diff-filter=A", "--name-only", `${baseHead}..${scope.current_head}`,
+        ]);
+        if (committed.ok) {
+            for (const path of committed.lines) {
+                if (isCodeLikePath(path))
+                    added.add(path);
+            }
+        }
+    }
+    const dirty = dirtyCodeFiles(projectRoot);
+    if (dirty.ok) {
+        for (const file of dirty.files) {
+            if (file.status === "added" && isCodeLikePath(file.path))
+                added.add(file.path);
+        }
+    }
+    for (const path of scope.untracked_paths) {
+        if (isCodeLikePath(path))
+            added.add(path);
+    }
+    return [...added].sort();
+}
 export function codeReviewPacketContext(changeRoot, projectRoot, scope, events) {
     const taskExecutionIndex = taskExecutionIndexFromEvents(projectRoot, events);
     // changed_paths 未知（快照缺失）或不完整（committed 段 diff 失败）的 task
@@ -379,6 +414,7 @@ export function codeReviewPacketContext(changeRoot, projectRoot, scope, events)
         task_execution_index: taskExecutionIndex,
         unattributed_paths: scope.review_paths.filter(path => !attributedPaths.has(path)).sort(),
         unknown_attribution_tasks: unknownAttributionTasks,
+        added_code_paths: addedCodePathsForScope(projectRoot, scope),
     };
 }
 export function effectiveCoverageExemptionRefsFromEvents(events) {

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/next.js

@@ -115,14 +115,17 @@ function toNextOutput(change, plan) {
                 resume: { argv: ["superspec", "transition", "next", "--change", change] },
                 reason: plan.reason,
             };
-        case "run_transition":
+        case "run_transition": {
+            const findingContext = plan.reopen?.reason === "review_fix" ? plan.reopen.findingContext : undefined;
             return {
                 state: plan.state,
                 path: "next_command",
                 next_command: transitionCommand(change, plan.transition, formatTransitionArgs(plan)),
                 reason: plan.reason,
                 missing_inputs: [],
+                ...(findingContext ? { finding_context: findingContext } : {}),
             };
+        }
         case "done":
             return {
                 state: plan.state,

package/dist/phase_plan.d.ts

@@ -1,7 +1,7 @@
 import type { ReviewGateRule } from "./review_job_gates.ts";
 import { exploreAnswerRegistrationPayload } from "./explore_round.ts";
 import { proposeAnswerRegistrationPayload } from "./propose_round.ts";
-import type { AcceptedMaterialFollowupContinuation, AskUser, Event, ExecutionPolicy, Job, JobRole, PlanningValidationProfile, WorkflowArtifactKind, State } from "./types.ts";
+import type { AcceptedMaterialFollowupContinuation, AskUser, Event, ExecutionPolicy, Job, JobRole, PlanningValidationProfile, ReviewFindingContext, WorkflowArtifactKind, State } from "./types.ts";
 import type { Snapshot } from "./types.ts";
 import type { ReviewRisk } from "./review.ts";
 export type TransitionName = "explore" | "propose-ready" | "start-apply" | "task-start" | "task-complete" | "review-ready" | "reopen" | "accept";
@@ -29,6 +29,7 @@ export type ReopenNextStep = {
     jobId: string;
     findingId: string;
     reopenReason: string;
+    findingContext?: ReviewFindingContext;
 } | {
     to: "propose";
     reason: "review_finding";

package/dist/phase_plan.js

@@ -12,6 +12,16 @@ import { CODE_REVIEW_DECISION_ANSWER_LABELS, CODE_REVIEW_REPAIR_SCOPE_PREFIX, co
 import { isPhaseAdvanceAuthorized, latestAcceptedPhaseDecision, phaseConfirmationCommitPayload, phaseConfirmationForBoundary, phaseConfirmationMissingMessage, } from "./phase_confirmation.js";
 import { taskEvidenceReadiness } from "./task_evidence.js";
 import { workflowRiskForProposeRound, workflowRiskForState } from "./workflow_config.js";
+/** 从失败 finding 提取定位上下文：只回传 evidence（位置事实），不回传 description——那是审查建议叙事，不进执行上下文。 */
+function reviewFindingContext(finding) {
+    const evidence = typeof finding?.evidence === "string" ? finding.evidence.trim() : "";
+    if (!evidence)
+        return undefined;
+    return {
+        evidence,
+        note: "非授权上下文：仅用于定位问题代码；实现范围仍以任务行锚定的已批准行为为准",
+    };
+}
 function requiredJobs(state, jobs, reason) {
     return { kind: "required_jobs", state, jobs, reason };
 }
@@ -837,6 +847,7 @@ function planApplyDoneNext(context) {
                     jobId: latest.job.job_id,
                     findingId,
                     reopenReason: `修复代码审查问题 ${findingId}`,
+                    findingContext: reviewFindingContext(pendingFinding?.finding),
                 },
                 reason: `代码审查发现纯代码实现问题 ${findingId}，回到实现阶段修复`,
             };
@@ -862,6 +873,7 @@ function planApplyDoneNext(context) {
                         jobId: latest.job.job_id,
                         findingId,
                         reopenReason: `根据代码审查问题 ${findingId} 回到实现阶段修复`,
+                        findingContext: reviewFindingContext(pendingFinding?.finding),
                     },
                     reason: `使用者已确认问题 ${findingId} 直接回到实现阶段修复`,
                 };