@peterxiaoyang/superspec 0.1.41 → 0.1.42

package/dist/cli.js

@@ -10,6 +10,7 @@ import { next as nextCmd } from "./next.js";
 import { proposeReady, commitTransition, transitionInit, transitionExplore, startApply, taskStart, taskComplete, reopen, reviewReady, accept } from "./transition.js";
 import { recordJobSubmit, recordJobSubmitContent, recordUserDecision, recordUserDecisionContent, jobsList, jobsPacket } from "./record.js";
 import { recordTestRun, recordTestRunContent } from "./task.js";
+import { RecordInputDecodingError, decodeRecordInput } from "./record_input.js";
 import { probeOpenSpec, openspecStatus, changeRoot } from "./openspec.js";
 import { SUPERSPEC_VERSION } from "./version.js";
 const PACKAGE_NAME = "@peterxiaoyang/superspec";
@@ -54,7 +55,7 @@ function readStdinRecordContent(flag) {
     if (process.stdin.isTTY === true) {
         throw new StdinRecordInputError(flag);
     }
-    return readFileSync(0, "utf8");
+    return decodeRecordInput(readFileSync(0));
 }
 function transitionExitCode(result) {
     if (result.outcome === "blocked")
@@ -709,7 +710,7 @@ jobs 子命令：
                                 inputContent = readStdinRecordContent("--input");
                             }
                             catch (err) {
-                                if (err instanceof StdinRecordInputError) {
+                                if (err instanceof StdinRecordInputError || err instanceof RecordInputDecodingError) {
                                     console.error(err.message);
                                     return 1;
                                 }
@@ -773,7 +774,7 @@ jobs 子命令：
                                 : recordJobSubmit(projectRoot, change, cr, jobId, report);
                         }
                         catch (err) {
-                            if (err instanceof StdinRecordInputError) {
+                            if (err instanceof StdinRecordInputError || err instanceof RecordInputDecodingError) {
                                 console.error(err.message);
                                 return 1;
                             }
@@ -795,7 +796,7 @@ jobs 子命令：
                                 : recordUserDecision(projectRoot, change, inputFile);
                         }
                         catch (err) {
-                            if (err instanceof StdinRecordInputError) {
+                            if (err instanceof StdinRecordInputError || err instanceof RecordInputDecodingError) {
                                 console.error(err.message);
                                 return 1;
                             }
@@ -817,7 +818,7 @@ jobs 子命令：
                                 : recordTestRun(projectRoot, change, inputFile);
                         }
                         catch (err) {
-                            if (err instanceof StdinRecordInputError) {
+                            if (err instanceof StdinRecordInputError || err instanceof RecordInputDecodingError) {
                                 console.error(err.message);
                                 return 1;
                             }

package/dist/record.js

@@ -1,5 +1,5 @@
 // SuperSpec 流程引擎 — record：工作项结果登记
-import { readFileSync, existsSync } from "node:fs";
+import { existsSync } from "node:fs";
 import { isAbsolute, join, relative, resolve } from "node:path";
 import { ensureChangeLayout, readEvents, appendEvent, makeEvent, sha256File, sha256Text, withLock, appendRawRecord, } from "./store.js";
 import { rebuildSnapshot } from "./sync.js";
@@ -10,6 +10,7 @@ import { invalidReasonForSubmittedReport } from "./job_validity.js";
 import { jobSubmitArgv } from "./job_action.js";
 import { REVIEW_DOC_PATHS } from "./review.js";
 import { EXPLORE_DISCOVERY_REVIEW_GATE, PROPOSE_FINAL_REVIEW_GATE } from "./review_job_gates.js";
+import { RecordInputDecodingError, readRecordInputFile } from "./record_input.js";
 const REVIEW_REPORT_REQUIRED_FIELDS = ["role", "verdict", "findings"];
 const REVIEW_REPORT_OPTIONAL_FIELDS = ["summary", "evidence_refs", "risks", "open_questions"];
 const REVIEWER_KINDS = new Set(["codex-subagent", "human", "external-agent"]);
@@ -17,6 +18,13 @@ const CODE_REVIEW_FINDING_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._:-]*$/;
 function requiresReviewer(role) {
     return role === "critic" || role === "architect" || role === "test-engineer" || role === "code-reviewer";
 }
+/** All review reports with bound material acknowledge full file coverage. */
+function requiresReviewScope(job) {
+    return job.boundFiles.length > 0 && job.role !== "executor" && job.role !== "test-run";
+}
+function projectLocalInvalidReportMustTerminate(job) {
+    return job.role === "code-reviewer" || job.packet_context?.code_state_check !== undefined;
+}
 function isOrdinaryReviewer(role) {
     return role === "critic" || role === "architect" || role === "test-engineer";
 }
@@ -55,8 +63,8 @@ function previousRejectionInstruction(job) {
         return "";
     const reason = `上一次同角色审查没有形成可推进结论，原因：${previous.reason}。`;
     if (!previous.findings || previous.findings.length === 0)
-        return `${reason}本次请先针对该原因重新审查，`;
-    return `${reason}本工作项附带上一次同角色审查尚未闭环的问题列表；请优先逐项复核：同一问题仍存在时复用原 finding ID；legacy finding 没有 ID 时沿用其原始语义并补一个稳定 ID；已解决的问题不要重复报告，不得通过更换 ID、标题或措辞重复同一问题；新增问题必须提供与历史问题不同的具体证据。`;
+        return `${reason}完成全部材料覆盖和角色分析后，再针对该原因复核，`;
+    return `${reason}完成全部材料覆盖和角色分析后，再逐项复核本工作项附带的上一次同角色审查尚未闭环问题：同一问题仍存在时复用原 finding ID；legacy finding 没有 ID 时沿用其原始语义并补一个稳定 ID；已解决的问题不要重复报告，不得通过更换 ID、标题或措辞重复同一问题；新增问题必须提供与历史问题不同的具体证据。`;
 }
 function ordinaryReviewerFindingInstruction(job) {
     if (!isOrdinaryReviewer(job.role))
@@ -86,6 +94,23 @@ function reviewScopeInstruction(job, reviewTargets, readOnlyRefs) {
         : "";
     return targets + refs;
 }
+function reviewCoverageInstruction(job) {
+    if (!requiresReviewScope(job))
+        return "";
+    return `审查顺序固定为：先建立覆盖索引，按文件和标题/行段完整浏览全部 boundFiles 至文件末尾；长文档必须分段读取，每段只保留短锚点和候选风险，不能在发现第一个 blocker 时提交。随后按本角色职责进行跨文件分析；最后才复核历史 findings 并去重，一次性提交当前快照下发现的全部 blocker。报告中的 review_scope.checked_paths 必须列出全部已浏览的 boundFiles；它只是覆盖回执，不能代替语义审查。`;
+}
+function migrationEvidenceInstruction(job) {
+    const isProposeReview = PROPOSE_FINAL_REVIEW_GATE.isJobForGate(job);
+    if (!isProposeReview)
+        return "";
+    return "迁移与环境证据按阶段分层：Explore 记录迁移风险、兼容约束和外部未知；Propose 只需审查迁移策略、回滚/兼容设计、任务与可执行测试计划；Apply/Review 才记录实际 datasource、制品 SHA、Flyway history、审计日志和运行证据。可因策略、计划或文档矛盾而 fail；不得只因实际环境证据尚未产生而 fail。";
+}
+function recordInputInstruction(job) {
+    const encoding = "stdin 请传 UTF-8 JSON；Windows PowerShell 请设置 $OutputEncoding 和 [Console]::OutputEncoding 为 UTF-8，文件备用方式请使用 Set-Content -Encoding utf8。为兼容旧版 PowerShell，带 BOM 的 UTF-16LE 文件也可接受。";
+    if (!projectLocalInvalidReportMustTerminate(job))
+        return encoding;
+    return `${encoding}项目内 fallback 报告若存在解码或协议错误会终结当前工作项，以免被后续代码状态检查当作改动；如需保留同一工作项重交，请使用 stdin 或工作区外临时文件。`;
+}
 function asObject(value) {
     return value && typeof value === "object" && !Array.isArray(value) ? value : null;
 }
@@ -169,6 +194,23 @@ function validateCodeReviewScope(obj, job, checks) {
         }
     }
 }
+function validateReviewScope(obj, job, checks) {
+    const scope = asObject(obj.review_scope);
+    if (!scope) {
+        checks.push("审查报告缺少覆盖范围字段 review_scope");
+        return;
+    }
+    if (!stringArray(scope.checked_paths)) {
+        checks.push("审查报告覆盖范围里的 checked_paths 必须是字符串数组");
+        return;
+    }
+    const checkedPaths = new Set(scope.checked_paths);
+    for (const bound of job.boundFiles) {
+        if (!checkedPaths.has(bound.path)) {
+            checks.push(`审查报告未说明已检查 ${bound.path}`);
+        }
+    }
+}
 function actionableCodeReviewFindings(findings) {
     if (!Array.isArray(findings))
         return { actionable: [], reasons: ["报告字段 findings 必须是数组"] };
@@ -307,6 +349,35 @@ function terminalJobSubmitResult(events, jobId, terminal, reportDigest) {
         message: `工作项 ${jobId} 已结束（${terminal}），不接受新报告。需要新工作项请重新执行对应的 transition。`,
     };
 }
+function retryableJobSubmitResult(jobId, checks) {
+    return {
+        accepted: false,
+        message: `工作项 ${jobId} 的报告未接受，可修正后以同一工作项重新提交：${checks.join("; ")}`,
+        job_state: "requested",
+        events_written: 0,
+    };
+}
+function terminalInvalidReportResult(input) {
+    const rawRef = input.job.role === "code-reviewer" && input.parsedReport
+        ? appendRawRecord(input.projectRoot, input.change, "review-reports", input.parsedReport)
+        : null;
+    appendEvent(input.projectRoot, input.change, makeEvent(input.change, "job_rejected", codeReviewRejectEventPayload({
+        jobId: input.jobId,
+        job: input.job,
+        reportDigest: input.reportDigest,
+        resultKind: "invalid_report",
+        reason: input.reason,
+        parsedReport: input.parsedReport,
+        rawRef,
+        reportPath: input.reportPath,
+    })));
+    return {
+        event_type: "job_rejected",
+        accepted: false,
+        message: `工作项 ${input.jobId} 被拒绝：${input.reason}`,
+        job_state: "rejected",
+    };
+}
 function recordJobSubmitLoaded(projectRoot, change, changeRoot, jobId, job, events, reportContent, reportDigest, reportFile) {
     const checks = [];
     let parsedReport = null;
@@ -340,6 +411,9 @@ function recordJobSubmitLoaded(projectRoot, change, changeRoot, jobId, job, even
             if (job.role === "code-reviewer") {
                 validateCodeReviewScope(parsedReport, job, checks);
             }
+            else if (requiresReviewScope(job)) {
+                validateReviewScope(parsedReport, job, checks);
+            }
         }
     }
     catch {
@@ -352,37 +426,22 @@ function recordJobSubmitLoaded(projectRoot, change, changeRoot, jobId, job, even
         events,
         reportPath,
     });
-    if (invalidReason) {
-        checks.push(invalidReason);
-    }
-    if (!reportContent.trim()) {
+    if (!reportContent.trim() && !checks.includes("报告内容为空")) {
         checks.push("报告内容为空");
     }
-    if (checks.length > 0) {
-        const resultKind = "invalid_report";
-        const rawRef = job.role === "code-reviewer" && parsedReport
-            ? appendRawRecord(projectRoot, change, "review-reports", parsedReport)
-            : null;
-        const rejectEvent = makeEvent(change, "job_rejected", {
-            ...codeReviewRejectEventPayload({
-                jobId,
-                job,
-                reportDigest,
-                resultKind,
-                reason: checks.join("; "),
-                parsedReport,
-                rawRef,
-                reportPath,
-            }),
+    if (invalidReason) {
+        return terminalInvalidReportResult({
+            projectRoot, change, jobId, job, reportDigest, reason: invalidReason, parsedReport, reportPath,
+        });
+    }
+    // Code-state-sensitive review jobs must record project-local fallback paths for later scope scans.
+    if (checks.length > 0 && projectLocalInvalidReportMustTerminate(job) && reportPath) {
+        return terminalInvalidReportResult({
+            projectRoot, change, jobId, job, reportDigest, reason: checks.join("; "), parsedReport, reportPath,
         });
-        appendEvent(projectRoot, change, rejectEvent);
-        return {
-            event_type: "job_rejected",
-            accepted: false,
-            message: `工作项 ${jobId} 被拒绝：${checks.join("; ")}`,
-            job_state: "rejected",
-        };
     }
+    if (checks.length > 0)
+        return retryableJobSubmitResult(jobId, checks);
     if (job.role !== "code-reviewer" && parsedReport?.verdict === "fail") {
         const rawRef = appendRawRecord(projectRoot, change, "review-reports", parsedReport);
         const rejectEvent = makeEvent(change, "job_rejected", failedReviewReportRejectEventPayload({
@@ -412,23 +471,12 @@ function recordJobSubmitLoaded(projectRoot, change, changeRoot, jobId, job, even
         if (verdict === "pass") {
             if (blockingCount > 0) {
                 const reason = "报告结论为 pass 时不能包含 blocking:true 的阻塞问题";
-                const rawRef = appendRawRecord(projectRoot, change, "review-reports", parsedReport);
-                appendEvent(projectRoot, change, makeEvent(change, "job_rejected", codeReviewRejectEventPayload({
-                    jobId,
-                    job,
-                    reportDigest,
-                    resultKind: "invalid_report",
-                    reason,
-                    parsedReport,
-                    rawRef,
-                    reportPath,
-                })));
-                return {
-                    event_type: "job_rejected",
-                    accepted: false,
-                    message: `工作项 ${jobId} 被拒绝：${reason}`,
-                    job_state: "rejected",
-                };
+                if (projectLocalInvalidReportMustTerminate(job) && reportPath) {
+                    return terminalInvalidReportResult({
+                        projectRoot, change, jobId, job, reportDigest, reason, parsedReport, reportPath,
+                    });
+                }
+                return retryableJobSubmitResult(jobId, [reason]);
             }
         }
         else if (verdict === "fail") {
@@ -490,10 +538,25 @@ export function recordJobSubmit(projectRoot, change, changeRoot, jobId, reportFi
             return terminalJobSubmitResult(events, jobId, terminal, reportDigest);
         }
         if (!existsSync(reportFile)) {
-            return { event_type: "job_rejected", accepted: false, message: `报告文件不存在：${reportFile}` };
+            return retryableJobSubmitResult(jobId, [`报告文件不存在：${reportFile}`]);
         }
-        const reportContent = readFileSync(reportFile, "utf8");
         const reportDigest = sha256File(reportFile) ?? "sha256:unknown";
+        let reportContent;
+        try {
+            reportContent = readRecordInputFile(reportFile);
+        }
+        catch (err) {
+            if (err instanceof RecordInputDecodingError) {
+                const reportPath = projectRelativePath(projectRoot, reportFile);
+                if (projectLocalInvalidReportMustTerminate(job) && reportPath) {
+                    return terminalInvalidReportResult({
+                        projectRoot, change, jobId, job, reportDigest, reason: err.message, parsedReport: null, reportPath,
+                    });
+                }
+                return retryableJobSubmitResult(jobId, [err.message]);
+            }
+            throw err;
+        }
         return recordJobSubmitLoaded(projectRoot, change, changeRoot, jobId, job, events, reportContent, reportDigest, reportFile);
     });
 }
@@ -688,7 +751,16 @@ export function recordUserDecision(projectRoot, change, inputFile) {
             appendEvent(projectRoot, change, makeEvent(change, "user_decision_recorded", { accepted: false, reason: "file_not_found", path: inputFile }));
             return { event_type: "user_decision_recorded", accepted: false, message: `决策文件不存在：${inputFile}` };
         }
-        const content = readFileSync(inputFile, "utf8");
+        let content;
+        try {
+            content = readRecordInputFile(inputFile);
+        }
+        catch (err) {
+            if (err instanceof RecordInputDecodingError) {
+                return { accepted: false, message: err.message, events_written: 0 };
+            }
+            throw err;
+        }
         const inputDigest = sha256File(inputFile) ?? "sha256:unknown";
         return recordUserDecisionLoaded(projectRoot, change, events, content, inputDigest);
     });
@@ -739,8 +811,8 @@ function packetFieldDescriptions() {
     return {
         job_id: "工作项 ID，用于提交本次审查或验证报告。",
         packet_digest: "工作项说明摘要，用于证明报告对应的是当前这份工作项说明。",
-        boundFiles: "本工作项绑定的文件清单；代码审查报告必须说明这些文件是否都看过。",
-        review_scope: "报告中的审查覆盖范围，说明看了哪些文件、哪些没看及原因。",
+        boundFiles: "本工作项绑定的文件清单；审查报告必须说明这些文件是否都看过。",
+        review_scope: "报告中的审查覆盖范围；普通 reviewer/verifier 用 checked_paths 回执全部绑定文件，code-reviewer 还需按专用协议说明未检查项。",
         code_review_scope: "代码审查范围：从已审基点到当前 HEAD 的提交改动、工作区改动和未跟踪代码文件。",
         task_execution_index: "按任务汇总的执行证据：每个任务（task）的执行依据、声明测试、测试证据和改动文件。",
         contract: "任务启动时的执行依据快照：tests/design/source/reason/guard 分别对应 测试/设计/来源/原因/边界；null 表示历史任务没有执行依据。",
@@ -768,6 +840,7 @@ export function jobsPacket(projectRoot, change, jobId) {
         return { found: false, message: `工作项 ${jobId} 不存在` };
     }
     const isCodeReviewer = job.role === "code-reviewer";
+    const hasReviewScope = requiresReviewScope(job);
     const packetContext = job.packet_context;
     const { reviewTargets, readOnlyRefs } = reviewScopeForJob(job);
     return {
@@ -797,16 +870,22 @@ export function jobsPacket(projectRoot, change, jobId) {
             file_fallback: true,
             output_contract_fields: isCodeReviewer
                 ? [...REVIEW_REPORT_REQUIRED_FIELDS, "reviewer", "review_scope"]
-                : requiresReviewer(job.role) ? [...REVIEW_REPORT_REQUIRED_FIELDS, "reviewer"] : [...REVIEW_REPORT_REQUIRED_FIELDS],
+                : [
+                    ...REVIEW_REPORT_REQUIRED_FIELDS,
+                    ...(requiresReviewer(job.role) ? ["reviewer"] : []),
+                    ...(hasReviewScope ? ["review_scope"] : []),
+                ],
             output_contract_optional_fields: [...REVIEW_REPORT_OPTIONAL_FIELDS],
             字段说明: packetFieldDescriptions(),
             output_instructions: `${roleDescription(job.role)}。` +
                 reviewScopeInstruction(job, reviewTargets, readOnlyRefs) +
+                migrationEvidenceInstruction(job) +
                 (job.review_evidence_digest ? `本工作项对应的执行证据版本为 ${job.review_evidence_digest}，` : "") +
+                reviewCoverageInstruction(job) +
                 previousRejectionInstruction(job) +
                 (requiresReviewer(job.role) ? `必须由独立 ${recommendedAgentForRole(job.role)} 审查角色执行，并在审查者来源字段（reviewer.kind/id）中记录来源，` : "") +
                 ordinaryReviewerFindingInstruction(job) +
-                `产出 JSON 报告内容并优先通过 --report - 从 stdin 登记；文件路径模式仅作备用。协议字段含义见 packet 顶层“字段说明”，普通对话不要原样复述 JSON。` +
+                `产出 JSON 报告内容并优先通过 --report - 从 stdin 登记；文件路径模式仅作备用。${recordInputInstruction(job)}协议字段含义见 packet 顶层“字段说明”，普通对话不要原样复述 JSON。` +
                 (isCodeReviewer
                     ? `最小格式：{"role":"code-reviewer","verdict":"pass|fail","review_scope":{"job_id":"${job.job_id}","packet_digest":"${job.packet_digest}","checked_paths":${JSON.stringify(job.boundFiles.map(f => f.path))},"checked_docs":${JSON.stringify(REVIEW_DOC_PATHS)},"unchecked":[]},"findings":[],"reviewer":{"kind":"codex-subagent","id":"<thread-or-agent-id>"}}；审查覆盖范围（review_scope）用来说明本次审查覆盖了哪些文件和文档，已检查路径（checked_paths）与未检查项（unchecked）必须合起来覆盖全部绑定文件（boundFiles），unchecked 条目格式为 {"path":"<path>","reason":"<reason>"}。`
                         + `报告结论为 fail 时，问题列表（findings）至少包含一个可处理、可追溯的阻塞问题，字段为 {"id":"<stable-id>","blocking":true,"type":"implementation|spec|mixed","description":"<what>","evidence":"<why>","source_refs":["<path:line>"],"impact":"<impact>","suggested_action":"apply|propose"}。问题类型（type）中 implementation 表示纯代码实现问题，spec 表示方案/需求文档问题，mixed 表示需要使用者判断的混合问题。`
@@ -814,13 +893,13 @@ export function jobsPacket(projectRoot, change, jobId) {
                             ? `本工作项带任务执行索引（task_execution_index）：按 task 对照其执行依据快照（contract）审查——实现路线对照 design 引用原文、累计 diff 对照 guard 边界、测试断言对照 tests 声明的 scenario；每项的 scope_note 是执行者登记的范围扩大说明，判断其合理性与验证充分性；changed_paths 是归属线索不是结论（null 表示未知）；unattributed_paths 中的无主改动逐个判断合理性；coverage_exemption_refs 解释未绑定 task 的 TEST 豁免。`
                             : "")
                     : job.role === "verifier"
-                        ? `最小格式：{"role":"verifier","verdict":"pass|fail","findings":[]}。核对代码审查记录（code_review_gate）：passed 必须能追溯到已接受的代码审查工作项，skipped 必须能证明本次没有代码类改动。核对代码审查问题闭环：实现修复任务必须带审查修复引用（review_fix_of:<job_id>#<problem_id>），方案/混合问题必须有用户决策或后续修复证据。核对 RED/GREEN：证据须在同一已完成任务的任务尝试 ID（task_completed.attempt_id）下闭环——普通 TDD 任务至少一个同 TEST 先 RED（expected_failure）后 GREEN（expected_success）配对且每个声明 TEST 都有 GREEN；特征化任务（no_tdd_reason:characterization）可用 characterization_pass 作为通过证据，不要求 RED；测试运行证据应包含测试 ID（test_id）、命令（command）、工作目录（cwd）、退出码（exit_code）、语义状态（semantic_status）；审查修复的回归测试运行可用回归覆盖任务列表（covers_task_ids）说明覆盖了哪些已完成任务；缺少任务尝试 ID（attempt_id）的旧证据只能弱引用。` +
+                        ? `最小格式：{"role":"verifier","verdict":"pass|fail","findings":[]${hasReviewScope ? `,"review_scope":{"checked_paths":${JSON.stringify(job.boundFiles.map(file => file.path))}}` : ""}}。核对代码审查记录（code_review_gate）：passed 必须能追溯到已接受的代码审查工作项，skipped 必须能证明本次没有代码类改动。核对代码审查问题闭环：实现修复任务必须带审查修复引用（review_fix_of:<job_id>#<problem_id>），方案/混合问题必须有用户决策或后续修复证据。核对 RED/GREEN：证据须在同一已完成任务的任务尝试 ID（task_completed.attempt_id）下闭环——普通 TDD 任务至少一个同 TEST 先 RED（expected_failure）后 GREEN（expected_success）配对且每个声明 TEST 都有 GREEN；特征化任务（no_tdd_reason:characterization）可用 characterization_pass 作为通过证据，不要求 RED；测试运行证据应包含测试 ID（test_id）、命令（command）、工作目录（cwd）、退出码（exit_code）、语义状态（semantic_status）；审查修复的回归测试运行可用回归覆盖任务列表（covers_task_ids）说明覆盖了哪些已完成任务；缺少任务尝试 ID（attempt_id）的旧证据只能弱引用。` +
                             (packetContext?.code_state_check
                                 ? `本工作项带代码状态检查（code_state_check）：head_matches 为 false 或 changed_paths 非空表示代码审查后代码又发生变化，须在报告中列出差异并交主流程与用户裁决，不自行判定无害，也不据此自动否定已接受的代码审查。`
                                 : "")
                         : requiresReviewer(job.role)
-                            ? `最小格式：{"role":"${job.role}","verdict":"pass|fail","findings":[],"reviewer":{"kind":"codex-subagent","id":"<thread-or-agent-id>"}}`
-                            : `最小格式：{"role":"${job.role}","verdict":"pass|fail","findings":[]}`),
+                            ? `最小格式：{"role":"${job.role}","verdict":"pass|fail","findings":[]${hasReviewScope ? `,"review_scope":{"checked_paths":${JSON.stringify(job.boundFiles.map(file => file.path))}}` : ""},"reviewer":{"kind":"codex-subagent","id":"<thread-or-agent-id>"}}`
+                            : `最小格式：{"role":"${job.role}","verdict":"pass|fail","findings":[]${hasReviewScope ? `,"review_scope":{"checked_paths":${JSON.stringify(job.boundFiles.map(file => file.path))}}` : ""}}`),
             stop_conditions: ["审查完成后提交报告，不要修改文档"],
             created_from_transition: job.created_from_transition,
         },

package/dist/record_input.d.ts

@@ -0,0 +1,9 @@
+/**
+ * JSON record 输入只接受 UTF-8（可带 BOM）或带 BOM 的 UTF-16LE。
+ * 不猜测系统 ANSI/GBK 等编码，避免把损坏文本静默归档为 UTF-8 JSONL。
+ */
+export declare class RecordInputDecodingError extends Error {
+    constructor(message?: string);
+}
+export declare function decodeRecordInput(bytes: Buffer): string;
+export declare function readRecordInputFile(path: string): string;

package/dist/record_input.js

@@ -0,0 +1,34 @@
+// SuperSpec 流程引擎 — record JSON 输入的无损解码
+import { readFileSync } from "node:fs";
+/**
+ * JSON record 输入只接受 UTF-8（可带 BOM）或带 BOM 的 UTF-16LE。
+ * 不猜测系统 ANSI/GBK 等编码，避免把损坏文本静默归档为 UTF-8 JSONL。
+ */
+export class RecordInputDecodingError extends Error {
+    constructor(message = "JSON 输入编码无效：仅支持 UTF-8（可带 BOM）或带 BOM 的 UTF-16LE") {
+        super(message);
+        this.name = "RecordInputDecodingError";
+    }
+}
+function decode(bytes, encoding) {
+    try {
+        return new TextDecoder(encoding, { fatal: true }).decode(bytes);
+    }
+    catch {
+        throw new RecordInputDecodingError();
+    }
+}
+export function decodeRecordInput(bytes) {
+    // UTF-8 BOM.
+    if (bytes[0] === 0xef && bytes[1] === 0xbb && bytes[2] === 0xbf) {
+        return decode(bytes.subarray(3), "utf-8");
+    }
+    // Windows PowerShell 5.1 files and redirected output commonly use this form.
+    if (bytes[0] === 0xff && bytes[1] === 0xfe) {
+        return decode(bytes.subarray(2), "utf-16le");
+    }
+    return decode(bytes, "utf-8");
+}
+export function readRecordInputFile(path) {
+    return decodeRecordInput(readFileSync(path));
+}

package/dist/task.js

@@ -3,6 +3,7 @@ import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { sha256Text, ensureChangeLayout, appendEvent, makeEvent, withLock, appendRawRecord, readEvents } from "./store.js";
 import { tasksStructureDigest as formatDigest } from "./format.js";
+import { RecordInputDecodingError, readRecordInputFile } from "./record_input.js";
 /** tasks.md 结构指纹（委托给 format.ts 统一实现） */
 export function tasksStructureDigestOf(changeRoot) {
     const p = join(changeRoot, "tasks.md");
@@ -144,7 +145,14 @@ export function recordTestRun(projectRoot, change, inputFile) {
         ensureChangeLayout(projectRoot, change);
         if (!existsSync(inputFile))
             return { accepted: false, message: `文件不存在：${inputFile}` };
-        return recordTestRunLoaded(projectRoot, change, readFileSync(inputFile, "utf8"));
+        try {
+            return recordTestRunLoaded(projectRoot, change, readRecordInputFile(inputFile));
+        }
+        catch (err) {
+            if (err instanceof RecordInputDecodingError)
+                return { accepted: false, message: err.message };
+            throw err;
+        }
     });
 }
 /** record test-run：从 JSON 内容登记测试运行记录 */

package/dist/types.d.ts

@@ -297,8 +297,10 @@ export interface TransitionResult {
     details?: Record<string, unknown>;
 }
 export interface RecordResult {
-    event_type: EventType;
+    /** Undefined means the input was rejected before an event was written and may be corrected and resubmitted. */
+    event_type?: EventType;
     accepted: boolean;
     message: string;
     job_state?: JobState;
+    events_written?: number;
 }

package/package.json

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