@peterxiaoyang/superspec 0.1.54 → 0.1.56

package/dist/record.js

@@ -8,6 +8,7 @@ import { isPhaseConfirmationScope, phaseActionForAnswer, phaseConfirmationForCur
 import { CODE_REVIEW_DECISION_ANSWER_LABELS, CODE_REVIEW_DECISION_SCOPE_PREFIX, codeReviewJobStaleReason, codeReviewDecisionAnswerLabel, currentCodeReviewWorkingPaths, latestCodeReviewFailedStatus, normalizeCodeReviewDecisionAnswer, parseCodeReviewDecisionScope, } from "./code_review.js";
 import { invalidReasonForSubmittedReport } from "./job_validity.js";
 import { jobSubmitArgv } from "./job_action.js";
+import { hasBehaviorAnchor, isCodeReviewClaimKind, resolveApprovedRefs, } from "./approved_ref.js";
 import { REVIEW_DOC_PATHS, REVIEW_REJECTION_OVERRIDE_SCOPE_PREFIX, REVIEW_REJECTION_OVERRIDE_ANSWER, parseReviewRejectionOverrideScope, reviewGateRoleResolution, reviewRejectionOverrideScope, } from "./review.js";
 import { EXPLORE_DISCOVERY_REVIEW_GATE, PROPOSE_FINAL_REVIEW_GATE } from "./review_job_gates.js";
 import { RecordInputDecodingError, readRecordInputFile } from "./record_input.js";
@@ -16,7 +17,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";
@@ -56,7 +57,7 @@ function roleDescription(role) {
         case "verifier":
             return "验证 proposal、实现状态、任务完成、测试契约和 SuperSpec 证据是否足以支撑完成结论";
         case "code-reviewer":
-            return "审查 apply 后的代码实现质量、健壮性、性能、安全、兼容、边界条件、是否偏离 proposal/design/tasks/test-contract 以及关键测试缺口";
+            return "独立审查实现是否以最小语义影响兑现已批准计划，找出真实缺陷、边界条件、安全/性能/兼容问题与关键测试缺口，并区分漏做与计划或验收没有要求的改动";
         case "executor":
             return "执行受限实现工作项";
         case "test-run":
@@ -339,7 +340,7 @@ function validateReviewScope(obj, job, checks) {
         }
     }
 }
-function actionableCodeReviewFindings(findings) {
+function actionableCodeReviewFindings(findings, changeRoot) {
     if (!Array.isArray(findings))
         return { actionable: [], reasons: ["报告字段 findings 必须是数组"] };
     const actionable = [];
@@ -387,6 +388,18 @@ function actionableCodeReviewFindings(findings) {
         if (type === "implementation" && finding.suggested_action !== "apply") {
             findingReasons.push(`纯代码实现问题 ${id} 的 suggested_action 必须是 apply`);
         }
+        if (!isCodeReviewClaimKind(finding.claim_kind)) {
+            findingReasons.push(`阻塞问题 ${id} 的 claim_kind 必须是 missing_approved|breaks_existing|unjustified_addition`);
+        }
+        const resolved = resolveApprovedRefs(changeRoot, finding.approved_refs);
+        if (!resolved.ok) {
+            findingReasons.push(...resolved.reasons.map((reason) => `阻塞问题 ${id} ${reason}`));
+        }
+        else if (finding.claim_kind === "missing_approved"
+            && finding.suggested_action === "apply"
+            && !hasBehaviorAnchor(resolved.values)) {
+            findingReasons.push(`阻塞问题 ${id} 的 missing_approved 在 suggested_action=apply 时必须引用可解析的 TEST 或 spec Requirement；若缺口属于计划或验收本身的问题，改用 type=mixed 且 suggested_action=propose 交使用者裁决`);
+        }
         if (findingReasons.length > 0) {
             reasons.push(...findingReasons);
             continue;
@@ -614,7 +627,7 @@ function recordJobSubmitLoaded(projectRoot, change, changeRoot, jobId, job, even
         const blockingCount = Array.isArray(findings)
             ? findings.filter(item => asObject(item)?.blocking === true).length
             : 0;
-        const { actionable, reasons } = actionableCodeReviewFindings(findings);
+        const { actionable, reasons } = actionableCodeReviewFindings(findings, changeRoot);
         if (verdict === "pass") {
             if (blockingCount > 0) {
                 const reason = "报告结论为 pass 时不能包含 blocking:true 的阻塞问题";
@@ -1165,6 +1178,9 @@ function packetFieldDescriptions() {
         changed_paths: "与某个任务（task）或代码状态检查相关的改动文件。",
         changed_paths_partial_reason: "该任务（task）的提交段 diff 失败原因；存在时 changed_paths 只包含工作区对比结果，归属可能不完整。",
         unattributed_paths: "代码审查范围中暂时无法归属到某个任务（task）的文件。",
+        added_code_paths: "相对本次代码审查基点新建的代码文件，供判断是否服务已批准行为。",
+        claim_kind: "阻塞问题相对已批准计划的关系：漏做、破坏已有行为、或计划或验收没有要求的改动。",
+        approved_refs: "指向当前 change 已批准材料的引用；引擎只检查能否解析，apply 漏做还需要 TEST 或 spec Requirement。",
         unknown_attribution_tasks: "因为缺少边界快照或提交段 diff 失败而无法完整计算改动归属的任务（task）。",
         coverage_exemption_refs: "测试覆盖豁免引用：说明某个 TEST 为什么没有绑定到任务（task）。",
         code_review_gate: "最终验证读取的代码审查门禁事实：passed 指向已接受的代码审查工作项，skipped 表示本轮没有代码类改动。",
@@ -1210,6 +1226,7 @@ export function jobsPacket(projectRoot, change, jobId) {
             ...(packetContext?.task_execution_index ? { task_execution_index: packetContext.task_execution_index } : {}),
             ...(packetContext?.unattributed_paths ? { unattributed_paths: packetContext.unattributed_paths } : {}),
             ...(packetContext?.unknown_attribution_tasks ? { unknown_attribution_tasks: packetContext.unknown_attribution_tasks } : {}),
+            ...(packetContext?.added_code_paths ? { added_code_paths: packetContext.added_code_paths } : {}),
             ...(packetContext?.code_state_check ? { code_state_check: packetContext.code_state_check } : {}),
             packet_digest: job.packet_digest,
             required_output_kind: "job_report_json",
@@ -1234,10 +1251,10 @@ 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 不允许仍有未检查的绑定文件。`
-                        + `报告结论为 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 表示需要使用者判断的混合问题。`
+                    ? `格式骨架：{"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","claim_kind":"missing_approved|breaks_existing|unjustified_addition","approved_refs":["TEST-001"],"description":"<what>","evidence":"<why>","source_refs":["<path:line>"],"impact":"<impact>","suggested_action":"apply|propose"}。问题类型（type）中 implementation 表示纯代码实现问题，spec 表示方案/需求文档问题，mixed 表示需要使用者判断的混合问题；claim_kind 与 approved_refs 见字段说明。`
                         + (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 是本轮冻结的审查范围；若它来自前一轮审查后的增量，只复核本轮变化及其直接影响链路，不要求重复审查未变化文件，但仍要判断批准行为是否完整闭合。`
+                            ? `本工作项带任务执行索引（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 中的无主改动和 added_code_paths 中的新建代码文件，均需判断是否服务已批准行为；coverage_exemption_refs 解释未绑定 task 的 TEST 豁免。当前 packet 的 boundFiles 是本轮冻结的审查范围；若它来自前一轮审查后的增量，只复核本轮变化及其直接影响链路，不要求重复审查未变化文件，但仍要判断批准行为是否完整闭合。`
                             : "")
                     : job.role === "verifier"
                         ? `最小格式：{"role":"verifier","verdict":"pass","findings":[]${hasReviewScope ? `,"review_scope":{"checked_paths":${JSON.stringify(job.boundFiles.map(file => file.path))}}` : ""}}。verdict 只能为 pass 或 fail；核对代码审查记录（code_review_gate）：passed 必须能追溯到已接受的代码审查工作项，skipped 必须能证明本次没有代码类改动。核对修复闭环：task_execution_index.fix.source=code_review 时必须核对 review_finding 对应问题是否关闭；source=self_test 时必须核对 parent_task_id、记录的自测原因、本次 attempt 验证和最新代码审查是否共同闭环。方案/混合问题必须有用户决策或后续修复证据。按 task_execution_index 的 required_evidence 核对测试证据：red_required 时需要同一 TEST 的 RED（expected_failure）后 GREEN；green_required 时每个声明 TEST 都需要允许的 GREEN 语义状态；测试运行证据应包含测试 ID（test_id）、命令（command）、工作目录（cwd）、退出码（exit_code）、语义状态（semantic_status）。修复 task 的回归测试运行可用回归覆盖任务列表（covers_task_ids）说明覆盖了哪些已完成任务；缺少任务尝试 ID（attempt_id）的旧证据只能弱引用。` +
@@ -1245,7 +1262,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

@@ -9,6 +9,7 @@ import { REVIEW_CODE_REVIEW_GATE_ID, REVIEW_FINAL_VERIFIER_GATE, REVIEW_FINAL_VE
 import { codeReviewBoundFiles, codeReviewDecisionScope, codeReviewJobStaleReason, codeReviewPacketContext, codeReviewPacketDigest, collectCodeReviewGateFacts, computeCodeStateCheck, currentCodeReviewWorkingPaths, dismissedCodeReviewSummary, effectiveCoverageExemptionRefsFromEvents, latestCodeReviewGateEvidence, latestCodeReviewDecision, latestCodeReviewFailedStatus, missingCoverageExemptionTestIds, requiresFinalVerifierForCurrentReview, scanCodeChangesForReview, taskExecutionIndexForReview, } from "./code_review.js";
 import { taskEvidenceReadiness } from "./task_evidence.js";
 import { adoptedContractForTask, findTaskInLines, isFixTaskId, parseTasksMd, parseTestContractEntries, } from "./format.js";
+import { isCodeReviewClaimKind, reviewFixReason } from "./approved_ref.js";
 import { applyRequirementModeForCurrentRound, applyPlanningDocsChangedSinceBaseline, executionRequirementVersionForCurrentRound, blockingJobsForApplyDone, executionPolicyForCurrentRound, formatPendingTaskMessage, latestAcceptedProposalBaseline, pendingTaskStatusForApply, planningValidationProfileForNewRound, planTransition, discoveryDocsBaseline, exploreAnswerRegistrationPayloadForChange, proposeAnswerRegistrationPayloadForChange, proposalDocsBaseline, } from "./phase_plan.js";
 import { latestAcceptedPhaseDecision, phaseConfirmationCommitPayload, phaseConfirmationForBoundary, phaseConfirmationMissingMessage, } from "./phase_confirmation.js";
 import { currentGitHead, dirtyCodeFiles, stageProductionJavaFilesSince } from "./git_state.js";
@@ -359,15 +360,29 @@ function findReviewFailedFinding(events, ref) {
     return { event: status.terminal.event, finding };
 }
 function reviewFixDescriptor(ref, finding) {
-    const reason = typeof finding.description === "string" && finding.description.trim()
-        ? finding.description.trim().replace(/\s+/g, " ")
-        : `修复代码审查问题 ${ref.findingId}`;
+    const claimKind = isCodeReviewClaimKind(finding.claim_kind) ? finding.claim_kind : null;
+    const approvedRefs = Array.isArray(finding.approved_refs)
+        ? finding.approved_refs.filter((item) => typeof item === "string" && item.trim() !== "")
+        : [];
+    const reason = claimKind && approvedRefs.length > 0
+        ? reviewFixReason(claimKind, approvedRefs).replace(/\s+/g, " ")
+        : typeof finding.description === "string" && finding.description.trim()
+            ? finding.description.trim().replace(/\s+/g, " ")
+            : `修复代码审查问题 ${ref.findingId}`;
+    const reviewFinding = {
+        job_id: ref.jobId,
+        finding_id: ref.findingId,
+    };
+    if (approvedRefs.length > 0)
+        reviewFinding.approved_refs = approvedRefs;
+    if (claimKind)
+        reviewFinding.claim_kind = claimKind;
     return {
         fix_id: `REVIEW-FIX-${ref.jobId}#${ref.findingId}`,
         source: "code_review",
         parent_task_id: null,
         reason,
-        review_finding: { job_id: ref.jobId, finding_id: ref.findingId },
+        review_finding: reviewFinding,
     };
 }
 function selfTestFixBaseId(parentTaskId, reason) {

package/dist/types.d.ts

@@ -10,6 +10,7 @@ export type JobState = "requested" | "accepted" | "rejected";
 export type JobRole = "critic" | "architect" | "test-engineer" | "executor" | "test-run" | "verifier" | "code-reviewer";
 export type ReviewJobGateId = "explore.discovery_review" | "propose.final_review" | "review.code_review" | "review.final_verifier";
 export type CodeReviewResultKind = "invalid_report" | "non_actionable_report" | "review_failed";
+export type CodeReviewClaimKind = "missing_approved" | "breaks_existing" | "unjustified_addition";
 export interface ReviewPreviousRejection {
     result_kind: CodeReviewResultKind;
     reason: string;
@@ -63,6 +64,8 @@ export interface FixDescriptor {
     review_finding?: {
         job_id: string;
         finding_id: string;
+        approved_refs?: string[];
+        claim_kind?: CodeReviewClaimKind;
     };
 }
 export interface DirtyFileFingerprint {
@@ -129,6 +132,7 @@ export interface JobPacketContext {
     task_execution_index?: TaskExecutionIndexEntry[];
     unattributed_paths?: string[];
     unknown_attribution_tasks?: string[];
+    added_code_paths?: string[];
     code_state_check?: CodeStateCheck;
 }
 export interface JobPacket {
@@ -148,6 +152,7 @@ export interface JobPacket {
     task_execution_index?: TaskExecutionIndexEntry[];
     unattributed_paths?: string[];
     unknown_attribution_tasks?: string[];
+    added_code_paths?: string[];
     code_state_check?: CodeStateCheck;
     packet_digest: string;
     required_output_kind: string;
@@ -371,6 +376,11 @@ export interface TestEvidenceAction {
     };
     required_fields: Array<"command" | "cwd" | "exit_code">;
 }
+/** review-fix 计划附带的原始审查问题上下文；仅供定位代码，不是实现授权。 */
+export interface ReviewFindingContext {
+    evidence: string;
+    note: string;
+}
 export type NextOutput = {
     state: State;
 } & ({
@@ -378,6 +388,7 @@ export type NextOutput = {
     next_command: string;
     reason: string;
     missing_inputs: MissingInput[];
+    finding_context?: ReviewFindingContext;
 } | {
     path: "required_job";
     required_jobs: RequiredJobAction[];

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.54",
+  "version": "0.1.56",
   "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。
 
@@ -23,6 +23,8 @@ Apply 的成功标准是完整兑现已批准行为，并在满足验收的实
 - 所有 task 已完成后，若问题仍能关联一个已完成 task、且不改变已批准行为和方案，主流程执行 `superspec transition reopen --change "<change>" --to apply --self-test-fix "<task>" --reason "<reason>"`，让工作流创建修复事项；随后继续 `next`，不得手改 tasks。
 - 无法关联既有 task，或需要改变行为、验收、接口、数据语义或实现路线时，才回 propose。
 
+用户明确否定某个不属于已批准行为的实现装置时，同样按上面三条规则恢复已批准行为，但顺序相反：先完成代码上的移除或修复（self-test-fix 的 reason 写恢复了哪条已批准行为，不写撤回或删除），确认能通过后再把这次否决写进 design 的非目标或相关 task 的边界——计划材料一旦先改，self-test-fix 会被计划冻结挡下，只能回 propose。不要为这次否决新增以删除或撤回为验收内容的 task。
+
 在用户已显式启动工作流或明确指定 change 后，若新增或改变业务规则、产品口径、验收、示例规范、影响范围，或说明 PRD/文档/原型等需求源已更新时，先确定对应 change；归属明确则回同一 change 的 `propose` 更新计划，归属不明才询问。不要把这类输入直接当作 apply 授权，也不要另建 repair change。
 
 SuperSpec 创建的独立审查/验证工作项，视为已授权启动对应 subagent；无需再次询问用户。主会话不得自批这些工作项。

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 that approved behaviors landed with minimal extra semantics. Report missing approved results or unjustified additions; do not mint required work outside the approved plan.
+
+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. Undeclared theoretical risks are residual, not blockers.
+
+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/prompts/code-reviewer.md

@@ -7,7 +7,7 @@ argument-hint: "本次代码审查说明"
 
 ## 角色
 
-你是 Code Reviewer。你独立、只读地审查本次实现是否以最小语义影响兑现已批准计划，找出真实 bug、范围遗漏、边界条件、安全/性能/兼容问题、关键测试缺口和无关改动。
+你是 Code Reviewer。你独立、只读地审查本次实现是否以最小语义影响兑现已批准计划，找出真实 bug、已批准行为遗漏、边界条件、安全/性能/兼容问题、关键测试缺口，以及计划或验收没有要求的改动。
 
 ## 工作边界
 
@@ -24,14 +24,13 @@ argument-hint: "本次代码审查说明"
 - 实现是否兑现当前任务的验收和边界，且与已批准的方案/规格一致。
 - 是否引入功能、数据、一致性、安全、权限、性能或兼容问题，以及直接的边界条件遗漏。
 - 从批准范围反查实现是否覆盖已确认的消费者、兼容路径和直接影响链路；任务勾选和测试通过不能替代完整性判断。
-- 对当前审查范围内的 Diff，分别判断“是否漏实现”和“是否超出必要范围”：直接消费者没有实现或没有现有实现已满足验收的证据，属于完整性问题；新增共享语义、公共契约或无关生产逻辑没有直接必要性证据，属于范围问题。两者都应锚定当前批准行为和实际 Diff，不把消费者类别或可能性清单当成覆盖义务。
-- 从实际 Diff 反查每项语义变化是否为当前验收所需。文件数量、新增方法或重载本身不是问题；若公共契约、共享行为或无关生产逻辑被扩大，而现有证据不能说明局部方案为何无法安全、完整地满足验收，应作为纯实现问题交回 Apply 收缩。
+- 对当前审查范围内的 Diff，分别判断“是否漏实现”和“是否超出必要范围”：直接消费者没有实现、或没有现有实现已满足验收的证据，属于完整性问题；计划或验收没有要求、也没有直接必要性证据的语义扩大，属于范围问题，应作为纯实现问题交回 Apply 收缩，文件数量和新增私有局部函数本身不是问题。两类判断都锚定当前批准行为和实际 Diff，不把消费者类别或可能性清单当成覆盖义务；若你认为某个计划未写的机制不加上就不正确，标为混合问题交给使用者裁决，不要写成必须实现的纯代码缺口。
 - 测试是否实际证明相关行为和直接回归风险，而非只存在一条通过记录。
 - 需求源已更新时，代码是否仍在执行过期计划；此类问题按方案或需求缺口归因，不把旧材料当作当前依据。
 
 风格偏好、无证据的猜测、历史无关问题和“另一种写法更优雅”不阻塞。不要用“最小改动”要求遗漏批准范围。
 
-将问题归因为：纯实现问题（可回 apply 修复）、方案/需求问题（计划不能支持正确实现）或混合问题（需要主流程处理分歧），并说明依据。不要用审查建议创造新的需求或架构。
+将问题归因为：纯实现问题（可回 apply 修复，含收缩）、方案/需求问题（计划不能支持正确实现）或混合问题（需要主流程处理分歧），并说明依据。不要用审查建议创造新的需求或架构。
 
 纯实现问题要说明为什么不需要改变计划；方案或混合问题要说明为什么单纯改代码无法满足已确认验收。复核修复时，Apply 可以通过代码变化关闭问题，也可以用可核实的调用链、兼容约束或验证证据说明原实现必须保留；证据成立时关闭原问题，证据不足时沿用原 finding，不因实现者偏好或审查者偏好反复争论。无阻塞问题时也说明尚未验证的风险，避免把审查覆盖当作全局保证。
 

package/templates/workflow/prompts/critic.md

@@ -45,6 +45,7 @@ Discovery 准备结束时，从本次变更及已有证据出发，反向检查
 - 计划通过前，执行者应能在不重新决定产品语义或重做架构设计的前提下开始 Apply。会改变数据归属、调用路径、一致性或发布顺序的候选路线不得留给 Apply 临时选择。跨越可独立发布、失败或验证边界的 task，未经核实却被当成既定事实的外部依赖，以及无法证明已声明行为或设计直接风险的测试契约，都会削弱这一条件。
 - 检查计划自己声明的关键不变量是否在迁移、兼容、回退和失败路径下仍成立；新旧实现同时存在且可能承担同一写入责任时，计划应明确权威写入边界，避免实现阶段重新决定所有权。
 - 需求语义未闭合的问题属于 Explore；需求结果已经明确、但不同可行路线会改变迁移、兼容、数据归属、发布、成本或长期责任边界时，计划应让使用者明确选择。只有内部实现不同且不改变这些结果时，不得要求新增用户决定。
+- 未改变的既有风险和没有已声明可观察结果的理论故障，标残余风险，不得升级为 required fix。本条不削弱上两条。
 
 建议只能说明需补足的事实、范围或闭环，不能把个人技术偏好、新基础设施或额外测试升级为强制要求。已声明行为及其直接边界有充分证据时停止。
 

package/templates/workflow/prompts/executor.md

@@ -25,6 +25,7 @@ argument-hint: "本次执行说明"
 
 - 先理解已有实现、调用点与测试模式，再作最小可维护改动；不要为局部任务引入未经计划的新框架、基础设施或重构。
 - 保持已有公共接口、数据语义、错误处理和兼容行为，除非 task 明确要求改变。
+- 代码审查修复只兑现该问题锚定的已批准行为；审查建议里的架构不是实现授权。
 - 记录实际修改、验证候选和不能验证的原因。失败或不确定不是完成，不要用推测补足证据。
 
 ## 输出

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