@peterxiaoyang/superspec 0.1.45 → 0.1.46

package/dist/format.d.ts

@@ -53,6 +53,11 @@ export type TestContractParseResult = {
 };
 /** 解析 tasks.md 的全部任务行 */
 export declare function parseTasksMd(content: string): ParsedTask[];
+/**
+ * tasks.md 的机械结构校验。任务是否拆分合理、顺序是否符合真实依赖仍由
+ * Critic/Architect 判断；这里仅拒绝引擎无法可靠驱动的格式。
+ */
+export declare function validateTasksDocument(content: string): string[];
 export declare function hasTaskBoundExecutionRequirements(content: string): boolean;
 export declare function parseExecutionRequirements(content: string): ParsedExecutionRequirement[];
 export declare function orphanExecutionRequirementErrors(content: string): string[];
@@ -64,12 +69,23 @@ export declare function adoptedContractForTask(content: string, taskId: string,
 export declare function isReviewFixTaskId(taskId: string): boolean;
 export declare function isCharacterizationTask(task: ParsedTask): boolean;
 export declare function parseTestContractEntries(content: string): TestContractParseResult;
+export interface ProposalImpactValidation {
+    ok: boolean;
+    message: string;
+}
+/** OpenSpec 项目的 proposal 采用固定 Impact 表格，供状态机进行纯结构校验。 */
+export declare function validateProposalImpact(content: string): ProposalImpactValidation;
 export interface ExecutionRequirementValidation {
     ok: boolean;
     mode: boolean;
     contracts: ParsedExecutionRequirement[];
     errors: string[];
 }
+/**
+ * 在已初始化的当前工作流中，把执行依据的文件/锚点可解析性作为状态机协议。
+ * “该材料是否足以支撑 task”仍然是 Critic/Architect 的语义判断。
+ */
+export declare function validateExecutionRequirementDocumentReferences(changeRoot: string, contracts: readonly ParsedExecutionRequirement[]): string[];
 export declare function validateExecutionRequirements(content: string, testContractContent: string | null, executionPolicy?: ExecutionPolicy, executionRequirementVersion?: 1 | 2): ExecutionRequirementValidation;
 /** 返回未完成任务 */
 export declare function pendingTasksInContent(content: string): ParsedTask[];

package/dist/format.js

@@ -1,9 +1,9 @@
 // SuperSpec 流程引擎 — format.ts：文档格式解析的唯一权威源
 //
-// 所有文档的格式定义和解析逻辑都在这里。skills 文案引用这里的格式。
-// 修改格式 = 修改这里 + 对应 skill。禁止在其它地方重复解析。
-import { readFileSync, existsSync } from "node:fs";
-import { join } from "node:path";
+// 所有可机械判定的文档协议、格式定义和解析逻辑都在这里。skills 只指导
+// 生成与语义判断，不得自行充当格式校验器或在其它地方重复解析。
+import { readFileSync, existsSync, realpathSync } from "node:fs";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
 import { GREEN_ONLY_NO_TDD_REASON } from "./types.js";
 // ===== discovery.md =====
 //
@@ -52,6 +52,7 @@ const DISCOVERY_CHAIN_REQUIRED_COLUMNS = [
     "证据",
     "状态",
 ];
+const DISCOVERY_CHAIN_STATUSES = new Set(["已确认", "未知阻塞", "未知非阻塞"]);
 export function splitMarkdownTableRow(line) {
     const trimmed = line.trim();
     if (!trimmed.startsWith("|") || !trimmed.endsWith("|"))
@@ -95,6 +96,9 @@ export function validateDiscoveryChainCoverage(content) {
             }
         }
         const status = cells[statusIdx]?.trim() ?? "";
+        if (!DISCOVERY_CHAIN_STATUSES.has(status)) {
+            return { ok: false, message: `链路五要素第 ${rowNum} 行状态必须是 已确认、未知阻塞 或 未知非阻塞`, present: true };
+        }
         if (status.includes("未知阻塞") && countDiscoveryOpenQuestions(content) === 0) {
             return { ok: false, message: "链路五要素存在未知阻塞，但待确认问题中没有未解决项", present: true };
         }
@@ -183,6 +187,28 @@ export function parseTasksMd(content) {
     }
     return tasks;
 }
+/**
+ * tasks.md 的机械结构校验。任务是否拆分合理、顺序是否符合真实依赖仍由
+ * Critic/Architect 判断；这里仅拒绝引擎无法可靠驱动的格式。
+ */
+export function validateTasksDocument(content) {
+    const errors = [];
+    if (!/^#\s+Tasks\s*$/m.test(content))
+        errors.push("tasks.md 缺少顶级 # Tasks 标题");
+    const tasks = parseTasksMd(content);
+    const seen = new Set();
+    for (const task of tasks) {
+        if (seen.has(task.taskId))
+            errors.push(`tasks.md task ID 重复：${task.taskId}`);
+        seen.add(task.taskId);
+    }
+    for (const [index, line] of content.split("\n").entries()) {
+        if (/^\s+-\s+\[[ xX]\]\s+/.test(line)) {
+            errors.push(`tasks.md 第 ${index + 1} 行存在缩进 checkbox；只有顶格 checkbox 可以作为可执行 task`);
+        }
+    }
+    return errors;
+}
 function isTopLevelTaskLine(line) {
     return TASK_LINE_RE.test(line);
 }
@@ -329,15 +355,23 @@ export function parseTestContractEntries(content) {
             if (row.length === 0)
                 break;
             const testId = (row[testIdIdx] ?? "").trim();
-            if (!testId.startsWith("TEST-"))
-                continue;
+            const scenario = (row[scenarioIdx] ?? "").trim();
+            if (!testId) {
+                return { ok: false, entries: [], message: `test-contract.md 第 ${rowIndex + 1} 行缺少 test_id` };
+            }
+            if (!/^TEST-[A-Za-z0-9_-]+$/.test(testId)) {
+                return { ok: false, entries: [], message: `test-contract.md 中 TEST ID 格式无效：${testId}` };
+            }
             if (seen.has(testId)) {
                 return { ok: false, entries: [], message: `test-contract.md 中 TEST ID 重复：${testId}` };
             }
+            if (!scenario) {
+                return { ok: false, entries: [], message: `test-contract.md 中 ${testId} 缺少 scenario` };
+            }
             seen.add(testId);
             entries.push({
                 test_id: testId,
-                scenario: (row[scenarioIdx] ?? "").trim(),
+                scenario,
             });
         }
     }
@@ -347,6 +381,127 @@ export function parseTestContractEntries(content) {
         return { ok: false, entries: [], message: "test-contract.md 没有 TEST-* 行" };
     return { ok: true, entries };
 }
+/** OpenSpec 项目的 proposal 采用固定 Impact 表格，供状态机进行纯结构校验。 */
+export function validateProposalImpact(content) {
+    const body = sectionBodyByHeadings(content, ["Impact"]);
+    if (body == null)
+        return { ok: false, message: "proposal.md 缺少 ## Impact" };
+    const tableLines = body.split("\n").filter(line => line.trim().startsWith("|"));
+    if (tableLines.length < 3 || !isMarkdownTableSeparator(tableLines[1])) {
+        return { ok: false, message: "proposal.md 的 Impact 必须包含 Area / Reason 表格" };
+    }
+    const header = splitMarkdownTableRow(tableLines[0]).map(cell => cell.toLowerCase());
+    const areaIdx = header.indexOf("area");
+    const reasonIdx = header.indexOf("reason");
+    if (areaIdx < 0 || reasonIdx < 0) {
+        return { ok: false, message: "proposal.md 的 Impact 表格缺少 Area 或 Reason 列" };
+    }
+    const rows = tableLines.slice(2).map(splitMarkdownTableRow).filter(cells => cells.length > 0);
+    if (rows.length === 0)
+        return { ok: false, message: "proposal.md 的 Impact 表格至少需要一行" };
+    for (const [index, row] of rows.entries()) {
+        if (!row[areaIdx]?.trim() || !row[reasonIdx]?.trim()) {
+            return { ok: false, message: `proposal.md 的 Impact 第 ${index + 1} 行缺少 Area 或 Reason` };
+        }
+    }
+    return { ok: true, message: "proposal.md Impact 结构有效" };
+}
+function isQualifiedDocumentRef(value) {
+    const ref = value.trim();
+    return /^(?!\/)(?!.*(?:^|\/)\.\.(?:\/|$))[^\s#]+\.md#[^\s].*$/.test(ref);
+}
+function executionRequirementReferenceErrors(contract) {
+    const errors = [];
+    if (contract.contract.design && !isQualifiedDocumentRef(contract.contract.design)) {
+        errors.push(`${contract.taskId} 的设计必须使用 文件.md#标题 的可定位引用`);
+    }
+    for (const source of contract.contract.source) {
+        if (!isQualifiedDocumentRef(source)) {
+            errors.push(`${contract.taskId} 的来源必须使用 文件.md#标题 的可定位引用：${source}`);
+        }
+    }
+    return errors;
+}
+function parseQualifiedDocumentRef(value) {
+    const ref = value.trim();
+    const separator = ref.indexOf("#");
+    if (separator <= 0 || separator === ref.length - 1)
+        return null;
+    return { path: ref.slice(0, separator), anchor: ref.slice(separator + 1).trim() };
+}
+function isPathInside(root, target) {
+    const rel = relative(root, target);
+    return rel !== "" && !rel.startsWith(`..${sep}`) && rel !== ".." && !isAbsolute(rel);
+}
+function documentContainsAnchor(content, anchor) {
+    if (/^(?:TEST|CHAIN|IDC)-[A-Za-z0-9_-]+$/.test(anchor)) {
+        const token = new RegExp(`(?:^|[^A-Za-z0-9_-])${escapeRegex(anchor)}(?![A-Za-z0-9_-])`);
+        return token.test(content);
+    }
+    // 支持 Markdown ATX 标题可选的 closing sequence（`## Route ##`），但正文
+    // 中同名文字仍不能冒充可定位锚点。
+    const heading = new RegExp(`^#{1,6}[\\t ]+${escapeRegex(anchor)}(?:[\\t ]+#+)?[\\t ]*$`, "m");
+    return heading.test(content);
+}
+function documentAnchorParts(anchor) {
+    const parts = anchor.split(",").map(part => part.trim()).filter(Boolean);
+    return parts.length > 1 && parts.every(part => /^(?:TEST|CHAIN|IDC)-[A-Za-z0-9_-]+$/.test(part))
+        ? parts
+        : [anchor];
+}
+function canonicalDocumentRefPath(path) {
+    if (path === "discovery.md" || path === "test-contract.md") {
+        return join(".superspec", "artifacts", path);
+    }
+    return path;
+}
+/**
+ * 在已初始化的当前工作流中，把执行依据的文件/锚点可解析性作为状态机协议。
+ * “该材料是否足以支撑 task”仍然是 Critic/Architect 的语义判断。
+ */
+export function validateExecutionRequirementDocumentReferences(changeRoot, contracts) {
+    const root = resolve(changeRoot);
+    const realRoot = realpathSync(root);
+    const errors = [];
+    for (const contract of contracts) {
+        const refs = [contract.contract.design, ...contract.contract.source].filter((value) => Boolean(value));
+        for (const ref of refs) {
+            const parsed = parseQualifiedDocumentRef(ref);
+            if (!parsed)
+                continue; // 语法错误由 executionRequirementReferenceErrors 报告。
+            const target = resolve(root, canonicalDocumentRefPath(parsed.path));
+            if (!isPathInside(root, target)) {
+                errors.push(`${contract.taskId} 的引用越出 change 目录：${ref}`);
+                continue;
+            }
+            if (!existsSync(target)) {
+                errors.push(`${contract.taskId} 的引用文件不存在：${parsed.path}`);
+                continue;
+            }
+            // resolve/relative 只能识别字面 `..`，不能阻止 change 内的符号链接指向
+            // 外部文件；按真实路径再次校验，确保引用材料仍属于当前 change。
+            let realTarget;
+            try {
+                realTarget = realpathSync(target);
+            }
+            catch {
+                errors.push(`${contract.taskId} 的引用文件无法解析：${parsed.path}`);
+                continue;
+            }
+            if (!isPathInside(realRoot, realTarget)) {
+                errors.push(`${contract.taskId} 的引用越出 change 目录：${ref}`);
+                continue;
+            }
+            const targetContent = readFileSync(target, "utf8");
+            for (const anchor of documentAnchorParts(parsed.anchor)) {
+                if (!documentContainsAnchor(targetContent, anchor)) {
+                    errors.push(`${contract.taskId} 的引用锚点不存在：${parsed.path}#${anchor}`);
+                }
+            }
+        }
+    }
+    return errors;
+}
 export function validateExecutionRequirements(content, testContractContent, executionPolicy = "tdd", executionRequirementVersion = 2) {
     const tasks = parseTasksMd(content);
     // 历史 green-only task 在旧版本中用标记强制进入契约模式。保留该入口，
@@ -396,6 +551,7 @@ export function validateExecutionRequirements(content, testContractContent, exec
                 errors.push(`${task.taskId} 的执行依据缺少验收目标`);
             if (!contract.contract.guard)
                 errors.push(`${task.taskId} 的执行依据缺少边界`);
+            errors.push(...executionRequirementReferenceErrors(contract));
         }
         if (contract && (executionRequirementVersion === 1 && task.tddRequired || legacyGreenOnly) && contract.contract.tests.length === 0) {
             errors.push(`${task.taskId} 的执行依据缺少测试`);
@@ -484,11 +640,12 @@ export function validateUserDecision(d) {
 }
 // ===== test-contract.md =====
 //
-// 格式（propose skill 定义）：
+// 格式（状态机校验，propose skill 负责生成）：
 //   # Test Contract
 //   | test_id | scenario |
 //   |---|---|
 //   | TEST-001 | 注册时密码被加密 |
 //
-// 引擎行为：Phase 1-5 只校验文件存在性（轻量）。
-// 表格结构是 agent 指引，引擎不逐行解析。
+// 引擎行为：当 task 声明 TEST 时，状态机解析表格、TEST ID 和 scenario，
+// 并在 propose-ready / start-apply 阶段拒绝无效引用；测试语义和证明力仍由
+// Test Engineer 判断。

package/dist/openspec.d.ts

@@ -4,6 +4,19 @@ export interface OpenSpecProbe {
     changeExists: boolean;
     error?: string;
 }
+export interface OpenSpecStrictValidation {
+    /** 调用方已经按冻结 profile 决定是否执行 strict validation。 */
+    checked: boolean;
+    ok: boolean;
+    message: string;
+}
 export declare function probeOpenSpec(projectRoot: string, change?: string): OpenSpecProbe;
 export declare function openspecStatus(projectRoot: string, change: string): string;
+/**
+ * 计划阶段的原生 OpenSpec 结构 gate。
+ *
+ * 调用方已通过冻结的 planning profile 确认应执行 strict validation。这里不再
+ * 读取实时 config.yaml，避免计划就绪后环境变化导致准入标准漂移。
+ */
+export declare function validateOpenSpecChange(projectRoot: string, change: string): OpenSpecStrictValidation;
 export declare function changeRoot(projectRoot: string, change: string): string;

package/dist/openspec.js

@@ -36,6 +36,34 @@ export function openspecStatus(projectRoot, change) {
         return "sha256:unknown";
     }
 }
+/**
+ * 计划阶段的原生 OpenSpec 结构 gate。
+ *
+ * 调用方已通过冻结的 planning profile 确认应执行 strict validation。这里不再
+ * 读取实时 config.yaml，避免计划就绪后环境变化导致准入标准漂移。
+ */
+export function validateOpenSpecChange(projectRoot, change) {
+    validateChange(change);
+    try {
+        execFileSync("openspec", ["validate", change, "--type", "change", "--strict", "--no-interactive"], {
+            cwd: projectRoot,
+            encoding: "utf8",
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+        return { checked: true, ok: true, message: "OpenSpec 原生结构校验通过" };
+    }
+    catch (error) {
+        const failure = error;
+        const stdout = typeof failure.stdout === "string" ? failure.stdout : failure.stdout?.toString("utf8") ?? "";
+        const stderr = typeof failure.stderr === "string" ? failure.stderr : failure.stderr?.toString("utf8") ?? "";
+        const detail = [stdout, stderr].map(value => value.trim()).filter(Boolean).join("；");
+        return {
+            checked: true,
+            ok: false,
+            message: `OpenSpec strict 校验失败${detail ? `：${detail}` : "；请确认 openspec CLI 可用并修复 proposal/specs 结构"}`,
+        };
+    }
+}
 export function changeRoot(projectRoot, change) {
     return join(projectRoot, "openspec", "changes", change);
 }

package/dist/phase_plan.d.ts

@@ -1,5 +1,5 @@
 import type { ReviewGateRule } from "./review_job_gates.ts";
-import type { AcceptedMaterialFollowupContinuation, AskUser, Event, ExecutionPolicy, Job, JobRole, State } from "./types.ts";
+import type { AcceptedMaterialFollowupContinuation, AskUser, Event, ExecutionPolicy, Job, JobRole, PlanningValidationProfile, 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";
@@ -95,6 +95,8 @@ export declare function discoveryDocsChangedSinceBaseline(changeRoot: string, ba
 export declare function pendingTaskIds(changeRoot: string): string[];
 /** 当前 Apply round 的规则版本；缺失版本的历史 event 保持 v1 回放。 */
 export declare function executionRequirementVersionForCurrentRound(events: Event[]): 1 | 2;
+/** 新 planning round 在进入 propose 时冻结当前 OpenSpec 校验契约。 */
+export declare function planningValidationProfileForNewRound(projectRoot: string): PlanningValidationProfile;
 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;

package/dist/phase_plan.js

@@ -1,8 +1,9 @@
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { EXPLORE_DISCOVERY_REVIEW_GATE, PROPOSE_FINAL_REVIEW_GATE } from "./review_job_gates.js";
-import { collectProposeOpenQuestions, countDiscoveryOpenQuestions, parseTasksMd, pendingTasksInContent, validateDiscovery, validateExecutionRequirements, } from "./format.js";
+import { collectProposeOpenQuestions, countDiscoveryOpenQuestions, parseExecutionRequirements, parseTasksMd, pendingTasksInContent, validateDiscovery, validateExecutionRequirements, validateExecutionRequirementDocumentReferences, validateProposalImpact, validateTasksDocument, } from "./format.js";
 import { currentGitHead } from "./git_state.js";
+import { validateOpenSpecChange } from "./openspec.js";
 import { docRef, sha256File } from "./store.js";
 import { isReviewReadyVerifier, isFreshReviewVerifier, historicalProposeReadyRoles, readReviewPolicyFromEvents, reviewGateRoleResolution, reviewRejectionOverrideScope, reviewEvidenceDigest, } from "./review.js";
 import { CODE_REVIEW_DECISION_ANSWER_LABELS, CODE_REVIEW_REPAIR_SCOPE_PREFIX, codeReviewDecisionScope, codeReviewJobStaleReason, collectCodeReviewGateFacts, currentCodeReviewWorkingPaths, latestCodeReviewFailedStatus, requiresFinalVerifierForCurrentReview, scanCodeChangesForReview, } from "./code_review.js";
@@ -79,13 +80,19 @@ function reviewGatePlan(snapshot, events, changeRoot, gate, requiredRoles) {
     }
     return null;
 }
-function validateTasksPlan(changeRoot) {
+function validateTasksPlan(changeRoot, executionRequirementVersion) {
     const tasksPath = join(changeRoot, "tasks.md");
     if (!existsSync(tasksPath))
         return "tasks.md 不存在";
     const tasksContent = readFileSync(tasksPath, "utf8");
-    if (!tasksContent.includes("# Tasks") && !tasksContent.includes("- [ ]"))
-        return "tasks.md 内容不像任务计划文档";
+    if (executionRequirementVersion === 1) {
+        return tasksContent.includes("# Tasks") || tasksContent.includes("- [ ]")
+            ? null
+            : "tasks.md 内容不像任务计划文档";
+    }
+    const errors = validateTasksDocument(tasksContent);
+    if (errors.length > 0)
+        return errors.join("；");
     return null;
 }
 export function executionPolicyForRisk(risk) {
@@ -122,6 +129,43 @@ function missingBaseArtifact(changeRoot, risk) {
     }
     return null;
 }
+/** OpenSpec strict gate 只在当前 planning round 冻结为 strict 时执行。 */
+function validateOpenSpecPlanningDocuments(projectRoot, change, changeRoot, profile) {
+    if (profile == null || profile.openspec.mode !== "strict")
+        return null;
+    const currentConfigDigest = sha256File(join(projectRoot, "openspec", "config.yaml"));
+    if (currentConfigDigest !== profile.openspec.config_digest) {
+        return "OpenSpec 配置自本 planning round 起已变化；请恢复原配置或 reopen --to propose 创建新的计划轮";
+    }
+    const tasksPath = join(changeRoot, "tasks.md");
+    const referenceErrors = validateExecutionRequirementDocumentReferences(changeRoot, parseExecutionRequirements(readFileSync(tasksPath, "utf8")));
+    if (referenceErrors.length > 0)
+        return referenceErrors.join("；");
+    const proposalPath = join(changeRoot, "proposal.md");
+    if (!existsSync(proposalPath))
+        return "proposal.md 不存在";
+    const impact = validateProposalImpact(readFileSync(proposalPath, "utf8"));
+    if (!impact.ok)
+        return impact.message;
+    const native = validateOpenSpecChange(projectRoot, change);
+    return native.ok ? null : native.message;
+}
+function validatePlanningPreflight(projectRoot, change, changeRoot, risk, executionPolicy, profile) {
+    const executionRequirementVersion = profile?.version ?? 1;
+    const tasksPlanError = validateTasksPlan(changeRoot, executionRequirementVersion);
+    if (tasksPlanError)
+        return { error: tasksPlanError, contractMode: false };
+    const executionRequirementPlan = validateExecutionRequirementPlan(changeRoot, executionPolicy, executionRequirementVersion);
+    if (!executionRequirementPlan.ok)
+        return { error: executionRequirementPlan.message, contractMode: false };
+    const missingArtifact = missingBaseArtifact(changeRoot, risk);
+    if (missingArtifact)
+        return { error: missingArtifact, contractMode: false };
+    return {
+        error: validateOpenSpecPlanningDocuments(projectRoot, change, changeRoot, profile),
+        contractMode: executionRequirementPlan.mode,
+    };
+}
 export function proposalDocsBaseline(changeRoot) {
     // 与 Propose gate 的可修改审查目标保持同一来源：specs/ 用目录聚合指纹，避免 reopen 基线漏掉任一个可修改的计划材料。
     const docs = PROPOSE_FINAL_REVIEW_GATE.reviewTargets;
@@ -234,6 +278,62 @@ function executionRequirementVersionForProposeRound(events) {
     }
     return 1;
 }
+function isPlanningValidationProfile(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const profile = value;
+    if (profile.version !== 2 || !profile.openspec || typeof profile.openspec !== "object")
+        return false;
+    return profile.openspec.mode === "disabled" ||
+        profile.openspec.mode === "strict" && typeof profile.openspec.config_digest === "string";
+}
+/** 新 planning round 在进入 propose 时冻结当前 OpenSpec 校验契约。 */
+export function planningValidationProfileForNewRound(projectRoot) {
+    const configDigest = sha256File(join(projectRoot, "openspec", "config.yaml"));
+    return configDigest == null
+        ? { version: 2, openspec: { mode: "disabled" } }
+        : { version: 2, openspec: { mode: "strict", config_digest: configDigest } };
+}
+/** propose 状态尚未 ready 时，从进入本 planning round 的事件读取冻结 profile。 */
+function planningValidationProfileForPendingProposeRound(events) {
+    for (let i = events.length - 1; i >= 0; i--) {
+        const event = events[i];
+        if (event.event_type !== "transition_commit")
+            continue;
+        const payload = event.payload;
+        // 只读取“进入 propose”的边界事件。propose-ready 创建审查 job 时也会
+        // 保持在 propose；若把它误当作新的 planning round，便会覆盖此前冻结的
+        // profile 并把当前轮错误降级为 v1。
+        const entersPropose = payload.to_state === "propose" && (payload.transition === "explore" ||
+            payload.transition === "propose" ||
+            payload.transition === "reopen" && payload.reopen_target === "propose");
+        if (!entersPropose)
+            continue;
+        return isPlanningValidationProfile(payload.planning_validation_profile)
+            ? payload.planning_validation_profile
+            : null;
+    }
+    return null;
+}
+/** 已完成 propose-ready 的 round 只回放当时冻结的 profile。 */
+function planningValidationProfileForReadyProposeRound(events) {
+    for (let i = events.length - 1; i >= 0; i--) {
+        const event = events[i];
+        if (event.event_type !== "transition_commit")
+            continue;
+        const payload = event.payload;
+        if (payload.transition !== "propose-ready" || payload.to_state !== "propose_ready")
+            continue;
+        if (isPlanningValidationProfile(payload.planning_validation_profile))
+            return payload.planning_validation_profile;
+        // 过渡期已写 v2 执行依据、但尚未带 profile 的事件保持 v2 tasks 契约，
+        // 但不在 start-apply 追溯新增 strict gate。
+        return executionRequirementVersionFromPayload(event.payload) === 2
+            ? { version: 2, openspec: { mode: "disabled" } }
+            : null;
+    }
+    return null;
+}
 export function applyRequirementModeForCurrentRound(events) {
     const index = latestStartApplyIndex(events);
     if (index < 0)
@@ -730,7 +830,11 @@ function planExploreTransition(context) {
         fromState: "explore",
         toState: "propose",
         reason: "探索完成",
-        payload: phaseConfirmationCommitPayload(confirmation, decision),
+        payload: {
+            ...phaseConfirmationCommitPayload(confirmation, decision),
+            planning_validation_version: 2,
+            planning_validation_profile: planningValidationProfileForNewRound(projectRoot),
+        },
     };
 }
 function planProposeReadyTransition(context) {
@@ -738,20 +842,15 @@ function planProposeReadyTransition(context) {
     const risk = mode.risk;
     if (snapshot.state !== "propose")
         return { kind: "skip", message: `当前状态 ${snapshot.state}，不能 propose-ready` };
-    const tasksPlanError = validateTasksPlan(changeRoot);
-    if (tasksPlanError)
-        return { kind: "skip", message: tasksPlanError };
-    const executionRequirementPlan = validateExecutionRequirementPlan(changeRoot, executionPolicyForRisk(risk), 2);
-    if (!executionRequirementPlan.ok)
-        return { kind: "skip", message: executionRequirementPlan.message };
+    const planningProfile = planningValidationProfileForPendingProposeRound(context.events);
+    const preflight = validatePlanningPreflight(context.projectRoot, context.change, changeRoot, risk, executionPolicyForRisk(risk), planningProfile);
+    if (preflight.error)
+        return { kind: "skip", message: preflight.error };
     const openQuestions = collectProposeOpenQuestions(changeRoot);
     if (openQuestions.openCount > 0) {
         const files = openQuestions.files.map(f => `${f.path}(${f.openCount})`).join(", ");
         return { kind: "skip", message: `计划文档有 ${openQuestions.openCount} 个待用户确认问题：${files}` };
     }
-    const missingArtifact = missingBaseArtifact(changeRoot, risk);
-    if (missingArtifact)
-        return { kind: "skip", message: missingArtifact };
     const requiredRoles = PROPOSE_FINAL_REVIEW_GATE.requiredRolesForRisk(risk);
     const gatePlan = reviewGatePlan(snapshot, context.events, changeRoot, PROPOSE_FINAL_REVIEW_GATE, requiredRoles);
     if (gatePlan)
@@ -763,7 +862,11 @@ function planProposeReadyTransition(context) {
         reason: `risk=${risk}，所有需求已满足`,
         payload: {
             workflow_mode: risk,
-            execution_requirement_version: 2,
+            ...(planningProfile ? {
+                execution_requirement_version: 2,
+                planning_validation_version: 2,
+                planning_validation_profile: planningProfile,
+            } : {}),
         },
     };
 }
@@ -782,7 +885,12 @@ function planStartApplyTransition(context, enforceConfirmation = true) {
         return { kind: "skip", message: `回到 propose 后至少一个计划文档必须变化（基线绑定：${Object.keys(reopenBaseline).join("、")}）` };
     }
     const risk = workflowRiskForProposeRound(events, context.mode.risk);
-    const executionRequirementVersion = executionRequirementVersionForProposeRound(events);
+    const planningProfile = planningValidationProfileForReadyProposeRound(events);
+    const executionRequirementVersion = planningProfile?.version ?? executionRequirementVersionForProposeRound(events);
+    const executionPolicy = executionPolicyForRisk(risk);
+    const preflight = validatePlanningPreflight(projectRoot, context.change, changeRoot, risk, executionPolicy, planningProfile);
+    if (preflight.error)
+        return { kind: "skip", message: preflight.error };
     const requiredRoles = executionRequirementVersion === 2
         ? PROPOSE_FINAL_REVIEW_GATE.requiredRolesForRisk(risk)
         : historicalProposeReadyRoles(events);
@@ -796,10 +904,6 @@ function planStartApplyTransition(context, enforceConfirmation = true) {
     const acceptedConfirmation = enforceConfirmation
         ? acceptedProposeToApplyConfirmation(context, risk)
         : null;
-    const executionPolicy = executionPolicyForRisk(risk);
-    const executionRequirementPlan = validateExecutionRequirementPlan(changeRoot, executionPolicy, executionRequirementVersion);
-    if (!executionRequirementPlan.ok)
-        return { kind: "skip", message: executionRequirementPlan.message };
     if (enforceConfirmation && !acceptedConfirmation) {
         const confirmation = phaseConfirmationForBoundary(projectRoot, events, snapshot, "propose_to_apply", risk);
         return {
@@ -816,7 +920,7 @@ function planStartApplyTransition(context, enforceConfirmation = true) {
         payload: {
             apply_start_head: gitHead.head,
             apply_start_head_reason: gitHead.reason,
-            apply_contract_mode: executionRequirementPlan.mode,
+            apply_contract_mode: preflight.contractMode,
             ...(executionRequirementVersion === 2 ? { execution_requirement_version: 2 } : {}),
             execution_policy: executionPolicy,
             workflow_mode: risk,

package/dist/transition.js

@@ -9,7 +9,7 @@ import { REVIEW_CODE_REVIEW_GATE_ID, REVIEW_FINAL_VERIFIER_GATE_ID, reviewScopeF
 import { codeReviewBoundFiles, codeReviewDecisionScope, codeReviewJobStaleReason, codeReviewPacketContext, codeReviewPacketDigest, collectCodeReviewGateFacts, computeCodeStateCheck, currentCodeReviewWorkingPaths, dismissedCodeReviewSummary, latestCodeReviewDecision, latestCodeReviewFailedStatus, missingCoverageExemptionTestIds, requiresFinalVerifierForCurrentReview, scanCodeChangesForReview, } from "./code_review.js";
 import { taskEvidenceReadiness } from "./task_evidence.js";
 import { adoptedContractForTask, findTaskInLines, isReviewFixTaskId, parseTasksMd, parseTestContractEntries, } from "./format.js";
-import { applyRequirementModeForCurrentRound, executionRequirementVersionForCurrentRound, blockingJobsForApplyDone, executionPolicyForCurrentRound, formatPendingTaskMessage, latestAcceptedProposalBaseline, pendingTaskStatusForApply, planTransition, discoveryDocsBaseline, proposalDocsBaseline, } from "./phase_plan.js";
+import { applyRequirementModeForCurrentRound, executionRequirementVersionForCurrentRound, blockingJobsForApplyDone, executionPolicyForCurrentRound, formatPendingTaskMessage, latestAcceptedProposalBaseline, pendingTaskStatusForApply, planningValidationProfileForNewRound, planTransition, discoveryDocsBaseline, proposalDocsBaseline, } from "./phase_plan.js";
 import { latestAcceptedPhaseDecision, phaseConfirmationCommitPayload, phaseConfirmationForBoundary, phaseConfirmationMissingMessage, } from "./phase_confirmation.js";
 import { currentGitHead, dirtyCodeFiles, stageProductionJavaFilesSince } from "./git_state.js";
 import { workflowRiskForProject } from "./workflow_config.js";
@@ -826,6 +826,8 @@ export function reopen(projectRoot, change, changeRoot, to, reason, opts = {}) {
                         finding_id: ref.findingId,
                         decision_scope: scope,
                         baseline_docs: proposalDocsBaseline(changeRoot),
+                        planning_validation_version: 2,
+                        planning_validation_profile: planningValidationProfileForNewRound(projectRoot),
                     },
                 };
             }
@@ -915,6 +917,8 @@ export function reopen(projectRoot, change, changeRoot, to, reason, opts = {}) {
                         reopen_source: snapshot.state,
                         baseline_source: acceptedBaseline ? (baselineNeedsBackfill ? "accepted_backfill" : "accepted") : "reopen_fallback",
                         baseline_docs: baselineDocs,
+                        planning_validation_version: 2,
+                        planning_validation_profile: planningValidationProfileForNewRound(projectRoot),
                     },
                     extraEvents: planningReopenExtraEvents(snapshot, "propose", reason.trim()),
                 };

package/dist/types.d.ts

@@ -156,6 +156,16 @@ export interface Event {
     payload: Record<string, unknown>;
     event_digest: string;
 }
+export type OpenSpecValidationProfile = {
+    mode: "disabled";
+} | {
+    mode: "strict";
+    config_digest: string;
+};
+export interface PlanningValidationProfile {
+    version: 2;
+    openspec: OpenSpecValidationProfile;
+}
 export interface TransitionCommitPayload {
     transition: string;
     from_state: State;
@@ -190,6 +200,10 @@ export interface TransitionCommitPayload {
     workflow_mode?: "minimal" | "normal" | "strict";
     /** v2 起所有普通任务必须有五字段执行依据；缺失表示旧 change，沿用旧规则回放。 */
     execution_requirement_version?: 2;
+    /** 新 planning round 的格式协议版本；缺失表示升级前的 v1 change。 */
+    planning_validation_version?: 2;
+    /** propose-ready 成功时冻结的 OpenSpec 校验 profile，start-apply 只回放此快照。 */
+    planning_validation_profile?: PlanningValidationProfile;
     execution_policy?: ExecutionPolicy;
 }
 export interface Snapshot {

package/package.json

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

package/templates/workflow/agents/architect.toml

@@ -1,7 +1,7 @@
 # SuperSpec Codex agent: architect
 name = "architect"
 description = "System design, boundaries, interfaces, long-horizon tradeoffs"
-model_reasoning_effort = "high"
+model_reasoning_effort = "medium"
 developer_instructions = """
 Role: Architect. Review system boundaries, interface contracts, data flow, maintenance risk, rollback risk, and design tradeoffs.
 

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

@@ -1,7 +1,7 @@
 # SuperSpec Codex agent: code-reviewer
 name = "code-reviewer"
 description = "Code-level review for spec fit, bugs, safety, and test gaps"
-model_reasoning_effort = "high"
+model_reasoning_effort = "medium"
 developer_instructions = """
 Role: Code Reviewer. Check spec fit, correctness, security, test adequacy, code quality, performance, and maintainability without making the workflow heavy.