@peterxiaoyang/superspec 0.1.25-beta.0 → 0.1.27

package/README.md

@@ -81,7 +81,7 @@ superspec install
 ```
 
 这条命令的意思是：把 SuperSpec 当前可用的工作流入口安装到项目里。
-当前 beta 会安装 `.superspec/` 引擎目录、`.codex/skills/superspec-*` 阶段入口、`.codex/prompts/*.md` 角色 prompt、`.codex/agents/*.toml` 子智能体配置，并补齐 `.codex/config.toml` 的多 agent 开关。`superspec init --scope project` 仍作为兼容别名可用。
+当前 beta 会安装 `.superspec/` 引擎目录、`.codex/skills/superspec-*` 阶段入口、`.codex/prompts/*.md` 角色 prompt、`.codex/agents/*.toml` 子智能体配置，补齐 `.codex/config.toml` 的多 agent 开关，并在项目根 `AGENTS.md` 中维护 SuperSpec 轻量门禁片段。`superspec init --scope project` 仍作为兼容别名可用。
 
 Windows PowerShell 如果拦截 npm 的 `.ps1` 脚本，请改用：
 
@@ -160,6 +160,14 @@ openspec/changes/<变更ID>/.superspec/
 `.superspec/` 要不要提交到 git，由你的团队决定。
 如果不提交，删掉后就没有 git 历史可以恢复。
 
+## 流程门禁
+
+SuperSpec 的阶段入口由 `superspec transition next --change <变更ID>` 驱动。
+
+当当前阶段还有未完成的用户确认、审查、验证或工作项时，`next` 会先返回这些事项，不会把下一阶段命令作为推荐路径。重复运行会创建审查工作项的 transition 时，如果同阶段工作项已经存在，CLI 会返回正常的门禁结果，不会写入新事件，也不会把它当作程序错误。
+
+这仍然是轻量流程控制，不是写入拦截。它约束按 SuperSpec 正常入口执行时的下一步建议和状态提交结果，不承诺阻止绕过流程的手动编辑。
+
 ## Hook 会做什么
 
 SuperSpec 默认安装的 hook 只在子智能体启动和停止时运行：
@@ -238,7 +246,7 @@ superspec status
 superspec update
 ```
 
-这条命令会先检查 npm 上的 latest 版本；如果有新版，会自动执行全局升级并用新版 CLI 重新同步项目入口。同步内容包括补齐 `.superspec/changes` 运行时目录，并把当前 CLI 内置的 `.codex/skills/superspec-*`、`.codex/prompts/*.md`、`.codex/agents/*.toml` 同步到项目里。
+这条命令会先检查 npm 上的 latest 版本；如果有新版，会自动执行全局升级并用新版 CLI 重新同步项目入口。同步内容包括补齐 `.superspec/changes` 运行时目录，把当前 CLI 内置的 `.codex/skills/superspec-*`、`.codex/prompts/*.md`、`.codex/agents/*.toml` 同步到项目里，并更新 `AGENTS.md` 中 marker 包裹的 SuperSpec 轻量门禁片段。
 
 ## 进阶信息
 

package/dist/cli.js

@@ -54,6 +54,16 @@ function readStdinRecordContent(flag) {
     }
     return readFileSync(0, "utf8");
 }
+function transitionExitCode(result) {
+    if (result.outcome === "blocked")
+        return 0;
+    return result.events_written === 0 ? 1 : 0;
+}
+function proposeReadyExitCode(result) {
+    if (result.outcome === "blocked")
+        return 0;
+    return result.events_written === 0 && result.message.includes("不能") ? 1 : 0;
+}
 function parseVersion(version) {
     const match = version.trim().match(/^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/);
     if (!match)
@@ -106,6 +116,18 @@ function isTestMode() {
 function testEnv(name) {
     return isTestMode() ? process.env[name] : undefined;
 }
+function runtimePlatform() {
+    return testEnv("SUPERSPEC_TEST_PLATFORM") ?? process.platform;
+}
+function windowsAwareCommand(name) {
+    return runtimePlatform() === "win32" ? `${name}.cmd` : name;
+}
+function npmCommand() {
+    return windowsAwareCommand("npm");
+}
+function superspecCommand() {
+    return windowsAwareCommand("superspec");
+}
 function selfUpdateError(phase, err, latest = null) {
     return new SelfUpdateError(phase, commandErrorMessage(err), latest);
 }
@@ -147,7 +169,7 @@ function npmLatestVersion() {
     if (testLatest)
         return testLatest;
     try {
-        const output = execFileSync("npm", ["view", PACKAGE_NAME, "version"], { encoding: "utf8" });
+        const output = execFileSync(npmCommand(), ["view", PACKAGE_NAME, "version"], { encoding: "utf8" });
         return output.trim().replace(/^"|"$/g, "");
     }
     catch (err) {
@@ -161,7 +183,7 @@ function installLatestGlobal() {
     if (testEnv("SUPERSPEC_TEST_SKIP_GLOBAL_INSTALL") === "1")
         return;
     try {
-        execFileSync("npm", ["install", "-g", `${PACKAGE_NAME}@latest`], {
+        execFileSync(npmCommand(), ["install", "-g", `${PACKAGE_NAME}@latest`], {
             encoding: "utf8",
             stdio: ["ignore", "pipe", "pipe"],
         });
@@ -188,7 +210,7 @@ function pathCliVersion() {
             throw new Error(`无法解析 superspec --version 输出：${testOutput}`);
         return parsed;
     }
-    const output = execFileSync("superspec", ["--version"], {
+    const output = execFileSync(superspecCommand(), ["--version"], {
         encoding: "utf8",
         env: process.env,
     });
@@ -217,7 +239,7 @@ function rerunUpdatedCli(projectRoot, args) {
     if (testOutput)
         return testOutput;
     try {
-        return execFileSync("superspec", args, {
+        return execFileSync(superspecCommand(), args, {
             cwd: projectRoot,
             encoding: "utf8",
             env: process.env,
@@ -494,12 +516,12 @@ jobs 子命令：
                         const risk = opts.risk ?? "strict";
                         const result = proposeReady(projectRoot, change, cr, risk);
                         console.log(JSON.stringify(result, null, 2));
-                        return result.events_written === 0 && result.message.includes("不能") ? 1 : 0;
+                        return proposeReadyExitCode(result);
                     }
                     case "start-apply": {
                         const result = startApply(projectRoot, change, cr);
                         console.log(JSON.stringify(result, null, 2));
-                        return result.events_written === 0 ? 1 : 0;
+                        return transitionExitCode(result);
                     }
                     case "task-start": {
                         const taskId = opts.task;
@@ -509,7 +531,7 @@ jobs 子命令：
                         }
                         const result = taskStart(projectRoot, change, cr, taskId);
                         console.log(JSON.stringify(result, null, 2));
-                        return result.events_written === 0 ? 1 : 0;
+                        return transitionExitCode(result);
                     }
                     case "task-complete": {
                         const taskId = opts.task;
@@ -519,7 +541,7 @@ jobs 子命令：
                         }
                         const result = taskComplete(projectRoot, change, cr, taskId);
                         console.log(JSON.stringify(result, null, 2));
-                        return result.events_written === 0 ? 1 : 0;
+                        return transitionExitCode(result);
                     }
                     case "reopen": {
                         const to = opts.to;
@@ -534,23 +556,23 @@ jobs 子命令：
                         }
                         const result = reopen(projectRoot, change, cr, to, reason);
                         console.log(JSON.stringify(result, null, 2));
-                        return result.events_written === 0 ? 1 : 0;
+                        return transitionExitCode(result);
                     }
                     case "review-ready": {
                         const risk = opts.risk ?? "strict";
                         const result = reviewReady(projectRoot, change, cr, risk);
                         console.log(JSON.stringify(result, null, 2));
-                        return result.events_written === 0 ? 1 : 0;
+                        return transitionExitCode(result);
                     }
                     case "accept": {
                         const result = accept(projectRoot, change, cr);
                         console.log(JSON.stringify(result, null, 2));
-                        return result.events_written === 0 ? 1 : 0;
+                        return transitionExitCode(result);
                     }
                     case "archive": {
                         const result = archive(projectRoot, change, cr);
                         console.log(JSON.stringify(result, null, 2));
-                        return result.events_written === 0 ? 1 : 0;
+                        return transitionExitCode(result);
                     }
                     default:
                         console.error(`未知的 transition 子命令：${subcommand}`);

package/dist/install.d.ts

@@ -10,6 +10,7 @@ export interface InstallResult {
         prompts: string[];
         agents: string[];
         config: string;
+        agents_md: string;
         openspec_config: string;
     };
 }

package/dist/install.js

@@ -55,6 +55,9 @@ function assertWorkflowTemplates(templateRoot) {
         if (!existsSync(file))
             missing.push(file);
     }
+    const agentsMdTemplate = join(templateRoot, "AGENTS.md");
+    if (!existsSync(agentsMdTemplate))
+        missing.push(agentsMdTemplate);
     if (missing.length > 0) {
         throw new Error(`workflow templates missing: ${missing.join(", ")}`);
     }
@@ -66,7 +69,6 @@ function writeBundledFile(src, dest) {
         const current = readFileSync(dest, "utf8");
         if (current === next)
             return;
-        writeFileSync(`${dest}.bak`, current);
     }
     writeFileSync(dest, next);
 }
@@ -242,6 +244,38 @@ function ensureOpenSpecChineseContext(projectRoot) {
     writeFileSync(configPath, next);
     return OPENSPEC_CONFIG_PATH;
 }
+const AGENTS_MD_PATH = "AGENTS.md";
+const SUPERSPEC_AGENTS_START = "<!-- SUPERSPEC:AGENTS:START -->";
+const SUPERSPEC_AGENTS_END = "<!-- SUPERSPEC:AGENTS:END -->";
+function readAgentsMdTemplate(templateRoot) {
+    const template = readFileSync(join(templateRoot, AGENTS_MD_PATH), "utf8").trimEnd();
+    if (!template.includes(SUPERSPEC_AGENTS_START) || !template.includes(SUPERSPEC_AGENTS_END)) {
+        throw new Error(`workflow AGENTS.md template missing SuperSpec markers: ${join(templateRoot, AGENTS_MD_PATH)}`);
+    }
+    return template;
+}
+function replaceMarkerBlock(content, block) {
+    const start = content.indexOf(SUPERSPEC_AGENTS_START);
+    const end = content.indexOf(SUPERSPEC_AGENTS_END);
+    if (start < 0 || end < 0 || end < start)
+        return null;
+    const afterEnd = end + SUPERSPEC_AGENTS_END.length;
+    return `${content.slice(0, start)}${block}${content.slice(afterEnd)}`;
+}
+function ensureAgentsMd(projectRoot, block) {
+    const agentsPath = join(projectRoot, AGENTS_MD_PATH);
+    if (!existsSync(agentsPath)) {
+        writeFileSync(agentsPath, `${block}\n`);
+        return AGENTS_MD_PATH;
+    }
+    const current = readFileSync(agentsPath, "utf8");
+    const replaced = replaceMarkerBlock(current, block);
+    const next = replaced ?? `${current.trimEnd()}\n\n${block}\n`;
+    if (next === current)
+        return AGENTS_MD_PATH;
+    writeFileSync(agentsPath, next);
+    return AGENTS_MD_PATH;
+}
 export function installProject(projectRoot, options = {}) {
     if (!options.allowLegacyState && legacyStateFound(projectRoot)) {
         throw new Error("检测到老版 SuperSpec (0.x) 的状态文件。\n" +
@@ -251,6 +285,7 @@ export function installProject(projectRoot, options = {}) {
     }
     const templateRoot = options.templateRoot ?? defaultTemplateRoot();
     assertWorkflowTemplates(templateRoot);
+    const agentsMdTemplate = readAgentsMdTemplate(templateRoot);
     const engineDir = join(projectRoot, ".superspec");
     mkdirSync(join(engineDir, "changes"), { recursive: true });
     const gitignorePath = join(engineDir, ".gitignore");
@@ -266,6 +301,7 @@ export function installProject(projectRoot, options = {}) {
             prompts: copyPrompts(templateRoot, projectRoot),
             agents: copyAgents(templateRoot, projectRoot),
             config: ensureCodexConfig(projectRoot),
+            agents_md: ensureAgentsMd(projectRoot, agentsMdTemplate),
             openspec_config: ensureOpenSpecChineseContext(projectRoot),
         },
     };

package/dist/job_action.d.ts

@@ -0,0 +1,6 @@
+import type { Job, RequiredJobAction } from "./types.ts";
+export declare function jobPacketCommand(change: string, jobId: string): string;
+export declare function jobPacketArgv(change: string, jobId: string): string[];
+export declare function requiredJobAction(change: string, job: Job): RequiredJobAction;
+export declare function requiredJobActions(change: string, jobs: Job[]): RequiredJobAction[];
+export declare function jobSubmitArgv(change: string, jobId: string): string[];

package/dist/job_action.js

@@ -0,0 +1,21 @@
+// SuperSpec workflow engine - shared job action protocol helpers.
+export function jobPacketCommand(change, jobId) {
+    return `superspec jobs packet --change "${change}" --job "${jobId}"`;
+}
+export function jobPacketArgv(change, jobId) {
+    return ["superspec", "jobs", "packet", "--change", change, "--job", jobId];
+}
+export function requiredJobAction(change, job) {
+    return {
+        job_id: job.job_id,
+        role: job.role,
+        packet_command: jobPacketCommand(change, job.job_id),
+        packet_argv: jobPacketArgv(change, job.job_id),
+    };
+}
+export function requiredJobActions(change, jobs) {
+    return jobs.map(job => requiredJobAction(change, job));
+}
+export function jobSubmitArgv(change, jobId) {
+    return ["superspec", "record", "job-submit", "--change", change, "--job", jobId, "--report", "-"];
+}

package/dist/next.js

@@ -4,13 +4,22 @@ import { readFileSync } from "node:fs";
 import { join } from "node:path";
 import { readEvents, sha256Text } from "./store.js";
 import { isFreshReviewVerifier, isReviewReadyVerifier, readReviewPolicyFromEvents, reviewEvidenceDigest } from "./review.js";
+import { requiredJobActions } from "./job_action.js";
 import { validateDiscovery, countDiscoveryOpenQuestions, collectProposeOpenQuestions, parseTasksMd, pendingTasksInContent } 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 isExploreReviewJob(job) {
+    return job.created_from_transition === "explore" && job.role === "critic";
+}
+function requiredJobsOutput(state, change, jobs, reason) {
+    return {
+        state,
+        path: "required_job",
+        required_jobs: requiredJobActions(change, jobs),
+        reason,
+    };
 }
 function transitionCommand(change, name, extra = "") {
     return `superspec transition ${name} --change "${change}"${extra ? " " + extra : ""}`;
@@ -67,6 +76,9 @@ export function next(projectRoot, change, changeRoot, defaultRisk = "strict") {
     const snapshot = rebuildSnapshot(projectRoot, change, changeRoot);
     switch (snapshot.state) {
         case "init":
+            if (snapshot.open_jobs.length > 0) {
+                return requiredJobsOutput("init", change, snapshot.open_jobs, `有 ${snapshot.open_jobs.length} 个待完成工作项`);
+            }
             return {
                 state: "init",
                 path: "next_command",
@@ -75,6 +87,10 @@ export function next(projectRoot, change, changeRoot, defaultRisk = "strict") {
                 missing_inputs: [],
             };
         case "explore": {
+            const exploreReviewJobs = snapshot.open_jobs.filter(isExploreReviewJob);
+            if (exploreReviewJobs.length > 0) {
+                return requiredJobsOutput("explore", change, exploreReviewJobs, `有 ${exploreReviewJobs.length} 个待完成探索审查工作项`);
+            }
             // Phase 2：检查 discovery.md
             const discoveryCheck = validateDiscovery(changeRoot);
             if (!discoveryCheck.ok) {
@@ -117,17 +133,7 @@ export function next(projectRoot, change, changeRoot, defaultRisk = "strict") {
             }
             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),
-                }));
-                return {
-                    state: "propose",
-                    path: "required_job",
-                    required_jobs: jobs,
-                    reason: `有 ${jobs.length} 个待完成工作项`,
-                };
+                return requiredJobsOutput("propose", change, proposalReviewJobs, `有 ${proposalReviewJobs.length} 个待完成 proposal 审查工作项`);
             }
             return {
                 state: "propose",
@@ -140,16 +146,7 @@ export function next(projectRoot, change, changeRoot, defaultRisk = "strict") {
         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 requiredJobsOutput("propose_ready", change, proposalReviewJobs, `有 ${proposalReviewJobs.length} 个待完成 proposal 审查工作项`);
             }
             return {
                 state: "propose_ready",
@@ -160,6 +157,9 @@ export function next(projectRoot, change, changeRoot, defaultRisk = "strict") {
             };
         }
         case "apply": {
+            if (snapshot.open_jobs.length > 0) {
+                return requiredJobsOutput("apply", change, snapshot.open_jobs, `有 ${snapshot.open_jobs.length} 个待完成工作项`);
+            }
             // 检查是否所有任务已完成
             const pending = pendingTaskIds(changeRoot);
             if (pending.length > 0) {
@@ -190,15 +190,6 @@ export function next(projectRoot, change, changeRoot, defaultRisk = "strict") {
                     missing_inputs: [],
                 };
             }
-            // 有 open job → 做
-            if (snapshot.open_jobs.length > 0) {
-                return {
-                    state: "apply",
-                    path: "required_job",
-                    required_jobs: snapshot.open_jobs.map(j => ({ job_id: j.job_id, role: j.role, packet_command: packetCommand(change, j.job_id) })),
-                    reason: `有 ${snapshot.open_jobs.length} 个待完成工作项`,
-                };
-            }
             return {
                 state: "apply",
                 path: "next_command",
@@ -219,12 +210,7 @@ export function next(projectRoot, change, changeRoot, defaultRisk = "strict") {
                 };
             }
             if (snapshot.open_jobs.length > 0) {
-                return {
-                    state: "apply_done",
-                    path: "required_job",
-                    required_jobs: snapshot.open_jobs.map(j => ({ job_id: j.job_id, role: j.role, packet_command: packetCommand(change, j.job_id) })),
-                    reason: `有 ${snapshot.open_jobs.length} 个待完成工作项`,
-                };
+                return requiredJobsOutput("apply_done", change, snapshot.open_jobs, `有 ${snapshot.open_jobs.length} 个待完成工作项`);
             }
             return {
                 state: "apply_done",
@@ -247,16 +233,7 @@ export function next(projectRoot, change, changeRoot, defaultRisk = "strict") {
             }
             const reviewVerifierJobs = snapshot.open_jobs.filter(isReviewReadyVerifier);
             if (reviewVerifierJobs.length > 0) {
-                return {
-                    state: "review",
-                    path: "required_job",
-                    required_jobs: reviewVerifierJobs.map(j => ({
-                        job_id: j.job_id,
-                        role: j.role,
-                        packet_command: packetCommand(change, j.job_id),
-                    })),
-                    reason: `有 ${reviewVerifierJobs.length} 个待完成最终验证工作项`,
-                };
+                return requiredJobsOutput("review", change, reviewVerifierJobs, `有 ${reviewVerifierJobs.length} 个待完成最终验证工作项`);
             }
             const events = readEvents(projectRoot, change);
             const policy = readReviewPolicyFromEvents(events);
@@ -291,6 +268,9 @@ export function next(projectRoot, change, changeRoot, defaultRisk = "strict") {
             };
         }
         case "accepted":
+            if (snapshot.open_jobs.length > 0) {
+                return requiredJobsOutput("accepted", change, snapshot.open_jobs, `有 ${snapshot.open_jobs.length} 个待完成工作项，暂不归档`);
+            }
             return {
                 state: "accepted",
                 path: "next_command",
@@ -299,11 +279,20 @@ export function next(projectRoot, change, changeRoot, defaultRisk = "strict") {
                 missing_inputs: [],
             };
         case "archive":
+            if (snapshot.open_jobs.length > 0) {
+                return requiredJobsOutput("archive", change, snapshot.open_jobs, `有 ${snapshot.open_jobs.length} 个待完成工作项，暂不结束`);
+            }
             return {
                 state: "archive",
                 path: "done",
                 reason: "已归档，流程完成。",
             };
+        case "abandoned":
+            return {
+                state: "abandoned",
+                path: "done",
+                reason: "变更已放弃，流程终止。",
+            };
         default:
             return {
                 state: snapshot.state,

package/dist/record.js

@@ -3,6 +3,7 @@ import { readFileSync, existsSync } from "node:fs";
 import { join } from "node:path";
 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"]);
@@ -321,6 +322,7 @@ export function jobsPacket(projectRoot, change, jobId) {
             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],

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

@@ -26,12 +26,19 @@ export interface JobPacket {
     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;
@@ -120,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";
@@ -136,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.25-beta.0",
+  "version": "0.1.27",
   "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/skills/superspec-apply/SKILL.md

@@ -19,6 +19,8 @@ metadata:
 3. 登记结果
 4. 回到 1
 
+如果下一步提示当前阶段还有用户确认、审查或验证事项，先完成这些事项。完成前不要继续下一个任务、不要进入下一阶段；对用户说明时使用自然语言，不默认复述内部 JSON 字段或完整 packet。
+
 ## 本阶段做什么
 
 每个任务的循环：

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

@@ -18,6 +18,8 @@ metadata:
 2. 执行返回的命令
 3. 回到 1
 
+如果下一步提示还有用户确认、审查或验证事项，先完成这些事项。完成前不要归档或宣布流程完成；对用户说明时使用自然语言，不默认复述内部 JSON 字段或完整 packet。
+
 ## 本阶段做什么
 
 1. **确认状态为 accepted**：next 会检查

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

@@ -19,7 +19,9 @@ metadata:
 3. 登记结果
 4. 回到 1
 
-next 返回 `ask_user` 说明 discovery 不完整或有未确认问题。若 scope 是 `explore_discovery`，先检查并填写 discovery 草稿，不要把草稿占位内容直接转问用户；只有真实阻塞问题才向用户提问，收到回答后优先用 `superspec record user-decision --change "<change>" --input -` 从 stdin 登记 JSON 内容；文件路径模式仍可作为 fallback。
+如果下一步提示当前阶段还有用户确认、审查或验证事项，先完成这些事项。完成前不要进入下一阶段，也不要修改业务代码；对用户说明时使用自然语言，不默认复述内部 JSON 字段或完整 packet。
+
+如果下一步说明 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 -` 从 stdin 登记 JSON 报告内容；文件路径模式仍可作为 fallback。
 
@@ -52,22 +54,20 @@ next 返回 `ask_user` 说明 discovery 不完整或有未确认问题。若 sco
 
 写入 `openspec/changes/<change>/.superspec/artifacts/discovery.md`：
 
-如果文件已经存在并包含 `<!-- superspec:discovery-draft -->` 或“待探索后...”占位文本，说明它是引擎生成的草稿。完成探索后必须删除草稿标记并替换所有占位内容，否则引擎会继续阻止推进。
-
 ```markdown
 # Discovery
 
-## 当前代码事实
-- src/path.ts:10 当前系统怎么工作
-
 ## 需求理解
-（用户目标和当前实现之间的差异）
+- 用户目标
+
+## 现状
+- 当前系统怎么工作  src/path.ts:10
 
-## 影响范围候选
-- src/path.ts:10 可能受影响的代码表面和相邻风险
+## 影响范围
+- 可能受影响的代码表面和相邻风险
 
 ## 风险和边界
-（技术风险、依赖、兼容性；尽量绑定代码或文档锚点）
+- 技术风险、依赖、兼容性；尽量绑定代码或文档锚点
 
 ## 待确认问题
 - [ ] 问题1的描述

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

@@ -19,7 +19,9 @@ metadata:
 3. 登记结果
 4. 回到 1
 
-next 返回需要审查时，先按返回的审查说明完成对应审查，再优先用 `superspec record job-submit --change "<change>" --job <JOB> --report -` 从 stdin 提交 JSON 审查报告内容；文件路径模式仍可作为 fallback。
+如果下一步提示当前阶段还有用户确认、审查或验证事项，先完成这些事项。完成前不要进入下一阶段，也不要修改业务代码；对用户说明时使用自然语言，不默认复述内部 JSON 字段或完整 packet。
+
+如果下一步需要审查，先按返回的审查说明完成对应审查，再优先用 `superspec record job-submit --change "<change>" --job <JOB> --report -` 从 stdin 提交 JSON 审查报告内容；文件路径模式仍可作为 fallback。
 
 人类可读正文默认使用简体中文；OpenSpec 结构标题、规范关键字、命令、路径、JSON 字段、代码标识符保留原文。
 如果 OpenSpec 生成文档语言不符合预期，先检查 `openspec/config.yaml` 的官方 `context` 设置；不要在变更文档里添加自定义 `language` 字段。

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

@@ -19,7 +19,9 @@ metadata:
 3. 登记结果
 4. 回到 1
 
-next 返回需要 verifier 工作项时，先按返回的验证说明执行核对，再优先用 `superspec record job-submit --change "<change>" --job <JOB> --report -` 从 stdin 提交 JSON 验证报告内容；文件路径模式仍可作为 fallback。
+如果下一步提示当前阶段还有用户确认、审查或验证事项，先完成这些事项。完成前不要 accept 或 archive；对用户说明时使用自然语言，不默认复述内部 JSON 字段或完整 packet。
+
+如果下一步需要 verifier 工作项，先按返回的验证说明执行核对，再优先用 `superspec record job-submit --change "<change>" --job <JOB> --report -` 从 stdin 提交 JSON 验证报告内容；文件路径模式仍可作为 fallback。
 
 `record job-submit` 沿用现有 raw 归档：报告追加到 `raw/review-reports.jsonl`，不会为 review gate 新增 raw 文件类型。