@peterxiaoyang/superspec 0.1.46 → 0.1.48

package/dist/cli.js

@@ -66,7 +66,7 @@ function transitionExitCode(result) {
 function proposeReadyExitCode(result) {
     if (result.outcome === "blocked")
         return 0;
-    return result.events_written === 0 && result.message.includes("不能") ? 1 : 0;
+    return result.events_written === 0 && result.outcome === "advanced" && result.from_state === result.to_state ? 1 : 0;
 }
 function ensureWorkflowMode(projectRoot, _opts) {
     try {
@@ -493,10 +493,8 @@ async function askToUpdateSelfIfNeeded(projectRoot, rerunArgs) {
 // ===== 初始化 transition init =====
 // ===== init/explore 现在在 transition.ts 中（走统一锁内路径）=====
 // ===== 主分发 =====
-async function main(argv) {
-    // --help / 无参数 → 打印用法
-    if (argv.length === 0 || argv.includes("--help") || argv.includes("-h")) {
-        console.log(`SuperSpec 流程引擎 ${SUPERSPEC_VERSION}
+function topLevelHelp() {
+    return `SuperSpec 流程引擎 ${SUPERSPEC_VERSION}
 
 用法：superspec <命令> [选项]
 
@@ -507,14 +505,14 @@ async function main(argv) {
   jobs <子命令> --change <C>        工作项管理（见下）
   install                           安装项目工作流入口
   init --scope project              install 的兼容别名
-  update                           升级 CLI 到 npm latest 并同步项目工作流模板
-  version                          版本号
+  update                            升级 CLI 到 npm latest 并同步项目工作流模板
+  version                           版本号
 
 transition 子命令：
   init / explore / sync / next / propose-ready / start-apply
   task-start --task <T> / task-complete --task <T> [--input -]
   reopen --to explore|propose|apply --reason <TEXT>
-  reopen --to apply --reason <TEXT> [--review-fix <JOB#FINDING>]
+  reopen --to apply --reason <TEXT> [--review-fix <JOB#FINDING>|--self-test-fix <TASK>]
   reopen --to propose --reason <TEXT> [--review-finding <JOB#FINDING>]
   review-ready / accept
 
@@ -525,7 +523,49 @@ record 子命令：
 
 jobs 子命令：
   list / packet --job <J>
-`);
+`;
+}
+function commandHelp(command, subcommand) {
+    if (command === "record" && subcommand === "user-decision") {
+        return `用法：superspec record user-decision --change <C> --input <F|->
+
+从 JSON 文件读取用户决定；--input - 表示从 stdin 读取。
+输入至少包含 scope 和 answer，工作流给出的 question 可一并保留。
+
+示例：
+  printf '%s' '{"scope":"<next 返回的 scope>","question":"<原问题>","answer":"<用户答复>"}' | superspec record user-decision --change <C> --input -
+`;
+    }
+    if (command === "record" && subcommand === "job-submit") {
+        return `用法：superspec record job-submit --change <C> --job <J> --report <F|->
+
+提交 reviewer JSON 报告；--report - 表示从 stdin 读取。报告契约以 jobs packet 返回的 report_schema 为准。
+
+示例：
+  superspec jobs packet --change <C> --job <J>
+  superspec record job-submit --change <C> --job <J> --report report.json
+`;
+    }
+    if (command === "record" && subcommand === "test-run") {
+        return `用法：superspec record test-run --change <C> --input <F|->
+
+登记测试证据；--input - 表示从 stdin 读取。输入需包含 test_id、task_structure_digest、command、cwd、exit_code 和 semantic_status。
+
+示例：
+  printf '%s' '{"test_id":"TEST-001","task_structure_digest":"sha256:<digest>","command":"npm test","cwd":"<project>","exit_code":0,"semantic_status":"expected_success"}' | superspec record test-run --change <C> --input -
+`;
+    }
+    if (command === "transition" && subcommand === "propose-ready") {
+        return `用法：superspec transition propose-ready --change <C>
+
+校验当前计划材料和审查门禁；满足条件时推进到 propose_ready。工作流模式来自项目配置，不接受 --risk。
+`;
+    }
+    return topLevelHelp();
+}
+async function main(argv) {
+    if (argv.length === 0) {
+        console.log(topLevelHelp());
         return 0;
     }
     // version
@@ -534,6 +574,10 @@ jobs 子命令：
         return 0;
     }
     const { command, subcommand, opts } = parseArgs(argv);
+    if (argv.includes("--help") || argv.includes("-h") || command === "--help" || command === "-h") {
+        console.log(commandHelp(command, subcommand));
+        return 0;
+    }
     const projectRoot = process.cwd();
     // install / init / update 不需要 --change
     if (command === "install" || command === "init") {
@@ -735,6 +779,7 @@ jobs 子命令：
                         const result = reopen(projectRoot, change, cr, to, reason, {
                             ...(opts["review-fix"] ? { reviewFix: opts["review-fix"] } : {}),
                             ...(opts["review-finding"] ? { reviewFinding: opts["review-finding"] } : {}),
+                            ...(opts["self-test-fix"] ? { selfTestFix: opts["self-test-fix"] } : {}),
                         });
                         console.log(JSON.stringify(result, null, 2));
                         return transitionExitCode(result);

package/dist/code_review.d.ts

@@ -1,4 +1,4 @@
-import type { CodeReviewResultKind, CodeReviewScope, CodeStateCheck, CoverageExemptionRef, Event, Job, JobPacketContext, Ref, ReviewPreviousRejection } from "./types.ts";
+import type { CodeReviewGateEvidence, CodeReviewResultKind, CodeReviewScope, CodeStateCheck, CoverageExemptionRef, Event, Job, JobPacketContext, Ref, ReviewPreviousRejection, TaskExecutionIndexEntry } from "./types.ts";
 export declare const CODE_REVIEW_REPAIR_SCOPE_PREFIX = "code_reviewer_report_repair:";
 export declare const CODE_REVIEW_DECISION_SCOPE_PREFIX = "code_review_decision:";
 export declare const TEST_COVERAGE_EXEMPTION_SCOPE_PREFIX = "test_coverage_exemption:";
@@ -68,7 +68,15 @@ export declare function codeReviewPacketDigest(input: {
 export declare function codeReviewPacketContext(changeRoot: string, projectRoot: string, scope: CodeReviewScope, events: Event[]): JobPacketContext;
 export declare function effectiveCoverageExemptionRefsFromEvents(events: Event[]): CoverageExemptionRef[];
 export declare function missingCoverageExemptionTestIds(changeRoot: string, events: Event[]): string[];
+/** 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;
+export interface CodeReviewDecisionScopeRef {
+    jobId: string;
+    findingId: string;
+}
+/** 只接受状态机生成的 <job>#<finding> 决策范围。 */
+export declare function parseCodeReviewDecisionScope(scope: string): CodeReviewDecisionScopeRef | null;
 export declare function isCodeReviewDecisionAnswer(value: unknown): value is CodeReviewDecisionAnswer;
 export declare function codeReviewDecisionAnswerLabel(answer: CodeReviewDecisionAnswer): string;
 export declare function normalizeCodeReviewDecisionAnswer(value: unknown): CodeReviewDecisionAnswer | null;
@@ -82,5 +90,7 @@ export declare function latestApplyDoneToReviewGate(events: Event[]): {
     job_id?: string;
     reason?: string;
 } | null;
+/** Latest code-review gate fact for the current review cycle, frozen into verifier packets. */
+export declare function latestCodeReviewGateEvidence(events: Event[]): CodeReviewGateEvidence | null;
 export declare function requiresFinalVerifierForCurrentReview(events: Event[]): boolean;
 export declare function computeCodeStateCheck(projectRoot: string, events: Event[], ignoredCodePaths?: string[]): CodeStateCheck;

package/dist/code_review.js

@@ -418,6 +418,7 @@ function taskExecutionIndexFromEvents(projectRoot, events) {
             entries.push({
                 task_id: payload.task_id,
                 attempt_id: payload.attempt_id,
+                ...(attempt?.fix ? { fix: attempt.fix } : {}),
                 execution_policy: attempt?.execution_policy ?? "tdd",
                 changed_paths: changedResult ? changedResult.paths : null,
                 ...(changedResult?.partial_reason ? { changed_paths_partial_reason: changedResult.partial_reason } : {}),
@@ -435,6 +436,10 @@ function taskExecutionIndexFromEvents(projectRoot, events) {
     entries.sort((a, b) => a.task_id.localeCompare(b.task_id) || a.attempt_id.localeCompare(b.attempt_id));
     return entries;
 }
+/** Read-only execution evidence projected for code review and final verification. */
+export function taskExecutionIndexForReview(projectRoot, events) {
+    return taskExecutionIndexFromEvents(projectRoot, events);
+}
 function isCodeReviewerJob(job) {
     return job.role === "code-reviewer" && REVIEW_CODE_REVIEW_GATE.isJobForGate(job);
 }
@@ -446,6 +451,18 @@ function codeReviewResultKind(value) {
 export function codeReviewDecisionScope(jobId, findingId) {
     return `${CODE_REVIEW_DECISION_SCOPE_PREFIX}${jobId}#${findingId}`;
 }
+/** 只接受状态机生成的 <job>#<finding> 决策范围。 */
+export function parseCodeReviewDecisionScope(scope) {
+    if (!scope.startsWith(CODE_REVIEW_DECISION_SCOPE_PREFIX))
+        return null;
+    const value = scope.slice(CODE_REVIEW_DECISION_SCOPE_PREFIX.length);
+    const separator = value.indexOf("#");
+    if (separator <= 0 || separator === value.length - 1)
+        return null;
+    const jobId = value.slice(0, separator);
+    const findingId = value.slice(separator + 1);
+    return jobId.trim() !== "" && findingId.trim() !== "" ? { jobId, findingId } : null;
+}
 export function isCodeReviewDecisionAnswer(value) {
     return value === "reopen_propose" || value === "reopen_apply" || value === "dismiss";
 }
@@ -622,6 +639,29 @@ export function latestApplyDoneToReviewGate(events) {
     }
     return null;
 }
+/** Latest code-review gate fact for the current review cycle, frozen into verifier packets. */
+export function latestCodeReviewGateEvidence(events) {
+    for (let i = events.length - 1; i >= 0; i--) {
+        const event = events[i];
+        if (event.event_type !== "transition_commit")
+            continue;
+        const payload = event.payload;
+        if (payload.transition !== "review-ready" || payload.from_state !== "apply_done" || payload.to_state !== "review")
+            continue;
+        const gate = payload.code_review_gate;
+        if (!gate || (gate.decision !== "passed" && gate.decision !== "skipped"))
+            return null;
+        return {
+            decision: gate.decision,
+            job_id: typeof gate.job_id === "string" ? gate.job_id : null,
+            packet_digest: typeof gate.packet_digest === "string" ? gate.packet_digest : null,
+            ...(gate.reason === "no_code_changes" ? { reason: gate.reason } : {}),
+            event_id: event.event_id,
+            event_digest: event.event_digest,
+        };
+    }
+    return null;
+}
 export function requiresFinalVerifierForCurrentReview(events) {
     return latestApplyDoneToReviewGate(events) != null;
 }

package/dist/explore_round.d.ts

@@ -0,0 +1,25 @@
+import { type DiscoveryQuestion } from "./format.ts";
+import type { Event } from "./types.ts";
+/**
+ * 当前 Explore 轮次的稳定标识。
+ *
+ * 同一轮内补充调查或创建审查工作项不会使当前确认事项失效；只有首次进入
+ * Explore 或从后续阶段重新打开 Explore 时，才开始新的确认轮次。
+ */
+export declare function currentExploreRoundId(events: readonly Event[]): string;
+/** 在进入新 Explore 轮次时冻结已有已确认事项，避免升级时追溯历史答复。 */
+export declare function exploreAnswerRegistrationPayload(discoveryContent: string | null): {
+    explore_answer_registration: {
+        version: number;
+        baseline_closed_question_keys: string[];
+    };
+};
+/** 当前确认事项已通过本轮主流程登记过答复。 */
+export declare function exploreAnswerWasRecorded(events: readonly Event[], roundId: string, question: Pick<DiscoveryQuestion, "id" | "ordinal" | "text">, discoveryContent: string): boolean;
+/**
+ * 新协议轮次中，被回写为已确认的事项必须有对应答复记录。
+ * 进入本轮前已经关闭的事项作为基线保留，历史 change 因缺少协议标记整体兼容。
+ */
+export declare function unregisteredClosedExploreQuestions(events: readonly Event[], discoveryContent: string): DiscoveryQuestion[];
+/** 已正式展示但尚未登记答复的 Explore 问题不能通过删除问题行绕过。 */
+export declare function unresolvedPresentedExploreQuestionScopes(events: readonly Event[]): string[];

package/dist/explore_round.js

@@ -0,0 +1,139 @@
+import { discoveryQuestionContextFingerprint, discoveryQuestionDecisionBasisDigest, discoveryQuestionKey, parseDiscoveryQuestions, } from "./format.js";
+const EXPLORE_ANSWER_REGISTRATION_VERSION = 1;
+function isExploreRoundEntry(event) {
+    if (event.event_type !== "transition_commit")
+        return false;
+    const payload = event.payload;
+    return payload.transition === "explore" && payload.from_state === "init" && payload.to_state === "explore" ||
+        payload.transition === "reopen" && payload.reopen_target === "explore";
+}
+function currentExploreRoundEntry(events) {
+    for (let index = events.length - 1; index >= 0; index--) {
+        const event = events[index];
+        if (isExploreRoundEntry(event))
+            return { event, roundId: event.event_id };
+    }
+    return null;
+}
+/**
+ * 当前 Explore 轮次的稳定标识。
+ *
+ * 同一轮内补充调查或创建审查工作项不会使当前确认事项失效；只有首次进入
+ * Explore 或从后续阶段重新打开 Explore 时，才开始新的确认轮次。
+ */
+export function currentExploreRoundId(events) {
+    return currentExploreRoundEntry(events)?.roundId ?? "legacy-explore-round";
+}
+/** 在进入新 Explore 轮次时冻结已有已确认事项，避免升级时追溯历史答复。 */
+export function exploreAnswerRegistrationPayload(discoveryContent) {
+    const baselineClosedQuestionKeys = discoveryContent == null
+        ? []
+        : parseDiscoveryQuestions(discoveryContent)
+            .filter(question => question.status === "closed")
+            .map(discoveryQuestionKey)
+            .sort();
+    return {
+        explore_answer_registration: {
+            version: EXPLORE_ANSWER_REGISTRATION_VERSION,
+            baseline_closed_question_keys: baselineClosedQuestionKeys,
+        },
+    };
+}
+function currentExploreAnswerRegistration(events) {
+    const entry = currentExploreRoundEntry(events);
+    if (!entry) {
+        return {
+            enabled: false,
+            roundId: "legacy-explore-round",
+            baselineClosedQuestionKeys: new Set(),
+        };
+    }
+    const payload = entry.event.payload;
+    const registration = payload.explore_answer_registration;
+    if (registration?.version !== EXPLORE_ANSWER_REGISTRATION_VERSION || !Array.isArray(registration.baseline_closed_question_keys)) {
+        return {
+            enabled: false,
+            roundId: entry.roundId,
+            baselineClosedQuestionKeys: new Set(),
+        };
+    }
+    return {
+        enabled: true,
+        roundId: entry.roundId,
+        baselineClosedQuestionKeys: new Set(registration.baseline_closed_question_keys.filter((key) => typeof key === "string")),
+    };
+}
+/** 当前确认事项已通过本轮主流程登记过答复。 */
+export function exploreAnswerWasRecorded(events, roundId, question, discoveryContent) {
+    const currentContextFingerprint = discoveryQuestionContextFingerprint(discoveryContent, question);
+    if (!currentContextFingerprint)
+        return false;
+    const currentBasisDigest = discoveryQuestionDecisionBasisDigest(question);
+    return events.some(event => {
+        if (event.event_type !== "user_decision_recorded")
+            return false;
+        const payload = event.payload;
+        const recorded = payload.explore_open_question;
+        const revisionMatches = typeof recorded?.decision_basis_digest === "string"
+            ? recorded.decision_basis_digest === currentBasisDigest
+            : recorded?.context_fingerprint === currentContextFingerprint;
+        return payload.accepted === true &&
+            recorded?.round_id === roundId &&
+            recorded.question_id === question.id &&
+            (!question.id.startsWith("item-") || recorded.question_ordinal === question.ordinal) &&
+            revisionMatches;
+    });
+}
+/**
+ * 新协议轮次中，被回写为已确认的事项必须有对应答复记录。
+ * 进入本轮前已经关闭的事项作为基线保留，历史 change 因缺少协议标记整体兼容。
+ */
+export function unregisteredClosedExploreQuestions(events, discoveryContent) {
+    const registration = currentExploreAnswerRegistration(events);
+    if (!registration.enabled)
+        return [];
+    return parseDiscoveryQuestions(discoveryContent).filter(question => question.status === "closed" &&
+        !registration.baselineClosedQuestionKeys.has(discoveryQuestionKey(question)) &&
+        !exploreAnswerWasRecorded(events, registration.roundId, question, discoveryContent));
+}
+/** 已正式展示但尚未登记答复的 Explore 问题不能通过删除问题行绕过。 */
+export function unresolvedPresentedExploreQuestionScopes(events) {
+    const roundId = currentExploreRoundId(events);
+    const acceptedDecisions = events.flatMap(event => {
+        if (event.event_type !== "user_decision_recorded")
+            return [];
+        const payload = event.payload;
+        return payload.accepted === true ? [payload] : [];
+    });
+    const latestByQuestion = new Map();
+    for (const event of events) {
+        if (event.event_type !== "user_question_presented")
+            continue;
+        const payload = event.payload;
+        if (payload.phase !== "explore" || payload.round_id !== roundId || typeof payload.scope !== "string" || typeof payload.question_id !== "string")
+            continue;
+        const identity = payload.question_id.startsWith("item-")
+            ? `${payload.question_id}:${String(payload.question_ordinal)}`
+            : payload.question_id;
+        latestByQuestion.set(identity, {
+            scope: payload.scope,
+            legacyScope: typeof payload.legacy_scope === "string" ? payload.legacy_scope : null,
+            questionId: payload.question_id,
+            questionOrdinal: payload.question_ordinal,
+            revisionDigest: payload.decision_basis_digest,
+        });
+    }
+    return [...latestByQuestion.values()].flatMap(presented => {
+        const answered = acceptedDecisions.some(decision => {
+            if (decision.scope === presented.scope || decision.scope === presented.legacyScope)
+                return true;
+            const recorded = decision.explore_open_question;
+            return recorded?.round_id === roundId &&
+                recorded.question_id === presented.questionId &&
+                (!presented.questionId.startsWith("item-") || recorded.question_ordinal === presented.questionOrdinal) &&
+                typeof presented.revisionDigest === "string" &&
+                recorded.decision_basis_digest === presented.revisionDigest;
+        });
+        return answered ? [] : [presented.scope];
+    });
+}

package/dist/format.d.ts

@@ -1,5 +1,51 @@
 import { type ExecutionContract, type ExecutionPolicy } from "./types.ts";
-/** 从 discovery.md 提取"待确认问题"段内的未确认项数量 */
+export declare const EXPLORE_OPEN_QUESTION_SCOPE_PREFIX = "explore_open_question:";
+/**
+ * Discovery 的未确认项是用户决策的唯一候选来源。这里保留原有的“仅指定段落内
+ * checkbox 有效”语义；ID 缺失的历史文档按所有 checklist 在该段落中的稳定顺序
+ * 使用 item-N，避免升级时要求迁移历史 change。
+ */
+export interface DiscoveryOpenQuestion {
+    /** Q-xxx；历史材料没有 ID 时为 item-N。 */
+    id: string;
+    /** 在“待确认问题”段落中所有 checklist 的 1-based 顺序。 */
+    ordinal: number;
+    /** 去掉 markdown checkbox 后的原始内容，用于留痕与内部匹配。 */
+    text: string;
+    /** 包含 checkbox 的原始 Markdown 行，供诊断和测试使用。 */
+    raw: string;
+    /** 当前完整 discovery.md 的内容指纹，避免只改决策依据时沿用旧答复。 */
+    documentFingerprint: string;
+}
+/** Discovery 待确认段中的一项；状态机需要同时识别待答复和已回写的项。 */
+export interface DiscoveryQuestion extends DiscoveryOpenQuestion {
+    status: "open" | "closed";
+}
+/**
+ * 当前文档中同一确认事项的稳定键。结合 Q-ID、顺序和原文，避免把本轮开始前
+ * 已经确认的旧事项误认为新答复。
+ */
+export declare function discoveryQuestionKey(question: Pick<DiscoveryQuestion, "id" | "ordinal" | "text">): string;
+/**
+ * 当前决定所依据的规范化问题内容。会改变选择、推荐或影响的事实必须写入该问题项；
+ * 状态机只绑定这份明确依据，不猜测文档其它段落与决定是否相关。
+ */
+export declare function discoveryQuestionDecisionBasisDigest(question: Pick<DiscoveryQuestion, "id" | "ordinal" | "text">): string;
+/**
+ * 计算某一确认事项之外的 Discovery 决策上下文。回写时该事项本身会从问题改为
+ * 结论，因此只归一化这一行；其余事实、证据和其它待确认项的改动都会使指纹失效。
+ */
+export declare function discoveryQuestionContextFingerprint(content: string, question: Pick<DiscoveryQuestion, "id" | "ordinal">): string | null;
+/** 按文档顺序提取 discovery.md 的全部确认事项。 */
+export declare function parseDiscoveryQuestions(content: string): DiscoveryQuestion[];
+/** 按文档顺序提取 discovery.md 中尚未确认的问题。 */
+export declare function parseDiscoveryOpenQuestions(content: string): DiscoveryOpenQuestion[];
+export declare function discoveryOpenQuestionScope(question: Pick<DiscoveryOpenQuestion, "id" | "ordinal" | "text">, exploreRoundId: string): string;
+/** 兼容升级前已经展示给用户、但尚未登记的 scope。 */
+export declare function legacyDiscoveryOpenQuestionScope(question: Pick<DiscoveryOpenQuestion, "id" | "documentFingerprint">, exploreRoundId: string): string;
+/** 面向用户展示时隐藏 Q-xxx 这一内部编号；历史无编号问题保持原文。 */
+export declare function discoveryOpenQuestionDisplayText(question: Pick<DiscoveryOpenQuestion, "id" | "text">): string;
+/** 从 discovery.md 提取“待确认问题”段内的未确认项数量。 */
 export declare function countDiscoveryOpenQuestions(content: string): number;
 export interface DiscoveryChainCoverageCheck {
     ok: boolean;
@@ -9,7 +55,10 @@ export interface DiscoveryChainCoverageCheck {
 export declare function splitMarkdownTableRow(line: string): string[];
 /** 轻量校验 discovery.md 的链路五要素段。只校验结构和阻塞未知，不判断业务真假。 */
 export declare function validateDiscoveryChainCoverage(content: string): DiscoveryChainCoverageCheck;
-/** 完整校验 discovery.md：存在 + 非空 + 无未确认问题 */
+/**
+ * 校验 discovery.md 的可解析结构。未确认问题不是格式错误：next 会把第一个问题
+ * 作为当前用户决策返回；只有缺文档、空文档或已声明链路的结构错误才在此阻断。
+ */
 export declare function validateDiscovery(changeRoot: string): {
     ok: boolean;
     message: string;
@@ -19,6 +68,26 @@ export interface ProposeOpenQuestionFile {
     path: string;
     openCount: number;
 }
+export declare const PROPOSE_OPEN_QUESTION_SCOPE_PREFIX = "propose_open_question:";
+export interface ProposeQuestion {
+    path: string;
+    id: string;
+    ordinal: number;
+    text: string;
+    raw: string;
+    documentFingerprint: string;
+    status: "open" | "closed";
+}
+export declare function parseProposeQuestions(content: string, path: string): ProposeQuestion[];
+export declare function proposeQuestionKey(question: Pick<ProposeQuestion, "path" | "id" | "ordinal" | "text">): string;
+/** Propose 决定的明确依据；其它计划材料变化不会自动使已展示决定失效。 */
+export declare function proposeQuestionDecisionBasisDigest(question: Pick<ProposeQuestion, "path" | "id" | "ordinal" | "text">): string;
+export declare function proposeQuestionContextFingerprint(content: string, question: Pick<ProposeQuestion, "id" | "ordinal">): string | null;
+export declare function proposeOpenQuestionScope(question: ProposeQuestion, proposeRoundId: string): string;
+/** 兼容升级前已经展示给用户、但尚未登记的 scope。 */
+export declare function legacyProposeOpenQuestionScope(question: ProposeQuestion, proposeRoundId: string): string;
+export declare function proposeOpenQuestionDisplayText(question: Pick<ProposeQuestion, "id" | "text">): string;
+export declare function collectProposeQuestions(changeRoot: string): ProposeQuestion[];
 export declare function countProposeOpenQuestionsInContent(content: string): number;
 export declare function collectProposeOpenQuestions(changeRoot: string): {
     openCount: number;
@@ -66,6 +135,13 @@ export declare function adoptedContractForTask(content: string, taskId: string,
     parsed: ParsedExecutionRequirement | null;
     contract: ExecutionContract | null;
 };
+/**
+ * Fix task 由状态机从已批准的实现范围派生；它没有 proposal 阶段执行依据块。
+ * REVIEW-FIX-* 是发布前已有的持久化 task ID，FIX-SELFTEST-* 是当前引擎生成的
+ * 自测修复 task。不能把通用 FIX-* 前缀保留为内部命名空间。
+ */
+export declare function isFixTaskId(taskId: string): boolean;
+/** @deprecated 新代码使用 isFixTaskId；保留给旧扩展和历史调用。 */
 export declare function isReviewFixTaskId(taskId: string): boolean;
 export declare function isCharacterizationTask(task: ParsedTask): boolean;
 export declare function parseTestContractEntries(content: string): TestContractParseResult;