sdd-flow-kit 1.3.6 → 1.3.11

package/README.md

@@ -80,6 +80,39 @@ node ./node_modules/sdd-flow-kit/dist/postinstall.js
 
 #### 变更记录
 
+**1.3.11** — PRD 自动修复改为「每项最多 3 次」
+
+- 每轮只修 `prd-diff` 仍失败的剩余项；8 项已修好则下轮只盯剩下 2 项
+- 单项重试时 prompt 附「上次错误代码 + 错误描述」摘要，避免重复同样错误
+- 状态持久化：`.prd-remediate-state.json`；单项 3 次仍失败 → 写入 08 待人工确认
+
+**1.3.10** — PRD 自动修复支持多 Agent
+
+- `prd-remediate` 按项目安装环境自动选择 Cursor / Claude Code / Codex / OpenClaw
+- Claude Code 安装（`.claude/skills`）时默认用 `claude -p` 执行修复，不限于 Cursor
+- 可用 `--agent claude-code` 或 `SDD_FLOW_KIT_ENABLE_*_AUTORUN=0` 控制
+
+**1.3.9** — PRD 不一致自动修复循环（最多 3 次）
+
+- 新增 `prd-remediate`：`prd-diff` 失败 → 按 `09` 生成修复指引 → 调 AI 工具 `/opsx-apply` 修代码 → 再 `prd-diff`（**每项**最多 3 次）
+- 3 次仍失败：自动写入 `08`「待人工确认汇总」，状态 `待人工确认（自动修复3次未果）`
+- `validate` 内置上述循环；escalated 后 `needUserConfirm=true`
+
+**1.3.8** — PRD 脚本语义 diff + 全量测试覆盖门禁
+
+- 新增 `prd-diff`：机械提取 PRD 字面量，在 `src/`/`e2e/` 中搜索，生成 `09-PRD语义diff报告.md`
+- `gate prd-coverage` 增强：校验 08 证据路径真实存在、08 结论与脚本 diff 一致、可验证 PRD 须有自动化测试 + E2E
+- 解决「08 看起来合规但实际对比不准」：08 标「一致」但代码无 PRD 字面量 → gate 失败
+- 解决「E2E 只覆盖主路径」：所有 `ui-verifiable` / `behavior-verifiable` PRD 原子须在测试中引用 PRD-ID 或字面量，且须有 E2E
+- 所有声明 `e2e` 类型的 AC（含 P1/P2 边缘场景）均须有 e2e/ 下测试
+
+**1.3.7** — 强制验收与 PRD 一致性复查
+
+- `validate` 强制 E2E：缺 Playwright 时自动 `pnpm add -D @playwright/test` + `playwright install chromium`
+- 新增 `gate prd-coverage`：最细粒度 PRD 原子全覆盖 + 08 报告合规 + P0 AC 测试映射
+- 新增 `prd-review` 命令与 `08-PRD一致性复查报告.md` / 提示词（禁止揣摩、禁止兜底，不一致按 PRD 修复）
+- `deliver` 前必须通过 `prd-coverage` 门禁
+
 **1.3.3** — Confluence PRD 拉取修复（ADI 长标题页）
 
 - `confluence-doc.py`：匹配时统一 `-`/`_`；ADI 增加 `ADI_V*结算` 关键词

package/dist/cli.js

@@ -17,6 +17,9 @@ const runPhaseAdvance_1 = require("./steps/runPhaseAdvance");
 const runPropose_1 = require("./steps/runPropose");
 const runValidate_1 = require("./steps/runValidate");
 const runDeliver_1 = require("./steps/runDeliver");
+const runPrdReview_1 = require("./steps/runPrdReview");
+const runPrdDiff_1 = require("./steps/runPrdDiff");
+const runPrdRemediate_1 = require("./steps/runPrdRemediate");
 const bootstrap_1 = require("./core/bootstrap");
 const projectRoots_1 = require("./core/projectRoots");
 const ALLOWED_AGENTS = ["cursor", "claude-code", "codex", "openclaw", "custom"];
@@ -60,6 +63,14 @@ function printHelp() {
         "   npx sdd-flow-kit gate --project-root . --run-id <runId> --expect docs-closed",
         "   npx sdd-flow-kit gate --project-root . --run-id <runId> --expect ac-ready --change <name>",
         "   npx sdd-flow-kit gate --project-root . --run-id <runId> --expect ac-signed",
+        "   npx sdd-flow-kit gate --project-root . --run-id <runId> --expect prd-coverage --change <name>",
+        "",
+        "10) PRD 一致性复查（最细粒度，交付前强制）：",
+        "   npx sdd-flow-kit prd-review --project-root . --run-id <runId>",
+        "   # 在 AI 工具执行 openspec/PRD/<runId>/08-PRD一致性复查提示词.md",
+        "   npx sdd-flow-kit prd-diff --project-root . --run-id <runId>",
+        "   npx sdd-flow-kit prd-remediate --project-root . --run-id <runId> --change <name>",
+        "   npx sdd-flow-kit gate --project-root . --run-id <runId> --expect prd-coverage",
         "   npx sdd-flow-kit gate --project-root . --run-id <runId> --expect impl-allowed --change <name>",
         "   npx sdd-flow-kit gate --project-root . --run-id <runId> --expect validate-pass --change <name>",
         "",
@@ -102,6 +113,7 @@ async function main() {
         "docs-closed",
         "ac-ready",
         "ac-signed",
+        "prd-coverage",
         "propose-ready",
         "impl-allowed",
         "validate-pass",
@@ -126,6 +138,9 @@ async function main() {
         cmd !== "phase" &&
         cmd !== "propose" &&
         cmd !== "validate" &&
+        cmd !== "prd-review" &&
+        cmd !== "prd-diff" &&
+        cmd !== "prd-remediate" &&
         cmd !== "deliver") {
         printHelp();
         process_1.default.exitCode = 1;
@@ -169,6 +184,9 @@ async function main() {
         "phase",
         "propose",
         "validate",
+        "prd-review",
+        "prd-diff",
+        "prd-remediate",
         "deliver",
     ]);
     if (!skipBootstrap && !dryRun && bootstrapCommands.has(cmd)) {
@@ -268,6 +286,54 @@ async function main() {
             process_1.default.exitCode = 1;
         return;
     }
+    if (cmd === "prd-review") {
+        const result = await (0, runPrdReview_1.runPrdReview)({
+            projectRoot,
+            runId,
+            dryRun,
+        });
+        // eslint-disable-next-line no-console
+        console.log(result.ok ? `✅ ${result.detail}` : `❌ ${result.detail}`);
+        if (!result.ok)
+            process_1.default.exitCode = 1;
+        return;
+    }
+    if (cmd === "prd-diff") {
+        const result = await (0, runPrdDiff_1.runPrdDiff)({
+            projectRoot,
+            runId,
+            dryRun,
+        });
+        // eslint-disable-next-line no-console
+        console.log(result.ok ? `✅ ${result.detail}` : `❌ ${result.detail}`);
+        if (!result.ok)
+            process_1.default.exitCode = 1;
+        return;
+    }
+    if (cmd === "prd-remediate") {
+        if (!changeName) {
+            // eslint-disable-next-line no-console
+            console.error("prd-remediate 需要 --change <kebab-name>");
+            process_1.default.exitCode = 1;
+            return;
+        }
+        const result = await (0, runPrdRemediate_1.runPrdRemediate)({
+            projectRoot,
+            runId,
+            change: changeName,
+            agent,
+            dryRun,
+        });
+        // eslint-disable-next-line no-console
+        console.log(result.ok ? `✅ ${result.detail}` : `❌ ${result.detail}`);
+        if (result.needUserConfirm) {
+            // eslint-disable-next-line no-console
+            console.warn("⚠️ 自动修复 3 次未果，已写入 08 待人工确认汇总，需人工裁定后继续。");
+        }
+        if (!result.ok)
+            process_1.default.exitCode = 1;
+        return;
+    }
     if (cmd === "deliver") {
         if (!changeName) {
             // eslint-disable-next-line no-console

package/dist/core/agentRemediateInvoke.js

@@ -0,0 +1,188 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isRemediateAutorunEnabled = isRemediateAutorunEnabled;
+exports.resolveRemediateAgent = resolveRemediateAgent;
+exports.invokeAgentOpsxRemediate = invokeAgentOpsxRemediate;
+exports.agentRemediateHint = agentRemediateHint;
+const child_process_1 = require("child_process");
+const path_1 = __importDefault(require("path"));
+const fs_1 = require("./fs");
+const opsxDelivery_1 = require("./opsxDelivery");
+const opsxDelivery_2 = require("./opsxDelivery");
+function hasCommand(cmd) {
+    return (0, child_process_1.spawnSync)("which", [cmd], { stdio: "ignore" }).status === 0;
+}
+const AGENT_LABEL = {
+    cursor: "Cursor",
+    "claude-code": "Claude Code",
+    codex: "Codex",
+    openclaw: "OpenClaw",
+    custom: "Custom Agent",
+};
+/** PRD 自动修复：默认允许已选 agent 自动执行（可用环境变量关闭） */
+function isRemediateAutorunEnabled(agent) {
+    if (process.env.SDD_FLOW_KIT_ENABLE_AGENT_AUTORUN === "0")
+        return false;
+    switch (agent) {
+        case "cursor":
+            return process.env.SDD_FLOW_KIT_ENABLE_CURSOR_AUTORUN !== "0";
+        case "claude-code":
+            return process.env.SDD_FLOW_KIT_ENABLE_CLAUDE_AUTORUN !== "0";
+        case "codex":
+            return process.env.SDD_FLOW_KIT_ENABLE_CODEX_AUTORUN !== "0";
+        case "openclaw":
+            return process.env.SDD_FLOW_KIT_ENABLE_OPENCLAW_AUTORUN !== "0";
+        default:
+            return false;
+    }
+}
+/** 根据项目已安装的 skills 目录解析修复用 agent */
+async function resolveRemediateAgent(projectRoot, preferred) {
+    const pref = preferred && preferred !== "custom" ? preferred : undefined;
+    const resolved = await (0, opsxDelivery_1.resolveOpsxAgent)(projectRoot, pref !== null && pref !== void 0 ? pref : "claude-code");
+    if (resolved !== "custom" && hasAgentCli(resolved))
+        return resolved;
+    const candidates = ["claude-code", "cursor", "codex", "openclaw"];
+    for (const name of candidates) {
+        if (await hasAgentSkillDir(projectRoot, name) && hasAgentCli(name))
+            return name;
+    }
+    for (const name of candidates) {
+        if (hasAgentCli(name))
+            return name;
+    }
+    return pref !== null && pref !== void 0 ? pref : "claude-code";
+}
+async function hasAgentSkillDir(projectRoot, agent) {
+    const map = {
+        cursor: ".cursor/skills/sdd-flow-kit/SKILL.md",
+        "claude-code": ".claude/skills/sdd-flow-kit/SKILL.md",
+        codex: ".codex/skills/sdd-flow-kit/SKILL.md",
+        openclaw: ".openclaw/skills/sdd-flow-kit/SKILL.md",
+    };
+    const rel = map[agent];
+    if (!rel)
+        return false;
+    return (0, opsxDelivery_2.pathExists)(path_1.default.join(projectRoot, rel));
+}
+function hasAgentCli(agent) {
+    switch (agent) {
+        case "cursor":
+            return hasCommand("cursor");
+        case "claude-code":
+            return hasCommand("claude");
+        case "codex":
+            return hasCommand("codex");
+        case "openclaw":
+            return hasCommand("openclaw");
+        default:
+            return false;
+    }
+}
+function runAgentCommand(agent, projectRoot, outputRoot, prompt) {
+    switch (agent) {
+        case "cursor":
+            return (0, child_process_1.spawnSync)("cursor", ["agent", "--print", "--trust", "--workspace", projectRoot, prompt], { cwd: outputRoot, encoding: "utf8", env: process.env });
+        case "claude-code":
+            return (0, child_process_1.spawnSync)("claude", ["-p", prompt], {
+                cwd: projectRoot,
+                encoding: "utf8",
+                env: process.env,
+            });
+        case "codex": {
+            const withExec = (0, child_process_1.spawnSync)("codex", ["exec", prompt], {
+                cwd: projectRoot,
+                encoding: "utf8",
+                env: process.env,
+            });
+            if (withExec.status === 0 || withExec.stdout || withExec.stderr)
+                return withExec;
+            return (0, child_process_1.spawnSync)("codex", ["-p", prompt], {
+                cwd: projectRoot,
+                encoding: "utf8",
+                env: process.env,
+            });
+        }
+        case "openclaw": {
+            const withRun = (0, child_process_1.spawnSync)("openclaw", ["run", prompt], {
+                cwd: projectRoot,
+                encoding: "utf8",
+                env: process.env,
+            });
+            if (withRun.status === 0 || withRun.stdout || withRun.stderr)
+                return withRun;
+            return (0, child_process_1.spawnSync)("openclaw", ["-p", prompt], {
+                cwd: projectRoot,
+                encoding: "utf8",
+                env: process.env,
+            });
+        }
+        default:
+            return { status: 1, stdout: "", stderr: "unsupported agent" };
+    }
+}
+async function writeRemediateLog(outputRoot, attempt, agent, label, result) {
+    var _a;
+    await (0, fs_1.writeTextFileEnsuredDir)(path_1.default.join(outputRoot, `PRD-REMEDIATE-LOG-第${attempt}次.md`), [
+        `# PRD 自动修复日志（第 ${attempt} 次）`,
+        "",
+        `agent: ${label} (${agent})`,
+        `exit: ${(_a = result.status) !== null && _a !== void 0 ? _a : "unknown"}`,
+        "",
+        "## stdout",
+        result.stdout || "",
+        "",
+        "## stderr",
+        result.stderr || "",
+    ].join("\n"));
+}
+/**
+ * 调用已安装 AI 工具执行 /opsx-apply 修复（Cursor / Claude Code / Codex / OpenClaw）。
+ */
+async function invokeAgentOpsxRemediate(args) {
+    var _a, _b;
+    const agent = args.agent;
+    const label = (_a = AGENT_LABEL[agent]) !== null && _a !== void 0 ? _a : agent;
+    if (!isRemediateAutorunEnabled(agent)) {
+        await writeRemediateLog(args.outputRoot, args.attempt, agent, label, {
+            status: null,
+            stdout: "",
+            stderr: `${label} autorun 已关闭（环境变量）`,
+        });
+        return { ok: false, agent, detail: `${label} autorun 已关闭（环境变量）` };
+    }
+    if (!hasAgentCli(agent)) {
+        await writeRemediateLog(args.outputRoot, args.attempt, agent, label, {
+            status: null,
+            stdout: "",
+            stderr: `未检测到 ${label} CLI`,
+        });
+        return { ok: false, agent, detail: `未检测到 ${label} CLI，请手动执行 10-PRD自动修复指引` };
+    }
+    const result = runAgentCommand(agent, args.projectRoot, args.outputRoot, args.prompt);
+    await writeRemediateLog(args.outputRoot, args.attempt, agent, label, result);
+    if (result.status !== 0) {
+        return { ok: false, agent, detail: `${label} 执行退出码 ${(_b = result.status) !== null && _b !== void 0 ? _b : 1}` };
+    }
+    const complete = /PRD_REMEDIATE=COMPLETE/i.test(result.stdout || "");
+    return {
+        ok: complete,
+        agent,
+        detail: complete ? `${label} 修复完成` : `${label} 已执行但未输出 PRD_REMEDIATE=COMPLETE`,
+    };
+}
+function agentRemediateHint(agent) {
+    switch (agent) {
+        case "claude-code":
+            return "在 Claude Code 中执行 **/opsx-apply**（或阅读本文件后让 claude -p 执行）";
+        case "codex":
+            return "在 Codex 中执行修复指引（或 `codex exec` 读本文件）";
+        case "openclaw":
+            return "在 OpenClaw 中执行修复指引";
+        default:
+            return "在 Cursor 中执行 **/opsx-apply**";
+    }
+}

package/dist/core/playwrightEnsure.js

@@ -0,0 +1,142 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hasPlaywrightDependency = hasPlaywrightDependency;
+exports.ensurePlaywright = ensurePlaywright;
+exports.runMandatoryE2e = runMandatoryE2e;
+const child_process_1 = require("child_process");
+const promises_1 = __importDefault(require("fs/promises"));
+const path_1 = __importDefault(require("path"));
+const packageJsonPatch_1 = require("./packageJsonPatch");
+async function detectPackageManager(pkgRoot) {
+    try {
+        await promises_1.default.access(path_1.default.join(pkgRoot, "pnpm-lock.yaml"));
+        return "pnpm";
+    }
+    catch {
+        /* continue */
+    }
+    try {
+        await promises_1.default.access(path_1.default.join(pkgRoot, "yarn.lock"));
+        return "yarn";
+    }
+    catch {
+        /* continue */
+    }
+    return "npm";
+}
+async function readPkg(pkgRoot) {
+    try {
+        const text = await promises_1.default.readFile(path_1.default.join(pkgRoot, "package.json"), "utf8");
+        return JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+}
+async function hasPlaywrightDependency(pkgRoot) {
+    const pkg = await readPkg(pkgRoot);
+    if (!pkg)
+        return false;
+    const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+    return Boolean(deps["@playwright/test"] || deps.playwright);
+}
+function runCmd(cmd, args, cwd) {
+    var _a;
+    const ret = (0, child_process_1.spawnSync)(cmd, args, {
+        cwd,
+        stdio: "inherit",
+        shell: process.platform === "win32",
+        env: process.env,
+    });
+    if (ret.status !== 0) {
+        return { ok: false, detail: `${cmd} ${args.join(" ")} 退出码 ${(_a = ret.status) !== null && _a !== void 0 ? _a : 1}` };
+    }
+    return { ok: true, detail: "ok" };
+}
+/**
+ * 强制确保 Playwright 可用：缺依赖则安装，缺浏览器则 install chromium，缺 test:e2e 则写入脚本。
+ */
+async function ensurePlaywright(pkgRoot, dryRun = false) {
+    var _a;
+    const pkg = await readPkg(pkgRoot);
+    if (!pkg) {
+        return { ok: false, detail: "无法读取 package.json", installed: false };
+    }
+    const pm = await detectPackageManager(pkgRoot);
+    let installed = false;
+    if (!(await hasPlaywrightDependency(pkgRoot))) {
+        if (dryRun) {
+            return {
+                ok: false,
+                detail: `dry-run: 将安装 @playwright/test（${pm}）`,
+                installed: false,
+            };
+        }
+        const addArgs = pm === "pnpm"
+            ? ["add", "-D", "@playwright/test"]
+            : pm === "yarn"
+                ? ["add", "-D", "@playwright/test"]
+                : ["install", "-D", "@playwright/test"];
+        const add = runCmd(pm, addArgs, pkgRoot);
+        if (!add.ok) {
+            return { ok: false, detail: `安装 @playwright/test 失败: ${add.detail}`, installed: false };
+        }
+        installed = true;
+    }
+    if (!((_a = pkg.scripts) === null || _a === void 0 ? void 0 : _a["test:e2e"])) {
+        if (!dryRun) {
+            await (0, packageJsonPatch_1.patchPackageJsonScripts)(path_1.default.join(pkgRoot, "package.json"), { "test:e2e": "playwright test" }, { minDependencyCount: 1, minBytes: 40, minSizeRatio: 0.3 });
+        }
+    }
+    if (dryRun) {
+        return { ok: true, detail: "dry-run: Playwright 已就绪", installed };
+    }
+    const browsers = runCmd("npx", ["playwright", "install", "chromium"], pkgRoot);
+    if (!browsers.ok) {
+        return { ok: false, detail: `playwright install chromium 失败: ${browsers.detail}`, installed };
+    }
+    return { ok: true, detail: installed ? "已安装 @playwright/test 与 chromium" : "Playwright 已就绪", installed };
+}
+/** 强制执行 E2E（先 ensurePlaywright，再跑 test:e2e 或 playwright test） */
+async function runMandatoryE2e(pkgRoot, dryRun = false) {
+    var _a, _b, _c;
+    const ensured = await ensurePlaywright(pkgRoot, dryRun);
+    if (!ensured.ok) {
+        return { ok: false, exitCode: 1, detail: ensured.detail };
+    }
+    if (dryRun) {
+        return { ok: true, exitCode: 0, detail: "dry-run: would run playwright test" };
+    }
+    const pkg = await readPkg(pkgRoot);
+    if ((_a = pkg === null || pkg === void 0 ? void 0 : pkg.scripts) === null || _a === void 0 ? void 0 : _a["test:e2e"]) {
+        const pm = await detectPackageManager(pkgRoot);
+        const runScript = pm === "yarn" ? ["run", "test:e2e"] : ["run", "test:e2e"];
+        const ret = (0, child_process_1.spawnSync)(pm, runScript, {
+            cwd: pkgRoot,
+            stdio: "inherit",
+            shell: process.platform === "win32",
+            env: { ...process.env, CI: "1" },
+        });
+        const code = (_b = ret.status) !== null && _b !== void 0 ? _b : 1;
+        return {
+            ok: code === 0,
+            exitCode: code,
+            detail: code === 0 ? "test:e2e 全通过" : `test:e2e 退出码 ${code}`,
+        };
+    }
+    const ret = (0, child_process_1.spawnSync)("npx", ["playwright", "test"], {
+        cwd: pkgRoot,
+        stdio: "inherit",
+        shell: process.platform === "win32",
+        env: { ...process.env, CI: "1" },
+    });
+    const code = (_c = ret.status) !== null && _c !== void 0 ? _c : 1;
+    return {
+        ok: code === 0,
+        exitCode: code,
+        detail: code === 0 ? "playwright test 全通过" : `playwright test 退出码 ${code}`,
+    };
+}