sdd-flow-kit 1.0.27 → 1.1.0

package/dist/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.toRunOptions = exports.parseInvokeText = exports.runDoctor = exports.setupProject = exports.runFlow = exports.startFlowScaffold = void 0;
+exports.loadRunSession = exports.resolveRunDir = exports.runDeliver = exports.runPropose = exports.runPhaseAdvance = exports.printGateResult = exports.runGate = exports.toRunOptions = exports.parseInvokeText = exports.runDoctor = exports.setupProject = exports.runFlow = exports.startFlowScaffold = void 0;
 var startFlow_1 = require("./steps/startFlow");
 Object.defineProperty(exports, "startFlowScaffold", { enumerable: true, get: function () { return startFlow_1.startFlowScaffold; } });
 var runFlow_1 = require("./steps/runFlow");
@@ -12,3 +12,15 @@ Object.defineProperty(exports, "runDoctor", { enumerable: true, get: function ()
 var invokeFlow_1 = require("./steps/invokeFlow");
 Object.defineProperty(exports, "parseInvokeText", { enumerable: true, get: function () { return invokeFlow_1.parseInvokeText; } });
 Object.defineProperty(exports, "toRunOptions", { enumerable: true, get: function () { return invokeFlow_1.toRunOptions; } });
+var runGate_1 = require("./steps/runGate");
+Object.defineProperty(exports, "runGate", { enumerable: true, get: function () { return runGate_1.runGate; } });
+Object.defineProperty(exports, "printGateResult", { enumerable: true, get: function () { return runGate_1.printGateResult; } });
+var runPhaseAdvance_1 = require("./steps/runPhaseAdvance");
+Object.defineProperty(exports, "runPhaseAdvance", { enumerable: true, get: function () { return runPhaseAdvance_1.runPhaseAdvance; } });
+var runPropose_1 = require("./steps/runPropose");
+Object.defineProperty(exports, "runPropose", { enumerable: true, get: function () { return runPropose_1.runPropose; } });
+var runDeliver_1 = require("./steps/runDeliver");
+Object.defineProperty(exports, "runDeliver", { enumerable: true, get: function () { return runDeliver_1.runDeliver; } });
+var resolveRun_1 = require("./steps/resolveRun");
+Object.defineProperty(exports, "resolveRunDir", { enumerable: true, get: function () { return resolveRun_1.resolveRunDir; } });
+Object.defineProperty(exports, "loadRunSession", { enumerable: true, get: function () { return resolveRun_1.loadRunSession; } });

package/dist/steps/resolveRun.js

@@ -0,0 +1,61 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveRunDir = resolveRunDir;
+exports.loadRunSession = loadRunSession;
+const promises_1 = __importDefault(require("fs/promises"));
+const path_1 = __importDefault(require("path"));
+const sessionState_1 = require("../core/sessionState");
+const fs_1 = require("../core/fs");
+/**
+ * 解析 openspec/PRD 目录：优先 --run-id，否则取最近修改的 run 目录。
+ */
+async function resolveRunDir(projectRoot, runId) {
+    const candidates = [
+        path_1.default.join(projectRoot, "openspec", "PRD"),
+        path_1.default.join(projectRoot, "frontend", "openspec", "PRD"),
+    ];
+    for (const prdRoot of candidates) {
+        try {
+            const entries = await promises_1.default.readdir(prdRoot, { withFileTypes: true });
+            const dirs = entries.filter((e) => e.isDirectory()).map((e) => e.name);
+            if (dirs.length === 0)
+                continue;
+            if (runId) {
+                if (!dirs.includes(runId))
+                    continue;
+                const outputRoot = path_1.default.join(prdRoot, runId);
+                return { runId, outputRoot, prdRoot };
+            }
+            let latest = null;
+            for (const name of dirs) {
+                const full = path_1.default.join(prdRoot, name);
+                const st = await promises_1.default.stat(full);
+                if (!latest || st.mtimeMs > latest.mtime) {
+                    latest = { name, mtime: st.mtimeMs };
+                }
+            }
+            if (!latest)
+                continue;
+            const outputRoot = path_1.default.join(prdRoot, latest.name);
+            return { runId: latest.name, outputRoot, prdRoot };
+        }
+        catch {
+            // 目录不存在，尝试下一个候选
+        }
+    }
+    return null;
+}
+async function loadRunSession(projectRoot, runId) {
+    const resolved = await resolveRunDir(projectRoot, runId);
+    if (!resolved)
+        return null;
+    const raw = await (0, fs_1.readFileIfExists)(path_1.default.join(resolved.outputRoot, ".session-state.json"));
+    if (!raw)
+        return { resolved, session: null };
+    const parsed = JSON.parse(raw);
+    const session = (0, sessionState_1.normalizeSession)(parsed, resolved.outputRoot);
+    return { resolved, session };
+}

package/dist/steps/runDeliver.js

@@ -0,0 +1,82 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runDeliver = runDeliver;
+const path_1 = __importDefault(require("path"));
+const child_process_1 = require("child_process");
+const resolveRun_1 = require("./resolveRun");
+const runGate_1 = require("./runGate");
+const opsxDelivery_1 = require("../core/opsxDelivery");
+const fs_1 = require("../core/fs");
+async function resolvePackageRoot(projectRoot) {
+    const fe = path_1.default.join(projectRoot, "frontend", "package.json");
+    if (await (0, opsxDelivery_1.pathExists)(fe)) {
+        return path_1.default.join(projectRoot, "frontend");
+    }
+    return projectRoot;
+}
+/**
+ * 实现阶段交付：先 gate impl-allowed，再 ensure-opsx，再跑 opsx:delivery-pipeline，写入 .delivery-pass.json。
+ */
+async function runDeliver(options) {
+    var _a;
+    const loaded = await (0, resolveRun_1.loadRunSession)(options.projectRoot, options.runId);
+    if (!(loaded === null || loaded === void 0 ? void 0 : loaded.resolved)) {
+        return { ok: false, detail: "未找到 PRD run" };
+    }
+    const implGate = await (0, runGate_1.runGate)({
+        projectRoot: options.projectRoot,
+        runId: loaded.resolved.runId,
+        expect: "impl-allowed",
+        change: options.change,
+    });
+    if (!implGate.ok) {
+        (0, runGate_1.printGateResult)(implGate);
+        return { ok: false, detail: "impl-allowed gate 未通过" };
+    }
+    const pkgRoot = await resolvePackageRoot(options.projectRoot);
+    const agent = options.agent || "cursor";
+    if (options.dryRun) {
+        return { ok: true, detail: `dry-run: would deliver in ${pkgRoot}` };
+    }
+    const ensured = await (0, opsxDelivery_1.ensureOpsxWorkflow)({
+        projectRoot: pkgRoot,
+        agent,
+        dryRun: false,
+    });
+    if (!ensured.ready) {
+        return { ok: false, detail: "ensure-opsx 未就绪" };
+    }
+    let exitCode = 0;
+    if (!options.skipPipeline) {
+        const ret = (0, child_process_1.spawnSync)("pnpm", ["run", "opsx:delivery-pipeline", "--", options.change], {
+            cwd: pkgRoot,
+            stdio: "inherit",
+            shell: process.platform === "win32",
+        });
+        exitCode = (_a = ret.status) !== null && _a !== void 0 ? _a : 1;
+    }
+    const passPayload = {
+        change: options.change,
+        exitCode,
+        at: new Date().toISOString(),
+        projectRoot: pkgRoot,
+    };
+    await (0, fs_1.writeTextFileEnsuredDir)(path_1.default.join(loaded.resolved.outputRoot, ".delivery-pass.json"), `${JSON.stringify(passPayload, null, 2)}\n`);
+    if (exitCode !== 0) {
+        return { ok: false, detail: `delivery-pipeline 退出码 ${exitCode}` };
+    }
+    const shipped = await (0, runGate_1.runGate)({
+        projectRoot: options.projectRoot,
+        runId: loaded.resolved.runId,
+        expect: "shipped",
+        change: options.change,
+    });
+    (0, runGate_1.printGateResult)(shipped);
+    if (!shipped.ok) {
+        return { ok: false, detail: "pipeline 已跑但 shipped gate 未通过（检查 tasks.md）" };
+    }
+    return { ok: true, detail: "交付完成" };
+}

package/dist/steps/runGate.js

@@ -0,0 +1,220 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runGate = runGate;
+exports.printGateResult = printGateResult;
+const path_1 = __importDefault(require("path"));
+const prdArtifacts_1 = require("../core/prdArtifacts");
+const gitDiffGuard_1 = require("../core/gitDiffGuard");
+const openspecGate_1 = require("../core/openspecGate");
+const resolveRun_1 = require("./resolveRun");
+const fs_1 = require("../core/fs");
+function fail(checks, expect, runId) {
+    return { ok: false, expect, runId, checks };
+}
+function pass(checks, expect, runId) {
+    return { ok: checks.every((c) => c.ok), expect, runId, checks };
+}
+async function readActiveChange(projectRoot, session, override) {
+    if (override)
+        return override;
+    if (session === null || session === void 0 ? void 0 : session.activeChange)
+        return session.activeChange;
+    const rootCandidates = [projectRoot, path_1.default.join(projectRoot, "frontend")];
+    for (const root of rootCandidates) {
+        const text = await (0, fs_1.readFileIfExists)(path_1.default.join(root, ".opsx-active-change"));
+        if (text) {
+            const line = text
+                .split("\n")
+                .map((l) => l.trim())
+                .find(Boolean);
+            if (line)
+                return line;
+        }
+    }
+    return null;
+}
+function resolveImplRoots(projectRoot) {
+    const roots = [path_1.default.resolve(projectRoot)];
+    const fe = path_1.default.join(projectRoot, "frontend");
+    if (fe !== roots[0])
+        roots.push(path_1.default.resolve(fe));
+    return roots;
+}
+/**
+ * 脚本门禁：失败时 process.exitCode=1，成功 exit 0。
+ */
+async function runGate(options) {
+    const loaded = await (0, resolveRun_1.loadRunSession)(options.projectRoot, options.runId);
+    const checks = [];
+    if (!loaded || !loaded.resolved) {
+        checks.push({ name: "run-resolved", ok: false, detail: "未找到 openspec/PRD/<runId> 目录" });
+        return fail(checks, options.expect, null);
+    }
+    const { resolved, session } = loaded;
+    const outputRoot = resolved.outputRoot;
+    const runId = resolved.runId;
+    const implRoots = resolveImplRoots(options.projectRoot);
+    if (options.expect === "prd-fetched") {
+        const prd = await (0, prdArtifacts_1.isPrdFetched)(outputRoot);
+        checks.push({ name: "prd-fetched", ...prd });
+        return pass(checks, options.expect, runId);
+    }
+    if (options.expect === "questions-open") {
+        const closed = await (0, prdArtifacts_1.isQuestionsClosed)(outputRoot);
+        checks.push({
+            name: "questions-open",
+            ok: !closed.ok,
+            detail: closed.ok ? "矛盾点已闭合，不应处于提问模式" : "提问模式有效（未闭合）",
+        });
+        return pass(checks, options.expect, runId);
+    }
+    if (options.expect === "docs-closed") {
+        const prd = await (0, prdArtifacts_1.isPrdFetched)(outputRoot);
+        checks.push({ name: "prd-fetched", ...prd });
+        const closed = await (0, prdArtifacts_1.isQuestionsClosed)(outputRoot);
+        checks.push({ name: "questions-closed", ...closed });
+        const docs = await (0, prdArtifacts_1.areAnalysisDocsReady)(outputRoot);
+        checks.push({ name: "analysis-docs", ...docs });
+        if (session && session.docModeOnly === false) {
+            checks.push({
+                name: "doc-mode",
+                ok: false,
+                detail: "session.docModeOnly=false，请先处于文档阶段（勿提前 phase advance --to impl）",
+            });
+        }
+        else if (session) {
+            checks.push({ name: "doc-mode", ok: true, detail: "docModeOnly=true" });
+        }
+        else {
+            checks.push({ name: "doc-mode", ok: true, detail: "无 session，跳过 docModeOnly 校验" });
+        }
+        for (const root of implRoots) {
+            const gitRoot = (0, gitDiffGuard_1.resolveGitRoot)(root);
+            const diff = (0, gitDiffGuard_1.gitDiffNameOnly)(gitRoot);
+            if (!diff.isRepo) {
+                checks.push({ name: "git-impl-diff", ok: true, detail: "非 git 仓库，跳过 src 改动检测" });
+                continue;
+            }
+            const impl = (0, gitDiffGuard_1.findImplChanges)(diff.changedFiles);
+            checks.push({
+                name: "git-impl-diff",
+                ok: impl.length === 0,
+                detail: impl.length === 0
+                    ? "工作区无业务实现路径改动"
+                    : `禁止在文档阶段修改实现代码: ${impl.slice(0, 8).join(", ")}${impl.length > 8 ? "..." : ""}`,
+            });
+        }
+        return pass(checks, options.expect, runId);
+    }
+    if (options.expect === "propose-ready") {
+        const changeName = await readActiveChange(options.projectRoot, session, options.change);
+        if (!changeName) {
+            checks.push({ name: "active-change", ok: false, detail: "未指定 change（--change 或 .opsx-active-change）" });
+            return fail(checks, options.expect, runId);
+        }
+        const roots = [options.projectRoot, path_1.default.join(options.projectRoot, "frontend")];
+        let found = false;
+        for (const root of roots) {
+            if (await (0, openspecGate_1.changeDirExists)(root, changeName)) {
+                found = true;
+                const st = (0, openspecGate_1.checkOpenspecApplyReady)(root, changeName);
+                checks.push({ name: "openspec-apply-ready", ok: st.applyReady, detail: st.detail });
+                break;
+            }
+        }
+        if (!found) {
+            checks.push({
+                name: "change-dir",
+                ok: false,
+                detail: `openspec/changes/${changeName} 不存在`,
+            });
+        }
+        return pass(checks, options.expect, runId);
+    }
+    if (options.expect === "impl-allowed") {
+        if (!session) {
+            checks.push({ name: "session", ok: false, detail: "缺少 .session-state.json" });
+            return fail(checks, options.expect, runId);
+        }
+        checks.push({
+            name: "doc-mode-off",
+            ok: session.docModeOnly === false,
+            detail: session.docModeOnly === false
+                ? "已进入实现模式 docModeOnly=false"
+                : "仍处文档模式，请执行: sdd-flow-kit phase advance --to impl",
+        });
+        checks.push({
+            name: "phase-d",
+            ok: session.phase === "D" || session.status === "apply_in_progress",
+            detail: `当前 phase=${session.phase}, status=${session.status}`,
+        });
+        const changeName = await readActiveChange(options.projectRoot, session, options.change);
+        if (!changeName) {
+            checks.push({ name: "active-change", ok: false, detail: "未绑定 activeChange" });
+            return fail(checks, options.expect, runId);
+        }
+        const roots = [options.projectRoot, path_1.default.join(options.projectRoot, "frontend")];
+        for (const root of roots) {
+            if (await (0, openspecGate_1.changeDirExists)(root, changeName)) {
+                const st = (0, openspecGate_1.checkOpenspecApplyReady)(root, changeName);
+                checks.push({ name: "openspec-apply-ready", ok: st.applyReady, detail: st.detail });
+                break;
+            }
+        }
+        return pass(checks, options.expect, runId);
+    }
+    if (options.expect === "shipped") {
+        const changeName = await readActiveChange(options.projectRoot, session, options.change);
+        if (!changeName) {
+            checks.push({ name: "active-change", ok: false, detail: "未指定 change" });
+            return fail(checks, options.expect, runId);
+        }
+        const roots = [options.projectRoot, path_1.default.join(options.projectRoot, "frontend")];
+        for (const root of roots) {
+            if (await (0, openspecGate_1.changeDirExists)(root, changeName)) {
+                const tasks = await (0, openspecGate_1.checkTasksAllDone)(root, changeName);
+                checks.push({ name: "tasks-done", ...tasks });
+                const marker = await (0, fs_1.readFileIfExists)(path_1.default.join(outputRoot, ".delivery-pass.json"));
+                if (marker) {
+                    try {
+                        const j = JSON.parse(marker);
+                        const ok = j.exitCode === 0 && (!j.change || j.change === changeName);
+                        checks.push({
+                            name: "delivery-pass",
+                            ok,
+                            detail: ok ? "delivery-pass.json 有效" : "delivery-pass.json 与 change 不匹配或失败",
+                        });
+                    }
+                    catch {
+                        checks.push({ name: "delivery-pass", ok: false, detail: "delivery-pass.json 解析失败" });
+                    }
+                }
+                else {
+                    checks.push({
+                        name: "delivery-pass",
+                        ok: false,
+                        detail: "缺少 .delivery-pass.json，请先执行: sdd-flow-kit deliver --change <name>",
+                    });
+                }
+                break;
+            }
+        }
+        return pass(checks, options.expect, runId);
+    }
+    checks.push({ name: "expect", ok: false, detail: `未知 --expect: ${options.expect}` });
+    return fail(checks, options.expect, runId);
+}
+function printGateResult(result) {
+    var _a;
+    // eslint-disable-next-line no-console
+    console.log(`\n[sdd-flow-kit gate] expect=${result.expect} runId=${(_a = result.runId) !== null && _a !== void 0 ? _a : "?"}`);
+    for (const c of result.checks) {
+        // eslint-disable-next-line no-console
+        console.log(`  [${c.ok ? "OK" : "FAIL"}] ${c.name}: ${c.detail}`);
+    }
+    // eslint-disable-next-line no-console
+    console.log(result.ok ? "\n✅ GATE PASS\n" : "\n❌ GATE FAIL\n");
+}

package/dist/steps/runPhaseAdvance.js

@@ -0,0 +1,195 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runPhaseAdvance = runPhaseAdvance;
+const path_1 = __importDefault(require("path"));
+const runGate_1 = require("./runGate");
+const resolveRun_1 = require("./resolveRun");
+const sessionState_1 = require("../core/sessionState");
+const fs_1 = require("../core/fs");
+const gitDiffGuard_1 = require("../core/gitDiffGuard");
+async function writeNextMd(outputRoot, lines) {
+    const body = ["# NEXT（脚本门禁 — 请按顺序执行）", "", ...lines, ""].join("\n");
+    await (0, fs_1.writeTextFileEnsuredDir)(path_1.default.join(outputRoot, "NEXT.md"), body);
+}
+/**
+ * 阶段推进：先跑 gate，通过后更新 .session-state.json 与 NEXT.md。
+ */
+async function runPhaseAdvance(options) {
+    const loaded = await (0, resolveRun_1.loadRunSession)(options.projectRoot, options.runId);
+    if (!loaded || !loaded.resolved || !loaded.session) {
+        return { ok: false, runId: null, message: "未找到 run 或 .session-state.json" };
+    }
+    const { resolved, session } = loaded;
+    const outputRoot = resolved.outputRoot;
+    const runId = resolved.runId;
+    let gate = await (0, runGate_1.runGate)({
+        projectRoot: options.projectRoot,
+        runId,
+        expect: "prd-fetched",
+        change: options.change,
+    });
+    if (options.to === "after-prd") {
+        gate = await (0, runGate_1.runGate)({ projectRoot: options.projectRoot, runId, expect: "prd-fetched" });
+        if (!gate.ok) {
+            (0, runGate_1.printGateResult)(gate);
+            return { ok: false, runId, message: "gate prd-fetched 未通过" };
+        }
+        const next = {
+            ...session,
+            phase: "A",
+            status: "awaiting_user_confirmation",
+            docModeOnly: true,
+        };
+        if (!options.dryRun) {
+            await (0, sessionState_1.writeSession)(outputRoot, next);
+            await writeNextMd(outputRoot, [
+                "## 当前：阶段 A（需求分析）",
+                "1. 执行 `02-需求分析提示词.md`",
+                "2. 若未闭合：仅更新 `03-待确认问题清单.md`，然后执行：",
+                "```bash",
+                `npx sdd-flow-kit gate --project-root ${options.projectRoot} --run-id ${runId} --expect questions-open`,
+                "```",
+                "3. 用户确认后生成 01/02/04，再执行：",
+                "```bash",
+                `npx sdd-flow-kit phase advance --project-root ${options.projectRoot} --run-id ${runId} --to docs-done`,
+                "```",
+            ]);
+        }
+        return { ok: true, runId, message: "已进入阶段 A（PRD 已就绪）" };
+    }
+    if (options.to === "docs-done") {
+        gate = await (0, runGate_1.runGate)({ projectRoot: options.projectRoot, runId, expect: "docs-closed" });
+        if (!gate.ok) {
+            (0, runGate_1.printGateResult)(gate);
+            return { ok: false, runId, message: "gate docs-closed 未通过（禁止带 src 改动）" };
+        }
+        const next = {
+            ...session,
+            phase: "B",
+            status: "ready_for_propose",
+            docModeOnly: true,
+        };
+        if (!options.dryRun) {
+            await (0, sessionState_1.writeSession)(outputRoot, next);
+            await writeNextMd(outputRoot, [
+                "## 当前：阶段 B 完成 → 进入 C（提案）",
+                "1. 执行 openspec propose（或）：",
+                "```bash",
+                `npx sdd-flow-kit propose --project-root ${options.projectRoot} --run-id ${runId} --change <kebab-name>`,
+                "```",
+                "2. 提案 apply-ready 后：",
+                "```bash",
+                `npx sdd-flow-kit phase advance --project-root ${options.projectRoot} --run-id ${runId} --to propose-done --change <name>`,
+                "```",
+            ]);
+        }
+        return { ok: true, runId, message: "阶段 B 完成，可进入 propose" };
+    }
+    if (options.to === "propose-done") {
+        const changeName = options.change || session.activeChange;
+        if (!changeName) {
+            return { ok: false, runId, message: "需要 --change <name>" };
+        }
+        gate = await (0, runGate_1.runGate)({
+            projectRoot: options.projectRoot,
+            runId,
+            expect: "propose-ready",
+            change: changeName,
+        });
+        if (!gate.ok) {
+            (0, runGate_1.printGateResult)(gate);
+            return { ok: false, runId, message: "gate propose-ready 未通过" };
+        }
+        const next = {
+            ...session,
+            phase: "C",
+            status: "propose_done",
+            docModeOnly: true,
+            activeChange: changeName,
+        };
+        if (!options.dryRun) {
+            await (0, sessionState_1.writeSession)(outputRoot, next);
+            await (0, fs_1.writeTextFileEnsuredDir)(path_1.default.join(options.projectRoot, ".opsx-active-change"), `${changeName}\n`);
+            const fe = path_1.default.join(options.projectRoot, "frontend", ".opsx-active-change");
+            await (0, fs_1.writeTextFileEnsuredDir)(fe, `${changeName}\n`).catch(() => undefined);
+            await writeNextMd(outputRoot, [
+                "## 当前：阶段 C 完成 → 进入 D（实现）",
+                "```bash",
+                `npx sdd-flow-kit phase advance --project-root ${options.projectRoot} --run-id ${runId} --to impl --change ${changeName}`,
+                "```",
+            ]);
+        }
+        return { ok: true, runId, message: `提案就绪: ${changeName}` };
+    }
+    if (options.to === "impl") {
+        const changeName = options.change || session.activeChange;
+        if (!changeName) {
+            return { ok: false, runId, message: "需要 --change <name>" };
+        }
+        gate = await (0, runGate_1.runGate)({
+            projectRoot: options.projectRoot,
+            runId,
+            expect: "propose-ready",
+            change: changeName,
+        });
+        if (!gate.ok) {
+            (0, runGate_1.printGateResult)(gate);
+            return { ok: false, runId, message: "propose 未就绪，禁止进入实现" };
+        }
+        const gitRoot = (0, gitDiffGuard_1.resolveGitRoot)(path_1.default.join(options.projectRoot, "frontend") === path_1.default.join(options.projectRoot)
+            ? options.projectRoot
+            : path_1.default.join(options.projectRoot, "frontend"));
+        const head = (0, gitDiffGuard_1.gitDiffNameOnly)(gitRoot).head;
+        const next = {
+            ...session,
+            phase: "D",
+            status: "apply_in_progress",
+            docModeOnly: false,
+            activeChange: changeName,
+            implGitBaseline: head,
+        };
+        if (!options.dryRun) {
+            await (0, sessionState_1.writeSession)(outputRoot, next);
+            await writeNextMd(outputRoot, [
+                "## 当前：阶段 D（允许修改 src/）",
+                "实现前门禁：",
+                "```bash",
+                `npx sdd-flow-kit gate --project-root ${options.projectRoot} --run-id ${runId} --expect impl-allowed --change ${changeName}`,
+                "```",
+                "完成后交付：",
+                "```bash",
+                `npx sdd-flow-kit deliver --project-root ${options.projectRoot} --run-id ${runId} --change ${changeName}`,
+                "```",
+            ]);
+        }
+        return { ok: true, runId, message: "已进入实现阶段（docModeOnly=false）" };
+    }
+    if (options.to === "shipped") {
+        const changeName = options.change || session.activeChange;
+        gate = await (0, runGate_1.runGate)({
+            projectRoot: options.projectRoot,
+            runId,
+            expect: "shipped",
+            change: changeName,
+        });
+        if (!gate.ok) {
+            (0, runGate_1.printGateResult)(gate);
+            return { ok: false, runId, message: "gate shipped 未通过" };
+        }
+        const next = {
+            ...session,
+            phase: "done",
+            status: "complete",
+            docModeOnly: false,
+        };
+        if (!options.dryRun) {
+            await (0, sessionState_1.writeSession)(outputRoot, next);
+            await writeNextMd(outputRoot, ["## ✅ SDD 流程已完成（delivery-pass）"]);
+        }
+        return { ok: true, runId, message: "流程完成" };
+    }
+    return { ok: false, runId, message: `未知 --to: ${options.to}` };
+}

package/dist/steps/runPropose.js

@@ -0,0 +1,82 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runPropose = runPropose;
+const path_1 = __importDefault(require("path"));
+const child_process_1 = require("child_process");
+const resolveRun_1 = require("./resolveRun");
+const runGate_1 = require("./runGate");
+const fs_1 = require("../core/fs");
+const opsxDelivery_1 = require("../core/opsxDelivery");
+/**
+ * 创建/校验 openspec change，并检查 apply-ready（不代替 AI 写 proposal 正文，但强制 gate）。
+ */
+async function runPropose(options) {
+    const loaded = await (0, resolveRun_1.loadRunSession)(options.projectRoot, options.runId);
+    if (!(loaded === null || loaded === void 0 ? void 0 : loaded.resolved)) {
+        return { ok: false, detail: "未找到 PRD run" };
+    }
+    const docsGate = await (0, runGate_1.runGate)({
+        projectRoot: options.projectRoot,
+        runId: loaded.resolved.runId,
+        expect: "docs-closed",
+    });
+    if (!docsGate.ok) {
+        (0, runGate_1.printGateResult)(docsGate);
+        return { ok: false, detail: "docs-closed gate 未通过，禁止 propose" };
+    }
+    const roots = [options.projectRoot, path_1.default.join(options.projectRoot, "frontend")];
+    let cwd = options.projectRoot;
+    for (const r of roots) {
+        if (await (0, opsxDelivery_1.pathExists)(path_1.default.join(r, "openspec"))) {
+            cwd = r;
+            break;
+        }
+    }
+    if (options.dryRun) {
+        return { ok: true, detail: `dry-run: would openspec new change ${options.change}` };
+    }
+    const exists = (0, child_process_1.spawnSync)("openspec", ["status", "--change", options.change, "--json"], {
+        cwd,
+        encoding: "utf8",
+    });
+    if (exists.status !== 0) {
+        const created = (0, child_process_1.spawnSync)("openspec", ["new", "change", options.change], {
+            cwd,
+            stdio: "inherit",
+        });
+        if (created.status !== 0) {
+            return { ok: false, detail: `openspec new change 失败: ${options.change}` };
+        }
+    }
+    await (0, fs_1.writeTextFileEnsuredDir)(path_1.default.join(cwd, ".opsx-active-change"), `${options.change}\n`);
+    const proposeNote = [
+        "# Propose 脚本检查点",
+        "",
+        `change: \`${options.change}\``,
+        "",
+        "AI 须按 openspec-propose skill 生成 proposal/design/specs/tasks，完成后执行：",
+        "```bash",
+        `npx sdd-flow-kit gate --project-root ${options.projectRoot} --run-id ${loaded.resolved.runId} --expect propose-ready --change ${options.change}`,
+        `npx sdd-flow-kit phase advance --project-root ${options.projectRoot} --run-id ${loaded.resolved.runId} --to propose-done --change ${options.change}`,
+        "```",
+        "",
+    ].join("\n");
+    await (0, fs_1.writeTextFileEnsuredDir)(path_1.default.join(loaded.resolved.outputRoot, "05-openspec-提案草稿.md"), proposeNote);
+    const ready = await (0, runGate_1.runGate)({
+        projectRoot: options.projectRoot,
+        runId: loaded.resolved.runId,
+        expect: "propose-ready",
+        change: options.change,
+    });
+    (0, runGate_1.printGateResult)(ready);
+    if (!ready.ok) {
+        return {
+            ok: false,
+            detail: "change 已创建，但尚未 apply-ready；请生成 artifacts 后重跑 gate propose-ready",
+        };
+    }
+    return { ok: true, detail: `change ${options.change} apply-ready` };
+}