@peterxiaoyang/superspec 0.1.44 → 0.1.45

package/README.md

@@ -131,7 +131,7 @@ superspec.cmd install
 
 你日常主要记住这四个入口就够了。
 
-CLI 不带 `--risk` 时默认走完整审查路径；需要轻量路径时显式传 `--risk normal` 或 `--risk minimal`。探索阶段会创建 `critic` 工作项审查需求澄清记录；计划阶段会创建 `critic`、`architect` 和 `test-engineer` 工作项后再进入实现准备。
+工作流档位由项目配置统一控制，不通过命令行临时指定。探索阶段会按配置创建相应审查工作项；计划阶段按同一档位创建 `critic`、`architect`、`test-engineer` 等必要审查后再进入实现准备。
 
 ## 它会多保存哪些记录
 
@@ -191,6 +191,18 @@ superspec install
 
 `superspec install` 会创建缺失的 `openspec/config.yaml`，或在没有顶层 `context` 时追加这段官方中文 context。如果文件已经有顶层 `context`，SuperSpec 不会覆盖它。
 
+它还会创建项目级 `.superspec/config.json`，用于统一设置整个工作流的默认档位：
+
+```json
+{
+  "workflow": {
+    "mode": "normal"
+  }
+}
+```
+
+可选值为 `minimal`、`normal`、`strict`。`next`、Explore、Propose、进入 Apply 和 Review 都读取此配置；`--risk` 不再是用户可用的工作流入口。已启动的 task attempt 和已经建立的审查策略仍按其事件快照执行，不会被中途改配置追溯改写。
+
 可以用下面的命令检查生成的 instructions 是否包含语言上下文：
 
 ```bash

package/dist/cli.js

@@ -13,6 +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";
 const PACKAGE_NAME = "@peterxiaoyang/superspec";
 const OPENSPEC_PACKAGE_NAME = "@fission-ai/openspec";
 const OPENSPEC_REQUIRED_VERSION = "1.4.1";
@@ -67,19 +68,15 @@ function proposeReadyExitCode(result) {
         return 0;
     return result.events_written === 0 && result.message.includes("不能") ? 1 : 0;
 }
-function parseReviewRisk(value) {
-    if (value == null)
-        return "strict";
-    if (value === "minimal" || value === "normal" || value === "strict")
-        return value;
-    return null;
-}
-function readReviewRisk(opts) {
-    const risk = parseReviewRisk(opts.risk);
-    if (!risk) {
-        console.error("--risk 只能是 minimal、normal 或 strict");
+function ensureWorkflowMode(projectRoot, _opts) {
+    try {
+        workflowRiskForProject(projectRoot);
+        return true;
+    }
+    catch (err) {
+        console.error(err instanceof WorkflowConfigError ? err.message : String(err));
+        return false;
     }
-    return risk;
 }
 function parseVersion(version) {
     const match = version.trim().match(/^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/);
@@ -516,6 +513,7 @@ async function main(argv) {
 transition 子命令：
   init / explore / sync / next / propose-ready / start-apply
   task-start --task <T> / task-complete --task <T> [--input -]
+  reopen --to explore|propose|apply --reason <TEXT>
   reopen --to apply --reason <TEXT> [--review-fix <JOB#FINDING>]
   reopen --to propose --reason <TEXT> [--review-finding <JOB#FINDING>]
   review-ready / accept
@@ -640,16 +638,20 @@ jobs 子命令：
             }
             case "transition": {
                 const cr = changeRoot(projectRoot, change);
+                // mode 只能由项目配置和已冻结 round 快照决定；任何 transition 都不接受 --risk。
+                if (opts.risk !== undefined) {
+                    console.error("工作流模式由 .superspec/config.json 的 workflow.mode 控制，不支持 --risk");
+                    return 1;
+                }
                 switch (subcommand) {
                     case "init":
                         console.log(JSON.stringify(transitionInit(projectRoot, change, cr), null, 2));
                         return 0;
                     case "explore":
                         {
-                            const risk = readReviewRisk(opts);
-                            if (!risk)
+                            if (!ensureWorkflowMode(projectRoot, opts))
                                 return 1;
-                            console.log(JSON.stringify(transitionExplore(projectRoot, change, cr, risk), null, 2));
+                            console.log(JSON.stringify(transitionExplore(projectRoot, change, cr), null, 2));
                         }
                         return 0;
                     case "sync": {
@@ -664,18 +666,16 @@ jobs 子命令：
                         return 0;
                     }
                     case "next": {
-                        const risk = readReviewRisk(opts);
-                        if (!risk)
+                        if (!ensureWorkflowMode(projectRoot, opts))
                             return 1;
-                        const result = nextCmd(projectRoot, change, cr, risk);
+                        const result = nextCmd(projectRoot, change, cr);
                         console.log(JSON.stringify(result, null, 2));
                         return 0;
                     }
                     case "propose-ready": {
-                        const risk = readReviewRisk(opts);
-                        if (!risk)
+                        if (!ensureWorkflowMode(projectRoot, opts))
                             return 1;
-                        const result = proposeReady(projectRoot, change, cr, risk);
+                        const result = proposeReady(projectRoot, change, cr);
                         console.log(JSON.stringify(result, null, 2));
                         return proposeReadyExitCode(result);
                     }
@@ -740,10 +740,9 @@ jobs 子命令：
                         return transitionExitCode(result);
                     }
                     case "review-ready": {
-                        const risk = readReviewRisk(opts);
-                        if (!risk)
+                        if (!ensureWorkflowMode(projectRoot, opts))
                             return 1;
-                        const result = reviewReady(projectRoot, change, cr, risk);
+                        const result = reviewReady(projectRoot, change, cr);
                         console.log(JSON.stringify(result, null, 2));
                         return transitionExitCode(result);
                     }

package/dist/code_review.js

@@ -348,7 +348,9 @@ function changedPathsBetweenSnapshots(projectRoot, start, completed) {
     return { paths: [...changed].sort(), partial_reason: partialReason };
 }
 function testEvidenceForAttempt(events, attempt) {
-    const declaredTests = attempt.contract_mode === true ? attempt.contract?.tests ?? [] : [];
+    const declaredTests = attempt.contract_mode === true
+        ? attempt.required_evidence?.test_ids ?? attempt.contract?.tests ?? []
+        : [];
     const eventsByTest = new Map();
     for (const ev of events) {
         if (ev.event_type !== "test_run_recorded")
@@ -411,14 +413,17 @@ function taskExecutionIndexFromEvents(projectRoot, events) {
             const started = attempts.get(payload.attempt_id);
             const attempt = started?.attempt;
             const effectiveContract = attempt?.contract_mode === true ? attempt.contract ?? null : null;
+            const requiredEvidence = attempt?.required_evidence ?? null;
             const changedResult = changedPathsBetweenSnapshots(projectRoot, started?.boundary ?? null, boundaryFromPayload(ev.payload));
             entries.push({
                 task_id: payload.task_id,
                 attempt_id: payload.attempt_id,
+                execution_policy: attempt?.execution_policy ?? "tdd",
                 changed_paths: changedResult ? changedResult.paths : null,
                 ...(changedResult?.partial_reason ? { changed_paths_partial_reason: changedResult.partial_reason } : {}),
                 contract: effectiveContract,
-                declared_tests: effectiveContract?.tests ?? [],
+                required_evidence: requiredEvidence,
+                declared_tests: requiredEvidence?.test_ids ?? effectiveContract?.tests ?? [],
                 scope_note: payload.scope_note && typeof payload.scope_note === "object" && !Array.isArray(payload.scope_note)
                     ? payload.scope_note
                     : null,

package/dist/format.d.ts

@@ -1,4 +1,4 @@
-import type { ExecutionContract } from "./types.ts";
+import { type ExecutionContract, type ExecutionPolicy } from "./types.ts";
 /** 从 discovery.md 提取"待确认问题"段内的未确认项数量 */
 export declare function countDiscoveryOpenQuestions(content: string): number;
 export interface DiscoveryChainCoverageCheck {
@@ -35,6 +35,8 @@ export interface ParsedExecutionRequirement {
     taskId: string;
     lineIdx: number;
     contract: ExecutionContract;
+    /** 执行依据中实际出现的字段；用于区分“测试为空”和“遗漏测试字段”。 */
+    declaredFields: Array<keyof ExecutionContract>;
     errors: string[];
 }
 export interface TestContractEntry {
@@ -68,7 +70,7 @@ export interface ExecutionRequirementValidation {
     contracts: ParsedExecutionRequirement[];
     errors: string[];
 }
-export declare function validateExecutionRequirements(content: string, testContractContent: string | null): ExecutionRequirementValidation;
+export declare function validateExecutionRequirements(content: string, testContractContent: string | null, executionPolicy?: ExecutionPolicy, executionRequirementVersion?: 1 | 2): ExecutionRequirementValidation;
 /** 返回未完成任务 */
 export declare function pendingTasksInContent(content: string): ParsedTask[];
 /** 在 tasks.md 中按 taskId 精确查找任务（词边界，不误判子串） */

package/dist/format.js

@@ -4,6 +4,7 @@
 // 修改格式 = 修改这里 + 对应 skill。禁止在其它地方重复解析。
 import { readFileSync, existsSync } from "node:fs";
 import { join } from "node:path";
+import { GREEN_ONLY_NO_TDD_REASON } from "./types.js";
 // ===== discovery.md =====
 //
 // 格式（explore skill 定义）：
@@ -151,8 +152,11 @@ const CONTRACT_FIELD_ALIASES = {
     "Design": "design",
     "来源": "source",
     "Source": "source",
-    "原因": "reason",
-    "Reason": "reason",
+    // 原因是历史文档字段；新文档用验收，二者都归一为 acceptance。
+    "验收": "acceptance",
+    "Acceptance": "acceptance",
+    "原因": "acceptance",
+    "Reason": "acceptance",
     "边界": "guard",
     "Guard": "guard",
 };
@@ -197,7 +201,7 @@ function emptyContract() {
         tests: [],
         design: null,
         source: [],
-        reason: null,
+        acceptance: null,
         guard: null,
     };
 }
@@ -224,7 +228,7 @@ function parseExecutionRequirementBlock(lines, task, headerIdx) {
         if (/^\s*-\s+\[[ xX]\]/.test(line)) {
             errors.push(`${task.taskId} 的执行依据内不能包含复选框`);
         }
-        const fieldMatch = line.match(/^\s*-\s*(测试|Tests|设计|Design|来源|Source|原因|Reason|边界|Guard)\s*[:：]\s*(.*)$/);
+        const fieldMatch = line.match(/^\s*-\s*(测试|Tests|设计|Design|来源|Source|验收|Acceptance|原因|Reason|边界|Guard)\s*[:：]\s*(.*)$/);
         if (fieldMatch) {
             const key = CONTRACT_FIELD_ALIASES[fieldMatch[1]];
             const value = fieldMatch[2].trim();
@@ -247,7 +251,7 @@ function parseExecutionRequirementBlock(lines, task, headerIdx) {
         }
         index += 1;
     }
-    return { taskId: task.taskId, lineIdx: task.lineIdx, contract, errors };
+    return { taskId: task.taskId, lineIdx: task.lineIdx, contract, declaredFields: [...seen], errors };
 }
 export function hasTaskBoundExecutionRequirements(content) {
     const lines = content.split("\n");
@@ -343,28 +347,58 @@ export function parseTestContractEntries(content) {
         return { ok: false, entries: [], message: "test-contract.md 没有 TEST-* 行" };
     return { ok: true, entries };
 }
-export function validateExecutionRequirements(content, testContractContent) {
-    const mode = hasTaskBoundExecutionRequirements(content);
+export function validateExecutionRequirements(content, testContractContent, executionPolicy = "tdd", executionRequirementVersion = 2) {
+    const tasks = parseTasksMd(content);
+    // 历史 green-only task 在旧版本中用标记强制进入契约模式。保留该入口，
+    // 防止已生成但尚未执行的 change 在升级后静默退回无验证的 legacy 模式；
+    // 新 Propose 不再产生此标记。
+    const hasLegacyGreenOnlyTask = tasks.some(task => task.noTddReason === GREEN_ONLY_NO_TDD_REASON);
+    // v2 不允许“所有任务都没有执行依据”这一静默回退：新 Propose 的每个普通
+    // task 都必须显式声明五字段。v1 的缺失版本仍保留旧的按需契约语义。
+    const hasV2OrdinaryTask = executionRequirementVersion === 2 && tasks.some(task => !isReviewFixTaskId(task.taskId));
+    const mode = hasTaskBoundExecutionRequirements(content) || hasLegacyGreenOnlyTask || hasV2OrdinaryTask;
     const contracts = parseExecutionRequirements(content);
     // 孤儿检测必须在 mode=false 的 early return 之前：全部块都悬空时 mode=false，
     // 恰恰是最需要报错的场景（否则契约模式静默失效）
     const errors = [...orphanExecutionRequirementErrors(content), ...contracts.flatMap(item => item.errors)];
     if (!mode)
         return { ok: errors.length === 0, mode, contracts, errors };
-    const tasks = parseTasksMd(content);
     const contractsByTask = new Map(contracts.map(item => [item.taskId, item]));
     const declaredTestIds = new Set();
     let needsTestContract = false;
     for (const task of tasks) {
         const contract = contractsByTask.get(task.taskId);
-        if (task.tddRequired && !isReviewFixTaskId(task.taskId)) {
-            if (!contract) {
-                errors.push(`${task.taskId} 缺少执行依据`);
-                continue;
-            }
-            if (contract.contract.tests.length === 0) {
-                errors.push(`${task.taskId} 是普通 TDD 任务，执行依据缺少测试`);
-            }
+        const legacyGreenOnly = task.noTddReason === GREEN_ONLY_NO_TDD_REASON;
+        if (legacyGreenOnly && task.tddRequired) {
+            errors.push(`${task.taskId} 的 no_tdd_reason=${GREEN_ONLY_NO_TDD_REASON} 必须同时声明 tdd_required:false`);
+        }
+        if (legacyGreenOnly && executionPolicy !== "green_only") {
+            errors.push(`${task.taskId} 的 no_tdd_reason=${GREEN_ONLY_NO_TDD_REASON} 只允许用于 GREEN-only apply`);
+        }
+        // v2 是本次改造后的新计划：每个普通 task 必须声明完整五字段，
+        // `测试:` 可显式为空以表达非行为任务。旧计划只保持原 TDD 契约要求。
+        if (executionRequirementVersion === 2 && !isReviewFixTaskId(task.taskId) && !contract) {
+            errors.push(`${task.taskId} 缺少执行依据`);
+            continue;
+        }
+        if (executionRequirementVersion === 1 && task.tddRequired && !isReviewFixTaskId(task.taskId) && !contract) {
+            errors.push(`${task.taskId} 缺少执行依据`);
+            continue;
+        }
+        if (contract && executionRequirementVersion === 2) {
+            if (!contract.declaredFields.includes("tests"))
+                errors.push(`${task.taskId} 的执行依据缺少测试字段`);
+            if (!contract.contract.design)
+                errors.push(`${task.taskId} 的执行依据缺少设计`);
+            if (contract.contract.source.length === 0)
+                errors.push(`${task.taskId} 的执行依据缺少来源`);
+            if (!contract.contract.acceptance)
+                errors.push(`${task.taskId} 的执行依据缺少验收目标`);
+            if (!contract.contract.guard)
+                errors.push(`${task.taskId} 的执行依据缺少边界`);
+        }
+        if (contract && (executionRequirementVersion === 1 && task.tddRequired || legacyGreenOnly) && contract.contract.tests.length === 0) {
+            errors.push(`${task.taskId} 的执行依据缺少测试`);
         }
         if (contract && contract.contract.tests.length > 0) {
             needsTestContract = true;

package/dist/git_state.d.ts

@@ -1,8 +1,13 @@
-import type { DirtyFileFingerprint } from "./types.ts";
+import type { BoundarySnapshot, DirtyFileFingerprint } from "./types.ts";
 export interface GitHeadResult {
     head: string | null;
     reason: string;
 }
+export interface JavaAutoStageResult {
+    status: "staged" | "skipped" | "failed";
+    files: string[];
+    reason?: string;
+}
 export declare function currentGitHead(projectRoot: string): GitHeadResult;
 export declare function normalizeGitPath(rawPath: string): string;
 export declare function gitLines(projectRoot: string, args: string[]): {
@@ -33,4 +38,10 @@ export declare function dirtyCodePaths(projectRoot: string): {
     paths: string[];
     reason: string;
 };
+/**
+ * 仅暂存当前 task 启动后新生成的生产 Java 文件。
+ * 不能安全归因的既有文件改动绝不自动 git add：它们可能包含用户或并行任务的未提交内容。
+ * 测试源码和常见测试类命名会被排除；没有可用的启动边界或 Git 状态异常时，不影响任务完成。
+ */
+export declare function stageProductionJavaFilesSince(projectRoot: string, before: BoundarySnapshot | null): JavaAutoStageResult;
 export declare function projectHasReadableDirectory(projectRoot: string): boolean;

package/dist/git_state.js

@@ -169,6 +169,51 @@ export function dirtyCodePaths(projectRoot) {
         return { ok: false, paths: [], reason: dirty.reason };
     return { ok: true, paths: [...new Set(dirty.files.map(file => file.path))].sort() };
 }
+function isJavaTestPath(path) {
+    const normalized = path.replace(/\\/g, "/");
+    const base = normalized.split("/").pop() ?? normalized;
+    return /(^|\/)src\/test\//i.test(normalized) ||
+        /(?:Test|Tests|TestCase|IT|ITCase)\.java$/i.test(base);
+}
+/**
+ * 仅暂存当前 task 启动后新生成的生产 Java 文件。
+ * 不能安全归因的既有文件改动绝不自动 git add：它们可能包含用户或并行任务的未提交内容。
+ * 测试源码和常见测试类命名会被排除；没有可用的启动边界或 Git 状态异常时，不影响任务完成。
+ */
+export function stageProductionJavaFilesSince(projectRoot, before) {
+    if (!before) {
+        return { status: "skipped", files: [], reason: "missing_task_start_boundary" };
+    }
+    const current = dirtyCodeFiles(projectRoot);
+    if (!current.ok) {
+        return { status: "failed", files: [], reason: current.reason };
+    }
+    const currentByPath = new Map(current.files.map(file => [file.path, file]));
+    const beforeByPath = new Map(before.dirty_files.map(file => [file.path, file]));
+    const files = diffFingerprints(before.dirty_files, current.files)
+        .filter(path => path.toLowerCase().endsWith(".java"))
+        .filter(path => !isJavaTestPath(path))
+        // "added" 且 task-start 边界不存在，才是可归因于本任务的新生成文件。
+        // 已有未跟踪文件或已有源码的任何修改一律不碰，避免把用户工作带入 index。
+        .filter(path => !beforeByPath.has(path) && currentByPath.get(path)?.status === "added")
+        .filter(path => currentByPath.get(path)?.status !== "deleted")
+        .sort();
+    if (files.length === 0)
+        return { status: "skipped", files: [], reason: "no_changed_production_java" };
+    try {
+        execFileSync("git", ["-C", projectRoot, "add", "--", ...files], {
+            stdio: ["ignore", "ignore", "pipe"],
+        });
+        return { status: "staged", files };
+    }
+    catch (err) {
+        return {
+            status: "failed",
+            files,
+            reason: err instanceof Error ? err.message : "git add failed",
+        };
+    }
+}
 export function projectHasReadableDirectory(projectRoot) {
     return existsSync(projectRoot) && statSync(projectRoot).isDirectory();
 }

package/dist/install.d.ts

@@ -10,6 +10,7 @@ export interface InstallResult {
         prompts: string[];
         agents: string[];
         config: string;
+        workflow_config: string;
         agents_md: string;
         openspec_config: string;
     };

package/dist/install.js

@@ -1,6 +1,7 @@
 import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { SUPERSPEC_VERSION } from "./version.js";
+import { DEFAULT_WORKFLOW_RISK, WORKFLOW_CONFIG_PATH } from "./workflow_config.js";
 export const WORKFLOW_SKILLS = [
     "superspec-explore",
     "superspec-propose",
@@ -247,6 +248,16 @@ 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 默认值。
+        // 未执行安装的旧项目仍由 workflowRiskForProject 保守回放 strict。
+        writeFileSync(configPath, JSON.stringify({ workflow: { mode: DEFAULT_WORKFLOW_RISK } }, null, 2) + "\n");
+    }
+    return WORKFLOW_CONFIG_PATH;
+}
 const AGENTS_MD_PATH = "AGENTS.md";
 const SUPERSPEC_AGENTS_START = "<!-- SUPERSPEC:AGENTS:START -->";
 const SUPERSPEC_AGENTS_END = "<!-- SUPERSPEC:AGENTS:END -->";
@@ -304,6 +315,7 @@ export function installProject(projectRoot, options = {}) {
             prompts: copyPrompts(templateRoot, projectRoot),
             agents: copyAgents(templateRoot, projectRoot),
             config: ensureCodexConfig(projectRoot),
+            workflow_config: ensureWorkflowConfig(projectRoot),
             agents_md: ensureAgentsMd(projectRoot, agentsMdTemplate),
             openspec_config: ensureOpenSpecChineseContext(projectRoot),
         },

package/dist/next.d.ts

@@ -1,3 +1,3 @@
 import type { NextOutput } from "./types.ts";
 /** next 命令：读 snapshot，返回唯一可执行路径 */
-export declare function next(projectRoot: string, change: string, changeRoot: string, defaultRisk?: "minimal" | "normal" | "strict"): NextOutput;
+export declare function next(projectRoot: string, change: string, changeRoot: string, defaultRisk?: import("./review.ts").ReviewRisk): NextOutput;

package/dist/next.js

@@ -3,6 +3,7 @@ import { rebuildSnapshot } from "./sync.js";
 import { readEvents } from "./store.js";
 import { requiredJobActions } from "./job_action.js";
 import { planNextStep } from "./phase_plan.js";
+import { workflowRiskForProject } from "./workflow_config.js";
 function requiredJobsOutput(state, change, jobs, reason) {
     return {
         state,
@@ -14,12 +15,6 @@ function requiredJobsOutput(state, change, jobs, reason) {
 function transitionCommand(change, name, extra = "") {
     return `superspec transition ${name} --change "${change}"${extra ? " " + extra : ""}`;
 }
-function riskFlag(risk) {
-    return risk === "strict" ? "" : `--risk ${risk}`;
-}
-function riskArg(risk) {
-    return risk ? riskFlag(risk) : "";
-}
 function formatTransitionArgs(plan) {
     if (plan.taskId)
         return `--task ${plan.taskId}`;
@@ -32,7 +27,7 @@ function formatTransitionArgs(plan) {
     if (plan.reopen?.reason === "review_finding") {
         return `--to propose --review-finding ${plan.reopen.jobId}#${plan.reopen.findingId} --reason "根据代码审查问题 ${plan.reopen.findingId} 回到计划阶段"`;
     }
-    return riskArg(plan.risk);
+    return "";
 }
 function toNextOutput(change, plan) {
     switch (plan.kind) {
@@ -58,7 +53,7 @@ function toNextOutput(change, plan) {
     }
 }
 /** next 命令：读 snapshot，返回唯一可执行路径 */
-export function next(projectRoot, change, changeRoot, defaultRisk = "strict") {
+export function next(projectRoot, change, changeRoot, defaultRisk = workflowRiskForProject(projectRoot)) {
     const snapshot = rebuildSnapshot(projectRoot, change, changeRoot);
     const events = readEvents(projectRoot, change);
     const plannedNextStep = planNextStep({ projectRoot, change, changeRoot, events, snapshot, mode: { kind: "risk", risk: defaultRisk } });

package/dist/phase_confirmation.d.ts

@@ -20,7 +20,13 @@ export interface PhaseConfirmationDecision {
     scope: string;
     answer: string;
     decision: PhaseDecision;
+    review_risk: ReviewRisk;
 }
+/**
+ * 阶段确认不是 mode 的输入。它只读取当前 planning/apply round 的冻结快照；
+ * 仍处于 Explore/Propose 时才从项目配置获取候选 mode。
+ */
+export declare function workflowRiskForPhaseConfirmation(projectRoot: string, events: Event[], snapshot: Snapshot): ReviewRisk;
 export declare function isPhaseConfirmationScope(value: unknown): value is string;
 export declare function phaseConfirmationForBoundary(projectRoot: string, events: Event[], snapshot: Snapshot, boundary: PhaseBoundary, risk?: ReviewRisk): PhaseConfirmation | null;
 export declare function phaseConfirmationForCurrentState(projectRoot: string, events: Event[], snapshot: Snapshot, risk?: ReviewRisk): PhaseConfirmation | null;

package/dist/phase_confirmation.js

@@ -3,6 +3,7 @@ import { historicalProposeReadyRoles, reviewEvidenceDigest, reviewGateRoleResolu
 import { EXPLORE_DISCOVERY_REVIEW_GATE, PROPOSE_FINAL_REVIEW_GATE } from "./review_job_gates.js";
 import { changeRoot as openspecChangeRoot } from "./openspec.js";
 import { findLatestEvent, sha256Text } from "./store.js";
+import { hasFrozenWorkflowModeForProposeRound, workflowRiskForProject, workflowRiskForState, } from "./workflow_config.js";
 export const PHASE_CONFIRMATION_SCOPE_PREFIX = "phase_confirmation:";
 function latestTransition(events, predicate) {
     return findLatestEvent(events, "transition_commit", event => predicate(event.payload));
@@ -25,7 +26,7 @@ const SPECS = {
             },
         ],
         scopePrefix: `${PHASE_CONFIRMATION_SCOPE_PREFIX}explore_to_propose`,
-        epoch: events => latestTransition(events, payload => payload.from_state === "init" && payload.to_state === "explore"),
+        epoch: events => latestTransition(events, payload => payload.to_state === "explore" && payload.from_state !== "explore"),
     },
     propose_to_apply: {
         state: "propose_ready",
@@ -66,9 +67,18 @@ function boundaryForState(state) {
     }
 }
 function ordinaryReviewRolesForBoundary(events, boundary, gate, risk) {
-    return boundary === "propose_to_apply"
-        ? historicalProposeReadyRoles(events)
-        : gate.requiredRolesForRisk(risk);
+    // 历史 plan 没有冻结 mode，当时的 gate 只能按实际创建过的角色回放。
+    if (boundary === "propose_to_apply" && !hasFrozenWorkflowModeForProposeRound(events)) {
+        return historicalProposeReadyRoles(events);
+    }
+    return gate.requiredRolesForRisk(risk);
+}
+/**
+ * 阶段确认不是 mode 的输入。它只读取当前 planning/apply round 的冻结快照；
+ * 仍处于 Explore/Propose 时才从项目配置获取候选 mode。
+ */
+export function workflowRiskForPhaseConfirmation(projectRoot, events, snapshot) {
+    return workflowRiskForState(events, snapshot.state, workflowRiskForProject(projectRoot));
 }
 function materialDigest(projectRoot, events, snapshot, boundary, risk) {
     const head = currentGitHead(projectRoot);
@@ -105,6 +115,7 @@ function materialDigest(projectRoot, events, snapshot, boundary, risk) {
             .sort((left, right) => `${left.gate_id}\u0000${left.role}\u0000${left.job_id}`.localeCompare(`${right.gate_id}\u0000${right.role}\u0000${right.job_id}`))
         : [];
     return sha256Text(JSON.stringify({
+        review_risk: risk,
         documents,
         tasks_structure_digest: snapshot.tasks_structure_digest,
         accepted_jobs: acceptedJobs,
@@ -121,14 +132,13 @@ function materialDigest(projectRoot, events, snapshot, boundary, risk) {
 function phaseRecordArgv(change) {
     return ["superspec", "record", "user-decision", "--change", change, "--input", "-"];
 }
-function nextArgv(change, risk) {
+function nextArgv(change, _risk) {
     return [
         "superspec",
         "transition",
         "next",
         "--change",
         change,
-        ...(risk === "strict" ? [] : ["--risk", risk]),
     ];
 }
 function buildActions(change, boundary, scope, question, specs, risk) {
@@ -220,6 +230,11 @@ export function latestAcceptedPhaseDecision(events, confirmation) {
         scope: confirmation.scope,
         answer: payload.answer,
         decision: payload.phase_confirmation.decision,
+        review_risk: payload.phase_confirmation.review_risk === "minimal" ||
+            payload.phase_confirmation.review_risk === "normal" ||
+            payload.phase_confirmation.review_risk === "strict"
+            ? payload.phase_confirmation.review_risk
+            : "strict",
     };
 }
 export function isPhaseAdvanceAuthorized(events, confirmation) {
@@ -237,6 +252,7 @@ export function phaseConfirmationCommitPayload(confirmation, decision) {
             material_digest: confirmation.material_digest,
             scope: confirmation.scope,
             decision_event_id: decision.event.event_id,
+            review_risk: decision.review_risk,
         },
     };
 }

package/dist/phase_plan.d.ts

@@ -1,5 +1,5 @@
 import type { ReviewGateRule } from "./review_job_gates.ts";
-import type { AcceptedMaterialFollowupContinuation, AskUser, Event, Job, JobRole, State } from "./types.ts";
+import type { AcceptedMaterialFollowupContinuation, AskUser, Event, ExecutionPolicy, Job, JobRole, 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";
@@ -83,11 +83,18 @@ export interface ApplyPendingTaskStatus {
     needsCompletionEvent: string[];
     completedByEvent: string[];
 }
+export declare function executionPolicyForRisk(risk: ReviewRisk): ExecutionPolicy;
+export declare function executionPolicyForCurrentRound(events: Event[]): ExecutionPolicy;
 export declare function proposalDocsBaseline(changeRoot: string): Record<string, string>;
+export declare function discoveryDocsBaseline(changeRoot: string): Record<string, string>;
 export declare function latestAcceptedProposalBaseline(events: Event[]): Record<string, string> | null;
 export declare function latestReopenProposeBaseline(events: Event[]): Record<string, string> | null;
+export declare function latestReopenExploreBaseline(events: Event[]): Record<string, string> | null;
 export declare function proposalDocsChangedSinceBaseline(changeRoot: string, baseline: Record<string, string>): boolean;
+export declare function discoveryDocsChangedSinceBaseline(changeRoot: string, baseline: Record<string, string>): boolean;
 export declare function pendingTaskIds(changeRoot: string): string[];
+/** 当前 Apply round 的规则版本；缺失版本的历史 event 保持 v1 回放。 */
+export declare function executionRequirementVersionForCurrentRound(events: Event[]): 1 | 2;
 export declare function applyRequirementModeForCurrentRound(events: Event[]): boolean;
 export declare function pendingTaskStatusForApply(changeRoot: string, events: Event[]): ApplyPendingTaskStatus;
 export declare function formatPendingTaskMessage(ids: string[], action: string): string;