sdd-flow-kit 1.0.27 → 1.1.1

package/README.md

@@ -73,14 +73,55 @@ npx sdd-flow-kit doctor --agent cursor
 
 #### 使用说明
 
-##### 需求澄清：用户无需背提示词
+##### 安装根：cd 到哪，装到哪（v1.2+）
+
+默认 **`installRoot = 你执行命令时的当前目录`**（`process.cwd()`），也可用 `--project-root` / `SDD_FLOW_KIT_INSTALL_ROOT` 指定。
+
+| 你 cd 到 | 会安装到 |
+|----------|----------|
+| `adInsight-web/frontend` | `frontend/package.json`、`.cursor/skills`、`.opsx`、`pnpm run opsx:delivery-pipeline` |
+| `adInsight-web`（仓库根） | 仓库根（需根目录也有 `package.json`，否则会失败） |
+
+```bash
+cd /path/to/adInsight-web/frontend
+npx sdd-flow-kit install --project ADI -y
+npx sdd-flow-kit run --product ADI --version 2.3.2 -y
+```
+
+**PRD / gate 的 `--project-root`**：与安装根相同；若 `openspec/` 在上级目录，工具会**向上查找**已有 `openspec/PRD`（不把安装写到上级）。
+
+旧行为（在仓库根执行时自动落到 `frontend/`）：设置 `SDD_FLOW_KIT_LEGACY_MONOREPO=1`。
 
-`install` 会写入 `.cursor/rules/sdd-flow-kit-gates.mdc` 与触发 Skill。  
-澄清阶段你**直接粘贴确认点**（编号列表即可），AI 先进入文档模式更新 `openspec/PRD/**`。  
-**默认**：03 闭环并生成 01/02/04 后，**同一回合自动** `/opsx-propose`（01+02+UI）→ `/opsx-apply`，无需再说「继续」。  
-说「只提案」或「先别写代码」可停在提案阶段；设 `autoChainOpsx: false` 可恢复人工分步。
+##### 脚本门禁（v1.1+，**不依赖自然语言**）
+
+`run` 会在 `openspec/PRD/<runId>/NEXT.md` 写入**必须按顺序执行的命令**。AI 与人都以 **exit code** 为准：失败则不得进入下一阶段、不得改 `src/`。
+
+```bash
+# 门禁（失败 exit 1）
+npx sdd-flow-kit gate --project-root . --run-id <runId> --expect prd-fetched
+npx sdd-flow-kit gate --project-root . --run-id <runId> --expect docs-closed      # 检测 git 是否误改 src
+npx sdd-flow-kit gate --project-root . --run-id <runId> --expect propose-ready --change <name>
+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 shipped --change <name>
+
+# 阶段推进（更新 .session-state.json + NEXT.md）
+npx sdd-flow-kit phase advance --project-root . --run-id <runId> --to after-prd
+npx sdd-flow-kit phase advance --project-root . --run-id <runId> --to docs-done
+npx sdd-flow-kit phase advance --project-root . --run-id <runId> --to propose-done --change <name>
+npx sdd-flow-kit phase advance --project-root . --run-id <runId> --to impl --change <name>
+npx sdd-flow-kit phase advance --project-root . --run-id <runId> --to shipped --change <name>
+
+# 提案 / 交付
+npx sdd-flow-kit propose --project-root . --run-id <runId> --change <name>
+npx sdd-flow-kit deliver --project-root . --run-id <runId> --change <name>
+```
+
+`docs-closed` 会在 git 仓库中扫描 `src/`、`frontend/src/` 等路径；文档阶段若已有实现层改动，**gate 失败**。
+
+##### 需求澄清：用户无需背提示词
 
-阶段口语（可选，用于断点续跑）：`继续` / `做提案` / `开始 apply`。
+`install` 会写入 `.cursor/rules/sdd-flow-kit-gates.mdc` 与触发 Skill（已改为**脚本优先**）。  
+用户粘贴确认点后：先更新 01/02/03/04，再执行 `gate docs-closed` → `phase advance --to docs-done`；**禁止**跳过 gate 直接改代码。
 
 ##### `/opsx-apply` 与 TDD + Playwright 检查机制
 
@@ -105,9 +146,10 @@ npx sdd-flow-kit doctor --agent cursor --fix     # 检查并尝试修复
 
 #### 当前自动化边界
 
-- 已支持：跨工具统一目录结构、提示词、报告模板、执行清单
-- 已支持：环境检测与按工具自动执行 `npx @lixin5257xxx/opsx-workflow setup ...`
-- 自动化增强：`claude-code` adapter 支持 `claude -p` 自动执行并记录 `AUTO-RUN-LOG.md`（失败自动降级人工）
+- 已支持：跨工具统一目录结构、提示词、报告模板、**NEXT.md 脚本清单**
+- 已支持：**gate / phase / propose / deliver** 命令（exit code 机械门禁）
+- 已支持：`ensure-opsx` + `openspec status` 校验 apply-ready
+- 未支持：在 Cursor 内全自动跑完全流程（Cursor adapter 仍为 manual）；可选 `SDD_FLOW_KIT_ENABLE_CLAUDE_AUTORUN=1` 给 Claude Code
 
 #### npm 发包流程
 

package/dist/cli.js

@@ -12,6 +12,11 @@ const utils_1 = require("./core/utils");
 const setupProject_1 = require("./steps/setupProject");
 const doctor_1 = require("./steps/doctor");
 const invokeFlow_1 = require("./steps/invokeFlow");
+const runGate_1 = require("./steps/runGate");
+const runPhaseAdvance_1 = require("./steps/runPhaseAdvance");
+const runPropose_1 = require("./steps/runPropose");
+const runDeliver_1 = require("./steps/runDeliver");
+const projectRoots_1 = require("./core/projectRoots");
 const ALLOWED_AGENTS = ["cursor", "claude-code", "codex", "openclaw", "custom"];
 function getArgValue(flag) {
     const idx = process_1.default.argv.indexOf(flag);
@@ -45,10 +50,23 @@ function printHelp() {
         "",
         "6) Apply 前确保 OPSX+TDD+Playwright（/opsx-apply 前必须）：",
         "   npx sdd-flow-kit ensure-opsx --agent cursor -y",
-        "   （缺省时自动 npx @lixin5257xxx/opsx-workflow setup）",
+        "",
+        "7) 脚本门禁（失败 exit 1，不依赖自然语言）：",
+        "   npx sdd-flow-kit gate --project-root . --run-id <runId> --expect prd-fetched",
+        "   npx sdd-flow-kit gate --project-root . --run-id <runId> --expect docs-closed",
+        "   npx sdd-flow-kit gate --project-root . --run-id <runId> --expect impl-allowed --change <name>",
+        "",
+        "8) 阶段推进（更新 session + NEXT.md）：",
+        "   npx sdd-flow-kit phase advance --project-root . --run-id <runId> --to after-prd|docs-done|propose-done|impl|shipped",
+        "",
+        "9) 提案 / 交付：",
+        "   npx sdd-flow-kit propose --project-root . --run-id <runId> --change <name>",
+        "   npx sdd-flow-kit deliver --project-root . --run-id <runId> --change <name>",
         "",
         "可选参数：",
-        "   --projectRoot <path>   目标项目根目录（默认当前目录）",
+        "   --projectRoot <path>   目标项目根目录（默认当前目录 = 安装根，cd 到哪装到哪）",
+        "   环境变量 SDD_FLOW_KIT_INSTALL_ROOT 可覆盖安装根（绝对路径）",
+        "   环境变量 SDD_FLOW_KIT_LEGACY_MONOREPO=1 恢复「仓库根无 package.json 时落到 frontend/」",
         "   --agent <name>         cursor | claude-code | codex | openclaw | custom（默认 claude-code）",
         "   --branch <name>        开发分支；不存在会自动创建",
         "   --project <name>       OMS | ADI | 欢盟 | AD Tools（默认 OMS，用于生成 docs/*-doc-skill）",
@@ -61,32 +79,53 @@ function printHelp() {
     ].join("\n"));
 }
 async function main() {
-    var _a, _b, _c, _d;
+    var _a, _b, _c, _d, _e, _f, _g, _h;
     const cmd = process_1.default.argv[2];
     if (!cmd || cmd === "--help" || cmd === "-h") {
         printHelp();
         return;
     }
+    const GATE_EXPECTS = [
+        "prd-fetched",
+        "questions-open",
+        "docs-closed",
+        "propose-ready",
+        "impl-allowed",
+        "shipped",
+    ];
+    const PHASE_TARGETS = [
+        "after-prd",
+        "docs-done",
+        "propose-done",
+        "impl",
+        "shipped",
+    ];
     if (cmd !== "start" &&
         cmd !== "run" &&
         cmd !== "setup" &&
         cmd !== "install" &&
         cmd !== "doctor" &&
         cmd !== "ensure-opsx" &&
-        cmd !== "invoke") {
+        cmd !== "invoke" &&
+        cmd !== "gate" &&
+        cmd !== "phase" &&
+        cmd !== "propose" &&
+        cmd !== "deliver") {
         printHelp();
         process_1.default.exitCode = 1;
         return;
     }
     const product = getArgValue("--product");
     const version = getArgValue("--version");
-    const projectRoot = (_a = getArgValue("--projectRoot")) !== null && _a !== void 0 ? _a : process_1.default.cwd();
-    const branch = (_b = getArgValue("--branch")) !== null && _b !== void 0 ? _b : undefined;
+    const projectRoot = path_1.default.resolve((_b = (_a = getArgValue("--project-root")) !== null && _a !== void 0 ? _a : getArgValue("--projectRoot")) !== null && _b !== void 0 ? _b : process_1.default.cwd());
+    const runId = (_d = (_c = getArgValue("--run-id")) !== null && _c !== void 0 ? _c : getArgValue("--runId")) !== null && _d !== void 0 ? _d : undefined;
+    const changeName = (_e = getArgValue("--change")) !== null && _e !== void 0 ? _e : undefined;
+    const branch = (_f = getArgValue("--branch")) !== null && _f !== void 0 ? _f : undefined;
     const yes = process_1.default.argv.includes("-y");
     const dryRun = process_1.default.argv.includes("--dry-run");
     const planJson = process_1.default.argv.includes("--plan-json");
-    const agentValue = (_c = getArgValue("--agent")) !== null && _c !== void 0 ? _c : "claude-code";
-    const projectKind = ((_d = getArgValue("--project")) !== null && _d !== void 0 ? _d : "OMS");
+    const agentValue = (_g = getArgValue("--agent")) !== null && _g !== void 0 ? _g : "claude-code";
+    const projectKind = ((_h = getArgValue("--project")) !== null && _h !== void 0 ? _h : "OMS");
     if (!ALLOWED_AGENTS.includes(agentValue)) {
         // eslint-disable-next-line no-console
         console.error(`不支持的 --agent: ${agentValue}`);
@@ -102,10 +141,96 @@ async function main() {
         process_1.default.exitCode = 1;
         return;
     }
+    if (cmd === "gate") {
+        const expect = getArgValue("--expect");
+        if (!expect || !GATE_EXPECTS.includes(expect)) {
+            // eslint-disable-next-line no-console
+            console.error(`gate 需要 --expect ${GATE_EXPECTS.join("|")}`);
+            process_1.default.exitCode = 1;
+            return;
+        }
+        const result = await (0, runGate_1.runGate)({
+            projectRoot,
+            runId,
+            expect,
+            change: changeName,
+        });
+        (0, runGate_1.printGateResult)(result);
+        if (!result.ok)
+            process_1.default.exitCode = 1;
+        return;
+    }
+    if (cmd === "phase") {
+        const sub = process_1.default.argv[3];
+        if (sub !== "advance") {
+            // eslint-disable-next-line no-console
+            console.error("用法: sdd-flow-kit phase advance --to <target> ...");
+            process_1.default.exitCode = 1;
+            return;
+        }
+        const to = getArgValue("--to");
+        if (!to || !PHASE_TARGETS.includes(to)) {
+            // eslint-disable-next-line no-console
+            console.error(`需要 --to ${PHASE_TARGETS.join("|")}`);
+            process_1.default.exitCode = 1;
+            return;
+        }
+        const result = await (0, runPhaseAdvance_1.runPhaseAdvance)({
+            projectRoot,
+            runId,
+            to,
+            change: changeName,
+            dryRun,
+        });
+        // eslint-disable-next-line no-console
+        console.log(result.ok ? `✅ ${result.message}` : `❌ ${result.message}`);
+        if (!result.ok)
+            process_1.default.exitCode = 1;
+        return;
+    }
+    if (cmd === "propose") {
+        if (!changeName) {
+            // eslint-disable-next-line no-console
+            console.error("propose 需要 --change <kebab-name>");
+            process_1.default.exitCode = 1;
+            return;
+        }
+        const result = await (0, runPropose_1.runPropose)({
+            projectRoot,
+            runId,
+            change: changeName,
+            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 === "deliver") {
+        if (!changeName) {
+            // eslint-disable-next-line no-console
+            console.error("deliver 需要 --change <kebab-name>");
+            process_1.default.exitCode = 1;
+            return;
+        }
+        const result = await (0, runDeliver_1.runDeliver)({
+            projectRoot,
+            runId,
+            change: changeName,
+            agent,
+            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 === "doctor" || cmd === "ensure-opsx") {
         const fix = cmd === "ensure-opsx" || process_1.default.argv.includes("--fix");
         const doctor = await (0, doctor_1.runDoctor)({
-            projectRoot: path_1.default.resolve(projectRoot),
+            projectRoot,
             agent,
             fix,
             dryRun,
@@ -122,7 +247,7 @@ async function main() {
         }
         if (cmd === "ensure-opsx" && !dryRun) {
             await (0, setupProject_1.setupProject)({
-                projectRoot: path_1.default.resolve(projectRoot),
+                projectRoot,
                 agent,
                 yes: true,
                 light: true,
@@ -134,8 +259,10 @@ async function main() {
         return;
     }
     if (cmd === "setup" || cmd === "install") {
+        // eslint-disable-next-line no-console
+        console.log(`[sdd-flow-kit] 安装根 installRoot=${(0, projectRoots_1.resolveInstallRoot)(projectRoot)} (cwd=${process_1.default.cwd()})`);
         const result = await (0, setupProject_1.setupProject)({
-            projectRoot: path_1.default.resolve(projectRoot),
+            projectRoot,
             agent,
             branch,
             yes,
@@ -172,10 +299,9 @@ async function main() {
             if (!parsed) {
                 throw new Error("invoke 解析失败，请使用：开发 ADI 2.3.2 需求");
             }
-            const resolvedRoot = path_1.default.resolve(projectRoot);
             const options = (0, invokeFlow_1.toRunOptions)({
                 parsed,
-                projectRoot: resolvedRoot,
+                projectRoot,
                 branch,
                 yes,
                 dryRun,
@@ -194,22 +320,23 @@ async function main() {
         process_1.default.exitCode = 1;
         return;
     }
-    const resolvedRoot = path_1.default.resolve(projectRoot);
-    const runId = `${(0, utils_1.formatYYYYMMDD)(new Date())}-${product}-${version}`;
+    const scaffoldRunId = `${(0, utils_1.formatYYYYMMDD)(new Date())}-${product}-${version}`;
     if (cmd === "start") {
         await (0, startFlow_1.startFlowScaffold)({
             product,
             version,
-            projectRoot: resolvedRoot,
+            projectRoot,
         });
         // eslint-disable-next-line no-console
-        console.log(`已生成 SDD 流程产物骨架：openspec/PRD/${runId}/`);
+        console.log(`已生成 SDD 流程产物骨架：openspec/PRD/${scaffoldRunId}/`);
         return;
     }
+    // eslint-disable-next-line no-console
+    console.log(`[sdd-flow-kit] 安装根 installRoot=${(0, projectRoots_1.resolveInstallRoot)(projectRoot)} (cwd=${process_1.default.cwd()})`);
     const result = await (0, runFlow_1.runFlow)({
         product,
         version,
-        projectRoot: resolvedRoot,
+        projectRoot,
         agent,
         branch,
         yes,
@@ -222,6 +349,8 @@ async function main() {
     // eslint-disable-next-line no-console
     console.log(`流程已初始化：openspec/PRD/${result.runId}/`);
     // eslint-disable-next-line no-console
+    console.log(`请打开 openspec/PRD/${result.runId}/NEXT.md，按脚本顺序执行 gate / phase / propose / deliver。`);
+    // eslint-disable-next-line no-console
     console.log(`agent=${result.adapterName}, cli=${result.adapterAvailable ? "detected" : "missing"}, autoExecute=${result.executed ? "yes" : "manual"}`);
     // eslint-disable-next-line no-console
     console.log(`branch=${result.branch}, envSetup=${result.setupExecuted ? "installed" : "already-ready"}`);
@@ -233,7 +362,7 @@ async function main() {
         // eslint-disable-next-line no-console
         console.log(JSON.stringify({
             command: "run",
-            projectRoot: resolvedRoot,
+            projectRoot,
             dryRun,
             product,
             version,

package/dist/core/gitDiffGuard.js

@@ -0,0 +1,83 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.gitDiffNameOnly = gitDiffNameOnly;
+exports.isImplPath = isImplPath;
+exports.isAllowedDocPath = isAllowedDocPath;
+exports.findImplChanges = findImplChanges;
+exports.resolveGitRoot = resolveGitRoot;
+const child_process_1 = require("child_process");
+const path_1 = __importDefault(require("path"));
+/**
+ * 在 projectRoot 执行 git 命令；非 git 仓库时 isRepo=false（不阻断文档阶段）。
+ */
+function gitDiffNameOnly(projectRoot) {
+    const rev = (0, child_process_1.spawnSync)("git", ["rev-parse", "HEAD"], {
+        cwd: projectRoot,
+        encoding: "utf8",
+    });
+    if (rev.status !== 0) {
+        return { ok: true, isRepo: false, changedFiles: [], head: null };
+    }
+    const head = (rev.stdout || "").trim();
+    const diff = (0, child_process_1.spawnSync)("git", ["diff", "--name-only", "HEAD"], {
+        cwd: projectRoot,
+        encoding: "utf8",
+    });
+    const untracked = (0, child_process_1.spawnSync)("git", ["ls-files", "--others", "--exclude-standard"], {
+        cwd: projectRoot,
+        encoding: "utf8",
+    });
+    const changed = [
+        ...(diff.stdout || "").split("\n").filter(Boolean),
+        ...(untracked.stdout || "").split("\n").filter(Boolean),
+    ];
+    const unique = Array.from(new Set(changed));
+    return { ok: true, isRepo: true, changedFiles: unique, head };
+}
+/** 业务实现路径：命中则视为「实现层改动」 */
+const IMPL_PATH_PATTERNS = [
+    /^src\//,
+    /^e2e\//,
+    /^frontend\/src\//,
+    /^frontend\/e2e\//,
+    /^app\//,
+    /^pages\//,
+    /^components\//,
+];
+function isImplPath(filePath) {
+    const p = filePath.replace(/\\/g, "/");
+    return IMPL_PATH_PATTERNS.some((re) => re.test(p));
+}
+/** 仅允许 PRD / openspec 文档路径（阶段 B/C） */
+const DOC_PATH_PATTERNS = [
+    /^openspec\/PRD\//,
+    /^openspec\/changes\//,
+    /^frontend\/openspec\/PRD\//,
+    /^frontend\/openspec\/changes\//,
+    /^\.opsx-active-change$/,
+    /^frontend\/\.opsx-active-change$/,
+];
+function isAllowedDocPath(filePath) {
+    const p = filePath.replace(/\\/g, "/");
+    if (DOC_PATH_PATTERNS.some((re) => re.test(p)))
+        return true;
+    if (p.endsWith("docs/") || /^docs\//.test(p))
+        return true;
+    return false;
+}
+function findImplChanges(changedFiles) {
+    return changedFiles.filter((f) => isImplPath(f) && !isAllowedDocPath(f));
+}
+function resolveGitRoot(projectRoot) {
+    const top = (0, child_process_1.spawnSync)("git", ["rev-parse", "--show-toplevel"], {
+        cwd: projectRoot,
+        encoding: "utf8",
+    });
+    if (top.status === 0 && top.stdout) {
+        return top.stdout.trim();
+    }
+    return path_1.default.resolve(projectRoot);
+}

package/dist/core/openspecGate.js

@@ -0,0 +1,83 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkOpenspecApplyReady = checkOpenspecApplyReady;
+exports.checkTasksAllDone = checkTasksAllDone;
+exports.changeDirExists = changeDirExists;
+const child_process_1 = require("child_process");
+const promises_1 = __importDefault(require("fs/promises"));
+const path_1 = __importDefault(require("path"));
+const fs_1 = require("./fs");
+/**
+ * 解析 openspec status --json，判断 change 是否 apply-ready。
+ */
+function checkOpenspecApplyReady(projectRoot, changeName) {
+    const ret = (0, child_process_1.spawnSync)("openspec", ["status", "--change", changeName, "--json"], {
+        cwd: projectRoot,
+        encoding: "utf8",
+    });
+    if (ret.status !== 0) {
+        return {
+            ok: false,
+            changeName,
+            applyReady: false,
+            detail: ret.stderr || ret.stdout || "openspec status 失败",
+        };
+    }
+    try {
+        const json = JSON.parse(ret.stdout || "{}");
+        const requires = json.applyRequires || [];
+        const artifacts = json.artifacts || [];
+        const pending = requires.filter((id) => {
+            const art = artifacts.find((a) => a.id === id);
+            return !art || art.status !== "done";
+        });
+        const applyReady = pending.length === 0 && requires.length > 0;
+        return {
+            ok: true,
+            changeName,
+            applyReady,
+            detail: applyReady
+                ? "apply-ready"
+                : `待完成 artifacts: ${pending.join(", ") || requires.join(", ")}`,
+        };
+    }
+    catch (e) {
+        return {
+            ok: false,
+            changeName,
+            applyReady: false,
+            detail: `无法解析 openspec status JSON: ${e instanceof Error ? e.message : String(e)}`,
+        };
+    }
+}
+/**
+ * 检查 tasks.md 是否全部勾选完成。
+ */
+async function checkTasksAllDone(projectRoot, changeName) {
+    const tasksPath = path_1.default.join(projectRoot, "openspec", "changes", changeName, "tasks.md");
+    const content = await (0, fs_1.readFileIfExists)(tasksPath);
+    if (!content) {
+        return { ok: false, detail: `缺少 tasks.md: ${tasksPath}` };
+    }
+    const open = content.match(/^- \[ \]/gm);
+    if (open && open.length > 0) {
+        return { ok: false, detail: `tasks.md 仍有 ${open.length} 项未完成` };
+    }
+    const hasTask = /- \[[xX]\]/.test(content);
+    if (!hasTask) {
+        return { ok: false, detail: "tasks.md 无已勾选任务" };
+    }
+    return { ok: true, detail: "tasks.md 已全部勾选" };
+}
+async function changeDirExists(projectRoot, changeName) {
+    try {
+        await promises_1.default.access(path_1.default.join(projectRoot, "openspec", "changes", changeName));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/core/opsxDelivery.js

@@ -15,6 +15,7 @@ const child_process_1 = require("child_process");
 const promises_1 = __importDefault(require("fs/promises"));
 const path_1 = __importDefault(require("path"));
 const fs_1 = require("./fs");
+const projectRoots_1 = require("./projectRoots");
 const DELIVERY_SCRIPT_REL = ".cursor/skills/opsx-dev-delivery-pipeline/scripts/opsx-delivery-pipeline.sh";
 function deliveryPipelineNpmScripts() {
     const full = `bash ${DELIVERY_SCRIPT_REL}`;
@@ -92,13 +93,15 @@ function buildOpsxWorkflowSetupCommand(projectRoot, agent) {
     return { cmd: "npx", args: [...baseArgs, "--editor", "codex", "-y"] };
 }
 async function isOpsxApplyReady(projectRoot) {
-    const checks = await collectDeliverySetupChecks(projectRoot);
+    const installRoot = await (0, projectRoots_1.resolvePackageRoot)((0, projectRoots_1.resolveInstallRoot)(projectRoot));
+    const checks = await collectDeliverySetupChecks(installRoot);
     return checks.every((c) => c.ok);
 }
 /** 缺 openspec/TDD/Playwright 工作流时安装 @lixin5257xxx/opsx-workflow，并修复 delivery 脚本 */
 async function ensureOpsxWorkflow(options) {
+    const installRoot = await (0, projectRoots_1.resolvePackageRoot)((0, projectRoots_1.resolveInstallRoot)(options.projectRoot));
     const plannedActions = [];
-    let checks = await collectDeliverySetupChecks(options.projectRoot);
+    let checks = await collectDeliverySetupChecks(installRoot);
     if (checks.every((c) => c.ok)) {
         return {
             ready: true,
@@ -108,8 +111,8 @@ async function ensureOpsxWorkflow(options) {
             plannedActions,
         };
     }
-    const agent = await resolveOpsxAgent(options.projectRoot, options.agent);
-    const { cmd, args } = buildOpsxWorkflowSetupCommand(options.projectRoot, agent);
+    const agent = await resolveOpsxAgent(installRoot, options.agent);
+    const { cmd, args } = buildOpsxWorkflowSetupCommand(installRoot, agent);
     plannedActions.push(`missing opsx apply stack → run: ${cmd} ${args.join(" ")}`);
     if (options.dryRun) {
         return {
@@ -121,18 +124,18 @@ async function ensureOpsxWorkflow(options) {
         };
     }
     const ret = (0, child_process_1.spawnSync)(cmd, args, {
-        cwd: options.projectRoot,
+        cwd: installRoot,
         stdio: "inherit",
         env: process.env,
     });
     if (ret.status !== 0) {
         throw new Error(`opsx-workflow 安装失败：${cmd} ${args.join(" ")}`);
     }
-    const repairedScripts = await repairOpsxDeliveryScripts(options.projectRoot);
+    const repairedScripts = await repairOpsxDeliveryScripts(installRoot);
     if (repairedScripts) {
         plannedActions.push("repaired package.json opsx:delivery-pipeline scripts");
     }
-    checks = await collectDeliverySetupChecks(options.projectRoot);
+    checks = await collectDeliverySetupChecks(installRoot);
     return {
         ready: checks.every((c) => c.ok),
         workflowInstalled: true,
@@ -141,45 +144,52 @@ async function ensureOpsxWorkflow(options) {
         plannedActions,
     };
 }
-async function collectDeliverySetupChecks(projectRoot) {
+async function collectDeliverySetupChecks(installRoot) {
     var _a, _b, _c, _d, _e, _f;
     const checks = [];
+    const root = (0, projectRoots_1.resolveInstallRoot)(installRoot);
+    const openspecRoot = await (0, projectRoots_1.resolveOpenspecRoot)(root);
+    checks.push({
+        name: "install-root",
+        ok: true,
+        detail: `安装根=${root}`,
+    });
     checks.push({
         name: "openspec-dir",
-        ok: await pathExists(path_1.default.join(projectRoot, "openspec")),
-        detail: "openspec/ 目录",
+        ok: await pathExists(path_1.default.join(openspecRoot, "openspec")),
+        detail: openspecRoot === root ? "openspec/ 目录（安装根）" : `openspec/ 目录（上级 ${openspecRoot}）`,
     });
     checks.push({
         name: "openspec-cli",
         ok: hasCommand("openspec"),
         detail: "openspec CLI（npx openspec 或全局安装）",
     });
-    const skillPath = path_1.default.join(projectRoot, ".cursor", "skills", "opsx-dev-delivery-pipeline", "SKILL.md");
+    const skillPath = path_1.default.join(root, ".cursor", "skills", "opsx-dev-delivery-pipeline", "SKILL.md");
     checks.push({
         name: "opsx-dev-delivery-pipeline-skill",
         ok: await pathExists(skillPath),
         detail: skillPath,
     });
-    const tddPath = path_1.default.join(projectRoot, ".cursor", "skills", "tdd-script", "SKILL.md");
+    const tddPath = path_1.default.join(root, ".cursor", "skills", "tdd-script", "SKILL.md");
     checks.push({
         name: "tdd-script-skill",
         ok: await pathExists(tddPath),
         detail: tddPath,
     });
-    const applyPath = path_1.default.join(projectRoot, ".cursor", "skills", "openspec-apply-change", "SKILL.md");
+    const applyPath = path_1.default.join(root, ".cursor", "skills", "openspec-apply-change", "SKILL.md");
     checks.push({
         name: "openspec-apply-change-skill",
         ok: await pathExists(applyPath),
         detail: applyPath,
     });
-    const pipelineScript = path_1.default.join(projectRoot, DELIVERY_SCRIPT_REL);
+    const pipelineScript = path_1.default.join(root, DELIVERY_SCRIPT_REL);
     checks.push({
         name: "delivery-pipeline-script",
         ok: await pathExists(pipelineScript),
         detail: pipelineScript,
     });
     try {
-        const pkgText = await promises_1.default.readFile(path_1.default.join(projectRoot, "package.json"), "utf8");
+        const pkgText = await promises_1.default.readFile(path_1.default.join(root, "package.json"), "utf8");
         const pkg = JSON.parse(pkgText);
         const cmd = (_b = (_a = pkg.scripts) === null || _a === void 0 ? void 0 : _a["opsx:delivery-pipeline"]) !== null && _b !== void 0 ? _b : "";
         const ok = cmd.includes("opsx-dev-delivery-pipeline") &&
@@ -199,10 +209,10 @@ async function collectDeliverySetupChecks(projectRoot) {
         });
     }
     try {
-        const cfgText = await promises_1.default.readFile(path_1.default.join(projectRoot, ".opsx", "config.json"), "utf8");
+        const cfgText = await promises_1.default.readFile(path_1.default.join(root, ".opsx", "config.json"), "utf8");
         const cfg = JSON.parse(cfgText);
         const skillsDir = (_c = cfg.skillsDir) !== null && _c !== void 0 ? _c : "";
-        const hasCursorDelivery = await pathExists(path_1.default.join(projectRoot, ".cursor", "skills", "opsx-dev-delivery-pipeline", "SKILL.md"));
+        const hasCursorDelivery = await pathExists(path_1.default.join(root, ".cursor", "skills", "opsx-dev-delivery-pipeline", "SKILL.md"));
         const nameOk = ((_d = cfg.deliveryPipeline) === null || _d === void 0 ? void 0 : _d.skillName) === "opsx-dev-delivery-pipeline";
         const dirOk = (hasCursorDelivery && skillsDir.includes(".cursor")) ||
             (!hasCursorDelivery && (skillsDir.includes(".cursor") || skillsDir.includes(".claude")));
@@ -222,7 +232,7 @@ async function collectDeliverySetupChecks(projectRoot) {
         });
     }
     try {
-        const pkgText = await promises_1.default.readFile(path_1.default.join(projectRoot, "package.json"), "utf8");
+        const pkgText = await promises_1.default.readFile(path_1.default.join(root, "package.json"), "utf8");
         const pkg = JSON.parse(pkgText);
         const deps = { ...pkg.dependencies, ...pkg.devDependencies };
         const hasPw = Boolean(deps["@playwright/test"] || deps.playwright);
@@ -239,7 +249,7 @@ async function collectDeliverySetupChecks(projectRoot) {
             detail: "无法读取 package.json 检查 Playwright",
         });
     }
-    const agentsMd = path_1.default.join(projectRoot, "AGENTS.md");
+    const agentsMd = path_1.default.join(root, "AGENTS.md");
     checks.push({
         name: "agents-md",
         ok: await pathExists(agentsMd),