@peterxiaoyang/superspec 0.1.15-alpha → 0.1.17-alpha

package/dist/next.js

@@ -1,16 +1,23 @@
 // SuperSpec 流程引擎 — next：返回可执行路径
 import { rebuildSnapshot } from "./sync.js";
-import { existsSync, readFileSync } from "node:fs";
+import { readFileSync } from "node:fs";
 import { join } from "node:path";
-import { validateDiscovery, countDiscoveryOpenQuestions } from "./format.js";
+import { validateDiscovery, countDiscoveryOpenQuestions, collectProposeOpenQuestions } from "./format.js";
+const ACTIVE_PROPOSAL_REVIEW_ROLES = new Set(["critic", "architect", "test-engineer"]);
+function isActiveProposalReviewJob(job) {
+    return job.created_from_transition === "propose-ready" && ACTIVE_PROPOSAL_REVIEW_ROLES.has(job.role);
+}
 function packetCommand(change, jobId) {
     return `superspec jobs packet --change "${change}" --job "${jobId}"`;
 }
 function transitionCommand(change, name, extra = "") {
     return `superspec transition ${name} --change "${change}"${extra ? " " + extra : ""}`;
 }
+function riskFlag(risk) {
+    return risk === "strict" ? "" : `--risk ${risk}`;
+}
 /** next 命令：读 snapshot，返回唯一可执行路径 */
-export function next(projectRoot, change, changeRoot, defaultRisk = "normal") {
+export function next(projectRoot, change, changeRoot, defaultRisk = "strict") {
     const snapshot = rebuildSnapshot(projectRoot, change, changeRoot);
     switch (snapshot.state) {
         case "init":
@@ -46,14 +53,25 @@ export function next(projectRoot, change, changeRoot, defaultRisk = "normal") {
             return {
                 state: "explore",
                 path: "next_command",
-                next_command: transitionCommand(change, "explore"),
+                next_command: transitionCommand(change, "explore", riskFlag(defaultRisk)),
                 reason: "探索完成，推进到计划阶段",
                 missing_inputs: [],
             };
         }
         case "propose": {
-            if (snapshot.open_jobs.length > 0) {
-                const jobs = snapshot.open_jobs.map(j => ({
+            const openQuestions = collectProposeOpenQuestions(changeRoot);
+            if (openQuestions.openCount > 0) {
+                const files = openQuestions.files.map(f => `${f.path}(${f.openCount})`).join(", ");
+                const ask = {
+                    question: `计划文档有 ${openQuestions.openCount} 个待用户确认问题：${files}。请确认并更新计划文档后继续`,
+                    allowed_answers: ["所有问题已确认"],
+                    scope: "propose_open_questions",
+                };
+                return { state: "propose", path: "ask_user", ask_user: ask, reason: `有 ${openQuestions.openCount} 个 propose 未确认问题` };
+            }
+            const proposalReviewJobs = snapshot.open_jobs.filter(isActiveProposalReviewJob);
+            if (proposalReviewJobs.length > 0) {
+                const jobs = proposalReviewJobs.map(j => ({
                     job_id: j.job_id,
                     role: j.role,
                     packet_command: packetCommand(change, j.job_id),
@@ -65,16 +83,28 @@ export function next(projectRoot, change, changeRoot, defaultRisk = "normal") {
                     reason: `有 ${jobs.length} 个待完成工作项`,
                 };
             }
-            const riskFlag = `--risk ${defaultRisk}`;
             return {
                 state: "propose",
                 path: "next_command",
-                next_command: transitionCommand(change, "propose-ready", riskFlag),
+                next_command: transitionCommand(change, "propose-ready", riskFlag(defaultRisk)),
                 reason: "计划文档就绪，提交 propose-ready",
                 missing_inputs: [],
             };
         }
-        case "propose_ready":
+        case "propose_ready": {
+            const proposalReviewJobs = snapshot.open_jobs.filter(isActiveProposalReviewJob);
+            if (proposalReviewJobs.length > 0) {
+                return {
+                    state: "propose_ready",
+                    path: "required_job",
+                    required_jobs: proposalReviewJobs.map(j => ({
+                        job_id: j.job_id,
+                        role: j.role,
+                        packet_command: packetCommand(change, j.job_id),
+                    })),
+                    reason: `有 ${proposalReviewJobs.length} 个待完成 proposal 审查工作项`,
+                };
+            }
             return {
                 state: "propose_ready",
                 path: "next_command",
@@ -82,6 +112,7 @@ export function next(projectRoot, change, changeRoot, defaultRisk = "normal") {
                 reason: "计划就绪，开始执行",
                 missing_inputs: [],
             };
+        }
         case "apply": {
             // 有 open job → 做
             if (snapshot.open_jobs.length > 0) {
@@ -99,7 +130,7 @@ export function next(projectRoot, change, changeRoot, defaultRisk = "normal") {
                 return {
                     state: "apply",
                     path: "next_command",
-                    next_command: transitionCommand(change, "review-ready"),
+                    next_command: transitionCommand(change, "review-ready", riskFlag(defaultRisk)),
                     reason: "所有任务完成，进入审查",
                     missing_inputs: [],
                 };
@@ -124,7 +155,7 @@ export function next(projectRoot, change, changeRoot, defaultRisk = "normal") {
             return {
                 state: "apply_done",
                 path: "next_command",
-                next_command: transitionCommand(change, "review-ready"),
+                next_command: transitionCommand(change, "review-ready", riskFlag(defaultRisk)),
                 reason: "所有任务完成，进入审查",
                 missing_inputs: [],
             };

package/dist/record.js

@@ -2,6 +2,38 @@
 import { readFileSync, existsSync } from "node:fs";
 import { join } from "node:path";
 import { ensureChangeLayout, readEvents, appendEvent, makeEvent, sha256File, withLock, } from "./store.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"]);
+function requiresReviewer(role) {
+    return role === "critic" || role === "architect" || role === "test-engineer";
+}
+function recommendedAgentForRole(role) {
+    switch (role) {
+        case "critic": return "critic";
+        case "architect": return "architect";
+        case "test-engineer": return "test-engineer";
+        case "verifier": return "verifier";
+        case "executor": return "executor";
+        case "test-run": return "test-runner";
+    }
+}
+function roleDescription(role) {
+    switch (role) {
+        case "critic":
+            return "从反方角度审查需求澄清或计划材料中的隐藏假设、范围漂移、验收漏洞和证据缺口";
+        case "architect":
+            return "审查架构边界、接口契约、长期维护风险和设计取舍";
+        case "test-engineer":
+            return "审查测试契约、覆盖策略、RED/GREEN 可信度和验收场景映射";
+        case "verifier":
+            return "验证 proposal、实现状态、任务完成、测试契约和 SuperSpec 证据是否足以支撑完成结论";
+        case "executor":
+            return "执行受限实现工作项";
+        case "test-run":
+            return "执行受限测试工作项";
+    }
+}
 /** 从 events 中查找 job（H4 修复：job 只在 transition_commit 的 new_jobs payload 里） */
 function findJob(events, jobId) {
     for (const ev of events) {
@@ -65,15 +97,50 @@ export function recordJobSubmit(projectRoot, change, changeRoot, jobId, reportFi
         const reportDigest = sha256File(reportFile) ?? "sha256:unknown";
         // acceptance checks
         const checks = [];
-        // 0. 报告角色匹配（HIGH 5 修复）
+        // 0. 报告格式和角色匹配（最小 JSON contract）
         try {
             const report = JSON.parse(reportContent);
-            if (report.role && report.role !== job.role) {
-                checks.push(`报告角色 ${report.role} 与工作项角色 ${job.role} 不匹配`);
+            if (!report || typeof report !== "object" || Array.isArray(report)) {
+                checks.push("报告必须是 JSON object");
+            }
+            else {
+                const obj = report;
+                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 {
-            // 非 JSON 报告，Phase 1 允许（Phase 2 加正式 schema）
+            checks.push("报告必须是有效 JSON");
         }
         // 1. boundFiles 仍匹配当前文档（missing 也算不匹配）
         for (const bf of job.boundFiles) {
@@ -199,10 +266,18 @@ export function jobsPacket(projectRoot, change, jobId) {
         packet: {
             job_id: job.job_id,
             role: job.role,
+            recommended_agent: recommendedAgentForRole(job.role),
             boundFiles: job.boundFiles,
             packet_digest: job.packet_digest,
-            required_output_kind: "report",
-            output_instructions: `请审查 ${job.boundFiles.map(f => f.path).join(", ")}，产出审查报告`,
+            required_output_kind: "job_report_json",
+            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(", ")}，` +
+                (requiresReviewer(job.role) ? `必须由独立 ${recommendedAgentForRole(job.role)} reviewer 执行并在 reviewer.kind/id 中记录来源，` : "") +
+                `产出 JSON 报告文件并通过 superspec record job-submit 登记。` +
+                (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":[]}`),
             stop_conditions: ["审查完成后提交报告，不要修改文档"],
             created_from_transition: job.created_from_transition,
         },

package/dist/transition.d.ts

@@ -9,6 +9,7 @@ interface Decision {
         type: string;
         payload: Record<string, unknown>;
     }[];
+    details?: Record<string, unknown>;
     postCommit?: (projectRoot: string, change: string, changeRoot: string) => void;
 }
 /**
@@ -24,7 +25,7 @@ export declare function commitTransition(projectRoot: string, change: string, ch
 }): TransitionResult;
 export declare function proposeReady(projectRoot: string, change: string, changeRoot: string, risk?: "minimal" | "normal" | "strict"): TransitionResult;
 export declare function transitionInit(projectRoot: string, change: string, changeRoot: string): TransitionResult;
-export declare function transitionExplore(projectRoot: string, change: string, changeRoot: string): TransitionResult;
+export declare function transitionExplore(projectRoot: string, change: string, changeRoot: string, risk?: "minimal" | "normal" | "strict"): TransitionResult;
 export declare function startApply(projectRoot: string, change: string, changeRoot: string): TransitionResult;
 export declare function taskStart(projectRoot: string, change: string, changeRoot: string, taskId: string): TransitionResult;
 export declare function reviewReady(projectRoot: string, change: string, changeRoot: string, risk?: "minimal" | "normal" | "strict"): TransitionResult;

package/dist/transition.js

@@ -3,7 +3,7 @@ import { join } from "node:path";
 import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync } from "node:fs";
 import { ensureChangeLayout, readEvents, appendEvent, makeEvent, writeSnapshot, snapshotDigest, withLock, idempotencyKey, stagingDir, sha256File, sha256Text, } from "./store.js";
 import { rebuildSnapshot } from "./sync.js";
-import { validateDiscovery, findTaskInLines, parseTasksMd, tasksStructureDigest } from "./format.js";
+import { validateDiscovery, collectProposeOpenQuestions, findTaskInLines, parseTasksMd, tasksStructureDigest } from "./format.js";
 let transitionSeq = 0;
 function newTransitionId() { return `T-${Date.now()}-${++transitionSeq}`; }
 let jobSeq = 0;
@@ -11,13 +11,13 @@ function newJobId(change, role) { return `JOB-${change.slice(0, 8)}-${role.slice
 const TRANSITION_REQUIREMENTS = {
     "propose-ready": {
         minimal: [],
-        normal: ["proposal-auditor"],
-        strict: ["critic-review", "architect-review", "test-engineer-review"],
+        normal: ["critic"],
+        strict: ["critic", "architect", "test-engineer"],
     },
     "explore": {
         minimal: [],
         normal: [],
-        strict: ["clarification-review"],
+        strict: ["critic"],
     },
 };
 /**
@@ -28,10 +28,10 @@ const TRANSITION_REQUIREMENTS = {
 function checkOrCreateReviewJobs(snapshot, requiredRoles, changeRoot, change, transitionName, bindDocPaths) {
     const staleRoles = [];
     for (const role of requiredRoles) {
-        const openForRole = snapshot.open_jobs.find(j => j.role === role);
+        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}），请先完成它` };
-        const fresh = snapshot.accepted_jobs.find(j => j.role === role);
+        const fresh = snapshot.accepted_jobs.find(j => j.role === role && j.created_from_transition === transitionName);
         if (!fresh) {
             staleRoles.push({ role, reason: `需求 ${role} 无已接受的工作项` });
         }
@@ -57,6 +57,20 @@ function checkOrCreateReviewJobs(snapshot, requiredRoles, changeRoot, change, tr
     }
     return null; // 全部满足
 }
+function historicalProposeReadyRoles(projectRoot, change) {
+    const roles = new Set();
+    for (const ev of readEvents(projectRoot, change)) {
+        if (ev.event_type !== "transition_commit")
+            continue;
+        const newJobs = ev.payload.new_jobs ?? [];
+        for (const job of newJobs) {
+            if (job.created_from_transition === "propose-ready" &&
+                (job.role === "critic" || job.role === "architect" || job.role === "test-engineer"))
+                roles.add(job.role);
+        }
+    }
+    return [...roles];
+}
 /**
  * 已迁移到 format.ts：findTaskInLines / parseTasksMd / tasksStructureDigest
  * 以下保留 findTaskLine 作为兼容 wrapper（内部调用 format.ts）
@@ -92,7 +106,7 @@ export function commitTransition(projectRoot, change, changeRoot, opts) {
                 created_jobs: [], message: decision.message, events_written: 0,
             };
         }
-        const { fromState, toState, outcome, newJobs = [], reason, extraEvents = [] } = decision;
+        const { fromState, toState, outcome, newJobs = [], reason, extraEvents = [], details } = decision;
         if (fromState !== snapshot.state) {
             return {
                 transition: name, outcome: "advanced",
@@ -127,11 +141,12 @@ export function commitTransition(projectRoot, change, changeRoot, opts) {
             created_jobs: newJobs.map(j => j.job_id),
             message: outcome === "advanced" ? `状态推进：${fromState} → ${toState}` : `状态不变（${fromState}），创建了 ${newJobs.length} 个工作项`,
             events_written: 1 + extraEvents.length,
+            ...(details ? { details } : {}),
         };
     });
 }
 // ===== propose-ready =====
-export function proposeReady(projectRoot, change, changeRoot, risk = "normal") {
+export function proposeReady(projectRoot, change, changeRoot, risk = "strict") {
     return commitTransition(projectRoot, change, changeRoot, {
         name: "propose-ready", idempotencyInputs: { risk },
         decide: (snapshot) => {
@@ -143,6 +158,11 @@ export function proposeReady(projectRoot, change, changeRoot, risk = "normal") {
             const tasksContent = readFileSync(tasksPath, "utf8");
             if (!tasksContent.includes("# Tasks") && !tasksContent.includes("- [ ]"))
                 return { skip: true, message: "tasks.md 内容不像任务计划文档" };
+            const openQuestions = collectProposeOpenQuestions(changeRoot);
+            if (openQuestions.openCount > 0) {
+                const files = openQuestions.files.map(f => `${f.path}(${f.openCount})`).join(", ");
+                return { skip: true, message: `计划文档有 ${openQuestions.openCount} 个待用户确认问题：${files}` };
+            }
             if (risk !== "minimal") {
                 const artifactsDir = join(changeRoot, ".superspec", "artifacts");
                 for (const doc of ["discovery.md", "business-invariants.md", "test-contract.md"]) {
@@ -172,9 +192,9 @@ export function transitionInit(projectRoot, change, changeRoot) {
     });
 }
 // ===== explore =====
-export function transitionExplore(projectRoot, change, changeRoot) {
+export function transitionExplore(projectRoot, change, changeRoot, risk = "strict") {
     return commitTransition(projectRoot, change, changeRoot, {
-        name: "explore", idempotencyInputs: { phase: "explore" },
+        name: "explore", idempotencyInputs: { phase: "explore", risk },
         decide: (snapshot) => {
             if (snapshot.state === "init")
                 return { fromState: "init", toState: "explore", outcome: "advanced", reason: "进入探索阶段" };
@@ -182,12 +202,12 @@ export function transitionExplore(projectRoot, change, changeRoot) {
                 const discoveryPath = join(changeRoot, ".superspec", "artifacts", "discovery.md");
                 if (!existsSync(discoveryPath))
                     return { skip: true, message: "discovery.md 不存在" };
-                // explore→propose：校验 discovery + 通用 job 审查（normal+ 需 clarification-review）
+                // explore→propose：校验 discovery + strict 模式下的 critic 审查
                 const discoveryCheck = validateDiscovery(changeRoot);
                 if (!discoveryCheck.ok)
                     return { skip: true, message: discoveryCheck.message };
                 // 通用 job 审查（和 propose-ready 同一个 helper）
-                const requiredRoles = TRANSITION_REQUIREMENTS["explore"]?.["normal"] ?? [];
+                const requiredRoles = TRANSITION_REQUIREMENTS["explore"]?.[risk] ?? [];
                 const reviewResult = checkOrCreateReviewJobs(snapshot, requiredRoles, changeRoot, change, "explore", [".superspec/artifacts/discovery.md"]);
                 if (reviewResult)
                     return reviewResult;
@@ -204,6 +224,16 @@ export function startApply(projectRoot, change, changeRoot) {
         decide: (snapshot) => {
             if (snapshot.state !== "propose_ready")
                 return { skip: true, message: `当前状态 ${snapshot.state}，需要 propose_ready` };
+            const reviewedRoles = historicalProposeReadyRoles(projectRoot, change);
+            if (reviewedRoles.length > 0) {
+                const reviewResult = checkOrCreateReviewJobs(snapshot, reviewedRoles, changeRoot, change, "propose-ready", ["proposal.md", "tasks.md", "design.md", ".superspec/artifacts/discovery.md", ".superspec/artifacts/business-invariants.md", ".superspec/artifacts/test-contract.md"]);
+                if (reviewResult) {
+                    return {
+                        ...reviewResult,
+                        reason: `进入 apply 前需要 fresh proposal 审查：${reviewResult.reason}`,
+                    };
+                }
+            }
             return { fromState: "propose_ready", toState: "apply", outcome: "advanced", reason: "进入执行阶段" };
         },
     });
@@ -240,12 +270,13 @@ export function taskStart(projectRoot, change, changeRoot, taskId) {
                 fromState: "apply", toState: "apply", outcome: "advanced",
                 reason: `创建任务 ${taskId} 执行尝试`,
                 extraEvents: [{ type: "task_started", payload: attempt }],
+                details: { attempt_id: attempt.attempt_id },
             };
         },
     });
 }
 // ===== review-ready =====
-export function reviewReady(projectRoot, change, changeRoot, risk = "normal") {
+export function reviewReady(projectRoot, change, changeRoot, risk = "strict") {
     return commitTransition(projectRoot, change, changeRoot, {
         name: "review-ready", idempotencyInputs: { phase: "review-ready", risk },
         decide: (snapshot) => {
@@ -259,27 +290,26 @@ export function reviewReady(projectRoot, change, changeRoot, risk = "normal") {
                 return { fromState: "apply", toState: "apply_done", outcome: "advanced", reason: "所有任务完成" };
             }
             if (snapshot.state === "apply_done") {
-                // 检查是否有 final-audit job 需求
-                const finalAuditOpen = snapshot.open_jobs.find(j => j.role === "final-audit");
-                if (finalAuditOpen)
-                    return { skip: true, message: `有待完成的最终审查工作项 ${finalAuditOpen.job_id}` };
-                const finalAuditAccepted = snapshot.accepted_jobs.find(j => j.role === "final-audit");
-                // minimal 直接推进；normal/strict 需要 final-audit
-                if (risk !== "minimal" && !finalAuditAccepted) {
-                    // 创建 final-audit job
+                const isReviewReadyVerifier = (job) => job.role === "verifier" && job.created_from_transition === "review-ready";
+                const verifierOpen = snapshot.open_jobs.find(isReviewReadyVerifier);
+                if (verifierOpen)
+                    return { skip: true, message: `有待完成的最终验证工作项 ${verifierOpen.job_id}` };
+                const verifierAccepted = snapshot.accepted_jobs.find(isReviewReadyVerifier);
+                // minimal 直接推进；normal/strict 需要 review-ready verifier
+                if (risk !== "minimal" && !verifierAccepted) {
                     const docPaths = ["proposal.md", "tasks.md", "design.md", ".superspec/artifacts/discovery.md", ".superspec/artifacts/business-invariants.md", ".superspec/artifacts/test-contract.md"];
                     const boundFiles = docPaths.filter(p => existsSync(join(changeRoot, p))).map(p => ({ path: p, sha: sha256File(join(changeRoot, p)) ?? "sha256:missing" }));
                     const job = {
-                        job_id: newJobId(change, "final-audit"), role: "final-audit", state: "requested",
-                        boundFiles, packet_digest: sha256Text(JSON.stringify({ role: "final-audit", boundFiles })),
+                        job_id: newJobId(change, "verifier"), role: "verifier", state: "requested",
+                        boundFiles, packet_digest: sha256Text(JSON.stringify({ role: "verifier", boundFiles, created_from_transition: "review-ready" })),
                         created_from_transition: "review-ready", created_at: new Date().toISOString(),
                     };
                     return {
                         fromState: "apply_done", toState: "apply_done", outcome: "job_created",
-                        newJobs: [job], reason: "创建最终审查工作项",
+                        newJobs: [job], reason: "创建最终验证工作项",
                     };
                 }
-                return { fromState: "apply_done", toState: "review", outcome: "advanced", reason: "最终审查已接受，进入审查阶段" };
+                return { fromState: "apply_done", toState: "review", outcome: "advanced", reason: "最终验证已接受，进入审查阶段" };
             }
             return { skip: true, message: `当前状态 ${snapshot.state}，review-ready 不适用` };
         },

package/dist/types.d.ts

@@ -5,7 +5,7 @@ export type Ref = {
     sha: string;
 };
 export type JobState = "requested" | "accepted" | "rejected";
-export type JobRole = "proposal-auditor" | "clarification-review" | "critic-review" | "architect-review" | "test-engineer-review" | "executor" | "test-run" | "final-audit";
+export type JobRole = "critic" | "architect" | "test-engineer" | "executor" | "test-run" | "verifier";
 export interface Job {
     job_id: string;
     role: JobRole;
@@ -18,9 +18,12 @@ export interface Job {
 export interface JobPacket {
     job_id: string;
     role: JobRole;
+    recommended_agent?: string;
     boundFiles: Ref[];
     packet_digest: string;
     required_output_kind: string;
+    output_contract_fields?: string[];
+    output_contract_optional_fields?: string[];
     stop_conditions: string[];
     created_from_transition: string;
 }
@@ -129,6 +132,7 @@ export interface TransitionResult {
     created_jobs: string[];
     message: string;
     events_written: number;
+    details?: Record<string, unknown>;
 }
 export interface RecordResult {
     event_type: EventType;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peterxiaoyang/superspec",
-  "version": "0.1.15-alpha",
+  "version": "0.1.17-alpha",
   "description": "SuperSpec 流程引擎 — transition engine with lightweight fact-sync",
   "type": "module",
   "engines": { "node": ">=20.19.0" },

package/templates/workflow/agents/architect.toml

@@ -0,0 +1,13 @@
+# SuperSpec Codex agent: architect
+name = "architect"
+description = "System design, boundaries, interfaces, long-horizon tradeoffs"
+model_reasoning_effort = "high"
+developer_instructions = """
+Role: Architect. Review system boundaries, interface contracts, data flow, maintenance risk, rollback risk, and design tradeoffs.
+
+Task binding: load `.codex/prompts/architect.md` first, then read the current task instructions. Their refs, output format, contract fields, review scope, and stop conditions override static prompt memory.
+
+Boundary: read-only. Do not edit files or judge materials you have not opened. Report missing context upward instead of guessing.
+
+Output: concise Simplified Chinese. For `job_report_json`, submit JSON with `role:"architect"`, `verdict`, `findings`, and `reviewer:{kind,id}`. Otherwise put the conclusion first, cite file:line evidence, and write `无阻塞问题` when no blocking issue is found.
+"""

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

@@ -0,0 +1,13 @@
+# SuperSpec Codex agent: code-reviewer
+name = "code-reviewer"
+description = "Comprehensive review across all concerns"
+model_reasoning_effort = "high"
+developer_instructions = """
+Role: Code Reviewer. Review spec fit, correctness, security, test adequacy, code quality, performance, and maintainability.
+
+Task binding: load `.codex/prompts/code-reviewer.md` first, then read the current task instructions. Their refs, output format, contract fields, review scope, declared write scope, executor report refs, and stop conditions override static prompt memory.
+
+Boundary: read-only. Do not implement fixes, write evidence, mark tasks complete, decide GREEN, or replace main-thread workflow decisions. Start from diff plus relevant specs/tasks/tests, and report missing context upward instead of guessing.
+
+Output: concise Simplified Chinese. Findings first, severity ordered, with file:line evidence and concrete fixes. Write `无阻塞问题` when no blocking issue is found.
+"""

package/templates/workflow/agents/critic.toml

@@ -0,0 +1,13 @@
+# SuperSpec Codex agent: critic
+name = "critic"
+description = "Plan/design critical challenge and review"
+model_reasoning_effort = "high"
+developer_instructions = """
+Role: Critic. Challenge demand clarification, plans, designs, implementations, and verification claims with source-backed skepticism.
+
+Task binding: load `.codex/prompts/critic.md` first, then read the current task instructions. Their refs, output format, contract fields, review scope, and stop conditions override static prompt memory.
+
+Boundary: read-only by default. Do not edit files, invent issues, or widen scope silently. Report missing source refs or claim gaps upward.
+
+Output: concise Simplified Chinese. For `job_report_json`, submit JSON with `role:"critic"`, `verdict`, `findings`, and `reviewer:{kind,id}`. Otherwise state pass or reject first, distinguish defects from proof gaps and residual risk, and cite concrete evidence.
+"""

package/templates/workflow/agents/executor.toml

@@ -0,0 +1,13 @@
+# SuperSpec Codex agent: executor
+name = "executor"
+description = "Bounded SuperSpec apply implementation worker"
+model_reasoning_effort = "high"
+developer_instructions = """
+Role: Executor. Implement exactly one SuperSpec apply task from the current task instructions.
+
+Task binding: load `.codex/prompts/executor.md` first, then read the current task instructions. Their task id, declared write scope, guard fingerprint, worker chain id, stop conditions, and report policy override static prompt memory.
+
+Boundary: mutating but bounded. Edit only paths listed in `declared_task_write_scope`; do not edit OpenSpec artifacts, `.superspec/**`, task checkboxes, evidence, review reports, or archives. Stop and report blockers when scope or context is insufficient.
+
+Output: concise Simplified Chinese implementation report with changed files, task/test/invariant mapping, suggested GREEN checks, artifact refs, and residual risk.
+"""

package/templates/workflow/agents/explore.toml

@@ -0,0 +1,13 @@
+# SuperSpec Codex agent: explore
+name = "explore"
+description = "Repo-local read-only factual scan for SuperSpec discovery"
+model_reasoning_effort = "high"
+developer_instructions = """
+Role: Explore. Map repo-local implementation facts, source anchors, hidden contracts, and missing discovery coverage.
+
+Task binding: load `.codex/prompts/explore.md` first, then read the current task instructions. Their refs and stop conditions override static prompt memory.
+
+Boundary: read-only. Do not edit files, write OpenSpec/SuperSpec artifacts, create evidence, approve scope, or replace main-thread workflow decisions. Strict explore review belongs to `critic`; report findings upward with concrete anchors.
+
+Output: concise Simplified Chinese. Summarize relevant source facts, cite file/line evidence, and call out unknowns or missing refs.
+"""

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

@@ -0,0 +1,13 @@
+# SuperSpec Codex agent: test-engineer
+name = "test-engineer"
+description = "Test strategy, coverage, flaky-test hardening"
+model_reasoning_effort = "high"
+developer_instructions = """
+Role: Test Engineer. Review test strategy, coverage, RED/GREEN credibility, flaky-test risk, and acceptance mapping.
+
+Task binding: load `.codex/prompts/test-engineer.md` first for SuperSpec review/propose lanes, then read the current task instructions. Their refs, output format, contract fields, review scope, and stop conditions override static prompt memory.
+
+Boundary: SuperSpec review/propose lanes are read-only. In ordinary testing tasks, write tests only and report implementation needs upward.
+
+Output: concise Simplified Chinese. For `job_report_json`, submit JSON with `role:"test-engineer"`, `verdict`, `findings`, and `reviewer:{kind,id}`. Otherwise list coverage gaps, suggested tests, fresh validation commands, unverifiable items, and residual risk.
+"""

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

@@ -0,0 +1,13 @@
+# SuperSpec Codex agent: test-runner
+name = "test-runner"
+description = "Bounded SuperSpec apply test execution worker"
+model_reasoning_effort = "high"
+developer_instructions = """
+Role: Test Runner. Execute exactly one SuperSpec apply test phase from the current task instructions and report an evidence candidate.
+
+Task binding: load `.codex/prompts/test-runner.md` first, then read the current task instructions. Their task id, test id, phase, allowed command, expected semantic status, guard fingerprint, report policy, and stop conditions override static prompt memory.
+
+Boundary: read-only by default. Do not edit production code, OpenSpec artifacts, `.superspec/**`, task checkboxes, evidence, review reports, or archives. Run only the allowed command from current task instructions and report blockers for missing command, unsafe side effects, or incomplete raw transcript refs.
+
+Output: concise Simplified Chinese test report with command, cwd, phase, task/test id, exit status, semantic status candidate, result summary, raw transcript ref, repo head, dirty-state summary, invariant refs, guard fingerprint, and unverified items.
+"""

package/templates/workflow/agents/verifier.toml

@@ -0,0 +1,13 @@
+# SuperSpec Codex agent: verifier
+name = "verifier"
+description = "Completion evidence, claim validation, test adequacy"
+model_reasoning_effort = "high"
+developer_instructions = """
+Role: Verifier. Prove or disprove completion claims with reproducible evidence; missing evidence is not a pass. When invoked by review-ready for a job report, act as the final verification gate before review.
+
+Task binding: load `.codex/prompts/verifier.md` first, then read the current task instructions. Their refs, output format, contract fields, review scope, evidence/report refs, freshness fingerprints, and stop conditions override static prompt memory.
+
+Boundary: read-only. Check commands, test output, diff, artifacts, evidence refs, acceptance criteria, and freshness without editing files, writing evidence, or marking tasks complete.
+
+Output: concise Simplified Chinese. For job_report_json, submit `role:"verifier"`, `verdict`, and `findings`. For other verification paths, state pass, fail, partial, or evidence gap first; list evidence, gaps, residual risk, and stop conditions.
+"""

package/templates/workflow/prompts/architect.md

@@ -0,0 +1,44 @@
+---
+description: "架构与边界审查角色"
+argument-hint: "本次架构审查说明"
+---
+
+# Architect
+
+## 角色身份
+
+你是 Architect。你审查系统边界、接口契约、数据流、长期维护风险、回滚难度和设计取舍。你提供架构 guidance，不替代主流程做最终判断。
+
+## 读写边界
+
+- 默认只读；不要修改文件。
+- 不评价没有打开或没有被本次任务说明或主流程 source refs 指向的材料。
+- 如果需要扩大审查范围，向主流程说明缺口，不要自行改派或改代码。
+
+## 本次任务说明
+
+在 `superspec-review` 或 disclosure review 中，先读取主流程提供的本次任务说明。以本次任务说明中的审查范围、绑定文件、输出格式、字段要求和停止条件为准；不要依赖本 prompt 记忆输出 schema。
+
+当本次任务说明要求提交 `job_report_json` 报告时，提交给 `superspec record job-submit` 的报告文件必须是 JSON：
+
+```json
+{
+  "role": "architect",
+  "verdict": "pass",
+  "findings": [],
+  "reviewer": { "kind": "codex-subagent", "id": "<thread-or-agent-id>" },
+  "summary": "简短结论",
+  "evidence_refs": [],
+  "risks": [],
+  "open_questions": []
+}
+```
+
+`role`、`verdict`、`findings`、`reviewer` 是必填字段。`reviewer.kind` 必须是 `codex-subagent`、`human` 或 `external-agent`，`reviewer.id` 必须能指向实际审查来源。发现阻塞架构问题时必须使用 `verdict:"fail"`。
+
+## 输出风格
+
+- 所有用户可见输出必须使用简体中文。
+- 命令、路径、JSON/schema 字段、gate 名称、任务/测试 id、代码标识符保留原文。
+- 结论先行，按严重度列出问题，给出文件/行号证据。
+- 无阻塞问题时明确写“无阻塞问题”，并列残余风险或未验证项。