@peterxiaoyang/superspec 0.1.23 → 0.1.25-beta.0

package/dist/cli.js

@@ -1,15 +1,15 @@
 #!/usr/bin/env node
 // SuperSpec 流程引擎 — CLI 入口
-import { join } from "node:path";
 import { execFileSync } from "node:child_process";
 import { createInterface } from "node:readline/promises";
+import { readFileSync } from "node:fs";
 import { installProject } from "./install.js";
 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, archive } from "./transition.js";
-import { recordJobSubmit, recordUserDecision, jobsList, jobsPacket } from "./record.js";
-import { recordTestRun } from "./task.js";
+import { recordJobSubmit, recordJobSubmitContent, recordUserDecision, recordUserDecisionContent, jobsList, jobsPacket } from "./record.js";
+import { recordTestRun, recordTestRunContent } from "./task.js";
 import { probeOpenSpec, openspecStatus, changeRoot } from "./openspec.js";
 import { SUPERSPEC_VERSION } from "./version.js";
 const PACKAGE_NAME = "@peterxiaoyang/superspec";
@@ -42,6 +42,18 @@ function parseFlags(args) {
     }
     return opts;
 }
+class StdinRecordInputError extends Error {
+    constructor(flag) {
+        super(`${flag} - 需要通过 pipe 或重定向提供 JSON；不方便时请使用文件路径。`);
+        this.name = "StdinRecordInputError";
+    }
+}
+function readStdinRecordContent(flag) {
+    if (process.stdin.isTTY === true) {
+        throw new StdinRecordInputError(flag);
+    }
+    return readFileSync(0, "utf8");
+}
 function parseVersion(version) {
     const match = version.trim().match(/^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/);
     if (!match)
@@ -342,9 +354,9 @@ transition 子命令：
   review-ready / accept / archive
 
 record 子命令：
-  job-submit --job <J> --report <F>
-  user-decision --input <F>
-  test-run --input <F>
+  job-submit --job <J> --report <F|->
+  user-decision --input <F|->
+  test-run --input <F|->
 
 jobs 子命令：
   list / packet --job <J>
@@ -555,7 +567,19 @@ jobs 子命令：
                             console.error("record job-submit 需要 --job 和 --report");
                             return 1;
                         }
-                        const result = recordJobSubmit(projectRoot, change, cr, jobId, report);
+                        let result;
+                        try {
+                            result = report === "-"
+                                ? recordJobSubmitContent(projectRoot, change, cr, jobId, readStdinRecordContent("--report"))
+                                : recordJobSubmit(projectRoot, change, cr, jobId, report);
+                        }
+                        catch (err) {
+                            if (err instanceof StdinRecordInputError) {
+                                console.error(err.message);
+                                return 1;
+                            }
+                            throw err;
+                        }
                         console.log(JSON.stringify(result, null, 2));
                         return result.accepted ? 0 : 1;
                     }
@@ -565,7 +589,19 @@ jobs 子命令：
                             console.error("record user-decision 需要 --input");
                             return 1;
                         }
-                        const result = recordUserDecision(projectRoot, change, inputFile);
+                        let result;
+                        try {
+                            result = inputFile === "-"
+                                ? recordUserDecisionContent(projectRoot, change, readStdinRecordContent("--input"))
+                                : recordUserDecision(projectRoot, change, inputFile);
+                        }
+                        catch (err) {
+                            if (err instanceof StdinRecordInputError) {
+                                console.error(err.message);
+                                return 1;
+                            }
+                            throw err;
+                        }
                         console.log(JSON.stringify(result, null, 2));
                         return result.accepted ? 0 : 1;
                     }
@@ -575,7 +611,19 @@ jobs 子命令：
                             console.error("record test-run 需要 --input");
                             return 1;
                         }
-                        const result = recordTestRun(projectRoot, change, inputFile);
+                        let result;
+                        try {
+                            result = inputFile === "-"
+                                ? recordTestRunContent(projectRoot, change, readStdinRecordContent("--input"))
+                                : recordTestRun(projectRoot, change, inputFile);
+                        }
+                        catch (err) {
+                            if (err instanceof StdinRecordInputError) {
+                                console.error(err.message);
+                                return 1;
+                            }
+                            throw err;
+                        }
                         console.log(JSON.stringify(result, null, 2));
                         return result.accepted ? 0 : 1;
                     }

package/dist/record.d.ts

@@ -1,8 +1,12 @@
 import type { RecordResult, Job } from "./types.ts";
 /** record job-submit：登记工作项结果 */
 export declare function recordJobSubmit(projectRoot: string, change: string, changeRoot: string, jobId: string, reportFile: string): RecordResult;
+/** record job-submit：从 JSON 内容登记工作项结果 */
+export declare function recordJobSubmitContent(projectRoot: string, change: string, changeRoot: string, jobId: string, reportContent: string): RecordResult;
 /** record user-decision：登记用户决策 */
 export declare function recordUserDecision(projectRoot: string, change: string, inputFile: string): RecordResult;
+/** record user-decision：从 JSON 内容登记用户决策 */
+export declare function recordUserDecisionContent(projectRoot: string, change: string, content: string): RecordResult;
 /** jobs list（HIGH-1 修复：从 transition_commit.new_jobs 提取，不再依赖已删除的 job_requested 事件） */
 export declare function jobsList(projectRoot: string, change: string): {
     open: Job[];

package/dist/record.js

@@ -1,7 +1,7 @@
 // SuperSpec 流程引擎 — record：工作项结果登记
 import { readFileSync, existsSync } from "node:fs";
 import { join } from "node:path";
-import { ensureChangeLayout, readEvents, appendEvent, makeEvent, sha256File, withLock, appendRawRecord, } from "./store.js";
+import { ensureChangeLayout, readEvents, appendEvent, makeEvent, sha256File, sha256Text, withLock, appendRawRecord, } from "./store.js";
 import { reviewEvidenceDigest, reviewVerifierStaleReason } from "./review.js";
 const REVIEW_REPORT_REQUIRED_FIELDS = ["role", "verdict", "findings"];
 const REVIEW_REPORT_OPTIONAL_FIELDS = ["summary", "evidence_refs", "risks", "open_questions"];
@@ -57,142 +57,194 @@ function jobTerminalState(events, jobId) {
     }
     return null;
 }
+function terminalJobSubmitResult(events, jobId, terminal, reportDigest) {
+    const existing = events.find(e => (e.event_type === "job_accepted" || e.event_type === "job_rejected")
+        && e.payload.job_id === jobId
+        && e.payload.report_digest === reportDigest);
+    if (existing) {
+        return {
+            event_type: existing.event_type,
+            accepted: existing.event_type === "job_accepted",
+            message: "幂等返回：同 report 已提交",
+            job_state: existing.event_type === "job_accepted" ? "accepted" : "rejected",
+        };
+    }
+    return {
+        event_type: "job_rejected",
+        accepted: false,
+        message: `工作项 ${jobId} 已终态（${terminal}），不接受新报告。需要新工作项请重跑 transition。`,
+    };
+}
+function recordJobSubmitLoaded(projectRoot, change, changeRoot, jobId, job, events, reportContent, reportDigest) {
+    const checks = [];
+    let parsedReport = null;
+    try {
+        const report = JSON.parse(reportContent);
+        if (!report || typeof report !== "object" || Array.isArray(report)) {
+            checks.push("报告必须是 JSON object");
+        }
+        else {
+            parsedReport = report;
+            const obj = parsedReport;
+            for (const field of REVIEW_REPORT_REQUIRED_FIELDS) {
+                if (!(field in obj))
+                    checks.push(`报告缺少必填字段 ${field}`);
+            }
+            if (obj.role !== job.role) {
+                checks.push(`报告角色 ${String(obj.role)} 与工作项角色 ${job.role} 不匹配`);
+            }
+            if (obj.verdict !== "pass" && obj.verdict !== "fail") {
+                checks.push("报告 verdict 必须是 pass 或 fail");
+            }
+            if (!Array.isArray(obj.findings)) {
+                checks.push("报告 findings 必须是数组");
+            }
+            if (obj.verdict === "fail") {
+                checks.push("报告 verdict=fail，工作项未通过");
+            }
+            if (requiresReviewer(job.role)) {
+                if (!("reviewer" in obj))
+                    checks.push("报告缺少必填字段 reviewer");
+                const reviewer = obj.reviewer;
+                if (!reviewer || typeof reviewer !== "object" || Array.isArray(reviewer)) {
+                    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.id !== "string" || reviewer.id.trim() === "") {
+                        checks.push("报告 reviewer.id 必须是非空字符串");
+                    }
+                }
+            }
+        }
+    }
+    catch {
+        checks.push("报告必须是有效 JSON");
+    }
+    for (const bf of job.boundFiles) {
+        const currentSha = sha256File(join(changeRoot, bf.path)) ?? "sha256:missing";
+        if (currentSha !== bf.sha) {
+            checks.push(`绑定文件 ${bf.path} 已变化（${bf.sha} → ${currentSha}）`);
+        }
+    }
+    const reviewStaleReason = reviewVerifierStaleReason(job, changeRoot, reviewEvidenceDigest(events));
+    if (reviewStaleReason && !checks.includes(reviewStaleReason)) {
+        checks.push(reviewStaleReason);
+    }
+    if (!reportContent.trim()) {
+        checks.push("报告内容为空");
+    }
+    if (checks.length > 0) {
+        const rejectEvent = makeEvent(change, "job_rejected", {
+            job_id: jobId,
+            role: job.role,
+            report_digest: reportDigest,
+            reason: checks.join("; "),
+        });
+        appendEvent(projectRoot, change, rejectEvent);
+        return {
+            event_type: "job_rejected",
+            accepted: false,
+            message: `工作项 ${jobId} 被拒绝：${checks.join("; ")}`,
+            job_state: "rejected",
+        };
+    }
+    const rawRef = appendRawRecord(projectRoot, change, "review-reports", parsedReport);
+    const acceptEvent = makeEvent(change, "job_accepted", {
+        job_id: jobId,
+        role: job.role,
+        report_digest: reportDigest,
+        accepted_at: new Date().toISOString(),
+        ...rawRef,
+    });
+    appendEvent(projectRoot, change, acceptEvent);
+    return {
+        event_type: "job_accepted",
+        accepted: true,
+        message: `工作项 ${jobId}（${job.role}）已接受`,
+        job_state: "accepted",
+    };
+}
 /** record job-submit：登记工作项结果 */
 export function recordJobSubmit(projectRoot, change, changeRoot, jobId, reportFile) {
     return withLock(projectRoot, change, () => {
         ensureChangeLayout(projectRoot, change);
         const events = readEvents(projectRoot, change);
-        // 查找 job
         const job = findJob(events, jobId);
         if (!job) {
             return { event_type: "job_rejected", accepted: false, message: `工作项 ${jobId} 不存在` };
         }
-        // 检查终态
         const terminal = jobTerminalState(events, jobId);
         if (terminal) {
-            // 幂等检查：同 report_digest → 返回旧结果
             const reportDigest = sha256File(reportFile) ?? "sha256:unknown";
-            const existing = events.find(e => (e.event_type === "job_accepted" || e.event_type === "job_rejected")
-                && e.payload.job_id === jobId
-                && e.payload.report_digest === reportDigest);
-            if (existing) {
-                return {
-                    event_type: existing.event_type,
-                    accepted: existing.event_type === "job_accepted",
-                    message: "幂等返回：同 report 已提交",
-                    job_state: existing.event_type === "job_accepted" ? "accepted" : "rejected",
-                };
-            }
-            // 终态 job + 不同 report → 拒绝
-            return {
-                event_type: "job_rejected",
-                accepted: false,
-                message: `工作项 ${jobId} 已终态（${terminal}），不接受新报告。需要新工作项请重跑 transition。`,
-            };
+            return terminalJobSubmitResult(events, jobId, terminal, reportDigest);
         }
-        // 读报告
         if (!existsSync(reportFile)) {
             return { event_type: "job_rejected", accepted: false, message: `报告文件不存在：${reportFile}` };
         }
         const reportContent = readFileSync(reportFile, "utf8");
         const reportDigest = sha256File(reportFile) ?? "sha256:unknown";
-        // acceptance checks
-        const checks = [];
-        let parsedReport = null;
-        // 0. 报告格式和角色匹配（最小 JSON contract）
-        try {
-            const report = JSON.parse(reportContent);
-            if (!report || typeof report !== "object" || Array.isArray(report)) {
-                checks.push("报告必须是 JSON object");
-            }
-            else {
-                parsedReport = report;
-                const obj = parsedReport;
-                for (const field of REVIEW_REPORT_REQUIRED_FIELDS) {
-                    if (!(field in obj))
-                        checks.push(`报告缺少必填字段 ${field}`);
-                }
-                if (obj.role !== job.role) {
-                    checks.push(`报告角色 ${String(obj.role)} 与工作项角色 ${job.role} 不匹配`);
-                }
-                if (obj.verdict !== "pass" && obj.verdict !== "fail") {
-                    checks.push("报告 verdict 必须是 pass 或 fail");
-                }
-                if (!Array.isArray(obj.findings)) {
-                    checks.push("报告 findings 必须是数组");
-                }
-                if (obj.verdict === "fail") {
-                    checks.push("报告 verdict=fail，工作项未通过");
-                }
-                if (requiresReviewer(job.role)) {
-                    if (!("reviewer" in obj))
-                        checks.push("报告缺少必填字段 reviewer");
-                    const reviewer = obj.reviewer;
-                    if (!reviewer || typeof reviewer !== "object" || Array.isArray(reviewer)) {
-                        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.id !== "string" || reviewer.id.trim() === "") {
-                            checks.push("报告 reviewer.id 必须是非空字符串");
-                        }
-                    }
-                }
-            }
-        }
-        catch {
-            checks.push("报告必须是有效 JSON");
-        }
-        // 1. boundFiles 仍匹配当前文档（missing 也算不匹配）
-        for (const bf of job.boundFiles) {
-            const currentSha = sha256File(join(changeRoot, bf.path)) ?? "sha256:missing";
-            if (currentSha !== bf.sha) {
-                checks.push(`绑定文件 ${bf.path} 已变化（${bf.sha} → ${currentSha}）`);
-            }
-        }
-        const reviewStaleReason = reviewVerifierStaleReason(job, changeRoot, reviewEvidenceDigest(events));
-        if (reviewStaleReason && !checks.includes(reviewStaleReason)) {
-            checks.push(reviewStaleReason);
-        }
-        // 2. 报告格式基本校验（非空 JSON 或文本）
-        if (!reportContent.trim()) {
-            checks.push("报告内容为空");
+        return recordJobSubmitLoaded(projectRoot, change, changeRoot, jobId, job, events, reportContent, reportDigest);
+    });
+}
+/** record job-submit：从 JSON 内容登记工作项结果 */
+export function recordJobSubmitContent(projectRoot, change, changeRoot, jobId, reportContent) {
+    return withLock(projectRoot, change, () => {
+        ensureChangeLayout(projectRoot, change);
+        const events = readEvents(projectRoot, change);
+        const job = findJob(events, jobId);
+        if (!job) {
+            return { event_type: "job_rejected", accepted: false, message: `工作项 ${jobId} 不存在` };
         }
-        if (checks.length > 0) {
-            // 拒绝
-            const rejectEvent = makeEvent(change, "job_rejected", {
-                job_id: jobId,
-                role: job.role,
-                report_digest: reportDigest,
-                reason: checks.join("; "),
-            });
-            appendEvent(projectRoot, change, rejectEvent);
-            return {
-                event_type: "job_rejected",
-                accepted: false,
-                message: `工作项 ${jobId} 被拒绝：${checks.join("; ")}`,
-                job_state: "rejected",
-            };
+        const reportDigest = sha256Text(reportContent);
+        const terminal = jobTerminalState(events, jobId);
+        if (terminal) {
+            return terminalJobSubmitResult(events, jobId, terminal, reportDigest);
         }
-        // 接受
-        const rawRef = appendRawRecord(projectRoot, change, "review-reports", parsedReport);
-        const acceptEvent = makeEvent(change, "job_accepted", {
-            job_id: jobId,
-            role: job.role,
-            report_digest: reportDigest,
-            accepted_at: new Date().toISOString(),
-            ...rawRef,
-        });
-        appendEvent(projectRoot, change, acceptEvent);
+        return recordJobSubmitLoaded(projectRoot, change, changeRoot, jobId, job, events, reportContent, reportDigest);
+    });
+}
+function recordUserDecisionLoaded(projectRoot, change, events, content, inputDigest) {
+    let decision;
+    try {
+        decision = JSON.parse(content);
+    }
+    catch {
+        appendEvent(projectRoot, change, makeEvent(change, "user_decision_recorded", { accepted: false, reason: "invalid_json" }));
+        return { event_type: "user_decision_recorded", accepted: false, message: "决策文件不是有效 JSON" };
+    }
+    if (!decision.scope || !decision.answer) {
+        appendEvent(projectRoot, change, makeEvent(change, "user_decision_recorded", { accepted: false, reason: "missing_scope_or_answer" }));
+        return { event_type: "user_decision_recorded", accepted: false, message: "决策文件缺少 scope 或 answer" };
+    }
+    const existing = events.find(e => e.event_type === "user_decision_recorded"
+        && e.payload.input_digest === inputDigest);
+    if (existing) {
         return {
-            event_type: "job_accepted",
+            event_type: "user_decision_recorded",
             accepted: true,
-            message: `工作项 ${jobId}（${job.role}）已接受`,
-            job_state: "accepted",
+            message: "幂等返回：同 user decision 已登记",
         };
+    }
+    const normalizedDecision = {
+        scope: decision.scope,
+        question: decision.question ?? "",
+        answer: decision.answer,
+    };
+    const rawRef = appendRawRecord(projectRoot, change, "user-decisions", normalizedDecision);
+    const event = makeEvent(change, "user_decision_recorded", {
+        ...normalizedDecision,
+        input_digest: inputDigest,
+        ...rawRef,
     });
+    appendEvent(projectRoot, change, event);
+    return {
+        event_type: "user_decision_recorded",
+        accepted: true,
+        message: `用户决策已登记：scope=${decision.scope}`,
+    };
 }
 /** record user-decision：登记用户决策 */
 export function recordUserDecision(projectRoot, change, inputFile) {
@@ -204,45 +256,16 @@ export function recordUserDecision(projectRoot, change, inputFile) {
             return { event_type: "user_decision_recorded", accepted: false, message: `决策文件不存在：${inputFile}` };
         }
         const content = readFileSync(inputFile, "utf8");
-        let decision;
-        try {
-            decision = JSON.parse(content);
-        }
-        catch {
-            appendEvent(projectRoot, change, makeEvent(change, "user_decision_recorded", { accepted: false, reason: "invalid_json" }));
-            return { event_type: "user_decision_recorded", accepted: false, message: "决策文件不是有效 JSON" };
-        }
-        if (!decision.scope || !decision.answer) {
-            appendEvent(projectRoot, change, makeEvent(change, "user_decision_recorded", { accepted: false, reason: "missing_scope_or_answer" }));
-            return { event_type: "user_decision_recorded", accepted: false, message: "决策文件缺少 scope 或 answer" };
-        }
         const inputDigest = sha256File(inputFile) ?? "sha256:unknown";
-        const existing = events.find(e => e.event_type === "user_decision_recorded"
-            && e.payload.input_digest === inputDigest);
-        if (existing) {
-            return {
-                event_type: "user_decision_recorded",
-                accepted: true,
-                message: "幂等返回：同 user decision 已登记",
-            };
-        }
-        const normalizedDecision = {
-            scope: decision.scope,
-            question: decision.question ?? "",
-            answer: decision.answer,
-        };
-        const rawRef = appendRawRecord(projectRoot, change, "user-decisions", normalizedDecision);
-        const event = makeEvent(change, "user_decision_recorded", {
-            ...normalizedDecision,
-            input_digest: inputDigest,
-            ...rawRef,
-        });
-        appendEvent(projectRoot, change, event);
-        return {
-            event_type: "user_decision_recorded",
-            accepted: true,
-            message: `用户决策已登记：scope=${decision.scope}`,
-        };
+        return recordUserDecisionLoaded(projectRoot, change, events, content, inputDigest);
+    });
+}
+/** record user-decision：从 JSON 内容登记用户决策 */
+export function recordUserDecisionContent(projectRoot, change, content) {
+    return withLock(projectRoot, change, () => {
+        ensureChangeLayout(projectRoot, change);
+        const events = readEvents(projectRoot, change);
+        return recordUserDecisionLoaded(projectRoot, change, events, content, sha256Text(content));
     });
 }
 /** jobs list（HIGH-1 修复：从 transition_commit.new_jobs 提取，不再依赖已删除的 job_requested 事件） */
@@ -296,12 +319,15 @@ export function jobsPacket(projectRoot, change, jobId) {
             ...(job.review_evidence_digest ? { review_evidence_digest: job.review_evidence_digest } : {}),
             packet_digest: job.packet_digest,
             required_output_kind: "job_report_json",
+            preferred_input_mode: "stdin",
+            submission_command: `superspec record job-submit --change "${change}" --job "${job.job_id}" --report -`,
+            file_fallback: true,
             output_contract_fields: requiresReviewer(job.role) ? [...REVIEW_REPORT_REQUIRED_FIELDS, "reviewer"] : [...REVIEW_REPORT_REQUIRED_FIELDS],
             output_contract_optional_fields: [...REVIEW_REPORT_OPTIONAL_FIELDS],
             output_instructions: `${roleDescription(job.role)}。请审查 ${job.boundFiles.map(f => f.path).join(", ")}，` +
                 (job.review_evidence_digest ? `本工作项绑定的执行证据版本为 ${job.review_evidence_digest}，` : "") +
                 (requiresReviewer(job.role) ? `必须由独立 ${recommendedAgentForRole(job.role)} reviewer 执行并在 reviewer.kind/id 中记录来源，` : "") +
-                `产出 JSON 报告文件并通过 superspec record job-submit 登记。` +
+                `产出 JSON 报告内容并优先通过 --report - 从 stdin 登记；文件路径模式仍可作为 fallback。` +
                 (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":[]}`),

package/dist/task.d.ts

@@ -5,3 +5,8 @@ export declare function recordTestRun(projectRoot: string, change: string, input
     accepted: boolean;
     message: string;
 };
+/** record test-run：从 JSON 内容登记测试运行记录 */
+export declare function recordTestRunContent(projectRoot: string, change: string, content: string): {
+    accepted: boolean;
+    message: string;
+};

package/dist/task.js

@@ -11,39 +11,49 @@ export function tasksStructureDigestOf(changeRoot) {
     const content = readFileSync(p, "utf8");
     return formatDigest(content, sha256Text);
 }
+function recordTestRunLoaded(projectRoot, change, content) {
+    let tr;
+    try {
+        tr = JSON.parse(content);
+    }
+    catch {
+        return { accepted: false, message: "无效 JSON" };
+    }
+    if (!tr.test_id || !tr.task_structure_digest) {
+        return { accepted: false, message: "缺少 test_id 或 task_structure_digest" };
+    }
+    const normalizedTestRun = {
+        test_id: tr.test_id,
+        task_structure_digest: tr.task_structure_digest,
+        attempt_id: tr.attempt_id ?? null,
+        command: tr.command ?? "",
+        cwd: tr.cwd ?? "",
+        exit_code: tr.exit_code ?? -1,
+        semantic_status: tr.semantic_status ?? "unknown",
+        target_fingerprint: tr.target_fingerprint ?? null,
+        raw_log_ref: tr.raw_log_ref ?? null,
+    };
+    const rawRef = appendRawRecord(projectRoot, change, "test-runs", normalizedTestRun);
+    const event = makeEvent(change, "test_run_recorded", {
+        ...normalizedTestRun,
+        ...rawRef,
+    });
+    appendEvent(projectRoot, change, event);
+    return { accepted: true, message: `测试运行已登记：test_id=${tr.test_id}` };
+}
 /** record test-run：登记测试运行记录 */
 export function recordTestRun(projectRoot, change, inputFile) {
     return withLock(projectRoot, change, () => {
         ensureChangeLayout(projectRoot, change);
         if (!existsSync(inputFile))
             return { accepted: false, message: `文件不存在：${inputFile}` };
-        let tr;
-        try {
-            tr = JSON.parse(readFileSync(inputFile, "utf8"));
-        }
-        catch {
-            return { accepted: false, message: "无效 JSON" };
-        }
-        if (!tr.test_id || !tr.task_structure_digest) {
-            return { accepted: false, message: "缺少 test_id 或 task_structure_digest" };
-        }
-        const normalizedTestRun = {
-            test_id: tr.test_id,
-            task_structure_digest: tr.task_structure_digest,
-            attempt_id: tr.attempt_id ?? null,
-            command: tr.command ?? "",
-            cwd: tr.cwd ?? "",
-            exit_code: tr.exit_code ?? -1,
-            semantic_status: tr.semantic_status ?? "unknown",
-            target_fingerprint: tr.target_fingerprint ?? null,
-            raw_log_ref: tr.raw_log_ref ?? null,
-        };
-        const rawRef = appendRawRecord(projectRoot, change, "test-runs", normalizedTestRun);
-        const event = makeEvent(change, "test_run_recorded", {
-            ...normalizedTestRun,
-            ...rawRef,
-        });
-        appendEvent(projectRoot, change, event);
-        return { accepted: true, message: `测试运行已登记：test_id=${tr.test_id}` };
+        return recordTestRunLoaded(projectRoot, change, readFileSync(inputFile, "utf8"));
+    });
+}
+/** record test-run：从 JSON 内容登记测试运行记录 */
+export function recordTestRunContent(projectRoot, change, content) {
+    return withLock(projectRoot, change, () => {
+        ensureChangeLayout(projectRoot, change);
+        return recordTestRunLoaded(projectRoot, change, content);
     });
 }

package/dist/types.d.ts

@@ -24,6 +24,9 @@ export interface JobPacket {
     review_evidence_digest?: string;
     packet_digest: string;
     required_output_kind: string;
+    preferred_input_mode?: "stdin" | "file";
+    submission_command?: string;
+    file_fallback?: boolean;
     output_contract_fields?: string[];
     output_contract_optional_fields?: string[];
     stop_conditions: string[];

package/package.json

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

package/templates/workflow/prompts/architect.md

@@ -19,7 +19,7 @@ argument-hint: "本次架构审查说明"
 
 在 `superspec-review` 或 disclosure review 中，先读取主流程提供的本次任务说明。以本次任务说明中的审查范围、绑定文件、输出格式、字段要求和停止条件为准；不要依赖本 prompt 记忆输出 schema。
 
-当本次任务说明要求提交 `job_report_json` 报告时，提交给 `superspec record job-submit` 的报告文件必须是 JSON：
+当本次任务说明要求提交 `job_report_json` 报告时，提交给 `superspec record job-submit` 的报告内容必须是 JSON，并优先通过 `--report -` 从 stdin 登记：
 
 ```json
 {
@@ -36,6 +36,17 @@ argument-hint: "本次架构审查说明"
 
 `role`、`verdict`、`findings`、`reviewer` 是必填字段。`reviewer.kind` 必须是 `codex-subagent`、`human` 或 `external-agent`，`reviewer.id` 必须能指向实际审查来源。发现阻塞架构问题时必须使用 `verdict:"fail"`。
 
+## 计划 / 设计审查口径
+
+审查计划文档时，重点判断影响范围、技术决策和任务拆分是否能支撑后续实现，不要把文档格式本身当成目标。
+
+- `proposal.md` 的 `## Impact` 应通过 `Area` / `Reason` 说明受影响区域和原因；如果只有泛目录、没有原因或把 `Area` 当路径白名单，应提出阻塞或风险
+- `design.md` 应记录关键决策、替代方案和风险取舍；如果只是复制影响范围、任务清单或实现步骤，说明设计边界不清
+- `tasks.md` 可以用 Markdown 标题分组，但可执行边界必须落到顶格 checkbox 叶子 task
+- 任务分组应贴合系统边界；高风险模块、跨入口行为或难以 review 的大改动，应要求拆成可独立验证的 task
+- 如果分组标题、task id 或任务文本会让执行者容易启动错任务，应使用 `verdict:"fail"`
+- 不要为了弥补拆分不清而要求新增父子任务状态、额外设计字段或 tasks 反向引用 design；先要求更清楚的分组和叶子 task
+
 ## 输出风格
 
 - 所有用户可见输出必须使用简体中文。

package/templates/workflow/prompts/critic.md

@@ -20,7 +20,7 @@ argument-hint: "本次反方审查说明"
 
 在 `superspec-review` 或 disclosure review 中，先读取主流程提供的本次任务说明。以本次任务说明中的审查范围、绑定文件、输出格式、字段要求和停止条件为准；不要依赖本 prompt 记忆输出 schema。
 
-当本次任务说明要求提交 `job_report_json` 报告时，提交给 `superspec record job-submit` 的报告文件必须是 JSON：
+当本次任务说明要求提交 `job_report_json` 报告时，提交给 `superspec record job-submit` 的报告内容必须是 JSON，并优先通过 `--report -` 从 stdin 登记：
 
 ```json
 {
@@ -37,7 +37,43 @@ argument-hint: "本次反方审查说明"
 
 `role`、`verdict`、`findings`、`reviewer` 是必填字段。`reviewer.kind` 必须是 `codex-subagent`、`human` 或 `external-agent`，`reviewer.id` 必须能指向实际审查来源。发现阻塞问题时必须使用 `verdict:"fail"`，并在 `findings` 中给出证据和修复建议。
 
-当你在 `review_complete` 中承担 verification lane 时，必须确认本次任务说明要求输出验证意见；否则只输出 source guidance。
+当你在 `review_complete` 中承担验证职责时，必须确认本次任务说明要求输出验证意见；否则只输出 source guidance。
+
+## Discovery 审查口径
+
+当审查 explore 阶段的 discovery 时，判断它是否足以支撑进入 propose。不要接管设计，不要替主流程选方案。
+
+最小通过条件：
+
+- 代码影响型需求必须包含 repo source anchors；纯文档、配置或新文件任务没有代码锚点时，必须说明 `N/A` 理由并引用相关文档、配置或需求来源。
+- `当前代码事实` 必须能说明当前实现怎么工作，而不是泛泛复述需求。
+- `需求理解` 必须说明用户目标和当前实现之间的差异。
+- `影响范围候选` 中每个主要候选应有至少一个 `path:line` 或等价文档锚点；无法验证时必须标明不确定性。
+- 风险必须绑定具体代码、行为、数据或文档事实。
+- 未验证假设、会影响范围或验收的问题必须进入 `## 待确认问题`，或明确说明为什么非阻塞。
+
+代码影响型 discovery 缺少事实锚点、需求理解与当前实现脱节、或把未验证假设当成事实时，使用 `verdict:"fail"`。
+
+## Propose 审查口径
+
+审查 propose 阶段计划时，重点挑战影响范围、原因和任务计划是否会让 apply 跑偏。
+
+阻塞条件：
+
+- `proposal.md` 缺少 `## Impact`
+- `## Impact` 没有说明 `Area` / `Reason`
+- `Area` 只有泛目录，且没有原因或不确定性说明
+- `Reason` 只写“要改这里”，没有解释为什么受影响
+- `## Impact` 写成任务清单或路径白名单
+- `design.md` 把影响范围表、任务拆分或实现清单复制进去，导致技术决策不清
+- `tasks.md` 的任务拆分过粗，把多个独立行为放进同一个执行单元，导致 apply 难以用一组清晰的 RED/GREEN 证据验收
+- task id 重复、不稳定，或分组标题混入 task id，导致后续执行命令容易指错任务
+- 普通说明或缩进 checkbox 承载了实际未完成工作，导致工作流无法自然推进
+- task 中写入 RED/GREEN 命令、断言或预期输出，导致任务计划和实际执行证据混在一起
+
+发现这些问题时使用 `verdict:"fail"`，并给出最小拆分或补充建议。
+
+负例：一个 task 同时要求修改运行时行为、发布流程和文档，并且这些改动不能由同一组测试证据验收，应要求拆分；普通说明里出现 `TODO` / `follow-up` / “后续补”，但没有对应顶格 task，应使用 `verdict:"fail"`。
 
 ## 输出风格
 

package/templates/workflow/prompts/explore.md

@@ -15,11 +15,24 @@ argument-hint: "本次探索说明"
 - 优先使用 repo search 和文件读取验证事实，结论必须绑定可读源码或文档锚点。
 - 不要写 `proposal.md`/`design.md`/`tasks.md`/`specs/**`/`.superspec/**`。
 - 不能作为 `explore_complete` 的 role evidence；strict 风险模式需要门禁审查时交给 `critic`。
+- 当作为 explore subagent 深扫时，只输出事实、文件行号锚点、隐性约束、影响范围候选、风险和需要主流程确认的问题；不要输出实现方案，不要替主流程做取舍。
+- “影响范围候选”只描述现有代码表面、相邻模块和潜在风险，不写具体实现步骤。
 
 ## 本次任务说明
 
 如果主流程提供本次任务说明，先读取其中指向的 refs。以本次任务说明中的目标范围、来源 refs、必读 refs、artifact refs 和停止条件为准；不要依赖本 prompt 记忆输出 schema。
 
+## 深扫输出要求
+
+代码影响型需求必须尽量提供 `path:line` 形式的 repo source anchors。纯文档、配置或新文件任务没有代码锚点时，明确写出 `N/A` 理由，并引用相关文档、配置或需求来源。
+
+输出至少区分：
+
+- 已确认事实
+- 影响范围候选
+- 风险和隐性约束
+- 需要主流程确认的问题
+
 ## 输出风格
 
 - 所有用户可见输出必须使用简体中文。

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

@@ -7,20 +7,20 @@ argument-hint: "本次测试审查说明"
 
 ## 角色身份
 
-你是 Test Engineer。你审查测试策略、覆盖充分性、RED/GREEN 可信度、脆弱测试风险和验收场景映射。普通测试任务中可以编写测试；在 SuperSpec review/propose lane 中只提供 guidance，不直接改 artifact。
+你是 Test Engineer。你审查测试策略、覆盖充分性、RED/GREEN 可信度、脆弱测试风险和验收场景映射。普通测试任务中可以编写测试；在 SuperSpec review/propose 阶段中只提供 guidance，不直接改 artifact。
 
 ## 读写边界
 
-- SuperSpec review/propose lane 默认只读；不要修改方案、测试契约或实现。
+- SuperSpec review/propose 阶段默认只读；不要修改方案、测试契约或实现。
 - 普通测试实现任务中，只写测试，不写业务实现；需要实现改动时向主流程说明。
-- Apply 阶段如需新增或修改 RED/characterization 测试文件，只在主流程明确交付的 bounded native lane 内写测试；正式 RED/characterization/GREEN 运行证据仍由 test-runner 的本次测试说明生成。
+- Apply 阶段如需新增或修改 RED/characterization 测试文件，只在主流程明确交付的有界测试任务内写测试；正式 RED/characterization/GREEN 运行证据仍由 test-runner 的本次测试说明生成。
 - 必须核对现有测试模式和目标 acceptance，不用臆测替代证据。
 
 ## 本次任务说明
 
-在 SuperSpec review/propose lane 中，先读取主流程提供的本次任务说明。以本次任务说明中的审查范围、绑定文件、输出格式、字段要求和停止条件为准；不要依赖本 prompt 记忆输出 schema。
+在 SuperSpec review/propose 阶段中，先读取主流程提供的本次任务说明。以本次任务说明中的审查范围、绑定文件、输出格式、字段要求和停止条件为准；不要依赖本 prompt 记忆输出 schema。
 
-当本次任务说明要求提交 `job_report_json` 报告时，提交给 `superspec record job-submit` 的报告文件必须是 JSON：
+当本次任务说明要求提交 `job_report_json` 报告时，提交给 `superspec record job-submit` 的报告内容必须是 JSON，并优先通过 `--report -` 从 stdin 登记：
 
 ```json
 {
@@ -37,6 +37,16 @@ argument-hint: "本次测试审查说明"
 
 `role`、`verdict`、`findings`、`reviewer` 是必填字段。`reviewer.kind` 必须是 `codex-subagent`、`human` 或 `external-agent`，`reviewer.id` 必须能指向实际审查来源。测试契约、覆盖策略或验证路径不足时必须使用 `verdict:"fail"`。
 
+## 任务拆分与 RED/GREEN 审查口径
+
+在 propose 或 review 阶段审查 `tasks.md` 时：
+
+- TDD task 应能形成清晰 RED/GREEN 闭环，但 RED/GREEN 命令、断言或预期输出不应写进 `tasks.md`
+- `tasks.md` 只声明任务边界和 `tdd_required:true/false`；实际 RED/GREEN 细节属于 apply 阶段的 `record test-run` 证据
+- 无法定义目标测试身份、RED 失败信号、GREEN 覆盖映射，或只靠退出码/笼统命令证明的测试方案，应使用 `verdict:"fail"`
+- `tdd_required:false` 必须有明确 `no_tdd_reason`
+- 不要求建立新的 test-contract 关联，也不要求把 RED/GREEN 细节塞回 task 行
+
 ## 输出风格
 
 - 所有用户可见输出必须使用简体中文。

package/templates/workflow/prompts/verifier.md

@@ -35,7 +35,7 @@ argument-hint: "本次验证说明"
 
 `role`、`verdict`、`findings` 是必填字段。`verdict` 只能是 `pass` 或 `fail`。任务未完成、测试证据缺失、文档与实现状态不一致、绑定文件无法核对时输出 `verdict:"fail"`。
 
-`superspec-review` verification lane 先读主流程提供的本次验证说明；以本次任务说明中的引用范围、输出格式、字段要求和停止条件为准；不要依赖本 prompt 记忆输出 schema。
+`superspec-review` 验证环节先读主流程提供的本次验证说明；以本次任务说明中的引用范围、输出格式、字段要求和停止条件为准；不要依赖本 prompt 记忆输出 schema。
 
 确认本次任务说明要求输出 verification review 后，再输出 verification review。
 
@@ -45,6 +45,18 @@ apply worker report 字段以本次任务说明中的 `verifier_report_required_
 
 遵守本次任务说明中的报告策略：长日志、完整 diff、编译输出和大段生成内容用 artifact refs，不内联。
 
+## 计划 / 设计验证口径
+
+核对最终实现和计划文档时：
+
+- 实际代码改动应能从 `proposal.md` 的 `## Impact`、`design.md` 的关键决策或已完成 task 找到合理解释；无法解释的用户可见行为、新能力或大范围改动应使用 `verdict:"fail"`
+- `tasks.md` 在执行期间不应被改写计划内容；除目标 checkbox 被完成命令勾选外，新增任务、改任务含义或把未完成工作藏进普通说明，都应视为证明缺口
+- 已完成 TDD task 的 RED/GREEN 以 `record test-run` 证据为准，不以 `tasks.md` 的文字描述为准
+- 对每个已完成 TDD task，核对同一个 `task_completed.attempt_id` 下是否同时存在 RED/characterization 和 GREEN；新证据必须带同一 `attempt_id`
+- 缺少 `attempt_id`、只靠 `task_structure_digest` 匹配的 test-run 只能视为旧数据兼容，不作为新流程“确实跑了红绿验证”的强证明
+- test-run 证据应说明目标测试身份、`test_id`、`command`、`cwd`、`exit_code` 和 `semantic_status`；退出码本身不等于证明，环境错误 / 构建错误不算 RED/GREEN
+- 可追溯性以引擎记录的 test-run 事件、`raw_index` 和 `raw_digest` 为准；额外日志或 test-runner report 只作为补充引用
+
 ## 输出风格
 
 - 所有用户可见输出必须使用简体中文。

package/templates/workflow/skills/superspec-apply/SKILL.md

@@ -23,15 +23,19 @@ metadata:
 
 每个任务的循环：
 
-1. **任务开始**：`superspec transition task-start --change "<change>" --task TASK-XXX`
+1. **任务开始**：`superspec transition task-start --change "<change>" --task <task_id>`
 2. **拿到执行尝试 ID**：从 task-start 的返回结果或 `superspec status` 中读取当前活跃 attempt 的 `attempt_id`
-3. **红灯验证**：写测试，跑测试确认失败，`superspec record test-run --change "<change>" --input <FILE>`
+3. **红灯验证**：写测试，跑测试确认失败，优先用 `superspec record test-run --change "<change>" --input -` 从 stdin 登记 JSON 内容；文件路径模式仍可作为 fallback
 4. **代码实现**：根据任务写代码实现,保证代码不出现过渡设计以及代码质量
-5. **绿灯验证**：跑测试确认通过，`superspec record test-run --change "<change>" --input <FILE>`
-6. **任务结束标记完成**：`superspec transition task-complete --change "<change>" --task TASK-XXX`
+5. **绿灯验证**：跑测试确认通过，优先用 `superspec record test-run --change "<change>" --input -` 从 stdin 登记 JSON 内容；文件路径模式仍可作为 fallback
+6. **任务结束标记完成**：`superspec transition task-complete --change "<change>" --task <task_id>`
 
 no-TDD 任务（tdd_required:false + no_tdd_reason）跳过 RED/GREEN。
 
+只执行 `tasks.md` 中顶格 checkbox 行里的 `<task_id>`，例如 `1.1` 或 `TASK-001.1`。Markdown 标题只是分组，不传给 `task-start` / `task-complete`；普通 bullet 只是说明，不单独成为工作流执行单元。
+
+`tasks.md` 不写 RED/GREEN 命令、断言或预期输出。RED/GREEN 的真实证明来自 apply 阶段实际执行后登记的 `record test-run`。
+
 ## test-run 输入格式
 
 ```json
@@ -50,10 +54,18 @@ no-TDD 任务（tdd_required:false + no_tdd_reason）跳过 RED/GREEN。
 - `attempt_id`：从 task-start 结果获取，确保 RED/GREEN 绑定到正确的执行尝试
 - `semantic_status`：`expected_failure`（RED）/ `expected_success`（GREEN）/ `characterization_pass`
 - `task_structure_digest`：tasks.md 复选框归一化后的 sha256（引擎计算，你不需要手动算）
+- 新产生的 TDD 证据必须带当前 `attempt_id`；缺少 `attempt_id`、只靠 `task_structure_digest` 匹配的 test-run 仅用于旧数据兼容，不作为新流程强证明
+- `test_id`、`command`、`cwd`、`exit_code`、`semantic_status` 和目标测试身份必须能说明目标测试确实运行；退出码本身不等于证明
+- 可追溯证据以引擎记录的 test-run 事件为准；如有额外日志或 test-runner report，可作为补充引用，不作为必填字段
 
 ## Guardrails
 
 - 只改 tasks.md 里本任务范围相关的文件
+- 需要判断影响范围或改动原因不自明时，参考 `proposal.md` 的 `## Impact`，但不要把它当作路径白名单
+- 编码时发现未列入影响范围的文件，如果从 diff 或引用链能直接解释为同一任务下的局部引用、测试辅助或机械连带改动，可以继续
+- 如果发现新增能力、用户可见行为、明显新增影响范围或原因不自明，停止扩大实现并报告给主流程；不要在 apply 阶段补改 `proposal.md`
+- 不修改 `proposal.md`、`design.md`、`specs/**` 或 `.superspec/**`
+- active attempt 期间不要修改 `tasks.md` 中除 `task-complete` 自动勾选目标 checkbox 外的内容
 - 不跳过 RED 直接写 GREEN
 - 退出码 0 ≠ 测试通过——semantic_status 才是证据
 - 环境错误 / 构建失败不算 RED 或 GREEN

package/templates/workflow/skills/superspec-explore/SKILL.md

@@ -19,31 +19,55 @@ metadata:
 3. 登记结果
 4. 回到 1
 
-next 返回 `ask_user` 说明 discovery 不完整或有未确认问题——向用户提问，收到回答后 `superspec record user-decision --change "<change>" --input <FILE>`。
+next 返回 `ask_user` 说明 discovery 不完整或有未确认问题。若 scope 是 `explore_discovery`，先检查并填写 discovery 草稿，不要把草稿占位内容直接转问用户；只有真实阻塞问题才向用户提问，收到回答后优先用 `superspec record user-decision --change "<change>" --input -` 从 stdin 登记 JSON 内容；文件路径模式仍可作为 fallback。
 
-本技能默认走完整审查路径。探索完成后，`explore → propose` 会先创建 `critic` 工作项，由 Critic 角色审查需求澄清记录。审查完成后通过 `superspec record job-submit --change "<change>" --job <JOB> --report <FILE>` 登记报告。
+本技能默认走完整审查路径。探索完成后，`explore → propose` 会先创建 `critic` 工作项，由 Critic 角色审查需求澄清记录。审查完成后优先通过 `superspec record job-submit --change "<change>" --job <JOB> --report -` 从 stdin 登记 JSON 报告内容；文件路径模式仍可作为 fallback。
 
 ## 本阶段做什么
 
 1. **建立事实基线**：读代码、查架构、理解当前系统行为（只读）
-2. **写 discovery.md**：
+2. **写 discovery.md**：首次进入 explore 时引擎可能已创建草稿；必须用真实事实替换草稿标记和占位内容
 3. **澄清歧义**：有阻塞歧义时向用户提问
 
+## 探索分工
+
+主会话负责广度：理解用户需求、提出探索问题、汇总 discovery、判断哪些问题必须问用户。
+
+涉及多个文件、模块、入口或文件类型时，使用 `explore` subagent 做只读深扫。以下情况也应使用：
+
+- 当前行为不清楚
+- 涉及状态机、公共 API、数据格式、测试策略、权限、迁移或发布流程
+- 影响范围可能大于用户表述
+
+可跳过 subagent 的场景：
+
+- 纯文档
+- 明显 typo
+- 单文件机械小修
+- 明确无代码影响的需求
+
+跳过时在 discovery 中说明原因。`explore` subagent 只输出代码/文档事实、文件行号锚点、隐性约束、影响范围候选、风险和需要主流程确认的问题；不写方案、不写业务代码、不替主流程做决策。
+
 ## discovery.md 格式
 
 写入 `openspec/changes/<change>/.superspec/artifacts/discovery.md`：
 
+如果文件已经存在并包含 `<!-- superspec:discovery-draft -->` 或“待探索后...”占位文本，说明它是引擎生成的草稿。完成探索后必须删除草稿标记并替换所有占位内容，否则引擎会继续阻止推进。
+
 ```markdown
 # Discovery
 
-## 现状
-（当前系统怎么工作）
+## 当前代码事实
+- src/path.ts:10 当前系统怎么工作
 
-## 需要改什么
-（要实现的需求）
+## 需求理解
+（用户目标和当前实现之间的差异）
+
+## 影响范围候选
+- src/path.ts:10 可能受影响的代码表面和相邻风险
 
 ## 风险和边界
-（技术风险、依赖、兼容性）
+（技术风险、依赖、兼容性；尽量绑定代码或文档锚点）
 
 ## 待确认问题
 - [ ] 问题1的描述
@@ -51,6 +75,9 @@ next 返回 `ask_user` 说明 discovery 不完整或有未确认问题——向
 ```
 
 **重要**：`- [ ]` 标记的待确认问题必须全部解决（用户确认后改为 `- [x]` 或删除），否则工作流引擎会阻止推进到 propose。
+只有 `## 待确认问题` 段落内的 `- [ ]` 表示阻塞确认项。其他段落列事实、风险或影响范围时使用普通 bullet，不要用 checklist。
+
+代码影响型需求的 `当前代码事实`、`影响范围候选`、`风险和边界` 应尽量包含 `path:line` 锚点。纯文档、配置或新文件任务没有代码锚点时，写明 `N/A` 理由并引用相关文档、配置或需求来源。
 
 ## Guardrails
 

package/templates/workflow/skills/superspec-propose/SKILL.md

@@ -19,7 +19,7 @@ metadata:
 3. 登记结果
 4. 回到 1
 
-next 返回需要审查时，先按返回的审查说明完成对应审查，再用 `superspec record job-submit --change "<change>" --job <JOB> --report <FILE>` 提交审查报告。
+next 返回需要审查时，先按返回的审查说明完成对应审查，再优先用 `superspec record job-submit --change "<change>" --job <JOB> --report -` 从 stdin 提交 JSON 审查报告内容；文件路径模式仍可作为 fallback。
 
 人类可读正文默认使用简体中文；OpenSpec 结构标题、规范关键字、命令、路径、JSON 字段、代码标识符保留原文。
 如果 OpenSpec 生成文档语言不符合预期，先检查 `openspec/config.yaml` 的官方 `context` 设置；不要在变更文档里添加自定义 `language` 字段。
@@ -31,28 +31,63 @@ next 返回需要审查时，先按返回的审查说明完成对应审查，再
 ## 本阶段做什么
 
 ### proposal.md
-需求陈述、方案概述、影响范围。
+使用 OpenSpec proposal 原生结构。正文使用简体中文。
+
+SuperSpec 只增加一个轻量要求：在 OpenSpec 原生 `## Impact` 段落中，必须能看出受影响范围和原因。推荐写成：
+
+```markdown
+| Area | Reason |
+|---|---|
+| src/review.ts | 需要核对 review verifier 如何绑定文档和执行证据 |
+```
+
+规则：
+- `proposal.md` 说明为什么要做、做什么、能力变化和影响范围
+- `Area` 可以写代码区域、API、依赖、系统、配置或文档
+- `Reason` 只解释为什么该范围受影响，不写详细实现方案
+- `Area` 不作为路径白名单
+- 不写任务拆分
+- 只有存在阻塞确认项时才增加 `## 待用户确认`
 
 ### specs/
 OpenSpec 能力规范增量（`openspec instructions specs` 格式）。
 
 ### design.md
-技术方案、关键决策、替代方案。
+使用 OpenSpec design 原生结构。正文使用简体中文。
+
+规则：
+- `design.md` 写技术方案、关键决策、替代方案和风险取舍
+- 不复制 `proposal.md` 的影响范围表
+- 不写任务拆分
+- 只有存在阻塞确认项时才增加 `## 待用户确认`
 
 ### tasks.md
-任务列表，格式：
+使用 OpenSpec tasks 原生分组结构。每个顶格 checkbox 行是一个 SuperSpec 可执行 task，Markdown 标题只用于分组。
 
 ```markdown
 # Tasks
 
-- [ ] TASK-001 实现登录功能 tdd_required:true
-- [ ] TASK-002 更新文档 tdd_required:false no_tdd_reason:documentation-only
-- [ ] TASK-003 配置变更 tdd_required:false no_tdd_reason:configuration-only
+## Review verifier
+
+- [ ] 1.1 检查 verifier 绑定文档 tdd_required:true
+- [ ] 1.2 检查 verifier 绑定执行证据 tdd_required:true
+
+## Documentation
+
+- [ ] 2.1 更新文档 tdd_required:false no_tdd_reason:documentation-only
 ```
 
 规则：
+- 标题只分组，不是可执行 task；标题不要包含可执行 task id token，例如不要写 `## 1.1 Review verifier`
+- 顶格 `- [ ] <task_id> ...` 才是可执行 task，`<task_id>` 可以是 `1.1` 或 `TASK-001.1`
+- 每个可执行 task id 必须唯一、稳定
+- 不展示、不推荐缩进 checkbox；task 内部步骤用普通 bullet，不用 checkbox
 - `tdd_required:true`（默认）——改运行时代码/业务逻辑/数据迁移/权限/外部接口
 - `tdd_required:false` + `no_tdd_reason:xxx`——纯文档/配置/机械改名/生成物
+- task 行只标记是否需要 TDD，不写 RED/GREEN 命令、断言或预期输出；实际 RED/GREEN 由 apply 阶段执行，并通过 `record test-run` 绑定到 attempt
+- 一个 task 对应一个可独立验证的行为变化，或一个明确的非行为改动
+- 多个行为变化、多个入口、多个运行时模块混在一起，且不能形成同一个 RED/GREEN 闭环时，应拆开
+- 如果一个 task 需要“顺便”改很多不相邻模块，应在 propose 阶段重新拆分或补充任务，不留到 apply 阶段扩大范围
 
 ### business-invariants.md
 格式：
@@ -85,12 +120,14 @@ OpenSpec 能力规范增量（`openspec instructions specs` 格式）。
 - [ ] DEC-001 是否需要兼容历史行为？
 ```
 
-`next` 会在 propose 阶段检查 `proposal.md`、`design.md` 和 `test-contract.md` 的该段落。存在未确认项时，先向用户提问；收到回答后写入 JSON 文件并执行：
+`next` 会在 propose 阶段检查 `proposal.md`、`design.md` 和 `test-contract.md` 的该段落。存在未确认项时，先向用户提问；收到回答后将 JSON 内容通过 stdin 登记：
 
 ```bash
-superspec record user-decision --change "<change>" --input <FILE>
+superspec record user-decision --change "<change>" --input -
 ```
 
+文件路径模式仍可作为 fallback。
+
 然后把用户决定反映到 proposal/design/test-contract，并将对应确认项改为 `[x]` 或移出未确认列表。局部实现细节、命名、普通文件组织和不影响需求/验收/风险的技术微调不要升级为用户确认。
 
 ## 完成条件

package/templates/workflow/skills/superspec-review/SKILL.md

@@ -19,7 +19,7 @@ metadata:
 3. 登记结果
 4. 回到 1
 
-next 返回需要 verifier 工作项时，先按返回的验证说明执行核对，再用 `superspec record job-submit --change "<change>" --job <JOB> --report <FILE>` 提交验证报告。
+next 返回需要 verifier 工作项时，先按返回的验证说明执行核对，再优先用 `superspec record job-submit --change "<change>" --job <JOB> --report -` 从 stdin 提交 JSON 验证报告内容；文件路径模式仍可作为 fallback。
 
 `record job-submit` 沿用现有 raw 归档：报告追加到 `raw/review-reports.jsonl`，不会为 review gate 新增 raw 文件类型。