@peterxiaoyang/superspec 0.1.45 → 0.1.47

package/dist/format.js

@@ -1,9 +1,10 @@
 // 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 { sha256Text } from "./store.js";
 import { GREEN_ONLY_NO_TDD_REASON } from "./types.js";
 // ===== discovery.md =====
 //
@@ -24,7 +25,7 @@ function countOpenChecklistItemsInSection(content, headings) {
     const matches = sectionBody.match(/^\s*-\s+\[ \]/gm);
     return matches ? matches.length : 0;
 }
-function sectionBodyByHeadings(content, headings) {
+function sectionRangeByHeadings(content, headings) {
     const headingPattern = headings.map(escapeRegex).join("|");
     const sectionMatch = new RegExp(`^#{1,6}\\s*(?:${headingPattern})\\s*$`, "im").exec(content);
     if (!sectionMatch)
@@ -33,11 +34,90 @@ function sectionBodyByHeadings(content, headings) {
     // 截取到下一个标题或文件末尾
     const restContent = content.slice(sectionStart);
     const nextHeadingMatch = restContent.match(/^#{1,6}\s+/m);
-    return nextHeadingMatch ? restContent.slice(0, nextHeadingMatch.index) : restContent;
+    return {
+        start: sectionStart,
+        end: nextHeadingMatch ? sectionStart + nextHeadingMatch.index : content.length,
+    };
+}
+function sectionBodyByHeadings(content, headings) {
+    const range = sectionRangeByHeadings(content, headings);
+    return range ? content.slice(range.start, range.end) : null;
 }
-/** 从 discovery.md 提取"待确认问题"段内的未确认项数量 */
+const DISCOVERY_QUESTION_HEADINGS = ["待确认问题", "Open Questions", "Pending Questions"];
+export const EXPLORE_OPEN_QUESTION_SCOPE_PREFIX = "explore_open_question:";
+/**
+ * 当前文档中同一确认事项的稳定键。结合 Q-ID、顺序和原文，避免把本轮开始前
+ * 已经确认的旧事项误认为新答复。
+ */
+export function discoveryQuestionKey(question) {
+    return sha256Text(`${question.id}\n${question.ordinal}\n${question.text}`);
+}
+/**
+ * 计算某一确认事项之外的 Discovery 决策上下文。回写时该事项本身会从问题改为
+ * 结论，因此只归一化这一行；其余事实、证据和其它待确认项的改动都会使指纹失效。
+ */
+export function discoveryQuestionContextFingerprint(content, question) {
+    const range = sectionRangeByHeadings(content, DISCOVERY_QUESTION_HEADINGS);
+    if (!range)
+        return null;
+    const sectionBody = content.slice(range.start, range.end);
+    const checklist = /^\s*-\s+\[([ xX])\]\s+(.*?)\s*$/gm;
+    let ordinal = 0;
+    for (const match of sectionBody.matchAll(checklist)) {
+        ordinal += 1;
+        if (ordinal !== question.ordinal)
+            continue;
+        const lineStart = range.start + match.index;
+        const lineEnd = lineStart + match[0].length;
+        const placeholder = `- [ ] <discovery-question:${question.id}:${question.ordinal}>`;
+        return sha256Text(`${content.slice(0, lineStart)}${placeholder}${content.slice(lineEnd)}`);
+    }
+    return null;
+}
+/** 按文档顺序提取 discovery.md 的全部确认事项。 */
+export function parseDiscoveryQuestions(content) {
+    const sectionBody = sectionBodyByHeadings(content, DISCOVERY_QUESTION_HEADINGS);
+    if (sectionBody == null)
+        return [];
+    const documentFingerprint = sha256Text(content);
+    const questions = [];
+    const checklist = /^\s*-\s+\[([ xX])\]\s+(.*?)\s*$/gm;
+    let ordinal = 0;
+    for (const match of sectionBody.matchAll(checklist)) {
+        ordinal += 1;
+        const text = match[2];
+        const idMatch = /^\s*(Q-[A-Za-z0-9][A-Za-z0-9_-]*)\b/.exec(text);
+        questions.push({
+            id: idMatch?.[1] ?? `item-${ordinal}`,
+            ordinal,
+            text,
+            raw: match[0],
+            documentFingerprint,
+            status: match[1] === " " ? "open" : "closed",
+        });
+    }
+    return questions;
+}
+/** 按文档顺序提取 discovery.md 中尚未确认的问题。 */
+export function parseDiscoveryOpenQuestions(content) {
+    return parseDiscoveryQuestions(content)
+        .filter(question => question.status === "open")
+        .map(({ status: _status, ...question }) => question);
+}
+export function discoveryOpenQuestionScope(question, exploreRoundId) {
+    const fingerprint = sha256Text(`${exploreRoundId}\n${question.documentFingerprint}`);
+    return `${EXPLORE_OPEN_QUESTION_SCOPE_PREFIX}${fingerprint}:${question.id}`;
+}
+/** 面向用户展示时隐藏 Q-xxx 这一内部编号；历史无编号问题保持原文。 */
+export function discoveryOpenQuestionDisplayText(question) {
+    if (question.id.startsWith("Q-") && question.text.startsWith(question.id)) {
+        return question.text.slice(question.id.length).replace(/^[\s:：—–-]+/, "").trim();
+    }
+    return question.text.trim();
+}
+/** 从 discovery.md 提取“待确认问题”段内的未确认项数量。 */
 export function countDiscoveryOpenQuestions(content) {
-    return countOpenChecklistItemsInSection(content, ["待确认问题", "Open Questions", "Pending Questions"]);
+    return parseDiscoveryOpenQuestions(content).length;
 }
 const DISCOVERY_CHAIN_HEADINGS = ["链路五要素"];
 const DISCOVERY_CHAIN_REQUIRED_COLUMNS = [
@@ -52,6 +132,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,13 +176,19 @@ 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 };
         }
     }
     return { ok: true, message: "链路五要素就绪", present: true };
 }
-/** 完整校验 discovery.md：存在 + 非空 + 无未确认问题 */
+/**
+ * 校验 discovery.md 的可解析结构。未确认问题不是格式错误：next 会把第一个问题
+ * 作为当前用户决策返回；只有缺文档、空文档或已声明链路的结构错误才在此阻断。
+ */
 export function validateDiscovery(changeRoot) {
     const path = join(changeRoot, ".superspec", "artifacts", "discovery.md");
     if (!existsSync(path))
@@ -113,9 +200,11 @@ export function validateDiscovery(changeRoot) {
     if (!chainCoverage.ok)
         return { ok: false, message: chainCoverage.message, openCount: -1 };
     const openCount = countDiscoveryOpenQuestions(content);
-    if (openCount > 0)
-        return { ok: false, message: `discovery.md 有 ${openCount} 个未确认问题`, openCount };
-    return { ok: true, message: "discovery.md 就绪", openCount: 0 };
+    return {
+        ok: true,
+        message: openCount > 0 ? `discovery.md 结构有效，有 ${openCount} 个待确认问题` : "discovery.md 就绪",
+        openCount,
+    };
 }
 const PROPOSE_CONFIRMATION_DOCS = [
     "proposal.md",
@@ -183,6 +272,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);
 }
@@ -301,8 +412,17 @@ export function adoptedContractForTask(content, taskId, contractMode) {
     const parsed = executionRequirementForTask(content, taskId);
     return { parsed, contract: contractMode ? parsed?.contract ?? null : null };
 }
+/**
+ * Fix task 由状态机从已批准的实现范围派生；它没有 proposal 阶段执行依据块。
+ * REVIEW-FIX-* 是发布前已有的持久化 task ID，FIX-SELFTEST-* 是当前引擎生成的
+ * 自测修复 task。不能把通用 FIX-* 前缀保留为内部命名空间。
+ */
+export function isFixTaskId(taskId) {
+    return taskId.startsWith("REVIEW-FIX-") || taskId.startsWith("FIX-SELFTEST-");
+}
+/** @deprecated 新代码使用 isFixTaskId；保留给旧扩展和历史调用。 */
 export function isReviewFixTaskId(taskId) {
-    return taskId.startsWith("REVIEW-FIX-");
+    return isFixTaskId(taskId);
 }
 export function isCharacterizationTask(task) {
     return task.tddRequired === false && task.noTddReason === "characterization";
@@ -329,15 +449,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 +475,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 在旧版本中用标记强制进入契约模式。保留该入口，
@@ -355,7 +604,7 @@ export function validateExecutionRequirements(content, testContractContent, exec
     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 hasV2OrdinaryTask = executionRequirementVersion === 2 && tasks.some(task => !isFixTaskId(task.taskId));
     const mode = hasTaskBoundExecutionRequirements(content) || hasLegacyGreenOnlyTask || hasV2OrdinaryTask;
     const contracts = parseExecutionRequirements(content);
     // 孤儿检测必须在 mode=false 的 early return 之前：全部块都悬空时 mode=false，
@@ -377,11 +626,11 @@ export function validateExecutionRequirements(content, testContractContent, exec
         }
         // v2 是本次改造后的新计划：每个普通 task 必须声明完整五字段，
         // `测试:` 可显式为空以表达非行为任务。旧计划只保持原 TDD 契约要求。
-        if (executionRequirementVersion === 2 && !isReviewFixTaskId(task.taskId) && !contract) {
+        if (executionRequirementVersion === 2 && !isFixTaskId(task.taskId) && !contract) {
             errors.push(`${task.taskId} 缺少执行依据`);
             continue;
         }
-        if (executionRequirementVersion === 1 && task.tddRequired && !isReviewFixTaskId(task.taskId) && !contract) {
+        if (executionRequirementVersion === 1 && task.tddRequired && !isFixTaskId(task.taskId) && !contract) {
             errors.push(`${task.taskId} 缺少执行依据`);
             continue;
         }
@@ -396,6 +645,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 +734,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

@@ -1,8 +1,26 @@
 // SuperSpec 流程引擎 — OpenSpec 探测
-import { execSync, execFileSync } from "node:child_process";
+import { execFileSync } from "node:child_process";
 import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { createHash } from "node:crypto";
+function isTestMode() {
+    return process.env.SUPERSPEC_TEST_MODE === "1" || process.env.NODE_ENV === "test";
+}
+function runtimePlatform() {
+    return isTestMode() ? process.env.SUPERSPEC_TEST_PLATFORM ?? process.platform : process.platform;
+}
+function windowsCommandHost() {
+    return process.env.ComSpec ?? "cmd.exe";
+}
+/**
+ * 在 Windows 上，npm 安装的 CLI 是 .cmd 启动器，不能被 execFileSync 直接执行。
+ * 保留数组参数传递；只有启动器这一层通过 cmd.exe 运行。
+ */
+function execOpenSpec(args, options) {
+    if (runtimePlatform() !== "win32")
+        return execFileSync("openspec", args, options);
+    return execFileSync(windowsCommandHost(), ["/d", "/s", "/c", "openspec.cmd", ...args], options);
+}
 /** B2 修复：校验 change 字符集，防 shell 注入 */
 function validateChange(change) {
     if (!/^[A-Za-z0-9._-]+$/.test(change)) {
@@ -11,7 +29,10 @@ function validateChange(change) {
 }
 export function probeOpenSpec(projectRoot, change) {
     try {
-        const version = execSync("openspec --version 2>/dev/null", { encoding: "utf8" }).trim();
+        const version = execOpenSpec(["--version"], {
+            encoding: "utf8",
+            stdio: ["pipe", "pipe", "ignore"],
+        }).trim();
         let changeExists = false;
         if (change) {
             validateChange(change);
@@ -26,8 +47,8 @@ export function probeOpenSpec(projectRoot, change) {
 export function openspecStatus(projectRoot, change) {
     validateChange(change);
     try {
-        // B2 修复：用 execFileSync 数组传参，彻底避免 shell 解析
-        const result = execFileSync("openspec", ["status", "--change", change, "--json"], {
+        // B2 修复：参数始终走数组；Windows 仅通过 cmd.exe 运行 .cmd 启动器。
+        const result = execOpenSpec(["status", "--change", change, "--json"], {
             encoding: "utf8", cwd: projectRoot, stdio: ["pipe", "pipe", "ignore"],
         });
         return "sha256:" + createHash("sha256").update(result).digest("hex");
@@ -36,6 +57,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 {
+        execOpenSpec(["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_confirmation.js

@@ -1,10 +1,75 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
 import { currentGitHead, dirtyCodeFiles } from "./git_state.js";
 import { historicalProposeReadyRoles, reviewEvidenceDigest, reviewGateRoleResolution } from "./review.js";
 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 { parseExecutionRequirements, parseTasksMd, parseTestContractEntries } from "./format.js";
 import { hasFrozenWorkflowModeForProposeRound, workflowRiskForProject, workflowRiskForState, } from "./workflow_config.js";
 export const PHASE_CONFIRMATION_SCOPE_PREFIX = "phase_confirmation:";
+function taskTitle(content, task) {
+    const line = content.split("\n")[task.lineIdx] ?? "";
+    return line.replace(/^-\s+\[[ xX]\]\s+\S+\s*/, "").trim() || task.taskId;
+}
+function taskSummaryField(lines, task, labels) {
+    for (let index = task.lineIdx + 1; index < lines.length; index++) {
+        const line = lines[index];
+        if (/^-\s+\[[ xX]\]\s+\S+/.test(line) || /^#{1,6}\s+/.test(line))
+            break;
+        const match = /^\s*-\s*([^:：]+)\s*[:：]\s*(.+?)\s*$/.exec(line);
+        if (match && labels.includes(match[1].trim()))
+            return match[2].trim();
+    }
+    return null;
+}
+/**
+ * 这是阶段确认的临时阅读面，不是新的计划格式或 gate。优先读取 task 已声明的
+ * 交付/依赖/验收；缺省项如实标为未声明，避免将任务顺序臆造成真实依赖。
+ */
+function proposeTaskDeliverySummary(changeRoot) {
+    const tasksPath = join(changeRoot, "tasks.md");
+    if (!existsSync(tasksPath))
+        return null;
+    const tasksContent = readFileSync(tasksPath, "utf8");
+    const tasks = parseTasksMd(tasksContent);
+    if (tasks.length === 0)
+        return null;
+    const contracts = new Map(parseExecutionRequirements(tasksContent).map(item => [item.taskId, item.contract]));
+    const testContractPath = join(changeRoot, ".superspec", "artifacts", "test-contract.md");
+    const parsedTests = existsSync(testContractPath)
+        ? parseTestContractEntries(readFileSync(testContractPath, "utf8"))
+        : null;
+    const scenarios = parsedTests?.ok
+        ? new Map(parsedTests.entries.map(entry => [entry.test_id, entry.scenario]))
+        : new Map();
+    const lines = tasksContent.split("\n");
+    // Propose 展示的是当前计划，不是旧 Apply 轮的执行历史。重新打开同一 task 时，
+    // 当前 tasks.md 中的未勾选状态明确表示它已重新纳入本轮待实施范围。
+    const pendingTasks = tasks.filter(task => !task.done);
+    const completedCount = tasks.length - pendingTasks.length;
+    const items = pendingTasks.map((task, index) => {
+        const contract = contracts.get(task.taskId);
+        const explicitDelivery = taskSummaryField(lines, task, ["交付", "Delivery"]);
+        const explicitDependency = taskSummaryField(lines, task, ["依赖", "Dependencies", "Depends On"]);
+        const firstTest = contract?.tests[0];
+        const testScenario = firstTest ? scenarios.get(firstTest) : null;
+        const delivery = explicitDelivery ?? contract?.acceptance ?? taskTitle(tasksContent, task);
+        const dependency = explicitDependency ?? "无明确前置交付";
+        const acceptance = contract?.acceptance
+            ?? (testScenario ? `${firstTest}：${testScenario}` : "计划未单独声明验收");
+        return [
+            `${index + 1}. ${task.taskId} ${taskTitle(tasksContent, task)}`,
+            `   - 交付：${delivery}`,
+            `   - 依赖：${dependency}`,
+            `   - 验收：${acceptance}`,
+        ].join("\n");
+    });
+    const status = completedCount === 0
+        ? ""
+        : `已完成 ${completedCount} 项；${pendingTasks.length === 0 ? "当前没有待实施任务。" : `以下 ${pendingTasks.length} 项仍待实施或调整。`}\n\n`;
+    return `执行计划概览\n\n${status}${items.join("\n\n")}`;
+}
 function latestTransition(events, predicate) {
     return findLatestEvent(events, "transition_commit", event => predicate(event.payload));
 }
@@ -187,7 +252,11 @@ export function phaseConfirmationForBoundary(projectRoot, events, snapshot, boun
     const epochEventId = epoch?.event_id ?? `legacy-${spec.state}`;
     const digest = materialDigest(projectRoot, events, snapshot, boundary, risk);
     const scope = `${spec.scopePrefix}:${epochEventId}:${digest}`;
-    const actions = buildActions(snapshot.change_id, boundary, scope, spec.question, spec.actions, risk);
+    const summary = boundary === "propose_to_apply"
+        ? proposeTaskDeliverySummary(openspecChangeRoot(projectRoot, snapshot.change_id))
+        : null;
+    const question = summary ? `${summary}\n\n${spec.question}` : spec.question;
+    const actions = buildActions(snapshot.change_id, boundary, scope, question, spec.actions, risk);
     return {
         boundary,
         epoch_event_id: epochEventId,
@@ -195,7 +264,7 @@ export function phaseConfirmationForBoundary(projectRoot, events, snapshot, boun
         scope,
         actions,
         ask: {
-            question: spec.question,
+            question,
             allowed_answers: actions.map(action => action.label),
             scope,
             actions,

package/dist/phase_plan.d.ts

@@ -1,5 +1,6 @@
 import type { ReviewGateRule } from "./review_job_gates.ts";
-import type { AcceptedMaterialFollowupContinuation, AskUser, Event, ExecutionPolicy, Job, JobRole, State } from "./types.ts";
+import { exploreAnswerRegistrationPayload } from "./explore_round.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";
@@ -87,6 +88,8 @@ export declare function executionPolicyForRisk(risk: ReviewRisk): ExecutionPolic
 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>;
+/** 新 Explore 轮次冻结已有已确认事项，避免把历史答复当作本轮遗漏。 */
+export declare function exploreAnswerRegistrationPayloadForChange(changeRoot: string): ReturnType<typeof exploreAnswerRegistrationPayload>;
 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;
@@ -95,6 +98,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;