@peterxiaoyang/superspec 0.1.55 → 0.1.57

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/next.js

@@ -115,14 +115,17 @@ function toNextOutput(change, plan) {
                 resume: { argv: ["superspec", "transition", "next", "--change", change] },
                 reason: plan.reason,
             };
-        case "run_transition":
+        case "run_transition": {
+            const findingContext = plan.reopen?.reason === "review_fix" ? plan.reopen.findingContext : undefined;
             return {
                 state: plan.state,
                 path: "next_command",
                 next_command: transitionCommand(change, plan.transition, formatTransitionArgs(plan)),
                 reason: plan.reason,
                 missing_inputs: [],
+                ...(findingContext ? { finding_context: findingContext } : {}),
             };
+        }
         case "done":
             return {
                 state: plan.state,

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

@@ -1,9 +1,12 @@
 import type { ReviewGateRule } from "./review_job_gates.ts";
 import { exploreAnswerRegistrationPayload } from "./explore_round.ts";
 import { proposeAnswerRegistrationPayload } from "./propose_round.ts";
-import type { AcceptedMaterialFollowupContinuation, AskUser, Event, ExecutionPolicy, Job, JobRole, PlanningValidationProfile, WorkflowArtifactKind, State } from "./types.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";
@@ -29,6 +32,7 @@ export type ReopenNextStep = {
     jobId: string;
     findingId: string;
     reopenReason: string;
+    findingContext?: ReviewFindingContext;
 } | {
     to: "propose";
     reason: "review_finding";
@@ -118,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 校验契约。 */

package/dist/phase_plan.js

@@ -2,16 +2,29 @@ import { existsSync, readFileSync } from "node:fs";
 import { join, relative } from "node:path";
 import { EXPLORE_DISCOVERY_REVIEW_GATE, PROPOSE_FINAL_REVIEW_GATE } from "./review_job_gates.js";
 import { currentExploreRoundId, exploreAnswerRegistrationPayload, unregisteredClosedExploreQuestions, unresolvedPresentedExploreQuestionScopes, } from "./explore_round.js";
-import { currentProposeOpenQuestion, currentProposeRoundId, proposeAnswerRegistrationPayload, unregisteredClosedProposeQuestions, unresolvedPresentedProposeQuestionScopes, } from "./propose_round.js";
-import { discoveryOpenQuestionDisplayText, discoveryOpenQuestionScope, proposeOpenQuestionDisplayText, proposeOpenQuestionScope, parseExecutionRequirements, parseDiscoveryOpenQuestions, parseTasksMd, pendingTasksInContent, validateDiscovery, validateExecutionRequirements, validateExecutionRequirementDocumentReferences, validateProposalImpact, validateTasksDocument, } from "./format.js";
+import { currentProposeOpenQuestion, currentProposeRoundId, isPlanningValidationProfile, proposeAnswerRegistrationPayload, unregisteredClosedProposeQuestions, unresolvedPresentedProposeQuestionScopes, } from "./propose_round.js";
+import { discoveryOpenQuestionDisplayText, discoveryOpenQuestionScope, proposeOpenQuestionDisplayText, proposeOpenQuestionScope, parseExecutionRequirements, parseDiscoveryOpenQuestions, parseTasksMd, parseTestContractEntries, isFixTaskId, pendingTasksInContent, validateDiscovery, validateExecutionRequirements, validateExecutionRequirementDocumentReferences, validateProposalImpact, validateTasksDocument, parseStructureChangeLedger, validateStructureChangeLedger, } from "./format.js";
 import { currentGitHead } from "./git_state.js";
 import { validateOpenSpecChange } from "./openspec.js";
-import { docRef, sha256File } from "./store.js";
+import { docRef, sha256File, sha256Text, findLatestEvent } 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";
+import { CODE_REVIEW_DECISION_ANSWER_LABELS, CODE_REVIEW_REPAIR_SCOPE_PREFIX, codeReviewDecisionScope, codeReviewFindingNeedsUserDecision, codeReviewJobStaleReason, collectCodeReviewGateFacts, countReviewFixReopensSinceStartApply, currentCodeReviewWorkingPaths, isReviewFixCapReached, latestCodeReviewFailedStatus, requiresFinalVerifierForCurrentReview, scanCodeChangesForReview, } from "./code_review.js";
 import { isPhaseAdvanceAuthorized, latestAcceptedPhaseDecision, phaseConfirmationCommitPayload, phaseConfirmationForBoundary, phaseConfirmationMissingMessage, } from "./phase_confirmation.js";
 import { taskEvidenceReadiness } from "./task_evidence.js";
-import { workflowRiskForProposeRound, workflowRiskForState } from "./workflow_config.js";
+import { workflowRiskForProposeRound, workflowRiskForState, workflowBudgetForRisk } from "./workflow_config.js";
+export const PLAN_SIZE_BUDGET_SCOPE_PREFIX = "plan_size_budget:";
+export const PLAN_SIZE_BUDGET_CONFIRM_ANSWER = "确认规模合理，继续审查";
+export const PLAN_SIZE_BUDGET_SHRINK_ANSWER = "回去收缩计划";
+/** 从失败 finding 提取定位上下文：只回传 evidence（位置事实），不回传 description——那是审查建议叙事，不进执行上下文。 */
+function reviewFindingContext(finding) {
+    const evidence = typeof finding?.evidence === "string" ? finding.evidence.trim() : "";
+    if (!evidence)
+        return undefined;
+    return {
+        evidence,
+        note: "非授权上下文：仅用于定位问题代码；实现范围仍以任务行锚定的已批准行为为准",
+    };
+}
 function requiredJobs(state, jobs, reason) {
     return { kind: "required_jobs", state, jobs, reason };
 }
@@ -127,32 +140,47 @@ const REQUIRED_DESIGN_HEADINGS = [
     "## 实现方案",
 ];
 function validateDesignPlan(changeRoot, profile) {
-    if (profile?.openspec.mode !== "strict" || profile.design?.schema_version !== 1)
-        return null;
-    const designPath = join(changeRoot, "design.md");
-    if (!existsSync(designPath))
-        return null;
-    const lines = readFileSync(designPath, "utf8").split(/\r?\n/).map(line => line.trimEnd());
     const errors = [];
-    const headingIndexes = new Map();
-    for (const heading of REQUIRED_DESIGN_HEADINGS) {
-        const indexes = lines.flatMap((line, index) => line === heading ? [index] : []);
-        headingIndexes.set(heading, indexes);
-        if (indexes.length === 0)
-            errors.push(`design.md 缺少稳定结构标题：${heading}`);
-        if (indexes.length > 1)
-            errors.push(`design.md 稳定结构标题重复：${heading}`);
+    // 稳定标题检查自 design.schema_version 引入起生效；更早的 strict round 没有 design 字段，保持不检查。
+    if (profile?.openspec.mode === "strict" && profile.design != null) {
+        const designPath = join(changeRoot, "design.md");
+        if (existsSync(designPath)) {
+            const lines = readFileSync(designPath, "utf8").split(/\r?\n/).map(line => line.trimEnd());
+            const headingIndexes = new Map();
+            for (const heading of REQUIRED_DESIGN_HEADINGS) {
+                const indexes = lines.flatMap((line, index) => line === heading ? [index] : []);
+                headingIndexes.set(heading, indexes);
+                if (indexes.length === 0)
+                    errors.push(`design.md 缺少稳定结构标题：${heading}`);
+                if (indexes.length > 1)
+                    errors.push(`design.md 稳定结构标题重复：${heading}`);
+            }
+            if (errors.length === 0) {
+                let previousIndex = -1;
+                for (const heading of REQUIRED_DESIGN_HEADINGS) {
+                    const indexes = headingIndexes.get(heading);
+                    if (indexes[0] <= previousIndex) {
+                        errors.push(`design.md 稳定结构标题顺序错误：${heading}`);
+                        break;
+                    }
+                    previousIndex = indexes[0];
+                }
+            }
+        }
     }
-    if (errors.length > 0)
-        return errors.join("；");
-    let previousIndex = -1;
-    for (const heading of REQUIRED_DESIGN_HEADINGS) {
-        const indexes = headingIndexes.get(heading);
-        if (indexes[0] <= previousIndex)
-            return `design.md 稳定结构标题顺序错误：${heading}`;
-        previousIndex = indexes[0];
+    if (profile?.design?.schema_version === 2) {
+        const designPath = join(changeRoot, "design.md");
+        if (!existsSync(designPath)) {
+            errors.push('design.md 缺少 ## 结构变更清单；没有结构变更时在该标题下写"无"');
+        }
+        else {
+            const ledger = parseStructureChangeLedger(readFileSync(designPath, "utf8"));
+            const validation = validateStructureChangeLedger(changeRoot, ledger);
+            if (!validation.ok)
+                errors.push(...validation.errors);
+        }
     }
-    return null;
+    return errors.length > 0 ? [...new Set(errors)].join("；") : null;
 }
 export function executionPolicyForRisk(risk) {
     return risk === "strict" ? "tdd" : "green_only";
@@ -343,6 +371,102 @@ function latestStartApplyIndex(events) {
     }
     return -1;
 }
+function planSizeCountDigest(taskCount, testCount) {
+    return sha256Text(`${taskCount},${testCount}`).replace(/^sha256:/, "");
+}
+export function planSizeBudgetScope(proposeRoundId, taskCount, testCount) {
+    return `${PLAN_SIZE_BUDGET_SCOPE_PREFIX}${proposeRoundId}:${planSizeCountDigest(taskCount, testCount)}`;
+}
+function countNonFixPlanTasks(changeRoot) {
+    const tasksContent = readFileSync(join(changeRoot, "tasks.md"), "utf8");
+    return parseTasksMd(tasksContent).filter(task => !isFixTaskId(task.taskId)).length;
+}
+function countPlanTestEntries(changeRoot) {
+    const testContractPath = join(changeRoot, ".superspec", "artifacts", "test-contract.md");
+    if (!existsSync(testContractPath))
+        return 0;
+    const parsed = parseTestContractEntries(readFileSync(testContractPath, "utf8"));
+    return parsed.ok ? parsed.entries.length : 0;
+}
+function isOverPlanSizeBudget(budget, taskCount, testCount) {
+    const overTasks = budget.tasks !== null && taskCount > budget.tasks;
+    const overTests = budget.tests !== null && testCount > budget.tests;
+    return overTasks || overTests;
+}
+function latestPlanSizeBudgetAnswer(events, scope) {
+    const event = findLatestEvent(events, "user_decision_recorded", ev => {
+        const payload = ev.payload;
+        if (payload.scope !== scope)
+            return false;
+        if (payload.accepted === false)
+            return false;
+        return typeof payload.answer === "string" && payload.answer.trim() !== "";
+    });
+    if (!event)
+        return null;
+    const answer = event.payload.answer;
+    return typeof answer === "string" ? answer.trim() : null;
+}
+function planSizeBudgetOverageMessage(budget, taskCount, testCount) {
+    const parts = [];
+    if (budget.tasks !== null && taskCount > budget.tasks) {
+        parts.push(`任务 ${taskCount} 个（预算 ${budget.tasks}）`);
+    }
+    if (budget.tests !== null && testCount > budget.tests) {
+        parts.push(`TEST ${testCount} 个（预算 ${budget.tests}）`);
+    }
+    return parts.join("；");
+}
+function planSizeBudgetSkipReason(projectRoot, changeRoot, events, risk) {
+    const budget = workflowBudgetForRisk(projectRoot, risk);
+    if (!budget)
+        return null;
+    const taskCount = countNonFixPlanTasks(changeRoot);
+    const testCount = countPlanTestEntries(changeRoot);
+    if (!isOverPlanSizeBudget(budget, taskCount, testCount))
+        return null;
+    const scope = planSizeBudgetScope(currentProposeRoundId(events), taskCount, testCount);
+    const answer = latestPlanSizeBudgetAnswer(events, scope);
+    if (answer === PLAN_SIZE_BUDGET_CONFIRM_ANSWER)
+        return null;
+    if (answer === PLAN_SIZE_BUDGET_SHRINK_ANSWER) {
+        return `计划规模仍超过预算（${planSizeBudgetOverageMessage(budget, taskCount, testCount)}），请收缩 tasks 或 test-contract 后重试`;
+    }
+    return `计划规模超过预算（${planSizeBudgetOverageMessage(budget, taskCount, testCount)}），需要先确认规模或收缩计划`;
+}
+function planSizeBudgetNextStep(context) {
+    const { change, changeRoot, events, mode } = context;
+    const budget = workflowBudgetForRisk(context.projectRoot, mode.risk);
+    if (!budget)
+        return null;
+    const taskCount = countNonFixPlanTasks(changeRoot);
+    const testCount = countPlanTestEntries(changeRoot);
+    if (!isOverPlanSizeBudget(budget, taskCount, testCount))
+        return null;
+    const scope = planSizeBudgetScope(currentProposeRoundId(events), taskCount, testCount);
+    const answer = latestPlanSizeBudgetAnswer(events, scope);
+    if (answer === PLAN_SIZE_BUDGET_CONFIRM_ANSWER)
+        return null;
+    if (answer === PLAN_SIZE_BUDGET_SHRINK_ANSWER) {
+        return {
+            kind: "material_update_required",
+            state: "propose",
+            errors: [`计划规模仍超过预算：${planSizeBudgetOverageMessage(budget, taskCount, testCount)}`],
+            reason: "已选择收缩计划但规模未变化",
+        };
+    }
+    const overage = planSizeBudgetOverageMessage(budget, taskCount, testCount);
+    const question = `当前计划规模为 ${overage}。请确认是否按此规模继续进入审查，或先回去收缩 tasks / test-contract。`;
+    const ask = {
+        question,
+        allowed_answers: [PLAN_SIZE_BUDGET_CONFIRM_ANSWER, PLAN_SIZE_BUDGET_SHRINK_ANSWER],
+        scope,
+        record_argv: ["superspec", "record", "user-decision", "--change", change, "--input", "-"],
+        record_input: { scope, question, answer: null },
+        required_fields: ["answer"],
+    };
+    return { kind: "ask_user", state: "propose", ask, reason: "计划规模超过预算" };
+}
 function executionRequirementVersionFromPayload(payload) {
     return payload.execution_requirement_version === 2 ? 2 : 1;
 }
@@ -364,22 +488,12 @@ 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;
-    const designValid = profile.design == null || profile.design.schema_version === 1;
-    return designValid && (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" }, design: { schema_version: 1 } }
-        : { version: 2, openspec: { mode: "strict", config_digest: configDigest }, design: { schema_version: 1 } };
+        ? { version: 2, openspec: { mode: "disabled" }, design: { schema_version: 2 } }
+        : { version: 2, openspec: { mode: "strict", config_digest: configDigest }, design: { schema_version: 2 } };
 }
 /** propose 状态尚未 ready 时，从进入本 planning round 的事件读取冻结 profile。 */
 function planningValidationProfileForPendingProposeRound(events) {
@@ -654,6 +768,9 @@ export function planNextStep(context) {
                     reason: preflight.error,
                 };
             }
+            const budgetStep = planSizeBudgetNextStep(context);
+            if (budgetStep)
+                return budgetStep;
             const proposalReviewJobs = PROPOSE_FINAL_REVIEW_GATE.openJobsForGate(snapshot);
             if (proposalReviewJobs.length > 0) {
                 return requiredJobs("propose", proposalReviewJobs, `有 ${proposalReviewJobs.length} 个待完成 proposal 审查工作项`);
@@ -826,7 +943,8 @@ function planApplyDoneNext(context) {
         const findingId = pendingFinding?.id ?? "";
         const type = pendingFinding?.type;
         const decision = pendingFinding?.decision;
-        if (findingId && type === "implementation") {
+        const reviewFixCapReached = isReviewFixCapReached(context.projectRoot, events);
+        if (findingId && type === "implementation" && !reviewFixCapReached) {
             return {
                 kind: "run_transition",
                 state: "apply_done",
@@ -837,11 +955,12 @@ function planApplyDoneNext(context) {
                     jobId: latest.job.job_id,
                     findingId,
                     reopenReason: `修复代码审查问题 ${findingId}`,
+                    findingContext: reviewFindingContext(pendingFinding?.finding),
                 },
                 reason: `代码审查发现纯代码实现问题 ${findingId}，回到实现阶段修复`,
             };
         }
-        if (findingId && (type === "spec" || type === "mixed")) {
+        if (findingId && codeReviewFindingNeedsUserDecision(type, reviewFixCapReached)) {
             if (decision?.answer === "reopen_propose") {
                 return {
                     kind: "run_transition",
@@ -862,15 +981,21 @@ function planApplyDoneNext(context) {
                         jobId: latest.job.job_id,
                         findingId,
                         reopenReason: `根据代码审查问题 ${findingId} 回到实现阶段修复`,
+                        findingContext: reviewFindingContext(pendingFinding?.finding),
                     },
                     reason: `使用者已确认问题 ${findingId} 直接回到实现阶段修复`,
                 };
             }
             const problemKind = type === "spec"
                 ? "方案或需求文档可能需要调整"
-                : "代码实现和方案文档都可能有关";
+                : type === "mixed"
+                    ? "代码实现和方案文档都可能有关"
+                    : "纯代码实现问题";
+            const capNote = reviewFixCapReached && type === "implementation"
+                ? `本轮 Apply 已自动修复 ${countReviewFixReopensSinceStartApply(events)} 次，`
+                : "";
             const ask = {
-                question: `代码审查发现问题 ${findingId}：${problemKind}。请选择回到计划阶段修改文档、确认现有文档方向不变并回到实现阶段修代码，或驳回该问题；无论选择哪一项都必须写明原因。`,
+                question: `${capNote}代码审查发现问题 ${findingId}：${problemKind}。请选择回到计划阶段修改文档、确认现有文档方向不变并回到实现阶段修代码，或驳回该问题；无论选择哪一项都必须写明原因。`,
                 allowed_answers: [
                     CODE_REVIEW_DECISION_ANSWER_LABELS.reopen_propose,
                     CODE_REVIEW_DECISION_ANSWER_LABELS.reopen_apply,
@@ -1043,6 +1168,9 @@ function planProposeReadyTransition(context) {
     if (unresolvedPresentedProposeQuestionScopes(context.events).length > 0) {
         return { kind: "skip", message: "此前展示的设计问题缺少答复登记且已从计划材料消失，请恢复原问题并完成登记" };
     }
+    const budgetSkip = planSizeBudgetSkipReason(context.projectRoot, changeRoot, context.events, risk);
+    if (budgetSkip)
+        return { kind: "skip", message: budgetSkip };
     const requiredRoles = PROPOSE_FINAL_REVIEW_GATE.requiredRolesForRisk(risk);
     const gatePlan = reviewGatePlan(snapshot, context.events, changeRoot, PROPOSE_FINAL_REVIEW_GATE, requiredRoles);
     if (gatePlan)

package/dist/propose_round.d.ts

@@ -1,5 +1,11 @@
 import { type ProposeQuestion } from "./format.ts";
-import type { Event } from "./types.ts";
+import type { Event, PlanningValidationProfile } from "./types.ts";
+export declare function isPlanningValidationProfile(value: unknown): value is PlanningValidationProfile;
+/**
+ * 当前 planning round 的冻结 profile：优先取最近一次 propose-ready 写入的快照，
+ * 否则取进入 propose 的边界事件。两者都没有时是升级前的 v1 change。
+ */
+export declare function planningValidationProfileForCurrentRound(events: readonly Event[]): PlanningValidationProfile | null;
 export declare function currentProposeRoundId(events: readonly Event[]): string;
 export declare function proposeAnswerRegistrationPayload(changeRoot: string): {
     propose_answer_registration: {