@peterxiaoyang/superspec 0.1.45 → 0.1.47

package/dist/cli.js

@@ -514,7 +514,7 @@ 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
 
@@ -735,6 +735,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,23 @@
+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">, discoveryContent: string): boolean;
+/**
+ * 新协议轮次中，被回写为已确认的事项必须有对应答复记录。
+ * 进入本轮前已经关闭的事项作为基线保留，历史 change 因缺少协议标记整体兼容。
+ */
+export declare function unregisteredClosedExploreQuestions(events: readonly Event[], discoveryContent: string): DiscoveryQuestion[];

package/dist/explore_round.js

@@ -0,0 +1,94 @@
+import { discoveryQuestionContextFingerprint, 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;
+    return events.some(event => {
+        if (event.event_type !== "user_decision_recorded")
+            return false;
+        const payload = event.payload;
+        const recorded = payload.explore_open_question;
+        return payload.accepted === true &&
+            recorded?.round_id === roundId &&
+            recorded.question_id === question.id &&
+            recorded.question_ordinal === question.ordinal &&
+            recorded.context_fingerprint === currentContextFingerprint;
+    });
+}
+/**
+ * 新协议轮次中，被回写为已确认的事项必须有对应答复记录。
+ * 进入本轮前已经关闭的事项作为基线保留，历史 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));
+}

package/dist/format.d.ts

@@ -1,5 +1,44 @@
 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;
+/**
+ * 计算某一确认事项之外的 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" | "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 +48,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;
@@ -53,6 +95,11 @@ export type TestContractParseResult = {
 };
 /** 解析 tasks.md 的全部任务行 */
 export declare function parseTasksMd(content: string): ParsedTask[];
+/**
+ * tasks.md 的机械结构校验。任务是否拆分合理、顺序是否符合真实依赖仍由
+ * Critic/Architect 判断；这里仅拒绝引擎无法可靠驱动的格式。
+ */
+export declare function validateTasksDocument(content: string): string[];
 export declare function hasTaskBoundExecutionRequirements(content: string): boolean;
 export declare function parseExecutionRequirements(content: string): ParsedExecutionRequirement[];
 export declare function orphanExecutionRequirementErrors(content: string): string[];
@@ -61,15 +108,33 @@ 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;
+export interface ProposalImpactValidation {
+    ok: boolean;
+    message: string;
+}
+/** OpenSpec 项目的 proposal 采用固定 Impact 表格，供状态机进行纯结构校验。 */
+export declare function validateProposalImpact(content: string): ProposalImpactValidation;
 export interface ExecutionRequirementValidation {
     ok: boolean;
     mode: boolean;
     contracts: ParsedExecutionRequirement[];
     errors: string[];
 }
+/**
+ * 在已初始化的当前工作流中，把执行依据的文件/锚点可解析性作为状态机协议。
+ * “该材料是否足以支撑 task”仍然是 Critic/Architect 的语义判断。
+ */
+export declare function validateExecutionRequirementDocumentReferences(changeRoot: string, contracts: readonly ParsedExecutionRequirement[]): string[];
 export declare function validateExecutionRequirements(content: string, testContractContent: string | null, executionPolicy?: ExecutionPolicy, executionRequirementVersion?: 1 | 2): ExecutionRequirementValidation;
 /** 返回未完成任务 */
 export declare function pendingTasksInContent(content: string): ParsedTask[];