@peterxiaoyang/superspec 0.1.56 → 0.1.58

package/README.md

@@ -4,15 +4,26 @@
 [![Node.js](https://img.shields.io/badge/node-%3E%3D20.19.0-brightgreen?style=flat-square)](https://nodejs.org)
 [![OpenSpec](https://img.shields.io/badge/OpenSpec-compatible-6f42c1?style=flat-square)](https://github.com/Fission-AI/OpenSpec)
 
-SuperSpec 是一套面向 AI 编程代理的需求变更工作流。它在 OpenSpec 材料之上增加阶段控制、审查和验证记录，帮助 AI 从需求理解推进到可回放的交付结果。
+AI 写代码很快。真正慢的是之后：范围悄悄变大、完成全凭一张嘴、review 时问一句「这里为什么要改」它才承认不该改。
+
+SuperSpec 是一套跑在 AI 编程代理（Codex 等）下的需求变更工作流引擎。它把「不要乱改、别过度设计、做完要有证据」从 prompt 劝说升级成**机器门禁**——约束写在 CLI 和数据契约里，不靠模型自觉。
 
 ```text
 Explore → Propose → Apply → Review → Accepted
 ```
 
-SuperSpec 适合跨模块、涉及接口或需要方案审查的变更。简单的单文件修改不必强行使用完整工作流。普通请求也不会自动进入 SuperSpec，只有明确调用对应入口或继续已有 change 时才会启动。
+## 它拦得住什么
+
+| 你遇到的问题 | SuperSpec 的机制 |
+| --- | --- |
+| 「顺手」改了不该改的，加了不该加的方法 | 每个任务绑定五字段执行依据：测试 / 设计 / 来源 / 验收 / 边界，引用可解析性由状态机校验；实现越界必须走结构化的范围说明，而不是一句道歉 |
+| 说自己做完了，测过没有无从考证 | 任务启动即冻结证据要求：该 RED 的先失败、该 GREEN 的真通过，测试证据绑定任务尝试；全程事件日志带摘要，可回放、防篡改 |
+| 审查抓到了问题，修复时又把新架构夹带回来 | 阻塞问题必须标注类型（漏做 / 破坏已有 / 计划外新增）并**锚定到已批准材料**才能受理；修复任务的指令只兑现锚点，审查建议里的架构永远不是授权 |
+| 审查形同虚设，「看起来没问题」就通过 | critic / architect / test-engineer / code-reviewer / verifier 独立角色持密封工作项审查，pass 必须说明覆盖了什么，fail 必须给出可追溯的证据 |
+
+这些约束全部由引擎在提交口强制执行：答不出锚点的阻塞问题直接拒收，而不是等你在对话里追问。
 
-## 安装
+## 快速开始
 
 要求 Node.js `>=20.19.0`。
 
@@ -22,18 +33,17 @@ cd <your-project>
 superspec install
 ```
 
-`superspec install` 会把工作流入口、角色配置和运行时目录同步到当前项目，并准备 OpenSpec 依赖。`superspec init --scope project` 是兼容别名。
+`superspec install` 会把工作流入口、角色配置和运行时目录同步到当前项目，并准备 [OpenSpec](https://github.com/Fission-AI/OpenSpec) 依赖。
 
-检查安装：
+然后在 Codex 里对它说话：
 
-```bash
-superspec version
-superspec status
+```text
+superspec-explore change <change-name>。<你的需求>
 ```
 
-## 工作流入口
+工作流接管之后，每一步该做什么由 `superspec transition next` 决定——AI 不自由发挥流程，只在被授权的范围内干活。
 
-在 Codex 中显式调用对应 Skill。新需求通常从 `superspec-explore` 开始；已有 change 则从当前阶段继续。
+## 工作流入口
 
 | Skill | 作用 |
 | --- | --- |
@@ -42,35 +52,21 @@ superspec status
 | `superspec-apply` | 按已批准任务修改代码并验证 |
 | `superspec-review` | 审查实现并完成最终验证 |
 
-工作流会根据问题性质留在当前阶段修复，或回到计划阶段重新确认需求、验收和技术取舍。
-
-## 配置
+修不动会自己拐弯：能由既有任务解释的问题留在 Apply 内闭环；需要改需求、验收或技术取舍的，回到计划阶段重新确认。
 
-项目级配置位于 `.superspec/config.json`。未创建配置或未声明模式时，默认使用 `normal`：
-
-```json
-{
-  "workflow": {
-    "mode": "normal",
-    "hosts": ["codex"]
-  }
-}
-```
+## 轻量，且知道自己的边界
 
-可选模式为 `minimal`、`normal` 和 `strict`。模式主要影响计划阶段的审查强度；最终代码审查和验证仍由 Review 阶段负责。
+- **三档强度**：`minimal` / `normal` / `strict`（`.superspec/config.json`），按变更风险选择计划阶段的审查强度。
+- **不绑架日常**：简单的单文件修改不必走完整工作流；普通请求也不会自动进入 SuperSpec，只有显式调用入口才启动。
+- **诚实的能力边界**：它是流程与审计辅助，不是安全隔离或发布审批系统；不能替代代码审计、权限控制、合规检查和人工判断。
 
 ## 与 OpenSpec 的关系
 
-OpenSpec 负责变更材料和规格结构；SuperSpec 负责组织 AI 的探索、计划、实现、审查与证据记录。两者互补：
-
-```text
-OpenSpec：这次要改变什么
-SuperSpec：如何在边界内把它交付
-```
+OpenSpec 负责「这次要改变什么」，提供变更材料与规格结构；SuperSpec 负责「如何在边界内把它交付」，组织 AI 的探索、计划、实现、审查与证据记录。
 
-## 设计边界
+## 评测
 
-SuperSpec 是流程和审计辅助工具，不是安全隔离或发布审批系统。它不能替代代码审计、权限控制、合规检查和人工判断。
+仓库自带密封评测考场（隔离工作区 + 真实 Agent 运行 + 硬门禁 + 双模型语义复盘），用于验证工作流行为本身，而不只是 Prompt 文案。见 [`evals/README.md`](evals/README.md)。
 
 ## 致谢
 

package/dist/approved_ref.d.ts

@@ -1,6 +1,6 @@
 import type { CodeReviewClaimKind } from "./types.ts";
 export declare const CODE_REVIEW_CLAIM_KINDS: readonly ["missing_approved", "breaks_existing", "unjustified_addition"];
-export type ApprovedRefKind = "test" | "requirement" | "task" | "design" | "proposal";
+export type ApprovedRefKind = "test" | "requirement" | "task" | "design" | "proposal" | "structure";
 export interface ResolvedApprovedRef {
     raw: string;
     kind: ApprovedRefKind;

package/dist/approved_ref.js

@@ -1,25 +1,19 @@
 // SuperSpec 代码审查 approved_refs：只做存在性解析，不做语义匹配。
 import { readFileSync, statSync } from "node:fs";
 import { isAbsolute, join, relative, resolve, sep } from "node:path";
-import { parseTasksMd, parseTestContractEntries } from "./format.js";
+import { headingExists, parseTasksMd, parseTestContractEntries, parseStructureChangeLedger } from "./format.js";
 export const CODE_REVIEW_CLAIM_KINDS = [
     "missing_approved",
     "breaks_existing",
     "unjustified_addition",
 ];
 const TEST_ID_RE = /^TEST-[A-Za-z0-9_-]+$/;
+const STRUCTURE_LEDGER_ID_RE = /^SC-[A-Za-z0-9_-]+$/;
 const TEST_CONTRACT_REL = join(".superspec", "artifacts", "test-contract.md");
-function escapeRegex(value) {
-    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-}
 function isPathInside(root, target) {
     const rel = relative(root, target);
     return rel !== "" && !rel.startsWith(`..${sep}`) && rel !== ".." && !isAbsolute(rel);
 }
-function headingExists(content, title) {
-    const heading = new RegExp(`^#{1,6}[\\t ]+${escapeRegex(title)}(?:[\\t ]+#+)?[\\t ]*$`, "m");
-    return heading.test(content);
-}
 function shortTestId(raw) {
     const trimmed = raw.trim();
     if (TEST_ID_RE.test(trimmed))
@@ -106,6 +100,13 @@ export function resolveApprovedRef(changeRoot, raw) {
         return { ok: true, value: { raw: ref, kind: "task", short: anchor } };
     }
     if (path === "design.md") {
+        if (STRUCTURE_LEDGER_ID_RE.test(anchor)) {
+            const ledger = parseStructureChangeLedger(content);
+            if (ledger.present && ledger.entries.some(entry => entry.id === anchor)) {
+                return { ok: true, value: { raw: ref, kind: "structure", short: anchor } };
+            }
+            return { ok: false, reason: `design.md 结构变更清单中不存在 ${anchor}` };
+        }
         if (!headingExists(content, anchor))
             return { ok: false, reason: `design.md 中不存在标题「${anchor}」` };
         return { ok: true, value: { raw: ref, kind: "design", short: anchor } };

package/dist/cli.js

@@ -557,6 +557,8 @@ function topLevelHelp() {
   update [--hosts codex,omp]        升级 CLI 到 npm latest 并同步已选宿主入口
   version                           版本号
 
+工作流配置见 .superspec/config.json（workflow.mode、workflow.budget）。
+
 transition 子命令：
   init / explore / sync / next / propose-ready / start-apply
   task-start --task <T> / task-complete --task <T> [--input -]
@@ -589,10 +591,12 @@ function commandHelp(command, subcommand) {
         return `用法：superspec record job-submit --change <C> --job <J> --report <F|->
 
 提交 reviewer JSON 报告；--report - 表示从 stdin 读取。报告契约以 jobs packet 返回的 report_schema 为准。
+需要落盘时写到 packet 的 report_file_path（.superspec/changes/<C>/jobs/<J>.report.json），不要放进 openspec/changes 计划材料目录。
 
 示例：
   superspec jobs packet --change <C> --job <J>
-  superspec record job-submit --change <C> --job <J> --report report.json
+  superspec record job-submit --change <C> --job <J> --report -
+  superspec record job-submit --change <C> --job <J> --report .superspec/changes/<C>/jobs/<J>.report.json
 `;
     }
     if (command === "record" && subcommand === "test-run") {

package/dist/code_review.d.ts

@@ -76,6 +76,12 @@ export declare function missingCoverageExemptionTestIds(changeRoot: string, even
 /** Read-only execution evidence projected for code review and final verification. */
 export declare function taskExecutionIndexForReview(projectRoot: string, events: Event[]): TaskExecutionIndexEntry[];
 export declare function codeReviewDecisionScope(jobId: string, findingId: string): string;
+/** 自当前 Apply round 的 start-apply 起，带 review_fix_of 的 reopen 次数。 */
+export declare function countReviewFixReopensSinceStartApply(events: readonly Event[]): number;
+/** 上限是否生效按 Apply round 在 start-apply 冻结的档位判断（minimal 忽略），未冻结时回落项目配置。 */
+export declare function isReviewFixCapReached(projectRoot: string, events: readonly Event[]): boolean;
+/** spec / mixed 问题始终交使用者决策；implementation 问题只在自动修复触顶后交使用者决策。 */
+export declare function codeReviewFindingNeedsUserDecision(type: string | undefined, reviewFixCapReached: boolean): boolean;
 export interface CodeReviewDecisionScopeRef {
     jobId: string;
     findingId: string;

package/dist/code_review.js

@@ -4,7 +4,9 @@ import { join } from "node:path";
 import { findLatestEvent, sha256File, sha256Text } from "./store.js";
 import { REVIEW_CODE_REVIEW_GATE } from "./review_job_gates.js";
 import { codeFileContentSha, currentGitHead, diffFingerprints, dirtyCodeFiles, dirtyCodePaths, gitLines, isCodeLikePath, projectHasReadableDirectory, walkCodeFiles, } from "./git_state.js";
-import { parseExecutionRequirements, parseTestContractEntries } from "./format.js";
+import { parseExecutionRequirements, parseTestContractEntries, parseStructureChangeLedger } from "./format.js";
+import { planningValidationProfileForCurrentRound } from "./propose_round.js";
+import { workflowBudgetForRisk, workflowRiskForApplyRound, workflowRiskForProject } from "./workflow_config.js";
 export const CODE_REVIEW_REPAIR_SCOPE_PREFIX = "code_reviewer_report_repair:";
 export const CODE_REVIEW_DECISION_SCOPE_PREFIX = "code_review_decision:";
 export const TEST_COVERAGE_EXEMPTION_SCOPE_PREFIX = "test_coverage_exemption:";
@@ -395,6 +397,16 @@ export function addedCodePathsForScope(projectRoot, scope) {
     }
     return [...added].sort();
 }
+function structureLedgerForCodeReview(changeRoot, events) {
+    // 只有 v2 planning round 才有清单契约；v1 change 不写该字段，保持旧 packet 形态。
+    if (planningValidationProfileForCurrentRound(events)?.design?.schema_version !== 2)
+        return undefined;
+    const designPath = join(changeRoot, "design.md");
+    if (!existsSync(designPath))
+        return undefined;
+    const ledger = parseStructureChangeLedger(readFileSync(designPath, "utf8"));
+    return ledger.present ? ledger : undefined;
+}
 export function codeReviewPacketContext(changeRoot, projectRoot, scope, events) {
     const taskExecutionIndex = taskExecutionIndexFromEvents(projectRoot, events);
     // changed_paths 未知（快照缺失）或不完整（committed 段 diff 失败）的 task
@@ -408,6 +420,7 @@ export function codeReviewPacketContext(changeRoot, projectRoot, scope, events)
         for (const path of item.changed_paths ?? [])
             attributedPaths.add(path);
     }
+    const structureLedger = structureLedgerForCodeReview(changeRoot, events);
     return {
         code_review_scope: scope,
         coverage_exemption_refs: coverageExemptionRefs(changeRoot, events),
@@ -415,6 +428,7 @@ export function codeReviewPacketContext(changeRoot, projectRoot, scope, events)
         unattributed_paths: scope.review_paths.filter(path => !attributedPaths.has(path)).sort(),
         unknown_attribution_tasks: unknownAttributionTasks,
         added_code_paths: addedCodePathsForScope(projectRoot, scope),
+        ...(structureLedger ? { structure_ledger: structureLedger } : {}),
     };
 }
 export function effectiveCoverageExemptionRefsFromEvents(events) {
@@ -607,6 +621,47 @@ function codeReviewResultKind(value) {
 export function codeReviewDecisionScope(jobId, findingId) {
     return `${CODE_REVIEW_DECISION_SCOPE_PREFIX}${jobId}#${findingId}`;
 }
+// ===== review-fix 自动修复上限 =====
+//
+// next / reopen --review-fix / record user-decision 三处必须得出同一个结论，
+// 否则会出现 next 要求使用者决策而 CLI 直调仍自动放行的分叉。这里是唯一判定入口。
+/** 自当前 Apply round 的 start-apply 起，带 review_fix_of 的 reopen 次数。 */
+export function countReviewFixReopensSinceStartApply(events) {
+    let startIndex = -1;
+    for (let i = events.length - 1; i >= 0; i--) {
+        const ev = events[i];
+        if (ev.event_type !== "transition_commit")
+            continue;
+        const payload = ev.payload;
+        if (payload.transition === "start-apply" && payload.to_state === "apply") {
+            startIndex = i;
+            break;
+        }
+    }
+    if (startIndex < 0)
+        return 0;
+    let count = 0;
+    for (const ev of events.slice(startIndex + 1)) {
+        if (ev.event_type !== "transition_commit")
+            continue;
+        const payload = ev.payload;
+        if (typeof payload.review_fix_of === "string" && payload.review_fix_of.trim() !== "")
+            count++;
+    }
+    return count;
+}
+/** 上限是否生效按 Apply round 在 start-apply 冻结的档位判断（minimal 忽略），未冻结时回落项目配置。 */
+export function isReviewFixCapReached(projectRoot, events) {
+    const risk = workflowRiskForApplyRound(events, workflowRiskForProject(projectRoot));
+    const budget = workflowBudgetForRisk(projectRoot, risk);
+    if (!budget || budget.review_fix_rounds === null)
+        return false;
+    return countReviewFixReopensSinceStartApply(events) >= budget.review_fix_rounds;
+}
+/** spec / mixed 问题始终交使用者决策；implementation 问题只在自动修复触顶后交使用者决策。 */
+export function codeReviewFindingNeedsUserDecision(type, reviewFixCapReached) {
+    return type === "spec" || type === "mixed" || (type === "implementation" && reviewFixCapReached);
+}
 /** 只接受状态机生成的 <job>#<finding> 决策范围。 */
 export function parseCodeReviewDecisionScope(scope) {
     if (!scope.startsWith(CODE_REVIEW_DECISION_SCOPE_PREFIX))

package/dist/format.d.ts

@@ -1,4 +1,4 @@
-import { type ExecutionContract, type ExecutionPolicy } from "./types.ts";
+import { type ExecutionContract, type ExecutionPolicy, type StructureChangeLedger } from "./types.ts";
 export declare const EXPLORE_OPEN_QUESTION_SCOPE_PREFIX = "explore_open_question:";
 /**
  * Discovery 的未确认项是用户决策的唯一候选来源。这里保留原有的“仅指定段落内
@@ -93,6 +93,30 @@ export declare function collectProposeOpenQuestions(changeRoot: string): {
     openCount: number;
     files: ProposeOpenQuestionFile[];
 };
+export declare const STRUCTURE_CHANGE_CATEGORIES: readonly ["新增持久化结构", "迁移或回填", "功能开关", "新增公共接口", "删除既有路径", "改既有公共签名", "改变既有数据语义", "新增公共类型"];
+export type StructureChangeCategory = (typeof STRUCTURE_CHANGE_CATEGORIES)[number];
+export declare const STRUCTURE_DECISION_REQUIRED_CATEGORIES: ReadonlySet<string>;
+export declare function isStructureChangeCategory(value: string): value is StructureChangeCategory;
+export declare function parseStructureChangeLedger(content: string): StructureChangeLedger;
+export interface StructureChangeLedgerValidation {
+    ok: boolean;
+    errors: string[];
+}
+/** Markdown 标题是否存在（任意层级，允许闭合 #）。供文档引用解析共用。 */
+export declare function headingExists(content: string, title: string): boolean;
+/**
+ * 结构变更清单"需求依据"的唯一解析入口。与 approved_refs 的解析分开：
+ * 这里接受 discovery 标题、拒绝 proposal.md#Impact，且按类别收紧允许集。
+ */
+export declare function resolveStructureBasisRef(changeRoot: string, raw: unknown, category: string): {
+    ok: true;
+    value: string;
+} | {
+    ok: false;
+    reason: string;
+};
+export declare function validateStructureChangeLedger(changeRoot: string, ledger: StructureChangeLedger): StructureChangeLedgerValidation;
+export declare function formatStructureChangeLedgerSummary(ledger: StructureChangeLedger): string | null;
 export interface ParsedTask {
     taskId: string;
     lineIdx: number;

package/dist/format.js

@@ -2,7 +2,7 @@
 //
 // 所有可机械判定的文档协议、格式定义和解析逻辑都在这里。skills 只指导
 // 生成与语义判断，不得自行充当格式校验器或在其它地方重复解析。
-import { readFileSync, existsSync, realpathSync } from "node:fs";
+import { readFileSync, existsSync, realpathSync, statSync } 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";
@@ -321,6 +321,240 @@ export function collectProposeOpenQuestions(changeRoot) {
         files,
     };
 }
+// ===== design.md 结构变更清单 =====
+//
+// 格式（状态机校验，propose skill 负责生成）：
+//   ## 结构变更清单
+//   无
+// 或
+//   | ID | 类别 | 变更 | 需求依据 | 决定 |
+//   |---|---|---|---|---|
+//   | SC-001 | 新增持久化结构 | ... | specs/x/spec.md#Requirement: ... | DEC-001 |
+//
+// 需决定类别的依据只接受 specs Requirement 或 TEST；仅展示类别可另接受
+// proposal（Impact 除外）与 discovery 的标题。所有依据都必须能在当前 change 中解析。
+export const STRUCTURE_CHANGE_CATEGORIES = [
+    "新增持久化结构",
+    "迁移或回填",
+    "功能开关",
+    "新增公共接口",
+    "删除既有路径",
+    "改既有公共签名",
+    "改变既有数据语义",
+    "新增公共类型",
+];
+export const STRUCTURE_DECISION_REQUIRED_CATEGORIES = new Set([
+    "新增持久化结构",
+    "迁移或回填",
+    "功能开关",
+    "新增公共接口",
+    "删除既有路径",
+    "改既有公共签名",
+    "改变既有数据语义",
+]);
+const STRUCTURE_LEDGER_HEADINGS = ["结构变更清单"];
+const STRUCTURE_LEDGER_COLUMNS = ["ID", "类别", "变更", "需求依据", "决定"];
+const STRUCTURE_LEDGER_ID_RE = /^SC-[A-Za-z0-9_-]+$/;
+const STRUCTURE_LEDGER_NONE_RE = /^\s*无\s*$/;
+const STRUCTURE_TEST_ID_RE = /^TEST-[A-Za-z0-9_-]+$/;
+const DEC_ID_RE = /^DEC-[A-Za-z0-9][A-Za-z0-9_-]*$/;
+const DISPLAY_ONLY_DECISION_MARKERS = new Set(["—", "-", "–"]);
+const STRUCTURE_LEDGER_MISSING_MESSAGE = 'design.md 缺少 ## 结构变更清单；没有结构变更时在该标题下写"无"';
+const STRUCTURE_LEDGER_FORMAT_MESSAGE = `## 结构变更清单 一节只能是"无"或一张含 ${STRUCTURE_LEDGER_COLUMNS.join("、")} 列的表格，其他说明写到别的标题下`;
+export function isStructureChangeCategory(value) {
+    return STRUCTURE_CHANGE_CATEGORIES.includes(value);
+}
+export function parseStructureChangeLedger(content) {
+    const sectionBody = sectionBodyByHeadings(content, STRUCTURE_LEDGER_HEADINGS);
+    if (sectionBody == null) {
+        return { present: false, none: false, entries: [] };
+    }
+    if (STRUCTURE_LEDGER_NONE_RE.test(sectionBody)) {
+        return { present: true, none: true, entries: [] };
+    }
+    const tableLines = sectionBody.split("\n").filter(line => line.trim().startsWith("|"));
+    if (tableLines.length < 2) {
+        return { present: true, none: false, entries: [], format_error: STRUCTURE_LEDGER_FORMAT_MESSAGE };
+    }
+    const header = splitMarkdownTableRow(tableLines[0]);
+    if (header.length === 0 || !isMarkdownTableSeparator(tableLines[1])) {
+        return { present: true, none: false, entries: [], format_error: STRUCTURE_LEDGER_FORMAT_MESSAGE };
+    }
+    const columnIndexes = Object.fromEntries(STRUCTURE_LEDGER_COLUMNS.map(col => [col, header.indexOf(col)]));
+    if (STRUCTURE_LEDGER_COLUMNS.some(col => columnIndexes[col] < 0)) {
+        return { present: true, none: false, entries: [], format_error: STRUCTURE_LEDGER_FORMAT_MESSAGE };
+    }
+    const entries = [];
+    for (const row of tableLines.slice(2).map(splitMarkdownTableRow).filter(cells => cells.length > 0)) {
+        entries.push({
+            id: (row[columnIndexes.ID] ?? "").trim(),
+            category: (row[columnIndexes["类别"]] ?? "").trim(),
+            change: (row[columnIndexes["变更"]] ?? "").trim(),
+            basis: (row[columnIndexes["需求依据"]] ?? "").trim(),
+            decision: (row[columnIndexes["决定"]] ?? "").trim(),
+        });
+    }
+    if (entries.length === 0) {
+        return { present: true, none: false, entries: [], format_error: STRUCTURE_LEDGER_FORMAT_MESSAGE };
+    }
+    return { present: true, none: false, entries };
+}
+function readChangeDocument(changeRoot, relPath) {
+    const root = resolve(changeRoot);
+    const target = resolve(root, relPath);
+    if (!isPathInside(root, target))
+        return null;
+    try {
+        if (!existsSync(target) || !statSync(target).isFile())
+            return null;
+        return readFileSync(target, "utf8");
+    }
+    catch {
+        return null;
+    }
+}
+/** Markdown 标题是否存在（任意层级，允许闭合 #）。供文档引用解析共用。 */
+export function headingExists(content, title) {
+    const heading = new RegExp(`^#{1,6}[\\t ]+${escapeRegex(title)}(?:[\\t ]+#+)?[\\t ]*$`, "m");
+    return heading.test(content);
+}
+function splitBasisRef(basis) {
+    const separator = basis.indexOf("#");
+    if (separator <= 0 || separator === basis.length - 1)
+        return null;
+    return {
+        path: basis.slice(0, separator).replace(/\\/g, "/"),
+        anchor: basis.slice(separator + 1).trim(),
+    };
+}
+/**
+ * 结构变更清单"需求依据"的唯一解析入口。与 approved_refs 的解析分开：
+ * 这里接受 discovery 标题、拒绝 proposal.md#Impact，且按类别收紧允许集。
+ */
+export function resolveStructureBasisRef(changeRoot, raw, category) {
+    if (typeof raw !== "string" || raw.trim() === "") {
+        return { ok: false, reason: "需求依据必须是非空字符串" };
+    }
+    const basis = raw.trim();
+    if (/[\u0000-\u001f\u007f]/.test(basis)) {
+        return { ok: false, reason: `需求依据不能包含换行等控制字符：${JSON.stringify(basis)}` };
+    }
+    const decisionRequired = STRUCTURE_DECISION_REQUIRED_CATEGORIES.has(category);
+    const allowedHint = decisionRequired
+        ? "需决定类别请引用 specs Requirement 或 TEST"
+        : "请引用 specs Requirement、TEST、proposal 标题（Impact 除外）或 discovery 标题";
+    if (STRUCTURE_TEST_ID_RE.test(basis)) {
+        const content = readChangeDocument(changeRoot, join(".superspec", "artifacts", "test-contract.md"));
+        if (content == null)
+            return { ok: false, reason: `无法读取 test-contract.md，无法校验 TEST 依据：${basis}` };
+        const parsed = parseTestContractEntries(content);
+        if (!parsed.ok || !parsed.entries.some(entry => entry.test_id === basis)) {
+            return { ok: false, reason: `test-contract.md 中不存在 ${basis}` };
+        }
+        return { ok: true, value: basis };
+    }
+    const ref = splitBasisRef(basis);
+    if (!ref)
+        return { ok: false, reason: `需求依据格式无法解析，应为 文件#标题 或 TEST-ID：${basis}；${allowedHint}` };
+    if (/^specs\/[^/]+\/spec\.md$/.test(ref.path)) {
+        const requirementTitle = ref.anchor.startsWith("Requirement:")
+            ? ref.anchor.slice("Requirement:".length).trim()
+            : "";
+        if (!requirementTitle)
+            return { ok: false, reason: `spec 依据必须以 Requirement: 开头：${basis}` };
+        const content = readChangeDocument(changeRoot, ref.path);
+        if (content == null)
+            return { ok: false, reason: `${ref.path} 在当前 change 中不存在` };
+        if (!headingExists(content, `Requirement: ${requirementTitle}`)) {
+            return { ok: false, reason: `${ref.path} 中不存在 Requirement「${requirementTitle}」` };
+        }
+        return { ok: true, value: basis };
+    }
+    if (ref.path === "proposal.md" && ref.anchor === "Impact") {
+        return { ok: false, reason: `proposal.md#Impact 不能作为结构依据；${allowedHint}` };
+    }
+    if (decisionRequired) {
+        return { ok: false, reason: `需求依据 ${basis} 不满足类别要求；${allowedHint}` };
+    }
+    if (ref.path === "proposal.md") {
+        const content = readChangeDocument(changeRoot, "proposal.md");
+        if (content == null)
+            return { ok: false, reason: "proposal.md 在当前 change 中不存在" };
+        if (!headingExists(content, ref.anchor))
+            return { ok: false, reason: `proposal.md 中不存在标题「${ref.anchor}」` };
+        return { ok: true, value: basis };
+    }
+    const discoveryRel = ".superspec/artifacts/discovery.md";
+    if (ref.path === "discovery.md" || ref.path === discoveryRel) {
+        const content = readChangeDocument(changeRoot, join(".superspec", "artifacts", "discovery.md"));
+        if (content == null)
+            return { ok: false, reason: "discovery.md 在当前 change 中不存在" };
+        if (!headingExists(content, ref.anchor))
+            return { ok: false, reason: `discovery.md 中不存在标题「${ref.anchor}」` };
+        return { ok: true, value: basis };
+    }
+    return { ok: false, reason: `需求依据 ${basis} 无法解析；${allowedHint}` };
+}
+function isDisplayOnlyDecisionMarker(decision) {
+    return decision.trim() === "" || DISPLAY_ONLY_DECISION_MARKERS.has(decision.trim());
+}
+export function validateStructureChangeLedger(changeRoot, ledger) {
+    if (!ledger.present)
+        return { ok: false, errors: [STRUCTURE_LEDGER_MISSING_MESSAGE] };
+    if (ledger.none)
+        return { ok: true, errors: [] };
+    if (ledger.format_error)
+        return { ok: false, errors: [ledger.format_error] };
+    const errors = [];
+    const seenIds = new Set();
+    const knownDecIds = new Set(collectProposeQuestions(changeRoot).map(question => question.id));
+    for (const entry of ledger.entries) {
+        if (!STRUCTURE_LEDGER_ID_RE.test(entry.id)) {
+            errors.push(`结构变更清单 ${entry.id || "<空>"} 的 ID 格式无效，应为 SC-xxx`);
+            continue;
+        }
+        if (seenIds.has(entry.id)) {
+            errors.push(`结构变更清单 ID 重复：${entry.id}`);
+            continue;
+        }
+        seenIds.add(entry.id);
+        if (!isStructureChangeCategory(entry.category)) {
+            errors.push(`结构变更清单 ${entry.id} 的类别无效：${entry.category || "<空>"}；可用类别：${STRUCTURE_CHANGE_CATEGORIES.join("、")}`);
+            continue;
+        }
+        if (!entry.change) {
+            errors.push(`结构变更清单 ${entry.id} 的变更不能为空`);
+        }
+        const basis = resolveStructureBasisRef(changeRoot, entry.basis, entry.category);
+        if (!basis.ok)
+            errors.push(`结构变更清单 ${entry.id} 的需求依据无效：${basis.reason}`);
+        const decisionValid = DEC_ID_RE.test(entry.decision) && knownDecIds.has(entry.decision);
+        if (STRUCTURE_DECISION_REQUIRED_CATEGORIES.has(entry.category)) {
+            if (!decisionValid) {
+                errors.push(`结构变更清单 ${entry.id} 属于 ${entry.category}，必须在 决定 列引用一个 ## 待用户确认 中的 DEC`);
+            }
+        }
+        else if (!isDisplayOnlyDecisionMarker(entry.decision) && !decisionValid) {
+            errors.push(`结构变更清单 ${entry.id} 的决定列引用了无效的 DEC：${entry.decision}`);
+        }
+    }
+    return { ok: errors.length === 0, errors: [...new Set(errors)] };
+}
+export function formatStructureChangeLedgerSummary(ledger) {
+    if (!ledger.present || ledger.format_error)
+        return null;
+    if (ledger.none)
+        return "结构变更：无";
+    if (ledger.entries.length === 0)
+        return null;
+    const lines = ledger.entries.map(entry => {
+        const ref = splitBasisRef(entry.basis);
+        const basisLabel = ref && /^specs\//.test(ref.path) ? ref.anchor : entry.basis;
+        const decisionSuffix = DEC_ID_RE.test(entry.decision) ? ` — 决定 ${entry.decision}` : "";
+        return `- ${entry.id} [${entry.category}] ${entry.change} — 依据 ${basisLabel}${decisionSuffix}`;
+    });
+    return ["结构变更清单", "", ...lines].join("\n");
+}
 const TASK_LINE_RE = /^(- \[([ xX])\])\s+(\S+)/;
 // 块头独占一行（允许全角/半角冒号）；PREFIX 变体用于识别"块头带尾部内容/误加 bullet"的格式错误
 const EXECUTION_REQUIREMENT_LINE_RE = /^\s*执行依据[:：]\s*$/;

package/dist/phase_confirmation.js

@@ -5,7 +5,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 { parseExecutionRequirements, parseTasksMd, parseTestContractEntries } from "./format.js";
+import { parseExecutionRequirements, parseTasksMd, parseTestContractEntries, parseStructureChangeLedger, formatStructureChangeLedgerSummary } from "./format.js";
 import { hasFrozenWorkflowModeForProposeRound, workflowRiskForProject, workflowRiskForState, } from "./workflow_config.js";
 export const PHASE_CONFIRMATION_SCOPE_PREFIX = "phase_confirmation:";
 function taskTitle(content, task) {
@@ -68,7 +68,12 @@ function proposeTaskDeliverySummary(changeRoot) {
     const status = completedCount === 0
         ? ""
         : `已完成 ${completedCount} 项；${pendingTasks.length === 0 ? "当前没有待实施任务。" : `以下 ${pendingTasks.length} 项仍待实施或调整。`}\n\n`;
-    return `执行计划概览\n\n${status}${items.join("\n\n")}`;
+    const taskSummary = `执行计划概览\n\n${status}${items.join("\n\n")}`;
+    const designPath = join(changeRoot, "design.md");
+    const ledgerSummary = existsSync(designPath)
+        ? formatStructureChangeLedgerSummary(parseStructureChangeLedger(readFileSync(designPath, "utf8")))
+        : null;
+    return ledgerSummary ? `${taskSummary}\n\n${ledgerSummary}` : taskSummary;
 }
 function latestTransition(events, predicate) {
     return findLatestEvent(events, "transition_commit", event => predicate(event.payload));

package/dist/phase_plan.d.ts

@@ -4,6 +4,9 @@ import { proposeAnswerRegistrationPayload } from "./propose_round.ts";
 import type { AcceptedMaterialFollowupContinuation, AskUser, Event, ExecutionPolicy, Job, JobRole, PlanningValidationProfile, ReviewFindingContext, WorkflowArtifactKind, State } from "./types.ts";
 import type { Snapshot } from "./types.ts";
 import type { ReviewRisk } from "./review.ts";
+export declare const PLAN_SIZE_BUDGET_SCOPE_PREFIX = "plan_size_budget:";
+export declare const PLAN_SIZE_BUDGET_CONFIRM_ANSWER = "\u786E\u8BA4\u89C4\u6A21\u5408\u7406\uFF0C\u7EE7\u7EED\u5BA1\u67E5";
+export declare const PLAN_SIZE_BUDGET_SHRINK_ANSWER = "\u56DE\u53BB\u6536\u7F29\u8BA1\u5212";
 export type TransitionName = "explore" | "propose-ready" | "start-apply" | "task-start" | "task-complete" | "review-ready" | "reopen" | "accept";
 export type WorkflowMode = {
     kind: "risk";
@@ -119,6 +122,7 @@ export declare function latestReopenExploreBaseline(events: Event[]): Record<str
 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[];
+export declare function planSizeBudgetScope(proposeRoundId: string, taskCount: number, testCount: number): string;
 /** 当前 Apply round 的规则版本；缺失版本的历史 event 保持 v1 回放。 */
 export declare function executionRequirementVersionForCurrentRound(events: Event[]): 1 | 2;
 /** 新 planning round 在进入 propose 时冻结当前 OpenSpec 校验契约。 */