@peterxiaoyang/superspec 0.1.56 → 0.1.58

package/dist/phase_plan.js

@@ -2,16 +2,19 @@ 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() : "";
@@ -137,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";
@@ -353,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;
 }
@@ -374,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) {
@@ -664,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 审查工作项`);
@@ -836,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",
@@ -852,7 +960,7 @@ function planApplyDoneNext(context) {
                 reason: `代码审查发现纯代码实现问题 ${findingId}，回到实现阶段修复`,
             };
         }
-        if (findingId && (type === "spec" || type === "mixed")) {
+        if (findingId && codeReviewFindingNeedsUserDecision(type, reviewFixCapReached)) {
             if (decision?.answer === "reopen_propose") {
                 return {
                     kind: "run_transition",
@@ -880,9 +988,14 @@ function planApplyDoneNext(context) {
             }
             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,
@@ -1055,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: {

package/dist/propose_round.js

@@ -2,6 +2,41 @@ import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { collectProposeQuestions, parseProposeQuestions, proposeQuestionContextFingerprint, proposeQuestionDecisionBasisDigest, proposeQuestionKey, } from "./format.js";
 const PROPOSE_ANSWER_REGISTRATION_VERSION = 1;
+// ===== planning validation profile =====
+//
+// profile 在进入 propose 的边界事件上冻结，propose-ready 时复制到 propose_ready
+// 事件。所有读取方共用这里的判定，避免各处复制一份而在升级时漏改。
+export 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
+        || profile.design.schema_version === 2;
+    return designValid && (profile.openspec.mode === "disabled" ||
+        profile.openspec.mode === "strict" && typeof profile.openspec.config_digest === "string");
+}
+/**
+ * 当前 planning round 的冻结 profile：优先取最近一次 propose-ready 写入的快照，
+ * 否则取进入 propose 的边界事件。两者都没有时是升级前的 v1 change。
+ */
+export function planningValidationProfileForCurrentRound(events) {
+    for (let index = events.length - 1; index >= 0; index--) {
+        const event = events[index];
+        if (event.event_type !== "transition_commit")
+            continue;
+        const payload = event.payload;
+        const isReady = payload.transition === "propose-ready" && payload.to_state === "propose_ready";
+        if (!isReady && !isProposeRoundEntry(event))
+            continue;
+        return isPlanningValidationProfile(payload.planning_validation_profile)
+            ? payload.planning_validation_profile
+            : null;
+    }
+    return null;
+}
 function isProposeRoundEntry(event) {
     if (event.event_type !== "transition_commit")
         return false;

package/dist/record.d.ts

@@ -1,4 +1,6 @@
 import type { RecordResult, Job, JobPacket } from "./types.ts";
+/** 报告文件的推荐落盘位置：工作流记录目录，不进入计划材料。 */
+export declare function jobReportFilePath(change: string, jobId: string): string;
 /** record job-submit：登记工作项结果 */
 export declare function recordJobSubmit(projectRoot: string, change: string, changeRoot: string, jobId: string, reportFile: string): RecordResult;
 /** record job-submit：从 JSON 内容登记工作项结果 */

package/dist/record.js

@@ -5,7 +5,7 @@ import { ensureChangeLayout, readEvents, appendEvent, makeEvent, sha256File, sha
 import { rebuildSnapshot } from "./sync.js";
 import { changeRoot as openspecChangeRoot } from "./openspec.js";
 import { isPhaseConfirmationScope, phaseActionForAnswer, phaseConfirmationForCurrentState, workflowRiskForPhaseConfirmation, } from "./phase_confirmation.js";
-import { CODE_REVIEW_DECISION_ANSWER_LABELS, CODE_REVIEW_DECISION_SCOPE_PREFIX, codeReviewJobStaleReason, codeReviewDecisionAnswerLabel, currentCodeReviewWorkingPaths, latestCodeReviewFailedStatus, normalizeCodeReviewDecisionAnswer, parseCodeReviewDecisionScope, } from "./code_review.js";
+import { CODE_REVIEW_DECISION_ANSWER_LABELS, CODE_REVIEW_DECISION_SCOPE_PREFIX, codeReviewFindingNeedsUserDecision, codeReviewJobStaleReason, codeReviewDecisionAnswerLabel, currentCodeReviewWorkingPaths, isReviewFixCapReached, latestCodeReviewFailedStatus, normalizeCodeReviewDecisionAnswer, parseCodeReviewDecisionScope, } from "./code_review.js";
 import { invalidReasonForSubmittedReport } from "./job_validity.js";
 import { jobSubmitArgv } from "./job_action.js";
 import { hasBehaviorAnchor, isCodeReviewClaimKind, resolveApprovedRefs, } from "./approved_ref.js";
@@ -679,10 +679,23 @@ function recordJobSubmitLoaded(projectRoot, change, changeRoot, jobId, job, even
     return {
         event_type: "job_accepted",
         accepted: true,
-        message: `工作项 ${jobId}（${job.role}）已接受`,
+        message: `工作项 ${jobId}（${job.role}）已接受${misplacedReportFileNote(change, reportPath)}`,
         job_state: "accepted",
     };
 }
+/** 报告文件的推荐落盘位置：工作流记录目录，不进入计划材料。 */
+export function jobReportFilePath(change, jobId) {
+    return `.superspec/changes/${change}/jobs/${jobId}.report.json`;
+}
+/** 报告内容已存入 raw 记录；文件若写在 openspec change 目录里会跟计划材料一起进版本库，提示清理。 */
+function misplacedReportFileNote(change, reportPath) {
+    if (!reportPath)
+        return "";
+    const normalized = reportPath.replace(/\\/g, "/");
+    if (!normalized.startsWith(`openspec/changes/${change}/`))
+        return "";
+    return `；报告内容已存入工作流记录，${normalized} 位于计划材料目录，请删除该文件（落盘位置见 packet 的 report_file_path）`;
+}
 /** record job-submit：登记工作项结果 */
 export function recordJobSubmit(projectRoot, change, changeRoot, jobId, reportFile) {
     return withLock(projectRoot, change, () => {
@@ -1003,8 +1016,9 @@ function recordUserDecisionLoaded(projectRoot, change, events, content, inputDig
         const changeRoot = openspecChangeRoot(projectRoot, change);
         const snapshot = rebuildSnapshot(projectRoot, change, changeRoot);
         const status = latestCodeReviewFailedStatus(events);
+        const reviewFixCapReached = isReviewFixCapReached(projectRoot, events);
         const finding = ref && status?.terminal.job.job_id === ref.jobId
-            ? status.findings.find(item => item.id === ref.findingId && (item.type === "spec" || item.type === "mixed"))
+            ? status.findings.find(item => item.id === ref.findingId && codeReviewFindingNeedsUserDecision(item.type, reviewFixCapReached))
             : null;
         const staleReason = status && ref && status.terminal.job.job_id === ref.jobId
             ? codeReviewJobStaleReason(projectRoot, status.terminal.job, currentCodeReviewWorkingPaths(projectRoot, events), events)
@@ -1179,10 +1193,12 @@ function packetFieldDescriptions() {
         changed_paths_partial_reason: "该任务（task）的提交段 diff 失败原因；存在时 changed_paths 只包含工作区对比结果，归属可能不完整。",
         unattributed_paths: "代码审查范围中暂时无法归属到某个任务（task）的文件。",
         added_code_paths: "相对本次代码审查基点新建的代码文件，供判断是否服务已批准行为。",
+        structure_ledger: "design.md 中已批准的结构变更清单；清单是已批准结构的边界，清单外结构按 unjustified_addition 处理。",
         claim_kind: "阻塞问题相对已批准计划的关系：漏做、破坏已有行为、或计划或验收没有要求的改动。",
         approved_refs: "指向当前 change 已批准材料的引用；引擎只检查能否解析，apply 漏做还需要 TEST 或 spec Requirement。",
         unknown_attribution_tasks: "因为缺少边界快照或提交段 diff 失败而无法完整计算改动归属的任务（task）。",
         coverage_exemption_refs: "测试覆盖豁免引用：说明某个 TEST 为什么没有绑定到任务（task）。",
+        report_file_path: "报告需要落盘时的文件位置（项目相对路径），位于工作流记录目录；报告内容登记后由引擎存入 raw 记录，不属于计划材料。",
         code_review_gate: "最终验证读取的代码审查门禁事实：passed 指向已接受的代码审查工作项，skipped 表示本轮没有代码类改动。",
         code_state_check: "代码状态检查：最终验证时用于判断代码审查后代码是否又发生变化。",
         event_id: "事件 ID，用于追溯证据来源。",
@@ -1227,6 +1243,7 @@ export function jobsPacket(projectRoot, change, jobId) {
             ...(packetContext?.unattributed_paths ? { unattributed_paths: packetContext.unattributed_paths } : {}),
             ...(packetContext?.unknown_attribution_tasks ? { unknown_attribution_tasks: packetContext.unknown_attribution_tasks } : {}),
             ...(packetContext?.added_code_paths ? { added_code_paths: packetContext.added_code_paths } : {}),
+            ...(packetContext?.structure_ledger ? { structure_ledger: packetContext.structure_ledger } : {}),
             ...(packetContext?.code_state_check ? { code_state_check: packetContext.code_state_check } : {}),
             packet_digest: job.packet_digest,
             required_output_kind: "job_report_json",
@@ -1234,6 +1251,7 @@ export function jobsPacket(projectRoot, change, jobId) {
             submission_command: `superspec record job-submit --change "${change}" --job "${job.job_id}" --report -`,
             submission_argv: jobSubmitArgv(change, job.job_id),
             file_fallback: true,
+            report_file_path: jobReportFilePath(change, job.job_id),
             output_contract_fields: isCodeReviewer
                 ? [...REVIEW_REPORT_REQUIRED_FIELDS, "reviewer", "review_scope"]
                 : [
@@ -1249,12 +1267,12 @@ export function jobsPacket(projectRoot, change, jobId) {
                 (job.review_evidence_digest ? `本工作项对应的执行证据版本为 ${job.review_evidence_digest}，` : "") +
                 (isReviewer ? genericReviewCoverageInstruction(job) + proposalIncrementalReviewInstruction(job) + previousRejectionInstruction(job) : "") +
                 (requiresReviewer(job.role) ? `必须由独立 ${recommendedAgentForRole(job.role)} 审查角色执行，并在审查者来源字段（reviewer.kind/id）中记录来源，` : "") +
-                `产出 JSON 报告内容并优先通过 --report - 从 stdin 登记；文件路径模式仅作备用。${recordInputInstruction(job)}协议字段含义见 packet 顶层“字段说明”，普通对话不要原样复述 JSON。` +
+                `产出 JSON 报告内容并优先通过 --report - 从 stdin 登记；需要落盘时写到 report_file_path，不要写进 openspec/changes 或 .superspec/artifacts 等计划材料目录。${recordInputInstruction(job)}协议字段含义见 packet 顶层“字段说明”，普通对话不要原样复述 JSON。` +
                 (isCodeReviewer
                     ? `格式骨架：{"role":"code-reviewer","verdict":"pass","review_scope":{"job_id":"${job.job_id}","packet_digest":"${job.packet_digest}","checked_paths":[],"checked_docs":[],"unchecked":[]},"findings":[],"reviewer":{"kind":"subagent","id":"<thread-or-agent-id>"}}。提交前按真实审查结果填写数组；不得从 boundFiles 自动复制 checked_paths。verdict 只能为 pass 或 fail；审查覆盖范围（review_scope）用来说明本次审查覆盖了哪些文件和文档，已检查路径（checked_paths）与未检查项（unchecked）必须合起来覆盖全部绑定文件（boundFiles），unchecked 条目格式为 {"path":"<path>","reason":"<reason>"}；pass 不允许仍有未检查的绑定文件。`
                         + `报告结论为 fail 时，问题列表（findings）至少包含一个可处理、可追溯的阻塞问题，字段为 {"id":"<stable-id>","blocking":true,"type":"implementation|spec|mixed","claim_kind":"missing_approved|breaks_existing|unjustified_addition","approved_refs":["TEST-001"],"description":"<what>","evidence":"<why>","source_refs":["<path:line>"],"impact":"<impact>","suggested_action":"apply|propose"}。问题类型（type）中 implementation 表示纯代码实现问题，spec 表示方案/需求文档问题，mixed 表示需要使用者判断的混合问题；claim_kind 与 approved_refs 见字段说明。`
                         + (packetContext?.task_execution_index
-                            ? `本工作项带任务执行索引（task_execution_index）：按 task 对照其执行依据快照（contract）审查——实现路线对照 design 引用原文、累计 diff 对照 guard 边界、测试断言对照 tests 声明的 scenario；每项的 required_evidence 是 task-start 冻结的证据口径，red_required/green_required 分别说明是否需要 RED/GREEN；fix 非空表示状态机创建的实现修复，source、parent_task_id 和 reason 说明其归属，code_review 来源还需核对 review_finding；scope_note 既可能解释必要的范围扩大，也可能说明代码审查修复为何保留原实现，均需结合 Diff、调用链和验证证据独立判断；changed_paths 是归属线索不是结论（null 表示未知）；unattributed_paths 中的无主改动和 added_code_paths 中的新建代码文件，均需判断是否服务已批准行为；coverage_exemption_refs 解释未绑定 task 的 TEST 豁免。当前 packet 的 boundFiles 是本轮冻结的审查范围；若它来自前一轮审查后的增量，只复核本轮变化及其直接影响链路，不要求重复审查未变化文件，但仍要判断批准行为是否完整闭合。`
+                            ? `本工作项带任务执行索引（task_execution_index）：按 task 对照其执行依据快照（contract）审查——实现路线对照 design 引用原文、累计 diff 对照 guard 边界、测试断言对照 tests 声明的 scenario；每项的 required_evidence 是 task-start 冻结的证据口径，red_required/green_required 分别说明是否需要 RED/GREEN；fix 非空表示状态机创建的实现修复，source、parent_task_id 和 reason 说明其归属，code_review 来源还需核对 review_finding；scope_note 既可能解释必要的范围扩大，也可能说明代码审查修复为何保留原实现，均需结合 Diff、调用链和验证证据独立判断；changed_paths 是归属线索不是结论（null 表示未知）；unattributed_paths 中的无主改动和 added_code_paths 中的新建代码文件，均需判断是否服务已批准行为：放行其中任何计划外文件，都必须写明它服务于哪条已批准锚点、为何无法避免，说不出依据的按 unjustified_addition 收缩；coverage_exemption_refs 解释未绑定 task 的 TEST 豁免。当前 packet 的 boundFiles 是本轮冻结的审查范围；若它来自前一轮审查后的增量，只复核本轮变化及其直接影响链路，不要求重复审查未变化文件，但仍要判断批准行为是否完整闭合。`
                             : "")
                     : job.role === "verifier"
                         ? `最小格式：{"role":"verifier","verdict":"pass","findings":[]${hasReviewScope ? `,"review_scope":{"checked_paths":${JSON.stringify(job.boundFiles.map(file => file.path))}}` : ""}}。verdict 只能为 pass 或 fail；核对代码审查记录（code_review_gate）：passed 必须能追溯到已接受的代码审查工作项，skipped 必须能证明本次没有代码类改动。核对修复闭环：task_execution_index.fix.source=code_review 时必须核对 review_finding 对应问题是否关闭；source=self_test 时必须核对 parent_task_id、记录的自测原因、本次 attempt 验证和最新代码审查是否共同闭环。方案/混合问题必须有用户决策或后续修复证据。按 task_execution_index 的 required_evidence 核对测试证据：red_required 时需要同一 TEST 的 RED（expected_failure）后 GREEN；green_required 时每个声明 TEST 都需要允许的 GREEN 语义状态；测试运行证据应包含测试 ID（test_id）、命令（command）、工作目录（cwd）、退出码（exit_code）、语义状态（semantic_status）。修复 task 的回归测试运行可用回归覆盖任务列表（covers_task_ids）说明覆盖了哪些已完成任务；缺少任务尝试 ID（attempt_id）的旧证据只能弱引用。` +

package/dist/transition.js

@@ -6,7 +6,7 @@ import { rebuildSnapshot } from "./sync.js";
 import { requiredJobActions } from "./job_action.js";
 import { assertCommitPayloadExtension, isFreshReviewVerifier, isReviewReadyVerifier, latestReviewHistoryForGateRole, readReviewPolicyFromEvents, reviewBoundFiles, reviewEvidenceDigest, reviewPolicyForRisk, REVIEW_DOC_PATHS, } from "./review.js";
 import { REVIEW_CODE_REVIEW_GATE_ID, REVIEW_FINAL_VERIFIER_GATE, REVIEW_FINAL_VERIFIER_GATE_ID, reviewScopeForGateRole, } from "./review_job_gates.js";
-import { codeReviewBoundFiles, codeReviewDecisionScope, codeReviewJobStaleReason, codeReviewPacketContext, codeReviewPacketDigest, collectCodeReviewGateFacts, computeCodeStateCheck, currentCodeReviewWorkingPaths, dismissedCodeReviewSummary, effectiveCoverageExemptionRefsFromEvents, latestCodeReviewGateEvidence, latestCodeReviewDecision, latestCodeReviewFailedStatus, missingCoverageExemptionTestIds, requiresFinalVerifierForCurrentReview, scanCodeChangesForReview, taskExecutionIndexForReview, } from "./code_review.js";
+import { codeReviewBoundFiles, codeReviewDecisionScope, codeReviewJobStaleReason, codeReviewPacketContext, codeReviewPacketDigest, collectCodeReviewGateFacts, computeCodeStateCheck, currentCodeReviewWorkingPaths, dismissedCodeReviewSummary, effectiveCoverageExemptionRefsFromEvents, latestCodeReviewGateEvidence, latestCodeReviewDecision, latestCodeReviewFailedStatus, missingCoverageExemptionTestIds, requiresFinalVerifierForCurrentReview, scanCodeChangesForReview, taskExecutionIndexForReview, codeReviewFindingNeedsUserDecision, isReviewFixCapReached, } from "./code_review.js";
 import { taskEvidenceReadiness } from "./task_evidence.js";
 import { adoptedContractForTask, findTaskInLines, isFixTaskId, parseTasksMd, parseTestContractEntries, } from "./format.js";
 import { isCodeReviewClaimKind, reviewFixReason } from "./approved_ref.js";
@@ -1136,8 +1136,8 @@ export function reopen(projectRoot, change, changeRoot, to, reason, opts = {}) {
                 const found = findReviewFailedFinding(events, ref);
                 if (!found)
                     return { skip: true, message: `找不到有效的代码审查问题 ${opts.reviewFix}` };
-                const type = found.finding.type;
-                if (type === "spec" || type === "mixed") {
+                const type = typeof found.finding.type === "string" ? found.finding.type : undefined;
+                if (codeReviewFindingNeedsUserDecision(type, isReviewFixCapReached(projectRoot, events))) {
                     const scope = codeReviewDecisionScope(ref.jobId, ref.findingId);
                     const decision = latestCodeReviewDecision(events, scope);
                     if (decision?.answer !== "reopen_apply")

package/dist/types.d.ts

@@ -133,6 +133,7 @@ export interface JobPacketContext {
     unattributed_paths?: string[];
     unknown_attribution_tasks?: string[];
     added_code_paths?: string[];
+    structure_ledger?: StructureChangeLedger;
     code_state_check?: CodeStateCheck;
 }
 export interface JobPacket {
@@ -153,6 +154,7 @@ export interface JobPacket {
     unattributed_paths?: string[];
     unknown_attribution_tasks?: string[];
     added_code_paths?: string[];
+    structure_ledger?: StructureChangeLedger;
     code_state_check?: CodeStateCheck;
     packet_digest: string;
     required_output_kind: string;
@@ -160,6 +162,8 @@ export interface JobPacket {
     submission_command?: string;
     submission_argv?: string[];
     file_fallback?: boolean;
+    /** 需要落盘时的报告文件位置（项目相对路径），位于工作流记录目录而非计划材料目录。 */
+    report_file_path?: string;
     output_contract_fields?: string[];
     output_contract_optional_fields?: string[];
     字段说明?: Record<string, string>;
@@ -198,9 +202,23 @@ export interface PlanningValidationProfile {
     version: 2;
     openspec: OpenSpecValidationProfile;
     design?: {
-        schema_version: 1;
+        schema_version: 1 | 2;
     };
 }
+export interface StructureChangeEntry {
+    id: string;
+    category: string;
+    change: string;
+    basis: string;
+    decision: string;
+}
+export interface StructureChangeLedger {
+    present: boolean;
+    none: boolean;
+    entries: StructureChangeEntry[];
+    /** 标题存在但表格无法解析时的原因；有值时 entries 为空。 */
+    format_error?: string;
+}
 export interface TransitionCommitPayload {
     transition: string;
     from_state: State;

package/dist/workflow_config.d.ts

@@ -3,6 +3,16 @@ import type { Event, State } from "./types.ts";
 export declare const WORKFLOW_CONFIG_PATH = ".superspec/config.json";
 /** 项目未声明 workflow.mode 时采用的默认档位。 */
 export declare const DEFAULT_WORKFLOW_RISK: ReviewRisk;
+export declare const DEFAULT_WORKFLOW_BUDGET: {
+    readonly tasks: 10;
+    readonly tests: 20;
+    readonly review_fix_rounds: 2;
+};
+export type WorkflowBudget = {
+    tasks: number | null;
+    tests: number | null;
+    review_fix_rounds: number | null;
+};
 export declare const WORKFLOW_HOSTS: readonly ["codex", "omp"];
 export type WorkflowHost = (typeof WORKFLOW_HOSTS)[number];
 /** 未声明 hosts 的旧项目按 Codex 入口处理。 */
@@ -10,6 +20,11 @@ export declare const DEFAULT_WORKFLOW_HOSTS: WorkflowHost[];
 export declare class WorkflowConfigError extends Error {
     constructor(message: string);
 }
+/**
+ * 读取计划规模与 review-fix 上限；minimal 档整体忽略，budget 为 null 整体关闭，单项 null 关闭该项检查。
+ * 注意 0 不等于关闭：tasks/tests 为 0 表示任何任务/TEST 都超预算，review_fix_rounds 为 0 表示不允许自动修复。
+ */
+export declare function workflowBudgetForRisk(projectRoot: string, risk: ReviewRisk): WorkflowBudget | null;
 export declare function normalizeWorkflowHosts(values: readonly string[]): WorkflowHost[];
 export declare function parseWorkflowHostsFlag(raw: string): WorkflowHost[];
 /** 读取项目已选宿主。缺少配置或缺少 workflow.hosts 时默认 Codex。 */

package/dist/workflow_config.js

@@ -5,6 +5,11 @@ import { dirname, join } from "node:path";
 export const WORKFLOW_CONFIG_PATH = ".superspec/config.json";
 /** 项目未声明 workflow.mode 时采用的默认档位。 */
 export const DEFAULT_WORKFLOW_RISK = "normal";
+export const DEFAULT_WORKFLOW_BUDGET = {
+    tasks: 10,
+    tests: 20,
+    review_fix_rounds: 2,
+};
 export const WORKFLOW_HOSTS = ["codex", "omp"];
 /** 未声明 hosts 的旧项目按 Codex 入口处理。 */
 export const DEFAULT_WORKFLOW_HOSTS = ["codex"];
@@ -17,6 +22,48 @@ export class WorkflowConfigError extends Error {
 function isReviewRisk(value) {
     return value === "minimal" || value === "normal" || value === "strict";
 }
+function parseWorkflowBudgetValue(value, field) {
+    if (value === null)
+        return null;
+    if (typeof value !== "number" || !Number.isInteger(value) || value < 0) {
+        throw new WorkflowConfigError(`${WORKFLOW_CONFIG_PATH} 的 workflow.budget.${field} 必须是非负整数或 null`);
+    }
+    return value;
+}
+function workflowBudgetFromObject(budget) {
+    if (!budget)
+        return { ...DEFAULT_WORKFLOW_BUDGET };
+    const tasks = budget.tasks === undefined
+        ? DEFAULT_WORKFLOW_BUDGET.tasks
+        : parseWorkflowBudgetValue(budget.tasks, "tasks");
+    const tests = budget.tests === undefined
+        ? DEFAULT_WORKFLOW_BUDGET.tests
+        : parseWorkflowBudgetValue(budget.tests, "tests");
+    const review_fix_rounds = budget.review_fix_rounds === undefined
+        ? DEFAULT_WORKFLOW_BUDGET.review_fix_rounds
+        : parseWorkflowBudgetValue(budget.review_fix_rounds, "review_fix_rounds");
+    return { tasks, tests, review_fix_rounds };
+}
+/**
+ * 读取计划规模与 review-fix 上限；minimal 档整体忽略，budget 为 null 整体关闭，单项 null 关闭该项检查。
+ * 注意 0 不等于关闭：tasks/tests 为 0 表示任何任务/TEST 都超预算，review_fix_rounds 为 0 表示不允许自动修复。
+ */
+export function workflowBudgetForRisk(projectRoot, risk) {
+    if (risk === "minimal")
+        return null;
+    const workflow = workflowObject(readWorkflowConfigObject(projectRoot));
+    if (!workflow)
+        return { ...DEFAULT_WORKFLOW_BUDGET };
+    if (workflow.budget === undefined)
+        return { ...DEFAULT_WORKFLOW_BUDGET };
+    // budget: null 表示整体关闭预算与修复上限。
+    if (workflow.budget === null)
+        return { tasks: null, tests: null, review_fix_rounds: null };
+    if (typeof workflow.budget !== "object" || Array.isArray(workflow.budget)) {
+        throw new WorkflowConfigError(`${WORKFLOW_CONFIG_PATH} 的 workflow.budget 必须是 object 或 null`);
+    }
+    return workflowBudgetFromObject(workflow.budget);
+}
 function isWorkflowHost(value) {
     return value === "codex" || value === "omp";
 }

package/package.json

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

package/templates/workflow/prompts/architect.md

@@ -24,6 +24,7 @@ argument-hint: "本次架构审查说明"
 - 复用既有机制时，核对接入点、本次差异和保持语义；只审查本次接入是否破坏现有契约，不要求重建或重新证明底层基础设施。
 - 参考实现证明的是可复用能力和候选机制，不自动决定本次的接口、资源、数据模型或模块形态。新增 Controller、API、实体、表、公共类型、独立模块或跨仓库改动时，检查其是否承担不可由现有边界表达的独立责任；不要规定数量，但应挑战无必要依据的平行结构和机械复制。
 - 只有本次确实改变的兼容、并发、恢复、数据语义或发布顺序才需要明确设计；未改变的既有风险和理论故障不是 blocker。
+- 结构变更清单是本次已批准结构的边界。方案正文出现而清单未列的表、接口、开关、迁移或签名变化，或清单条目缺少 Requirement / TEST 依据，是 blocker；处理方向是删除或补依据。
 - 设计取舍受用户决定和明确非目标约束。报告无法满足的结果或事实冲突，不把未经采纳的架构方案写成 required fix。
 
 ### 方案可行性