@peterxiaoyang/superspec 0.1.24 → 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.24",
+  "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
 {

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
 {

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

@@ -20,7 +20,7 @@ argument-hint: "本次测试审查说明"
 
 在 SuperSpec review/propose 阶段中，先读取主流程提供的本次任务说明。以本次任务说明中的审查范围、绑定文件、输出格式、字段要求和停止条件为准；不要依赖本 prompt 记忆输出 schema。
 
-当本次任务说明要求提交 `job_report_json` 报告时，提交给 `superspec record job-submit` 的报告文件必须是 JSON：
+当本次任务说明要求提交 `job_report_json` 报告时，提交给 `superspec record job-submit` 的报告内容必须是 JSON，并优先通过 `--report -` 从 stdin 登记：
 
 ```json
 {

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

@@ -25,9 +25,9 @@ metadata:
 
 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>`
+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。

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

@@ -19,14 +19,14 @@ 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. **澄清歧义**：有阻塞歧义时向用户提问
 
 ## 探索分工
@@ -52,6 +52,8 @@ next 返回 `ask_user` 说明 discovery 不完整或有未确认问题——向
 
 写入 `openspec/changes/<change>/.superspec/artifacts/discovery.md`：
 
+如果文件已经存在并包含 `<!-- superspec:discovery-draft -->` 或“待探索后...”占位文本，说明它是引擎生成的草稿。完成探索后必须删除草稿标记并替换所有占位内容，否则引擎会继续阻止推进。
+
 ```markdown
 # Discovery
 

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` 字段。
@@ -120,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 文件类型。