@peterxiaoyang/superspec 0.1.58 → 0.1.60

package/dist/cli.js

@@ -8,7 +8,7 @@ import { writeSnapshot } from "./store.js";
 import { rebuildSnapshot } from "./sync.js";
 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 { recordJobSubmit, recordJobSubmitContent, recordUserDecision, recordUserDecisionContent, jobsList, jobsPacket, jobsContract } from "./record.js";
 import { recordTestRun, recordTestRunContent } from "./task.js";
 import { RecordInputDecodingError, decodeRecordInput } from "./record_input.js";
 import { probeOpenSpec, openspecStatus, changeRoot } from "./openspec.js";
@@ -573,10 +573,20 @@ record 子命令：
   test-run --input <F|->
 
 jobs 子命令：
-  list / packet --job <J>
+  list / packet --job <J> / contract --job <J> [--skeleton]
 `;
 }
 function commandHelp(command, subcommand) {
+    if (command === "jobs" && subcommand === "contract") {
+        return `用法：superspec jobs contract --change <C> --job <J> [--skeleton]
+
+输出该工作项的报告契约（默认）或可直接填写的报告骨架（--skeleton）。
+契约与 packet 顶层的 report_skeleton 同源；审查角色应在产出报告前先取骨架，逐字段填写。
+
+示例：
+  superspec jobs contract --change <C> --job <J> --skeleton
+`;
+    }
     if (command === "record" && subcommand === "user-decision") {
         return `用法：superspec record user-decision --change <C> --input <F|->
 
@@ -590,7 +600,7 @@ function commandHelp(command, subcommand) {
     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 为准。
+提交 reviewer JSON 报告；--report - 表示从 stdin 读取。报告契约（report_schema）见 superspec jobs contract --change <C> --job <J>；packet 顶层给出预填骨架（report_skeleton）。
 需要落盘时写到 packet 的 report_file_path（.superspec/changes/<C>/jobs/<J>.report.json），不要放进 openspec/changes 计划材料目录。
 
 示例：
@@ -958,6 +968,17 @@ async function main(argv) {
                         console.log(JSON.stringify(result, null, 2));
                         return result.found ? 0 : 1;
                     }
+                    case "contract": {
+                        const jobId = opts.job;
+                        if (!jobId) {
+                            console.error("jobs contract 需要 --job");
+                            return 1;
+                        }
+                        const skeletonOnly = opts.skeleton === "true";
+                        const result = jobsContract(projectRoot, change, jobId, { skeleton: skeletonOnly });
+                        console.log(JSON.stringify(skeletonOnly && result.found ? result.report_skeleton : result, null, 2));
+                        return result.found ? 0 : 1;
+                    }
                     default:
                         console.error(`未知的 jobs 子命令：${subcommand}`);
                         return 1;

package/dist/code_review.d.ts

@@ -105,4 +105,9 @@ export declare function latestApplyDoneToReviewGate(events: Event[]): {
 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;
+/** 已接受代码审查工作项在事件流里留下的范围外未检查摘要（pass 的置信边界）。 */
+export declare function outOfScopeUncheckedForJob(events: Event[], jobId: string): {
+    path: string;
+    reason: string;
+}[];
 export {};

package/dist/code_review.js

@@ -867,6 +867,9 @@ export function latestCodeReviewGateEvidence(events) {
             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 } : {}),
+            ...(Array.isArray(gate.out_of_scope_unchecked) && gate.out_of_scope_unchecked.length > 0
+                ? { out_of_scope_unchecked: gate.out_of_scope_unchecked }
+                : {}),
             event_id: event.event_id,
             event_digest: event.event_digest,
         };
@@ -969,3 +972,21 @@ export function computeCodeStateCheck(projectRoot, events, ignoredCodePaths = []
         scope_reason: scopeReason,
     };
 }
+/** 已接受代码审查工作项在事件流里留下的范围外未检查摘要（pass 的置信边界）。 */
+export function outOfScopeUncheckedForJob(events, jobId) {
+    for (let i = events.length - 1; i >= 0; i--) {
+        const event = events[i];
+        if (event.event_type !== "job_accepted")
+            continue;
+        const payload = event.payload;
+        if (payload.job_id !== jobId)
+            continue;
+        if (!Array.isArray(payload.out_of_scope_unchecked))
+            return [];
+        return payload.out_of_scope_unchecked.filter((item) => {
+            const candidate = item;
+            return typeof candidate?.path === "string" && typeof candidate?.reason === "string";
+        });
+    }
+    return [];
+}

package/dist/record.d.ts

@@ -1,4 +1,5 @@
-import type { RecordResult, Job, JobPacket } from "./types.ts";
+import type { RecordResult, Job, JobPacket, JobRole } from "./types.ts";
+import { type ReportSchemaContract } from "./report_contract.ts";
 /** 报告文件的推荐落盘位置：工作流记录目录，不进入计划材料。 */
 export declare function jobReportFilePath(change: string, jobId: string): string;
 /** record job-submit：登记工作项结果 */
@@ -24,3 +25,22 @@ export declare function jobsPacket(projectRoot: string, change: string, jobId: s
     packet?: JobPacket;
     message: string;
 };
+/**
+ * jobs contract：单独取报告契约（默认）或可填骨架（--skeleton）。
+ *
+ * 与 packet 顶层的 report_skeleton 同源，供审查角色在产出报告前自查结构，
+ * 不必从 packet 的长段落里提取。
+ */
+export declare function jobsContract(projectRoot: string, change: string, jobId: string, opts?: {
+    skeleton?: boolean;
+}): {
+    found: boolean;
+    job_id?: string;
+    role?: JobRole;
+    report_schema?: ReportSchemaContract;
+    report_skeleton?: Record<string, unknown>;
+    fill_items?: string[];
+    contract_command?: string;
+    skeleton_command?: string;
+    message: string;
+};

package/dist/record.js

@@ -15,20 +15,8 @@ import { RecordInputDecodingError, readRecordInputFile } from "./record_input.js
 import { currentExploreRoundId } from "./explore_round.js";
 import { currentProposeOpenQuestion, currentProposeQuestionContent, currentProposeRoundId, } from "./propose_round.js";
 import { discoveryOpenQuestionDisplayText, discoveryQuestionContextFingerprint, discoveryQuestionDecisionBasisDigest, discoveryOpenQuestionScope, legacyDiscoveryOpenQuestionScope, EXPLORE_OPEN_QUESTION_SCOPE_PREFIX, parseDiscoveryOpenQuestions, proposeOpenQuestionDisplayText, proposeOpenQuestionScope, proposeQuestionContextFingerprint, proposeQuestionDecisionBasisDigest, legacyProposeOpenQuestionScope, PROPOSE_OPEN_QUESTION_SCOPE_PREFIX, } from "./format.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(["subagent", "codex-subagent", "human", "external-agent"]);
+import { COVERAGE_MESSAGES, REVIEWER_KINDS, outOfScopeUncheckedFromReport, REVIEW_REPORT_OPTIONAL_FIELDS, REVIEW_REPORT_REQUIRED_FIELDS, isReviewRole, requiresReviewer, requiresReviewScope, reportSchemaForJob, reportSkeletonFillItems, reportSkeletonForJob, } from "./report_contract.js";
 const CODE_REVIEW_FINDING_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._:-]*$/;
-function isReviewRole(role) {
-    return role === "critic" || role === "architect" || role === "test-engineer" || role === "code-reviewer" || role === "verifier";
-}
-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 && isReviewRole(job.role);
-}
 function projectLocalInvalidReportMustTerminate(job) {
     return job.role === "code-reviewer" || job.packet_context?.code_state_check !== undefined;
 }
@@ -256,7 +244,7 @@ function uncheckedCodeReviewPaths(value, checks) {
     for (const item of value) {
         const obj = asObject(item);
         if (!obj) {
-            checks.push("代码审查覆盖范围里的未检查项必须是包含 path/reason 的对象");
+            checks.push(COVERAGE_MESSAGES.uncheckedItemNotObject);
             continue;
         }
         if (!nonEmptyString(obj.path)) {
@@ -284,8 +272,8 @@ function validateReviewer(obj, checks) {
         checks.push("报告 reviewer 必须是包含 kind/id 的对象");
     }
     else {
-        if (typeof reviewer.kind !== "string" || !REVIEWER_KINDS.has(reviewer.kind)) {
-            checks.push(`报告 reviewer.kind 必须是 ${[...REVIEWER_KINDS].join("|")} 之一`);
+        if (typeof reviewer.kind !== "string" || !REVIEWER_KINDS.includes(reviewer.kind)) {
+            checks.push(`报告 reviewer.kind 必须是 ${REVIEWER_KINDS.join("|")} 之一`);
         }
         if (typeof reviewer.id !== "string" || reviewer.id.trim() === "") {
             checks.push("报告 reviewer.id 必须是非空字符串");
@@ -295,7 +283,7 @@ function validateReviewer(obj, checks) {
 function validateCodeReviewScope(obj, job, checks) {
     const scope = asObject(obj.review_scope);
     if (!scope) {
-        checks.push("代码审查报告缺少覆盖范围字段 review_scope");
+        checks.push(COVERAGE_MESSAGES.codeReviewScopeMissing);
         return;
     }
     if (scope.job_id !== job.job_id) {
@@ -305,11 +293,11 @@ function validateCodeReviewScope(obj, job, checks) {
         checks.push("代码审查覆盖范围里的 packet_digest 与工作项不匹配，请使用当前工作项说明重新生成报告");
     }
     if (!stringArray(scope.checked_paths))
-        checks.push("代码审查覆盖范围里的 checked_paths 必须是字符串数组");
+        checks.push(COVERAGE_MESSAGES.checkedPathsNotStringArray);
     if (!stringArray(scope.checked_docs))
-        checks.push("代码审查覆盖范围里的 checked_docs 必须是字符串数组");
+        checks.push(COVERAGE_MESSAGES.checkedDocsNotStringArray);
     if (!Array.isArray(scope.unchecked))
-        checks.push("代码审查覆盖范围里的 unchecked 必须是数组");
+        checks.push(COVERAGE_MESSAGES.uncheckedNotArray);
     if (stringArray(scope.checked_paths) && Array.isArray(scope.unchecked)) {
         const checkedPaths = new Set(scope.checked_paths);
         const uncheckedPaths = uncheckedCodeReviewPaths(scope.unchecked, checks);
@@ -318,19 +306,21 @@ function validateCodeReviewScope(obj, job, checks) {
                 checks.push(`代码审查报告未说明是否检查了 ${bound.path}`);
             }
         }
-        if (obj.verdict === "pass" && uncheckedPaths.size > 0) {
-            checks.push("代码审查结论为 pass 时不能包含未检查的绑定文件");
+        // 只有绑定文件被列为未检查时才阻塞 pass：范围外观察（未跑构建、无关文件）写进
+        // unchecked 是诚实记录，不应让 pass 结论无法提交。
+        if (obj.verdict === "pass" && job.boundFiles.some(bound => uncheckedPaths.has(bound.path))) {
+            checks.push(COVERAGE_MESSAGES.passWithUncheckedBoundFile);
         }
     }
 }
 function validateReviewScope(obj, job, checks) {
     const scope = asObject(obj.review_scope);
     if (!scope) {
-        checks.push("审查报告缺少覆盖范围字段 review_scope");
+        checks.push(COVERAGE_MESSAGES.reviewScopeMissing);
         return;
     }
     if (!stringArray(scope.checked_paths)) {
-        checks.push("审查报告覆盖范围里的 checked_paths 必须是字符串数组");
+        checks.push(COVERAGE_MESSAGES.reviewCheckedPathsNotStringArray);
         return;
     }
     const checkedPaths = new Set(scope.checked_paths);
@@ -667,11 +657,15 @@ function recordJobSubmitLoaded(projectRoot, change, changeRoot, jobId, job, even
         }
     }
     const rawRef = appendRawRecord(projectRoot, change, "review-reports", parsedReport);
+    // pass 结论下的范围外未检查项不进门禁，但必须留在决策面：只翻 raw 才能看到
+    // 会让「pass 但未跑构建 / 未覆盖范围外文件」这一事实在流程里消失。
+    const outOfScopeUnchecked = job.role === "code-reviewer" ? outOfScopeUncheckedFromReport(parsedReport, job.boundFiles) : [];
     const acceptEvent = makeEvent(change, "job_accepted", {
         job_id: jobId,
         role: job.role,
         report_digest: reportDigest,
         accepted_at: new Date().toISOString(),
+        ...(outOfScopeUnchecked.length > 0 ? { out_of_scope_unchecked: outOfScopeUnchecked } : {}),
         ...(reportPath ? { report_path: reportPath } : {}),
         ...rawRef,
     });
@@ -1199,6 +1193,8 @@ function packetFieldDescriptions() {
         unknown_attribution_tasks: "因为缺少边界快照或提交段 diff 失败而无法完整计算改动归属的任务（task）。",
         coverage_exemption_refs: "测试覆盖豁免引用：说明某个 TEST 为什么没有绑定到任务（task）。",
         report_file_path: "报告需要落盘时的文件位置（项目相对路径），位于工作流记录目录；报告内容登记后由引擎存入 raw 记录，不属于计划材料。",
+        report_skeleton: "按本工作项预填的报告骨架（job_id / packet_digest / 空数组）；逐字段填写即可，不要自行设计结构。",
+        report_schema: "报告契约（字段形状、取值、条件、提示消息）；由 `superspec jobs contract --change <C> --job <J>` 输出，提交校验引用同一份定义。",
         code_review_gate: "最终验证读取的代码审查门禁事实：passed 指向已接受的代码审查工作项，skipped 表示本轮没有代码类改动。",
         code_state_check: "代码状态检查：最终验证时用于判断代码审查后代码是否又发生变化。",
         event_id: "事件 ID，用于追溯证据来源。",
@@ -1260,8 +1256,9 @@ export function jobsPacket(projectRoot, change, jobId) {
                     ...(hasReviewScope ? ["review_scope"] : []),
                 ],
             output_contract_optional_fields: [...REVIEW_REPORT_OPTIONAL_FIELDS],
+            report_skeleton: reportSkeletonForJob(job),
             字段说明: packetFieldDescriptions(),
-            output_instructions: `${roleDescription(job.role)}。` +
+            output_instructions: `${roleDescription(job.role)}。本工作项的报告结构以 packet 顶层 report_skeleton 为准（完整契约：superspec jobs contract --change "${change}" --job "${job.job_id}"）：按骨架逐字段填写，job_id / packet_digest 已按本工作项预填，不要改写，也不要用上一轮报告里的值。` +
                 (isReviewer ? reviewScopeInstruction(job, reviewTargets, readOnlyRefs) : "") +
                 (isReviewer ? migrationEvidenceInstruction(job) : "") +
                 (job.review_evidence_digest ? `本工作项对应的执行证据版本为 ${job.review_evidence_digest}，` : "") +
@@ -1269,19 +1266,19 @@ export function jobsPacket(projectRoot, change, jobId) {
                 (requiresReviewer(job.role) ? `必须由独立 ${recommendedAgentForRole(job.role)} 审查角色执行，并在审查者来源字段（reviewer.kind/id）中记录来源，` : "") +
                 `产出 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 不允许仍有未检查的绑定文件。`
+                    ? `格式骨架：${JSON.stringify(reportSkeletonForJob(job))}。提交前按真实审查结果填写数组；不得从 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 中的新建代码文件，均需判断是否服务已批准行为：放行其中任何计划外文件，都必须写明它服务于哪条已批准锚点、为何无法避免，说不出依据的按 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）的旧证据只能弱引用。` +
+                        ? `最小格式：${JSON.stringify(reportSkeletonForJob(job))}。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）的旧证据只能弱引用。` +
                             (packetContext?.code_state_check
                                 ? `本工作项带代码状态检查（code_state_check），它是创建 packet 时的快照：验证期间若代码状态已变化，不要提交该报告；主流程会通过 next 创建携带最新事实的验证工作项。`
                                 : "")
                         : isReviewer
-                            ? `最小格式：{"role":"${job.role}","verdict":"pass","findings":[]${hasReviewScope ? `,"review_scope":{"checked_paths":${JSON.stringify(job.boundFiles.map(file => file.path))}}` : ""},"reviewer":{"kind":"subagent","id":"<thread-or-agent-id>"}}。verdict 只能为 pass 或 fail。`
-                            : `最小格式：{"role":"${job.role}","verdict":"pass","findings":[]}。verdict 只能为 pass 或 fail。`),
+                            ? `最小格式：${JSON.stringify(reportSkeletonForJob(job))}。verdict 只能为 pass 或 fail。`
+                            : `最小格式：${JSON.stringify(reportSkeletonForJob(job))}。verdict 只能为 pass 或 fail。`),
             stop_conditions: isReviewer
                 ? ["完成审查后提交报告，不要修改文档"]
                 : job.role === "executor"
@@ -1292,3 +1289,28 @@ export function jobsPacket(projectRoot, change, jobId) {
         message: `工作项 ${jobId} 的执行说明`,
     };
 }
+/**
+ * jobs contract：单独取报告契约（默认）或可填骨架（--skeleton）。
+ *
+ * 与 packet 顶层的 report_skeleton 同源，供审查角色在产出报告前自查结构，
+ * 不必从 packet 的长段落里提取。
+ */
+export function jobsContract(projectRoot, change, jobId, opts = {}) {
+    const job = findJob(readEvents(projectRoot, change), jobId);
+    if (!job)
+        return { found: false, message: `工作项 ${jobId} 不存在` };
+    const base = ["superspec", "jobs", "contract", "--change", change, "--job", job.job_id];
+    return {
+        found: true,
+        job_id: job.job_id,
+        role: job.role,
+        report_schema: reportSchemaForJob(job),
+        report_skeleton: reportSkeletonForJob(job),
+        fill_items: reportSkeletonFillItems(job),
+        contract_command: base.join(" "),
+        skeleton_command: [...base, "--skeleton"].join(" "),
+        message: opts.skeleton
+            ? `工作项 ${job.job_id} 的报告骨架`
+            : `工作项 ${job.job_id} 的报告契约`,
+    };
+}

package/dist/report_contract.d.ts

@@ -0,0 +1,70 @@
+/**
+ * 报告契约单源：字段形状与取值、覆盖类提示消息、骨架渲染。
+ *
+ * 范围止于「形状」：字段名/类型/枚举/必填与否 + 跨字段条件 + 可直接填写的骨架。
+ * 面向模型的说明文字仍由 packet 的 output_instructions 承载，判据仍由 record.ts 的
+ * 校验函数执行（交叉规则与跨文件解析不声明化）。这样契约表不是第二份散文，
+ * 也不与校验器争谁说了算。
+ *
+ * packet 的 report_skeleton、`superspec jobs contract` 与提交校验共用这里的定义。
+ */
+import type { Job, JobRole } from "./types.ts";
+export declare const REVIEW_REPORT_REQUIRED_FIELDS: readonly ["role", "verdict", "findings"];
+export declare const REVIEW_REPORT_OPTIONAL_FIELDS: readonly ["summary", "evidence_refs", "risks", "open_questions"];
+/** reviewer.kind 允许取值：契约、packet 与提交校验共用。 */
+export declare const REVIEWER_KINDS: readonly ["subagent", "codex-subagent", "human", "external-agent"];
+/** 审查/验证类角色：报告需要 review_scope 覆盖回执。 */
+export declare function isReviewRole(role: JobRole): boolean;
+/** 需要 reviewer.kind/id 的角色。 */
+export declare function requiresReviewer(role: JobRole): boolean;
+/** 需要 review_scope 覆盖回执的工作项。 */
+export declare function requiresReviewScope(job: Job): boolean;
+/** 提交校验与契约共用的覆盖类提示消息：改这里即同时影响两侧。 */
+export declare const COVERAGE_MESSAGES: {
+    readonly codeReviewScopeMissing: "代码审查报告缺少覆盖范围字段 review_scope";
+    readonly reviewScopeMissing: "审查报告缺少覆盖范围字段 review_scope";
+    readonly checkedPathsNotStringArray: "代码审查覆盖范围里的 checked_paths 必须是字符串数组";
+    readonly reviewCheckedPathsNotStringArray: "审查报告覆盖范围里的 checked_paths 必须是字符串数组";
+    readonly checkedDocsNotStringArray: "代码审查覆盖范围里的 checked_docs 必须是字符串数组";
+    readonly uncheckedNotArray: "代码审查覆盖范围里的 unchecked 必须是数组";
+    readonly uncheckedItemNotObject: "代码审查覆盖范围里的未检查项必须是包含 path/reason 的对象";
+    readonly passWithUncheckedBoundFile: "代码审查结论为 pass 时不能包含未检查的绑定文件";
+};
+export interface ReportFieldContract {
+    type: "string" | "array" | "object";
+    required?: boolean;
+    values?: readonly string[];
+    pattern?: string;
+    item?: string;
+}
+export interface ReportSchemaContract {
+    role: JobRole;
+    required_fields: string[];
+    optional_fields: string[];
+    /** 顶层字段与 review_scope / findings 子字段的形状，键用点路径表示。 */
+    fields: Record<string, ReportFieldContract>;
+    /** 跨字段条件；校验器拒绝时的措辞与此保持一致。 */
+    conditions: string[];
+}
+/**
+ * 工作项报告契约：只描述形状与取值。模型需要的解释性文字见 packet 的
+ * `output_instructions` 与 `字段说明`；判据由 record.ts 执行。
+ */
+export declare function reportSchemaForJob(job: Job): ReportSchemaContract;
+/**
+ * 可直接填写的报告骨架。
+ *
+ * 只预填工作项常量（job_id / packet_digest）与空数组：code-reviewer 的 checked_paths
+ * 必须由审查者按实际浏览填写，预填会架空覆盖回执的意义。
+ * 普通 reviewer / verifier 的 checked_paths 仍按既有协议预填全部绑定文件。
+ */
+export declare function reportSkeletonForJob(job: Job): Record<string, unknown>;
+/** 骨架中必须由审查者替换的空值，供 packet 与 CLI 给出同一份填写提示。 */
+export declare function reportSkeletonFillItems(job: Job): string[];
+/** 报告里声明"未检查"且不属于绑定文件的条目（pass 的置信边界，供事件流与门禁透出）。 */
+export declare function outOfScopeUncheckedFromReport(report: Record<string, unknown> | null, boundFiles: {
+    path: string;
+}[]): {
+    path: string;
+    reason: string;
+}[];

package/dist/report_contract.js

@@ -0,0 +1,161 @@
+export const REVIEW_REPORT_REQUIRED_FIELDS = ["role", "verdict", "findings"];
+export const REVIEW_REPORT_OPTIONAL_FIELDS = ["summary", "evidence_refs", "risks", "open_questions"];
+/** reviewer.kind 允许取值：契约、packet 与提交校验共用。 */
+export const REVIEWER_KINDS = ["subagent", "codex-subagent", "human", "external-agent"];
+/** 需要 reviewer 来源字段的角色。 */
+const REVIEWER_ROLE = {
+    critic: true,
+    architect: true,
+    "test-engineer": true,
+    "code-reviewer": true,
+};
+/** 需要 review_scope 覆盖回执的角色。 */
+const REVIEW_SCOPE_ROLE = {
+    ...REVIEWER_ROLE,
+    verifier: true,
+};
+/** 审查/验证类角色：报告需要 review_scope 覆盖回执。 */
+export function isReviewRole(role) {
+    return REVIEW_SCOPE_ROLE[role] === true;
+}
+/** 需要 reviewer.kind/id 的角色。 */
+export function requiresReviewer(role) {
+    return REVIEWER_ROLE[role] === true;
+}
+/** 需要 review_scope 覆盖回执的工作项。 */
+export function requiresReviewScope(job) {
+    return job.boundFiles.length > 0 && isReviewRole(job.role);
+}
+/** 提交校验与契约共用的覆盖类提示消息：改这里即同时影响两侧。 */
+export const COVERAGE_MESSAGES = {
+    codeReviewScopeMissing: "代码审查报告缺少覆盖范围字段 review_scope",
+    reviewScopeMissing: "审查报告缺少覆盖范围字段 review_scope",
+    checkedPathsNotStringArray: "代码审查覆盖范围里的 checked_paths 必须是字符串数组",
+    reviewCheckedPathsNotStringArray: "审查报告覆盖范围里的 checked_paths 必须是字符串数组",
+    checkedDocsNotStringArray: "代码审查覆盖范围里的 checked_docs 必须是字符串数组",
+    uncheckedNotArray: "代码审查覆盖范围里的 unchecked 必须是数组",
+    uncheckedItemNotObject: "代码审查覆盖范围里的未检查项必须是包含 path/reason 的对象",
+    passWithUncheckedBoundFile: "代码审查结论为 pass 时不能包含未检查的绑定文件",
+};
+const FINDING_TYPES = ["implementation", "spec", "mixed"];
+const CLAIM_KINDS = ["missing_approved", "breaks_existing", "unjustified_addition"];
+const SUGGESTED_ACTIONS = ["apply", "propose"];
+/**
+ * 工作项报告契约：只描述形状与取值。模型需要的解释性文字见 packet 的
+ * `output_instructions` 与 `字段说明`；判据由 record.ts 执行。
+ */
+export function reportSchemaForJob(job) {
+    const isCodeReviewer = job.role === "code-reviewer";
+    const hasScope = requiresReviewScope(job);
+    const fields = {
+        role: { type: "string", required: true, values: [job.role] },
+        verdict: { type: "string", required: true, values: ["pass", "fail"] },
+        findings: { type: "array", required: true },
+        summary: { type: "string" },
+        evidence_refs: { type: "array" },
+        risks: { type: "array" },
+        open_questions: { type: "array" },
+    };
+    const conditions = ["verdict 只能是 pass 或 fail。"];
+    if (requiresReviewer(job.role)) {
+        fields.reviewer = { type: "object", required: true };
+        fields["reviewer.kind"] = { type: "string", required: true, values: REVIEWER_KINDS };
+        fields["reviewer.id"] = { type: "string", required: true };
+    }
+    if (isCodeReviewer) {
+        fields.review_scope = { type: "object", required: true };
+        fields["review_scope.job_id"] = { type: "string", required: true, values: [job.job_id] };
+        fields["review_scope.packet_digest"] = { type: "string", required: true, values: [job.packet_digest] };
+        fields["review_scope.checked_paths"] = { type: "array", required: true, item: "path" };
+        fields["review_scope.checked_docs"] = { type: "array", required: true, item: "path" };
+        fields["review_scope.unchecked"] = { type: "array", required: true, item: "{path, reason}" };
+        fields["findings[blocking=true].id"] = { type: "string", required: true, pattern: "^[A-Za-z0-9][A-Za-z0-9._:-]*$" };
+        fields["findings[blocking=true].type"] = { type: "string", required: true, values: FINDING_TYPES };
+        fields["findings[blocking=true].claim_kind"] = { type: "string", required: true, values: CLAIM_KINDS };
+        fields["findings[blocking=true].suggested_action"] = { type: "string", required: true, values: SUGGESTED_ACTIONS };
+        fields["findings[blocking=true].source_refs"] = { type: "array", required: true, item: "path:line" };
+        fields["findings[blocking=true].approved_refs"] = { type: "array", item: "已批准锚点" };
+        for (const field of ["description", "evidence", "impact"]) {
+            fields[`findings[blocking=true].${field}`] = { type: "string", required: true };
+        }
+        conditions.push("verdict=pass 时不得存在 blocking:true 的问题。", "verdict=pass 时 unchecked 中不得包含绑定文件；范围外观察写 unchecked 或 risks 都不会导致拒收。", "checked_paths 与 unchecked[].path 合起来必须覆盖全部绑定文件。", "verdict=fail 时必须给出至少一个字段完整的 blocking 问题，字段缺失会被判为不可处理报告。", "claim_kind=missing_approved 且 suggested_action=apply 时，approved_refs 必须含可解析的 TEST 或 spec Requirement；缺口属于计划或验收本身时，改用 type=mixed 且 suggested_action=propose。", "提交时引擎会比对冻结范围与当前代码状态：绑定文件已变化会被判为过期报告，需等 next 重建工作项，不要补写指纹。");
+    }
+    else if (hasScope) {
+        fields.review_scope = { type: "object", required: true };
+        fields["review_scope.checked_paths"] = { type: "array", required: true, item: "path" };
+        conditions.push("checked_paths 必须覆盖全部绑定文件。");
+    }
+    if (job.role !== "code-reviewer" && job.role !== "verifier") {
+        conditions.push("verdict=fail 时 findings 至少包含一个问题。");
+    }
+    return {
+        role: job.role,
+        required_fields: isCodeReviewer
+            ? [...REVIEW_REPORT_REQUIRED_FIELDS, "reviewer", "review_scope"]
+            : [
+                ...REVIEW_REPORT_REQUIRED_FIELDS,
+                ...(requiresReviewer(job.role) ? ["reviewer"] : []),
+                ...(hasScope ? ["review_scope"] : []),
+            ],
+        optional_fields: [...REVIEW_REPORT_OPTIONAL_FIELDS],
+        fields,
+        conditions,
+    };
+}
+/**
+ * 可直接填写的报告骨架。
+ *
+ * 只预填工作项常量（job_id / packet_digest）与空数组：code-reviewer 的 checked_paths
+ * 必须由审查者按实际浏览填写，预填会架空覆盖回执的意义。
+ * 普通 reviewer / verifier 的 checked_paths 仍按既有协议预填全部绑定文件。
+ */
+export function reportSkeletonForJob(job) {
+    const skeleton = {
+        role: job.role,
+        verdict: "pass",
+        findings: [],
+    };
+    if (requiresReviewer(job.role)) {
+        skeleton.reviewer = { kind: "subagent", id: "<agent-id>" };
+    }
+    if (job.role === "code-reviewer") {
+        skeleton.review_scope = {
+            job_id: job.job_id,
+            packet_digest: job.packet_digest,
+            checked_paths: [],
+            checked_docs: [],
+            unchecked: [],
+        };
+    }
+    else if (requiresReviewScope(job)) {
+        skeleton.review_scope = { checked_paths: job.boundFiles.map(file => file.path) };
+    }
+    return skeleton;
+}
+/** 骨架中必须由审查者替换的空值，供 packet 与 CLI 给出同一份填写提示。 */
+export function reportSkeletonFillItems(job) {
+    const items = ["verdict", "findings"];
+    if (requiresReviewer(job.role))
+        items.push("reviewer.id");
+    if (job.role === "code-reviewer") {
+        items.push("review_scope.checked_paths", "review_scope.checked_docs", "review_scope.unchecked");
+    }
+    return items;
+}
+/** 报告里声明"未检查"且不属于绑定文件的条目（pass 的置信边界，供事件流与门禁透出）。 */
+export function outOfScopeUncheckedFromReport(report, boundFiles) {
+    const scope = report?.review_scope;
+    if (!scope || !Array.isArray(scope.unchecked))
+        return [];
+    const bound = new Set(boundFiles.map(file => file.path));
+    const items = [];
+    for (const raw of scope.unchecked) {
+        const item = raw;
+        if (typeof item?.path !== "string" || typeof item?.reason !== "string")
+            continue;
+        if (bound.has(item.path))
+            continue;
+        items.push({ path: item.path, reason: item.reason });
+    }
+    return items;
+}

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, codeReviewFindingNeedsUserDecision, isReviewFixCapReached, } from "./code_review.js";
+import { codeReviewBoundFiles, codeReviewDecisionScope, codeReviewJobStaleReason, outOfScopeUncheckedForJob, 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";
@@ -552,6 +552,10 @@ function evaluateApplyDoneCodeReviewGate(input) {
                         job_id: latest.job.job_id,
                         packet_digest: latest.job.packet_digest,
                         current_head: acceptedScope.current_head,
+                        // pass 放行了范围外未检查项；把置信边界写进门禁事实，供最终验证与使用方读取。
+                        ...(outOfScopeUncheckedForJob(input.events, latest.job.job_id).length > 0
+                            ? { out_of_scope_unchecked: outOfScopeUncheckedForJob(input.events, latest.job.job_id) }
+                            : {}),
                     },
                 },
             };
@@ -1071,6 +1075,46 @@ function canReopenToPropose(from) {
     return from === "propose_ready" || from === "apply" || from === "apply_done" ||
         from === "review" || from === "accepted";
 }
+/**
+ * 普通 reopen --to propose 成功后附带一次非阻断提示：本次回退本可用 --self-test-fix 完成。
+ * 刻意不按 reason 关键词分类（主会话自由文本不可靠），也刻意不在 apply 状态提示
+ * （apply 内直接修任务即可，无需 reopen）。提示门禁与 self-test-fix 分支保持同一套：
+ * pending 为空、无活跃尝试、contract 模式需要完成事件、无未处理的代码审查问题；
+ * 条件不满足时不提示，避免建议一条必然被 skip 的命令。提示不改变任何转换结果。
+ */
+function selfTestFixAdvisory(change, changeRoot, snapshot, events, opts) {
+    if (opts.reviewFix || opts.reviewFinding || opts.selfTestFix)
+        return null;
+    if (!["apply_done", "review", "accepted"].includes(snapshot.state))
+        return null;
+    if (applyPlanningMaterialsChanged(changeRoot, events))
+        return null;
+    const status = pendingTaskStatusForApply(changeRoot, events);
+    if (status.pending.length > 0)
+        return null;
+    if (snapshot.active_task_attempts.some(attempt => attempt.state === "active"))
+        return null;
+    const tasksContent = readFileSync(join(changeRoot, "tasks.md"), "utf8");
+    let parentTaskId = null;
+    if (status.mode === "contract") {
+        parentTaskId = status.completedByEvent[0]
+            ?? parseTasksMd(tasksContent).find(task => hasHistoricalTaskCompletion(events, task.taskId))?.taskId
+            ?? null;
+    }
+    else {
+        parentTaskId = parseTasksMd(tasksContent).find(task => task.done)?.taskId ?? null;
+    }
+    if (!parentTaskId)
+        return null;
+    const failedReview = latestCodeReviewFailedStatus(events);
+    if (failedReview?.unresolved.length)
+        return null;
+    return [
+        `提示（猜测，可能不适用）：本次 reopen 已回退到 propose。若本意只是不改变已批准行为和方案，这一步本可避免——`,
+        `在 apply_done/review/accepted 状态应执行 superspec transition reopen --change "${change}" --to apply --self-test-fix "${parentTaskId}" --reason "<本次原因>"。`,
+        `当前已在 propose，请继续计划更新流程。`,
+    ].join("");
+}
 export function reopen(projectRoot, change, changeRoot, to, reason, opts = {}) {
     return commitTransition(projectRoot, change, changeRoot, {
         name: "reopen", idempotencyInputs: {
@@ -1125,6 +1169,8 @@ export function reopen(projectRoot, change, changeRoot, to, reason, opts = {}) {
             if (opts.reviewFix) {
                 if (to !== "apply")
                     return { skip: true, message: "--review-fix 只能用于回到实现阶段（reopen --to apply）" };
+                // 无需 invalidateOpenJobs：--review-fix 的引用来自已终结的代码审查问题，此时 open_jobs
+                // 通常为空；即使残留过期的工作项，也会被 apply_done 侧的新鲜度过滤与重建消化，不构成死锁。
                 if (snapshot.state !== "apply_done")
                     return { skip: true, message: `当前状态 ${snapshot.state}，不能通过代码审查修复回到实现阶段` };
                 if (applyPlanningMaterialsChanged(changeRoot, events)) {
@@ -1243,6 +1289,7 @@ export function reopen(projectRoot, change, changeRoot, to, reason, opts = {}) {
                         jobs: snapshot.open_jobs,
                     };
                 }
+                const selfTestFixAdvisoryText = selfTestFixAdvisory(change, changeRoot, snapshot, events, opts);
                 const currentBaseline = proposalDocsBaseline(changeRoot);
                 const acceptedBaseline = snapshot.state === "accepted" ? latestAcceptedProposalBaseline(events) : null;
                 // 旧版 accepted 事件的基线可能缺少后来纳入 Propose gate 的材料。保留其已冻结
@@ -1271,6 +1318,7 @@ export function reopen(projectRoot, change, changeRoot, to, reason, opts = {}) {
                         planning_validation_version: 2,
                         planning_validation_profile: planningValidationProfileForNewRound(projectRoot),
                     },
+                    ...(selfTestFixAdvisoryText ? { details: { advisory: selfTestFixAdvisoryText } } : {}),
                     extraEvents: planningReopenExtraEvents(snapshot, "propose", reason.trim()),
                 };
             }
@@ -1290,6 +1338,9 @@ export function reopen(projectRoot, change, changeRoot, to, reason, opts = {}) {
                 toState: "apply",
                 outcome: "advanced",
                 reason: `${reason.trim()}（pending tasks: ${pending.join(", ")}）`,
+                // 回到 Apply 意味着代码会被改动：仍在等待报告的审查工作项依据已失效，
+                // 在此显式作废，避免审查者继续投入后才发现报告过期。
+                extraEvents: invalidateOpenJobs(snapshot, "apply", reason.trim()),
             };
         },
     });

package/dist/types.d.ts

@@ -102,6 +102,11 @@ export interface CodeReviewGateEvidence {
     job_id: string | null;
     packet_digest: string | null;
     reason?: "no_code_changes";
+    /** pass 结论下的范围外未检查项：门禁事实的一部分，供最终验证与使用方判断置信边界。 */
+    out_of_scope_unchecked?: {
+        path: string;
+        reason: string;
+    }[];
     event_id: string;
     event_digest: string;
 }
@@ -166,6 +171,8 @@ export interface JobPacket {
     report_file_path?: string;
     output_contract_fields?: string[];
     output_contract_optional_fields?: string[];
+    /** 按本工作项预填的报告骨架；完整契约见 `superspec jobs contract`。 */
+    report_skeleton?: Record<string, unknown>;
     字段说明?: Record<string, string>;
     output_instructions?: string;
     stop_conditions: string[];

package/package.json

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

package/templates/workflow/agents/architect.toml

@@ -10,5 +10,5 @@ Task binding: load `.codex/prompts/architect.md` first, then read the current jo
 
 Boundary: read-only. Do not edit files or judge materials you have not opened. Report missing context upward instead of guessing.
 
-Output: concise Simplified Chinese. For JSON reports, follow the packet's report contract exactly. Otherwise put the conclusion first, cite file:line evidence, and write `无阻塞问题` when no blocking issue is found.
+Output: concise Simplified Chinese. For JSON reports, follow the packet's `report_skeleton` (full contract via `superspec jobs contract`) exactly. Otherwise put the conclusion first, cite file:line evidence, and write `无阻塞问题` when no blocking issue is found.
 """

package/templates/workflow/agents/code-reviewer.toml

@@ -10,5 +10,5 @@ Task binding: load `.codex/prompts/code-reviewer.md` first, then read the curren
 
 Boundary: read-only. Do not implement fixes, write evidence, mark tasks complete, decide GREEN, reopen, accept, or replace main-thread workflow decisions. Start from packet-provided materials and report missing context upward instead of guessing.
 
-Output: concise Simplified Chinese. For JSON reports, follow the packet's report contract exactly. Blocking issues must be traceable and actionable. Write `无阻塞问题` when no blocking issue is found.
+Output: concise Simplified Chinese. For JSON reports, follow the packet's `report_skeleton` (full contract via `superspec jobs contract`) exactly. Blocking issues must be traceable and actionable. Write `无阻塞问题` when no blocking issue is found.
 """

package/templates/workflow/agents/critic.toml

@@ -10,5 +10,5 @@ Task binding: load `.codex/prompts/critic.md` first, then read the current job p
 
 Boundary: read-only by default. Do not edit files, invent issues, or widen scope silently. Report missing source refs or claim gaps upward.
 
-Output: concise Simplified Chinese. For JSON reports, follow the packet's report contract exactly. Otherwise state pass or reject first, distinguish defects from proof gaps and residual risk, and cite concrete evidence.
+Output: concise Simplified Chinese. For JSON reports, follow the packet's `report_skeleton` (full contract via `superspec jobs contract`) exactly. Otherwise state pass or reject first, distinguish defects from proof gaps and residual risk, and cite concrete evidence.
 """

package/templates/workflow/agents/test-engineer.toml

@@ -10,5 +10,5 @@ Task binding: load `.codex/prompts/test-engineer.md` first, then read the curren
 
 Boundary: review jobs are read-only. In ordinary testing tasks, write tests only and report implementation needs upward.
 
-Output: concise Simplified Chinese. For JSON reports, follow the packet's report contract exactly. Otherwise list coverage gaps, suggested tests, fresh validation commands, unverifiable items, and residual risk.
+Output: concise Simplified Chinese. For JSON reports, follow the packet's `report_skeleton` (full contract via `superspec jobs contract`) exactly. Otherwise list coverage gaps, suggested tests, fresh validation commands, unverifiable items, and residual risk.
 """

package/templates/workflow/agents/test-runner.toml

@@ -8,7 +8,7 @@ Role: Test Runner. Execute exactly one SuperSpec apply test phase from the curre
 
 Task binding: load `.codex/prompts/test-runner.md` first, then read the current task instructions. Their task id, test id, phase, allowed command, expected semantic status, guard fingerprint, report policy, and stop conditions override static prompt memory.
 
-Boundary: read-only by default. Do not edit production code, OpenSpec artifacts, `.superspec/**`, task checkboxes, evidence, review reports, or archives. Run only the allowed command from current task instructions and report blockers for missing command, unsafe side effects, or incomplete raw transcript refs.
+Boundary: read-only by default. Do not edit production code, OpenSpec artifacts, `.superspec/**`, task checkboxes, evidence, review reports, or archives. Run only the allowed command from current task instructions and report blockers for missing command, unsafe side effects, or incomplete raw transcript refs. One run may back several declared TEST ids: register evidence per TEST id, and do not re-run the same command for a second registration.
 
 Output: concise Simplified Chinese test report with command, cwd, phase, task/test id, exit status, semantic status candidate, result summary, raw transcript ref, repo head, dirty-state summary, guard fingerprint, and unverified items.
 """

package/templates/workflow/agents/verifier.toml

@@ -10,5 +10,5 @@ Task binding: load `.codex/prompts/verifier.md` first, then read the current job
 
 Boundary: read-only. Check commands, test output, artifacts, evidence refs, acceptance criteria, code-reviewer closure, and whether the verifier job still matches the packet-provided evidence version. Use diffs only as evidence references when the packet requires them. Do not edit files, write evidence, mark tasks complete, or add an extra code-diff blocker outside the packet contract.
 
-Output: concise Simplified Chinese. For JSON reports, follow the packet's report contract exactly. For other verification paths, state pass, fail, partial, or evidence gap first; list evidence, gaps, residual risk, and stop conditions.
+Output: concise Simplified Chinese. For JSON reports, follow the packet's `report_skeleton` (full contract via `superspec jobs contract`) exactly. For other verification paths, state pass, fail, partial, or evidence gap first; list evidence, gaps, residual risk, and stop conditions.
 """

package/templates/workflow/agents-md/architect.md

@@ -10,4 +10,4 @@ Task binding: read the current SuperSpec job packet and task instructions first.
 
 Boundary: read-only. Do not edit files or judge materials you have not opened. Report missing context upward instead of guessing.
 
-Output: concise Simplified Chinese. For JSON reports, follow the packet's report contract exactly. Otherwise put the conclusion first, cite file:line evidence, and write `无阻塞问题` when no blocking issue is found.
+Output: concise Simplified Chinese. For JSON reports, follow the packet's `report_skeleton` (full contract via `superspec jobs contract`) exactly. Otherwise put the conclusion first, cite file:line evidence, and write `无阻塞问题` when no blocking issue is found.

package/templates/workflow/agents-md/code-reviewer.md

@@ -6,8 +6,8 @@ tools: read, grep, glob, bash
 
 Role: Code Reviewer. Check that approved behaviors landed with minimal extra semantics. Report missing approved results or unjustified additions; do not mint required work outside the approved plan.
 
-Task binding: read the current SuperSpec job packet and task instructions first. The job packet is the runtime contract; follow it over this prompt, including any previous rejection it asks you to correct.
+Task binding: read the current SuperSpec job packet and task instructions first. The job packet is the runtime contract; follow it over this prompt, including any previous rejection it asks you to correct. Report structure comes from the packet's `report_skeleton` (full contract via `superspec jobs contract`); never invent structure or reuse a previous round's report.
 
 Boundary: read-only. Do not implement fixes, write evidence, mark tasks complete, decide GREEN, reopen, accept, or replace main-thread workflow decisions. Start from packet-provided materials and report missing context upward instead of guessing.
 
-Output: concise Simplified Chinese. For JSON reports, follow the packet's report contract exactly. Blocking issues must be traceable and actionable. Write `无阻塞问题` when no blocking issue is found.
+Output: concise Simplified Chinese. For JSON reports, follow the packet's `report_skeleton` (full contract via `superspec jobs contract`) exactly. Blocking issues must be traceable and actionable. Write `无阻塞问题` when no blocking issue is found.

package/templates/workflow/agents-md/critic.md

@@ -10,4 +10,4 @@ Task binding: read the current SuperSpec job packet and task instructions first.
 
 Boundary: read-only by default. Do not edit files, invent issues, or widen scope silently. Report missing source refs or claim gaps upward. Undeclared theoretical risks are residual, not blockers.
 
-Output: concise Simplified Chinese. For JSON reports, follow the packet's report contract exactly. Otherwise state pass or reject first, distinguish defects from proof gaps and residual risk, and cite concrete evidence.
+Output: concise Simplified Chinese. For JSON reports, follow the packet's `report_skeleton` (full contract via `superspec jobs contract`) exactly. Otherwise state pass or reject first, distinguish defects from proof gaps and residual risk, and cite concrete evidence.

package/templates/workflow/agents-md/test-engineer.md

@@ -10,4 +10,4 @@ Task binding: read the current SuperSpec job packet and task instructions first.
 
 Boundary: review jobs are read-only. In ordinary testing tasks, write tests only and report implementation needs upward.
 
-Output: concise Simplified Chinese. For JSON reports, follow the packet's report contract exactly. Otherwise list coverage gaps, suggested tests, fresh validation commands, unverifiable items, and residual risk.
+Output: concise Simplified Chinese. For JSON reports, follow the packet's `report_skeleton` (full contract via `superspec jobs contract`) exactly. Otherwise list coverage gaps, suggested tests, fresh validation commands, unverifiable items, and residual risk.

package/templates/workflow/agents-md/test-runner.md

@@ -8,6 +8,6 @@ Role: Test Runner. Execute exactly one SuperSpec apply test phase from the curre
 
 Task binding: read the current SuperSpec task instructions first. Their task id, test id, phase, allowed command, expected semantic status, guard fingerprint, report policy, and stop conditions override this prompt.
 
-Boundary: read-only by default. Do not edit production code, OpenSpec artifacts, `.superspec/**`, task checkboxes, evidence, review reports, or archives. Run only the allowed command from current task instructions and report blockers for missing command, unsafe side effects, or incomplete raw transcript refs.
+Boundary: read-only by default. Do not edit production code, OpenSpec artifacts, `.superspec/**`, task checkboxes, evidence, review reports, or archives. Run only the allowed command from current task instructions and report blockers for missing command, unsafe side effects, or incomplete raw transcript refs. One run may back several declared TEST ids: register evidence per TEST id, and do not re-run the same command for a second registration.
 
 Output: concise Simplified Chinese test report with command, cwd, phase, task/test id, exit status, semantic status candidate, result summary, raw transcript ref, repo head, dirty-state summary, guard fingerprint, and unverified items.

package/templates/workflow/agents-md/verifier.md

@@ -10,4 +10,4 @@ Task binding: read the current SuperSpec job packet and task instructions first.
 
 Boundary: read-only. Check commands, test output, artifacts, evidence refs, acceptance criteria, code-reviewer closure, and whether the verifier job still matches the packet-provided evidence version. Use diffs only as evidence references when the packet requires them. Do not edit files, write evidence, mark tasks complete, or add an extra code-diff blocker outside the packet contract.
 
-Output: concise Simplified Chinese. For JSON reports, follow the packet's report contract exactly. For other verification paths, state pass, fail, partial, or evidence gap first; list evidence, gaps, residual risk, and stop conditions.
+Output: concise Simplified Chinese. For JSON reports, follow the packet's `report_skeleton` (full contract via `superspec jobs contract`) exactly. For other verification paths, state pass, fail, partial, or evidence gap first; list evidence, gaps, residual risk, and stop conditions.