@peterxiaoyang/superspec 0.1.24 → 0.1.26

package/dist/record.js

@@ -1,8 +1,9 @@
 // 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";
+import { jobSubmitArgv } from "./job_action.js";
 const REVIEW_REPORT_REQUIRED_FIELDS = ["role", "verdict", "findings"];
 const REVIEW_REPORT_OPTIONAL_FIELDS = ["summary", "evidence_refs", "risks", "open_questions"];
 const REVIEWER_KINDS = new Set(["codex-subagent", "human", "external-agent"]);
@@ -57,142 +58,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 +257,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 +320,16 @@ 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 -`,
+            submission_argv: jobSubmitArgv(change, job.job_id),
+            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/transition.d.ts

@@ -13,15 +13,22 @@ interface Decision {
     details?: Record<string, unknown>;
     postCommit?: (projectRoot: string, change: string, changeRoot: string) => void;
 }
+interface SkipDecision {
+    skip: true;
+    message: string;
+}
+interface BlockedDecision {
+    blocked: true;
+    reason: string;
+    jobs: Job[];
+    details?: Record<string, unknown>;
+}
 /**
  * 统一 transition 提交协议——所有校验在锁内。
  */
 export declare function commitTransition(projectRoot: string, change: string, changeRoot: string, opts: {
     name: string;
-    decide: (snapshot: Snapshot) => Decision | {
-        skip: true;
-        message: string;
-    };
+    decide: (snapshot: Snapshot) => Decision | SkipDecision | BlockedDecision;
     idempotencyInputs?: Record<string, unknown>;
 }): TransitionResult;
 export declare function proposeReady(projectRoot: string, change: string, changeRoot: string, risk?: "minimal" | "normal" | "strict"): TransitionResult;

package/dist/transition.js

@@ -3,6 +3,7 @@ import { join } from "node:path";
 import { existsSync, readFileSync, writeFileSync, readdirSync } from "node:fs";
 import { ensureChangeLayout, readEvents, appendEvent, makeEvent, writeSnapshot, snapshotDigest, withLock, idempotencyKey, sha256File, sha256Text, } from "./store.js";
 import { rebuildSnapshot } from "./sync.js";
+import { requiredJobActions } from "./job_action.js";
 import { assertCommitPayloadExtension, isFreshReviewVerifier, isReviewReadyVerifier, readReviewPolicyFromEvents, reviewBoundFiles, reviewEvidenceDigest, reviewPolicyForRisk, } from "./review.js";
 import { validateDiscovery, collectProposeOpenQuestions, findTaskInLines, parseTasksMd, pendingTasksInContent, tasksStructureDigest } from "./format.js";
 let transitionSeq = 0;
@@ -31,7 +32,7 @@ function checkOrCreateReviewJobs(snapshot, requiredRoles, changeRoot, change, tr
     for (const role of requiredRoles) {
         const openForRole = snapshot.open_jobs.find(j => j.role === role && j.created_from_transition === transitionName);
         if (openForRole)
-            return { fromState: snapshot.state, toState: snapshot.state, outcome: "advanced", reason: `工作项 ${role} 已存在（${openForRole.job_id}），请先完成它` };
+            return { blocked: true, reason: `状态未推进；已有待完成工作项 ${role}（${openForRole.job_id}）`, jobs: [openForRole] };
         const fresh = snapshot.accepted_jobs.find(j => j.role === role && j.created_from_transition === transitionName);
         if (!fresh) {
             staleRoles.push({ role, reason: `需求 ${role} 无已接受的工作项` });
@@ -114,13 +115,28 @@ export function commitTransition(projectRoot, change, changeRoot, opts) {
         const existing = events.find(e => e.idempotency_key === idemKey && e.event_type === "transition_commit");
         if (existing) {
             const p = existing.payload;
+            const newJobs = p.new_jobs ?? [];
             return {
                 transition: name, outcome: p.outcome,
                 from_state: p.from_state, to_state: p.to_state,
                 created_jobs: p.created_job_ids ?? [], message: "幂等返回", events_written: 0,
+                ...(newJobs.length > 0 ? { required_jobs: requiredJobActions(change, newJobs) } : {}),
             };
         }
         const decision = opts.decide(snapshot);
+        if ("blocked" in decision) {
+            return {
+                transition: name,
+                outcome: "blocked",
+                from_state: snapshot.state,
+                to_state: snapshot.state,
+                created_jobs: [],
+                required_jobs: requiredJobActions(change, decision.jobs),
+                message: decision.reason,
+                events_written: 0,
+                ...(decision.details ? { details: decision.details } : {}),
+            };
+        }
         if ("skip" in decision) {
             return {
                 transition: name, outcome: "advanced",
@@ -163,6 +179,7 @@ export function commitTransition(projectRoot, change, changeRoot, opts) {
         return {
             transition: name, outcome, from_state: fromState, to_state: toState,
             created_jobs: newJobs.map(j => j.job_id),
+            ...(newJobs.length > 0 ? { required_jobs: requiredJobActions(change, newJobs) } : {}),
             message: outcome === "advanced" ? `状态推进：${fromState} → ${toState}` : `状态不变（${fromState}），创建了 ${newJobs.length} 个工作项`,
             events_written: 1 + extraEvents.length,
             ...(details ? { details } : {}),
@@ -348,7 +365,7 @@ export function reviewReady(projectRoot, change, changeRoot, risk = "strict") {
             if (snapshot.state === "apply_done" || snapshot.state === "review") {
                 const verifierOpen = snapshot.open_jobs.find(isReviewReadyVerifier);
                 if (verifierOpen)
-                    return { skip: true, message: `有待完成的最终验证工作项 ${verifierOpen.job_id}` };
+                    return { blocked: true, reason: `状态未推进；已有待完成最终验证工作项 ${verifierOpen.job_id}`, jobs: [verifierOpen] };
                 const verifierAccepted = snapshot.accepted_jobs.find(job => isFreshReviewVerifier(job, changeRoot, currentEvidenceDigest));
                 if (!policy.requires_verifier) {
                     if (snapshot.state === "apply_done") {

package/dist/types.d.ts

@@ -24,11 +24,21 @@ export interface JobPacket {
     review_evidence_digest?: string;
     packet_digest: string;
     required_output_kind: string;
+    preferred_input_mode?: "stdin" | "file";
+    submission_command?: string;
+    submission_argv?: string[];
+    file_fallback?: boolean;
     output_contract_fields?: string[];
     output_contract_optional_fields?: string[];
     stop_conditions: string[];
     created_from_transition: string;
 }
+export interface RequiredJobAction {
+    job_id: string;
+    role: JobRole;
+    packet_command: string;
+    packet_argv: string[];
+}
 export type EventType = "transition_prepare" | "transition_commit" | "job_requested" | "job_invalidated" | "reopen" | "abandon" | "task_started" | "task_completed" | "task_abandoned" | "job_accepted" | "job_rejected" | "user_decision_recorded" | "test_run_recorded" | "task_activation_recorded" | "artifact_recorded";
 export interface Event {
     event_id: string;
@@ -117,11 +127,7 @@ export type NextOutput = {
     missing_inputs: MissingInput[];
 } | {
     path: "required_job";
-    required_jobs: {
-        job_id: string;
-        role: JobRole;
-        packet_command: string;
-    }[];
+    required_jobs: RequiredJobAction[];
     reason: string;
 } | {
     path: "ask_user";
@@ -133,10 +139,11 @@ export type NextOutput = {
 });
 export interface TransitionResult {
     transition: string;
-    outcome: "advanced" | "job_created";
+    outcome: "advanced" | "job_created" | "blocked";
     from_state: State;
     to_state: State;
     created_jobs: string[];
+    required_jobs?: RequiredJobAction[];
     message: string;
     events_written: number;
     details?: Record<string, unknown>;

package/package.json

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

package/templates/workflow/AGENTS.md

@@ -0,0 +1,11 @@
+<!-- SUPERSPEC:AGENTS:START -->
+# SuperSpec
+
+本项目启用 SuperSpec。使用 `superspec-*` 工作流时，以 `superspec transition next --change "<change>"` 返回的下一步为准；流程完成前不得跳阶段、不得自称完成。
+
+SuperSpec 创建的独立审查/验证工作项，视为已授权启动对应 subagent；无需再次询问用户。主会话不得自批这些工作项。
+
+审查/验证工作项只授权处理该工作项绑定的内容，不得扩大范围、跳过阶段或代替后续流程。若当前环境无法启动 subagent，只能使用本地或用户已授权的独立来源；没有可用独立来源时停在当前工作项并说明阻塞，主会话不得因此自批。
+
+执行 CLI 返回命令时优先使用 `*_argv` 字段。用户可见回复使用自然语言；除非用户要求调试信息，不复述内部 JSON 字段。
+<!-- SUPERSPEC:AGENTS:END -->

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
 {