@peterxiaoyang/superspec 0.1.14 → 0.1.16-alpha

package/dist/install.js

@@ -0,0 +1,161 @@
+import { copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+export const WORKFLOW_SKILLS = [
+    "superspec-explore",
+    "superspec-propose",
+    "superspec-apply",
+    "superspec-review",
+    "superspec-archive",
+];
+export const WORKFLOW_PROMPTS = [
+    "architect.md",
+    "code-reviewer.md",
+    "critic.md",
+    "executor.md",
+    "explore.md",
+    "final-audit.md",
+    "proposal-auditor.md",
+    "test-engineer.md",
+    "test-runner.md",
+    "verifier.md",
+];
+export const WORKFLOW_AGENTS = [
+    "architect.toml",
+    "code-reviewer.toml",
+    "critic.toml",
+    "executor.toml",
+    "explore.toml",
+    "final-audit.toml",
+    "proposal-auditor.toml",
+    "test-engineer.toml",
+    "test-runner.toml",
+    "verifier.toml",
+];
+function defaultTemplateRoot() {
+    return join(import.meta.dirname, "..", "templates", "workflow");
+}
+function legacyStateFound(projectRoot) {
+    const changesRoot = join(projectRoot, "openspec", "changes");
+    if (!existsSync(changesRoot))
+        return false;
+    const oldStateFiles = ["superspec-state.json", "superspec-state.lock", "ledger.jsonl"];
+    return oldStateFiles.some(file => readdirSync(changesRoot).some(change => existsSync(join(changesRoot, change, ".superspec", file))));
+}
+function assertWorkflowTemplates(templateRoot) {
+    const missing = [];
+    for (const skill of WORKFLOW_SKILLS) {
+        const file = join(templateRoot, "skills", skill, "SKILL.md");
+        if (!existsSync(file))
+            missing.push(file);
+    }
+    for (const prompt of WORKFLOW_PROMPTS) {
+        const file = join(templateRoot, "prompts", prompt);
+        if (!existsSync(file))
+            missing.push(file);
+    }
+    for (const agent of WORKFLOW_AGENTS) {
+        const file = join(templateRoot, "agents", agent);
+        if (!existsSync(file))
+            missing.push(file);
+    }
+    if (missing.length > 0) {
+        throw new Error(`workflow templates missing: ${missing.join(", ")}`);
+    }
+}
+function copySkills(templateRoot, projectRoot) {
+    const skillsDest = join(projectRoot, ".codex", "skills");
+    const installedSkills = [];
+    for (const skill of WORKFLOW_SKILLS) {
+        const src = join(templateRoot, "skills", skill, "SKILL.md");
+        mkdirSync(join(skillsDest, skill), { recursive: true });
+        copyFileSync(src, join(skillsDest, skill, "SKILL.md"));
+        installedSkills.push(skill);
+    }
+    return installedSkills;
+}
+function copyPrompts(templateRoot, projectRoot) {
+    const promptsDest = join(projectRoot, ".codex", "prompts");
+    const installedPrompts = [];
+    for (const prompt of WORKFLOW_PROMPTS) {
+        const src = join(templateRoot, "prompts", prompt);
+        mkdirSync(promptsDest, { recursive: true });
+        copyFileSync(src, join(promptsDest, prompt));
+        installedPrompts.push(prompt);
+    }
+    return installedPrompts;
+}
+function copyAgents(templateRoot, projectRoot) {
+    const agentsDest = join(projectRoot, ".codex", "agents");
+    const installedAgents = [];
+    for (const agent of WORKFLOW_AGENTS) {
+        const src = join(templateRoot, "agents", agent);
+        mkdirSync(agentsDest, { recursive: true });
+        copyFileSync(src, join(agentsDest, agent));
+        installedAgents.push(agent);
+    }
+    return installedAgents;
+}
+function insertMissingTableEntries(content, table, entries) {
+    const tablePattern = new RegExp(`^\\[${table}\\]\\s*$`, "m");
+    const tableMatch = tablePattern.exec(content);
+    const lines = Object.entries(entries).map(([key, value]) => `${key} = ${value}`);
+    if (!tableMatch) {
+        const separator = content.trim().length === 0 ? "" : "\n\n";
+        return `${content.trimEnd()}${separator}[${table}]\n${lines.join("\n")}\n`;
+    }
+    const tableStart = tableMatch.index;
+    const headerEnd = tableStart + tableMatch[0].length;
+    const nextTable = /^\[[^\]]+\]\s*$/m.exec(content.slice(headerEnd));
+    const tableEnd = nextTable ? headerEnd + nextTable.index : content.length;
+    const tableBody = content.slice(headerEnd, tableEnd);
+    const missing = lines.filter(line => {
+        const key = line.split(" = ", 1)[0];
+        return !new RegExp(`^\\s*${key}\\s*=`, "m").test(tableBody);
+    });
+    if (missing.length === 0)
+        return content;
+    return `${content.slice(0, headerEnd)}\n${missing.join("\n")}${content.slice(headerEnd)}`;
+}
+function ensureCodexConfig(projectRoot) {
+    const codexDir = join(projectRoot, ".codex");
+    const configPath = join(codexDir, "config.toml");
+    mkdirSync(codexDir, { recursive: true });
+    const current = existsSync(configPath) ? readFileSync(configPath, "utf8") : "";
+    let next = insertMissingTableEntries(current, "features", {
+        multi_agent: "true",
+        child_agents_md: "true",
+    });
+    next = insertMissingTableEntries(next, "agents", {
+        max_threads: "12",
+        max_depth: "1",
+    });
+    if (next !== current)
+        writeFileSync(configPath, next);
+    return ".codex/config.toml";
+}
+export function installProject(projectRoot, options = {}) {
+    if (legacyStateFound(projectRoot)) {
+        throw new Error("检测到老版 SuperSpec (0.x) 的状态文件。\n" +
+            "SuperSpec 0.1.16-alpha 是全新引擎，不兼容 0.x 的状态格式。\n" +
+            "请先用老版（0.1.x）完成或归档现有 change，再安装 0.1.16-alpha。\n" +
+            "或在全新项目目录中安装。");
+    }
+    const templateRoot = options.templateRoot ?? defaultTemplateRoot();
+    assertWorkflowTemplates(templateRoot);
+    const engineDir = join(projectRoot, ".superspec");
+    mkdirSync(join(engineDir, "changes"), { recursive: true });
+    const gitignorePath = join(engineDir, ".gitignore");
+    if (!existsSync(gitignorePath))
+        writeFileSync(gitignorePath, "changes/\n*.log\n*.tmp\n");
+    return {
+        ok: true,
+        message: "SuperSpec 0.1.16-alpha 已安装",
+        installed: {
+            engine_dir: ".superspec/",
+            skills: copySkills(templateRoot, projectRoot),
+            prompts: copyPrompts(templateRoot, projectRoot),
+            agents: copyAgents(templateRoot, projectRoot),
+            config: ensureCodexConfig(projectRoot),
+        },
+    };
+}

package/dist/next.d.ts

@@ -0,0 +1,3 @@
+import type { NextOutput } from "./types.ts";
+/** next 命令：读 snapshot，返回唯一可执行路径 */
+export declare function next(projectRoot: string, change: string, changeRoot: string, defaultRisk?: "minimal" | "normal" | "strict"): NextOutput;

package/dist/next.js

@@ -0,0 +1,161 @@
+// SuperSpec 流程引擎 — next：返回可执行路径
+import { rebuildSnapshot } from "./sync.js";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { validateDiscovery, countDiscoveryOpenQuestions } from "./format.js";
+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 : ""}`;
+}
+/** next 命令：读 snapshot，返回唯一可执行路径 */
+export function next(projectRoot, change, changeRoot, defaultRisk = "normal") {
+    const snapshot = rebuildSnapshot(projectRoot, change, changeRoot);
+    switch (snapshot.state) {
+        case "init":
+            return {
+                state: "init",
+                path: "next_command",
+                next_command: transitionCommand(change, "explore"),
+                reason: "初始化完成，开始探索",
+                missing_inputs: [],
+            };
+        case "explore": {
+            // Phase 2：检查 discovery.md
+            const discoveryCheck = validateDiscovery(changeRoot);
+            if (!discoveryCheck.ok) {
+                const ask = {
+                    question: discoveryCheck.message + "，请处理后继续",
+                    allowed_answers: ["已处理"],
+                    scope: "explore_discovery",
+                };
+                return { state: "explore", path: "ask_user", ask_user: ask, reason: discoveryCheck.message };
+            }
+            // 检查"待确认问题"段（用 format.ts 的段感知解析）
+            const content = readFileSync(join(changeRoot, ".superspec", "artifacts", "discovery.md"), "utf8");
+            const openQs = countDiscoveryOpenQuestions(content);
+            if (openQs > 0) {
+                const ask = {
+                    question: `discovery.md 有 ${openQs} 个未解决的待确认问题，请逐个确认`,
+                    allowed_answers: ["所有问题已确认"],
+                    scope: "explore_open_questions",
+                };
+                return { state: "explore", path: "ask_user", ask_user: ask, reason: `有 ${openQs} 个未确认问题` };
+            }
+            return {
+                state: "explore",
+                path: "next_command",
+                next_command: transitionCommand(change, "explore", `--risk ${defaultRisk}`),
+                reason: "探索完成，推进到计划阶段",
+                missing_inputs: [],
+            };
+        }
+        case "propose": {
+            if (snapshot.open_jobs.length > 0) {
+                const jobs = snapshot.open_jobs.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} 个待完成工作项`,
+                };
+            }
+            const riskFlag = `--risk ${defaultRisk}`;
+            return {
+                state: "propose",
+                path: "next_command",
+                next_command: transitionCommand(change, "propose-ready", riskFlag),
+                reason: "计划文档就绪，提交 propose-ready",
+                missing_inputs: [],
+            };
+        }
+        case "propose_ready":
+            return {
+                state: "propose_ready",
+                path: "next_command",
+                next_command: transitionCommand(change, "start-apply"),
+                reason: "计划就绪，开始执行",
+                missing_inputs: [],
+            };
+        case "apply": {
+            // 有 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} 个待完成工作项`,
+                };
+            }
+            // 检查是否所有任务已完成
+            const tasksContent = readFileSync(join(changeRoot, "tasks.md"), "utf8");
+            const allDone = !tasksContent.split("\n").some(l => l.includes("- [ ]"));
+            if (allDone) {
+                return {
+                    state: "apply",
+                    path: "next_command",
+                    next_command: transitionCommand(change, "review-ready"),
+                    reason: "所有任务完成，进入审查",
+                    missing_inputs: [],
+                };
+            }
+            return {
+                state: "apply",
+                path: "next_command",
+                next_command: transitionCommand(change, "task-start", "--task TASK-XXX"),
+                reason: "执行中：查看 tasks.md 找下一个未完成任务",
+                missing_inputs: [],
+            };
+        }
+        case "apply_done": {
+            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 {
+                state: "apply_done",
+                path: "next_command",
+                next_command: transitionCommand(change, "review-ready"),
+                reason: "所有任务完成，进入审查",
+                missing_inputs: [],
+            };
+        }
+        case "review":
+            return {
+                state: "review",
+                path: "next_command",
+                next_command: transitionCommand(change, "accept"),
+                reason: "审查完成，提交接受",
+                missing_inputs: [],
+            };
+        case "accepted":
+            return {
+                state: "accepted",
+                path: "next_command",
+                next_command: transitionCommand(change, "archive"),
+                reason: "审查通过，提交归档",
+                missing_inputs: [],
+            };
+        case "archive":
+            return {
+                state: "archive",
+                path: "done",
+                reason: "已归档，流程完成。",
+            };
+        default:
+            return {
+                state: snapshot.state,
+                path: "done",
+                reason: `状态 ${snapshot.state} 超出 Phase 1 范围`,
+            };
+    }
+}

package/dist/openspec.d.ts

@@ -0,0 +1,9 @@
+export interface OpenSpecProbe {
+    available: boolean;
+    version: string | null;
+    changeExists: boolean;
+    error?: string;
+}
+export declare function probeOpenSpec(projectRoot: string, change?: string): OpenSpecProbe;
+export declare function openspecStatus(projectRoot: string, change: string): string;
+export declare function changeRoot(projectRoot: string, change: string): string;

package/dist/openspec.js

@@ -0,0 +1,41 @@
+// SuperSpec 流程引擎 — OpenSpec 探测
+import { execSync, execFileSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { createHash } from "node:crypto";
+/** B2 修复：校验 change 字符集，防 shell 注入 */
+function validateChange(change) {
+    if (!/^[A-Za-z0-9._-]+$/.test(change)) {
+        throw new Error(`change 名称含非法字符：${change}（只允许字母数字._-）`);
+    }
+}
+export function probeOpenSpec(projectRoot, change) {
+    try {
+        const version = execSync("openspec --version 2>/dev/null", { encoding: "utf8" }).trim();
+        let changeExists = false;
+        if (change) {
+            validateChange(change);
+            changeExists = existsSync(join(projectRoot, "openspec", "changes", change));
+        }
+        return { available: true, version, changeExists };
+    }
+    catch {
+        return { available: false, version: null, changeExists: false, error: "openspec CLI 不可用" };
+    }
+}
+export function openspecStatus(projectRoot, change) {
+    validateChange(change);
+    try {
+        // B2 修复：用 execFileSync 数组传参，彻底避免 shell 解析
+        const result = execFileSync("openspec", ["status", "--change", change, "--json"], {
+            encoding: "utf8", cwd: projectRoot, stdio: ["pipe", "pipe", "ignore"],
+        });
+        return "sha256:" + createHash("sha256").update(result).digest("hex");
+    }
+    catch {
+        return "sha256:unknown";
+    }
+}
+export function changeRoot(projectRoot, change) {
+    return join(projectRoot, "openspec", "changes", change);
+}

package/dist/record.d.ts

@@ -0,0 +1,20 @@
+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 user-decision：登记用户决策 */
+export declare function recordUserDecision(projectRoot: string, change: string, inputFile: string): RecordResult;
+/** jobs list（HIGH-1 修复：从 transition_commit.new_jobs 提取，不再依赖已删除的 job_requested 事件） */
+export declare function jobsList(projectRoot: string, change: string): {
+    open: Job[];
+    accepted: Job[];
+    rejected: {
+        job_id: string;
+        role: string;
+    }[];
+};
+/** jobs packet：返回工作项执行说明 */
+export declare function jobsPacket(projectRoot: string, change: string, jobId: string): {
+    found: boolean;
+    packet?: Record<string, unknown>;
+    message: string;
+};

package/dist/record.js

@@ -0,0 +1,266 @@
+// SuperSpec 流程引擎 — record：工作项结果登记
+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"];
+function recommendedAgentForRole(role) {
+    switch (role) {
+        case "proposal-auditor": return "proposal-auditor";
+        case "critic": return "critic";
+        case "architect": return "architect";
+        case "test-engineer": return "test-engineer";
+        case "final-audit": return "final-audit";
+        case "executor": return "executor";
+        case "test-run": return "test-runner";
+    }
+}
+function roleDescription(role) {
+    switch (role) {
+        case "proposal-auditor":
+            return "审查 proposal/tasks/design/discovery/business-invariants/test-contract 是否足够进入实现计划门";
+        case "critic":
+            return "从反方角度审查需求澄清或计划材料中的隐藏假设、范围漂移、验收漏洞和证据缺口";
+        case "architect":
+            return "审查架构边界、接口契约、长期维护风险和设计取舍";
+        case "test-engineer":
+            return "审查测试契约、覆盖策略、RED/GREEN 可信度和验收场景映射";
+        case "final-audit":
+            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) {
+        if (ev.event_type === "transition_commit") {
+            const newJobs = ev.payload.new_jobs ?? [];
+            const job = newJobs.find(j => j.job_id === jobId);
+            if (job)
+                return job;
+        }
+    }
+    return null;
+}
+/** 检查 job 是否已终态 */
+function jobTerminalState(events, jobId) {
+    for (const ev of events) {
+        if (ev.event_type === "job_accepted" && ev.payload.job_id === jobId)
+            return "accepted";
+        if (ev.event_type === "job_rejected" && ev.payload.job_id === jobId)
+            return "rejected";
+    }
+    return null;
+}
+/** record job-submit：登记工作项结果 */
+export function recordJobSubmit(projectRoot, change, changeRoot, jobId, reportFile) {
+    return withLock(projectRoot, change, () => {
+        ensureChangeLayout(projectRoot, change);
+        const events = readEvents(projectRoot, change);
+        // 查找 job
+        const job = findJob(events, jobId);
+        if (!job) {
+            return { event_type: "job_rejected", accepted: false, message: `工作项 ${jobId} 不存在` };
+        }
+        // 检查终态
+        const terminal = jobTerminalState(events, jobId);
+        if (terminal) {
+            // 幂等检查：同 report_digest → 返回旧结果
+            const reportDigest = sha256File(reportFile) ?? "sha256:unknown";
+            const existing = events.find(e => (e.event_type === "job_accepted" || e.event_type === "job_rejected")
+                && e.payload.job_id === jobId
+                && e.payload.report_digest === reportDigest);
+            if (existing) {
+                return {
+                    event_type: existing.event_type,
+                    accepted: existing.event_type === "job_accepted",
+                    message: "幂等返回：同 report 已提交",
+                    job_state: existing.event_type === "job_accepted" ? "accepted" : "rejected",
+                };
+            }
+            // 终态 job + 不同 report → 拒绝
+            return {
+                event_type: "job_rejected",
+                accepted: false,
+                message: `工作项 ${jobId} 已终态（${terminal}），不接受新报告。需要新工作项请重跑 transition。`,
+            };
+        }
+        // 读报告
+        if (!existsSync(reportFile)) {
+            return { event_type: "job_rejected", accepted: false, message: `报告文件不存在：${reportFile}` };
+        }
+        const reportContent = readFileSync(reportFile, "utf8");
+        const reportDigest = sha256File(reportFile) ?? "sha256:unknown";
+        // acceptance checks
+        const checks = [];
+        // 0. 报告格式和角色匹配（最小 JSON contract）
+        try {
+            const report = JSON.parse(reportContent);
+            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，工作项未通过");
+                }
+            }
+        }
+        catch {
+            checks.push("报告必须是有效 JSON");
+        }
+        // 1. boundFiles 仍匹配当前文档（missing 也算不匹配）
+        for (const bf of job.boundFiles) {
+            const currentSha = sha256File(join(changeRoot, bf.path)) ?? "sha256:missing";
+            if (currentSha !== bf.sha) {
+                checks.push(`绑定文件 ${bf.path} 已变化（${bf.sha} → ${currentSha}）`);
+            }
+        }
+        // 2. 报告格式基本校验（非空 JSON 或文本）
+        if (!reportContent.trim()) {
+            checks.push("报告内容为空");
+        }
+        if (checks.length > 0) {
+            // 拒绝
+            const rejectEvent = makeEvent(change, "job_rejected", {
+                job_id: jobId,
+                role: job.role,
+                report_digest: reportDigest,
+                reason: checks.join("; "),
+            });
+            appendEvent(projectRoot, change, rejectEvent);
+            return {
+                event_type: "job_rejected",
+                accepted: false,
+                message: `工作项 ${jobId} 被拒绝：${checks.join("; ")}`,
+                job_state: "rejected",
+            };
+        }
+        // 接受
+        const acceptEvent = makeEvent(change, "job_accepted", {
+            job_id: jobId,
+            role: job.role,
+            report_digest: reportDigest,
+            accepted_at: new Date().toISOString(),
+        });
+        appendEvent(projectRoot, change, acceptEvent);
+        return {
+            event_type: "job_accepted",
+            accepted: true,
+            message: `工作项 ${jobId}（${job.role}）已接受`,
+            job_state: "accepted",
+        };
+    });
+}
+/** record user-decision：登记用户决策 */
+export function recordUserDecision(projectRoot, change, inputFile) {
+    return withLock(projectRoot, change, () => {
+        ensureChangeLayout(projectRoot, change);
+        if (!existsSync(inputFile)) {
+            appendEvent(projectRoot, change, makeEvent(change, "user_decision_recorded", { accepted: false, reason: "file_not_found", path: inputFile }));
+            return { event_type: "user_decision_recorded", accepted: false, message: `决策文件不存在：${inputFile}` };
+        }
+        const content = readFileSync(inputFile, "utf8");
+        let decision;
+        try {
+            decision = JSON.parse(content);
+        }
+        catch {
+            appendEvent(projectRoot, change, makeEvent(change, "user_decision_recorded", { accepted: false, reason: "invalid_json" }));
+            return { event_type: "user_decision_recorded", accepted: false, message: "决策文件不是有效 JSON" };
+        }
+        if (!decision.scope || !decision.answer) {
+            appendEvent(projectRoot, change, makeEvent(change, "user_decision_recorded", { accepted: false, reason: "missing_scope_or_answer" }));
+            return { event_type: "user_decision_recorded", accepted: false, message: "决策文件缺少 scope 或 answer" };
+        }
+        const event = makeEvent(change, "user_decision_recorded", {
+            scope: decision.scope,
+            question: decision.question ?? "",
+            answer: decision.answer,
+            input_digest: sha256File(inputFile) ?? "sha256:unknown",
+        });
+        appendEvent(projectRoot, change, event);
+        return {
+            event_type: "user_decision_recorded",
+            accepted: true,
+            message: `用户决策已登记：scope=${decision.scope}`,
+        };
+    });
+}
+/** jobs list（HIGH-1 修复：从 transition_commit.new_jobs 提取，不再依赖已删除的 job_requested 事件） */
+export function jobsList(projectRoot, change) {
+    const events = readEvents(projectRoot, change);
+    const open = [];
+    const accepted = [];
+    const rejected = [];
+    for (const ev of events) {
+        if (ev.event_type === "transition_commit") {
+            const newJobs = ev.payload.new_jobs ?? [];
+            for (const job of newJobs) {
+                if (!open.some(j => j.job_id === job.job_id) && !accepted.some(j => j.job_id === job.job_id) && !rejected.some(r => r.job_id === job.job_id)) {
+                    open.push(job);
+                }
+            }
+        }
+        else if (ev.event_type === "job_accepted") {
+            const { job_id } = ev.payload;
+            const idx = open.findIndex(j => j.job_id === job_id);
+            if (idx >= 0) {
+                const job = open.splice(idx, 1)[0];
+                job.state = "accepted";
+                accepted.push(job);
+            }
+        }
+        else if (ev.event_type === "job_rejected") {
+            const { job_id, role } = ev.payload;
+            const idx = open.findIndex(j => j.job_id === job_id);
+            if (idx >= 0)
+                open.splice(idx, 1)[0];
+            rejected.push({ job_id, role });
+        }
+    }
+    return { open, accepted, rejected };
+}
+/** jobs packet：返回工作项执行说明 */
+export function jobsPacket(projectRoot, change, jobId) {
+    const events = readEvents(projectRoot, change);
+    const job = findJob(events, jobId);
+    if (!job) {
+        return { found: false, message: `工作项 ${jobId} 不存在` };
+    }
+    return {
+        found: true,
+        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: "job_report_json",
+            output_contract_fields: [...REVIEW_REPORT_REQUIRED_FIELDS],
+            output_contract_optional_fields: [...REVIEW_REPORT_OPTIONAL_FIELDS],
+            output_instructions: `${roleDescription(job.role)}。请审查 ${job.boundFiles.map(f => f.path).join(", ")}，` +
+                `产出 JSON 报告文件并通过 superspec record job-submit 登记。` +
+                `最小格式：{"role":"${job.role}","verdict":"pass|fail","findings":[]}`,
+            stop_conditions: ["审查完成后提交报告，不要修改文档"],
+            created_from_transition: job.created_from_transition,
+        },
+        message: `工作项 ${jobId} 的执行说明`,
+    };
+}