@peterxiaoyang/superspec 0.1.24 → 0.1.26

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

@@ -1,15 +1,15 @@
 #!/usr/bin/env node
 // SuperSpec 流程引擎 — CLI 入口
-import { join } from "node:path";
 import { execFileSync } from "node:child_process";
 import { createInterface } from "node:readline/promises";
+import { readFileSync } from "node:fs";
 import { installProject } from "./install.js";
 import { writeSnapshot } from "./store.js";
 import { rebuildSnapshot } from "./sync.js";
 import { next as nextCmd } from "./next.js";
 import { proposeReady, commitTransition, transitionInit, transitionExplore, startApply, taskStart, taskComplete, reopen, reviewReady, accept, archive } from "./transition.js";
-import { recordJobSubmit, recordUserDecision, jobsList, jobsPacket } from "./record.js";
-import { recordTestRun } from "./task.js";
+import { recordJobSubmit, recordJobSubmitContent, recordUserDecision, recordUserDecisionContent, jobsList, jobsPacket } from "./record.js";
+import { recordTestRun, recordTestRunContent } from "./task.js";
 import { probeOpenSpec, openspecStatus, changeRoot } from "./openspec.js";
 import { SUPERSPEC_VERSION } from "./version.js";
 const PACKAGE_NAME = "@peterxiaoyang/superspec";
@@ -42,6 +42,28 @@ function parseFlags(args) {
     }
     return opts;
 }
+class StdinRecordInputError extends Error {
+    constructor(flag) {
+        super(`${flag} - 需要通过 pipe 或重定向提供 JSON；不方便时请使用文件路径。`);
+        this.name = "StdinRecordInputError";
+    }
+}
+function readStdinRecordContent(flag) {
+    if (process.stdin.isTTY === true) {
+        throw new StdinRecordInputError(flag);
+    }
+    return readFileSync(0, "utf8");
+}
+function 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)
@@ -342,9 +364,9 @@ transition 子命令：
   review-ready / accept / archive
 
 record 子命令：
-  job-submit --job <J> --report <F>
-  user-decision --input <F>
-  test-run --input <F>
+  job-submit --job <J> --report <F|->
+  user-decision --input <F|->
+  test-run --input <F|->
 
 jobs 子命令：
   list / packet --job <J>
@@ -482,12 +504,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;
@@ -497,7 +519,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;
@@ -507,7 +529,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;
@@ -522,23 +544,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}`);
@@ -555,7 +577,19 @@ jobs 子命令：
                             console.error("record job-submit 需要 --job 和 --report");
                             return 1;
                         }
-                        const result = recordJobSubmit(projectRoot, change, cr, jobId, report);
+                        let result;
+                        try {
+                            result = report === "-"
+                                ? recordJobSubmitContent(projectRoot, change, cr, jobId, readStdinRecordContent("--report"))
+                                : recordJobSubmit(projectRoot, change, cr, jobId, report);
+                        }
+                        catch (err) {
+                            if (err instanceof StdinRecordInputError) {
+                                console.error(err.message);
+                                return 1;
+                            }
+                            throw err;
+                        }
                         console.log(JSON.stringify(result, null, 2));
                         return result.accepted ? 0 : 1;
                     }
@@ -565,7 +599,19 @@ jobs 子命令：
                             console.error("record user-decision 需要 --input");
                             return 1;
                         }
-                        const result = recordUserDecision(projectRoot, change, inputFile);
+                        let result;
+                        try {
+                            result = inputFile === "-"
+                                ? recordUserDecisionContent(projectRoot, change, readStdinRecordContent("--input"))
+                                : recordUserDecision(projectRoot, change, inputFile);
+                        }
+                        catch (err) {
+                            if (err instanceof StdinRecordInputError) {
+                                console.error(err.message);
+                                return 1;
+                            }
+                            throw err;
+                        }
                         console.log(JSON.stringify(result, null, 2));
                         return result.accepted ? 0 : 1;
                     }
@@ -575,7 +621,19 @@ jobs 子命令：
                             console.error("record test-run 需要 --input");
                             return 1;
                         }
-                        const result = recordTestRun(projectRoot, change, inputFile);
+                        let result;
+                        try {
+                            result = inputFile === "-"
+                                ? recordTestRunContent(projectRoot, change, readStdinRecordContent("--input"))
+                                : recordTestRun(projectRoot, change, inputFile);
+                        }
+                        catch (err) {
+                            if (err instanceof StdinRecordInputError) {
+                                console.error(err.message);
+                                return 1;
+                            }
+                            throw err;
+                        }
                         console.log(JSON.stringify(result, null, 2));
                         return result.accepted ? 0 : 1;
                     }

package/dist/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.d.ts

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