sdd-flow-kit 1.1.0 → 1.1.1

package/README.md

@@ -73,6 +73,25 @@ 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`。
+
 ##### 脚本门禁（v1.1+，**不依赖自然语言**）
 
 `run` 会在 `openspec/PRD/<runId>/NEXT.md` 写入**必须按顺序执行的命令**。AI 与人都以 **exit code** 为准：失败则不得进入下一阶段、不得改 `src/`。

package/dist/cli.js

@@ -16,6 +16,7 @@ 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);
@@ -63,7 +64,9 @@ function printHelp() {
         "   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）",
@@ -256,6 +259,8 @@ 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,
             agent,
@@ -326,6 +331,8 @@ async function main() {
         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,

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),

package/dist/core/projectRoots.js

@@ -0,0 +1,94 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveInstallRoot = resolveInstallRoot;
+exports.isLegacyMonorepoMode = isLegacyMonorepoMode;
+exports.resolveOpenspecRoot = resolveOpenspecRoot;
+exports.resolvePackageRoot = resolvePackageRoot;
+exports.listOpenspecPrdRoots = listOpenspecPrdRoots;
+const promises_1 = __importDefault(require("fs/promises"));
+const path_1 = __importDefault(require("path"));
+async function pathExists(filePath) {
+    try {
+        await promises_1.default.access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * 安装根：严格等于 CLI 的 projectRoot（默认 process.cwd()）。
+ * 可通过 SDD_FLOW_KIT_INSTALL_ROOT 覆盖（绝对路径）。
+ * 原则：cd 到哪，package.json / .cursor/skills / opsx-workflow 就装到哪。
+ */
+function resolveInstallRoot(projectRoot) {
+    var _a;
+    const fromEnv = (_a = process.env.SDD_FLOW_KIT_INSTALL_ROOT) === null || _a === void 0 ? void 0 : _a.trim();
+    if (fromEnv)
+        return path_1.default.resolve(fromEnv);
+    return path_1.default.resolve(projectRoot);
+}
+/** 是否启用旧版 monorepo 行为（在仓库根执行时自动落到 frontend/） */
+function isLegacyMonorepoMode() {
+    return process.env.SDD_FLOW_KIT_LEGACY_MONOREPO === "1" || process.env.SDD_FLOW_KIT_LEGACY_MONOREPO === "true";
+}
+/**
+ * 从 installRoot 向上查找含 openspec/ 的目录（用于解析 PRD run、openspec CLI）。
+ * 找不到则退回 installRoot（将在其下新建 openspec/PRD）。
+ */
+async function resolveOpenspecRoot(installRoot) {
+    let cur = path_1.default.resolve(installRoot);
+    for (let i = 0; i < 12; i += 1) {
+        if (await pathExists(path_1.default.join(cur, "openspec"))) {
+            return cur;
+        }
+        const parent = path_1.default.dirname(cur);
+        if (parent === cur)
+            break;
+        cur = parent;
+    }
+    return path_1.default.resolve(installRoot);
+}
+/**
+ * 交付/门禁用的包根：默认与 installRoot 相同。
+ * 仅当 SDD_FLOW_KIT_LEGACY_MONOREPO=1 且 installRoot 无 package.json 但存在 frontend/package.json 时回落到 frontend/。
+ */
+async function resolvePackageRoot(installRoot) {
+    const root = resolveInstallRoot(installRoot);
+    if (!isLegacyMonorepoMode()) {
+        return root;
+    }
+    const pkgAtRoot = path_1.default.join(root, "package.json");
+    if (await pathExists(pkgAtRoot)) {
+        return root;
+    }
+    const fePkg = path_1.default.join(root, "frontend", "package.json");
+    if (await pathExists(fePkg)) {
+        return path_1.default.join(root, "frontend");
+    }
+    return root;
+}
+/**
+ * 收集自 installRoot 向上所有存在的 openspec/PRD 目录（用于 resolveRun）。
+ */
+async function listOpenspecPrdRoots(startDir) {
+    const seen = new Set();
+    const out = [];
+    let cur = path_1.default.resolve(startDir);
+    for (let i = 0; i < 12; i += 1) {
+        const prdRoot = path_1.default.join(cur, "openspec", "PRD");
+        const key = prdRoot.toLowerCase();
+        if (!seen.has(key) && (await pathExists(prdRoot))) {
+            seen.add(key);
+            out.push(prdRoot);
+        }
+        const parent = path_1.default.dirname(cur);
+        if (parent === cur)
+            break;
+        cur = parent;
+    }
+    return out;
+}

package/dist/steps/resolveRun.js

@@ -7,16 +7,15 @@ exports.resolveRunDir = resolveRunDir;
 exports.loadRunSession = loadRunSession;
 const promises_1 = __importDefault(require("fs/promises"));
 const path_1 = __importDefault(require("path"));
+const projectRoots_1 = require("../core/projectRoots");
 const sessionState_1 = require("../core/sessionState");
 const fs_1 = require("../core/fs");
 /**
- * 解析 openspec/PRD 目录：优先 --run-id，否则取最近修改的 run 目录。
+ * 解析 openspec/PRD 目录：从 installRoot（cwd）向上查找；优先 --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"),
-    ];
+    const installRoot = (0, projectRoots_1.resolveInstallRoot)(projectRoot);
+    const candidates = await (0, projectRoots_1.listOpenspecPrdRoots)(installRoot);
     for (const prdRoot of candidates) {
         try {
             const entries = await promises_1.default.readdir(prdRoot, { withFileTypes: true });

package/dist/steps/runDeliver.js

@@ -9,14 +9,8 @@ const child_process_1 = require("child_process");
 const resolveRun_1 = require("./resolveRun");
 const runGate_1 = require("./runGate");
 const opsxDelivery_1 = require("../core/opsxDelivery");
+const projectRoots_1 = require("../core/projectRoots");
 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。
  */
@@ -36,10 +30,11 @@ async function runDeliver(options) {
         (0, runGate_1.printGateResult)(implGate);
         return { ok: false, detail: "impl-allowed gate 未通过" };
     }
-    const pkgRoot = await resolvePackageRoot(options.projectRoot);
+    const installRoot = (0, projectRoots_1.resolveInstallRoot)(options.projectRoot);
+    const pkgRoot = await (0, projectRoots_1.resolvePackageRoot)(installRoot);
     const agent = options.agent || "cursor";
     if (options.dryRun) {
-        return { ok: true, detail: `dry-run: would deliver in ${pkgRoot}` };
+        return { ok: true, detail: `dry-run: would deliver in ${pkgRoot} (installRoot=${installRoot})` };
     }
     const ensured = await (0, opsxDelivery_1.ensureOpsxWorkflow)({
         projectRoot: pkgRoot,

package/dist/steps/runGate.js

@@ -8,6 +8,7 @@ exports.printGateResult = printGateResult;
 const path_1 = __importDefault(require("path"));
 const prdArtifacts_1 = require("../core/prdArtifacts");
 const gitDiffGuard_1 = require("../core/gitDiffGuard");
+const projectRoots_1 = require("../core/projectRoots");
 const openspecGate_1 = require("../core/openspecGate");
 const resolveRun_1 = require("./resolveRun");
 const fs_1 = require("../core/fs");
@@ -22,9 +23,28 @@ async function readActiveChange(projectRoot, session, 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"));
+    const installRoot = (0, projectRoots_1.resolveInstallRoot)(projectRoot);
+    const prdRoots = await (0, projectRoots_1.listOpenspecPrdRoots)(installRoot);
+    const dirs = [installRoot, ...prdRoots.map((p) => path_1.default.dirname(path_1.default.dirname(p)))];
+    const seen = new Set();
+    for (const root of dirs) {
+        const key = path_1.default.resolve(root);
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        const text = await (0, fs_1.readFileIfExists)(path_1.default.join(key, ".opsx-active-change"));
+        if (text) {
+            const line = text
+                .split("\n")
+                .map((l) => l.trim())
+                .find(Boolean);
+            if (line)
+                return line;
+        }
+    }
+    if ((0, projectRoots_1.isLegacyMonorepoMode)()) {
+        const fe = path_1.default.join(installRoot, "frontend", ".opsx-active-change");
+        const text = await (0, fs_1.readFileIfExists)(fe);
         if (text) {
             const line = text
                 .split("\n")
@@ -36,11 +56,15 @@ async function readActiveChange(projectRoot, session, override) {
     }
     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));
+async function resolveImplRoots(projectRoot) {
+    const installRoot = (0, projectRoots_1.resolveInstallRoot)(projectRoot);
+    const roots = [installRoot];
+    if ((0, projectRoots_1.isLegacyMonorepoMode)()) {
+        const pkgRoot = await (0, projectRoots_1.resolvePackageRoot)(installRoot);
+        if (pkgRoot !== installRoot && !roots.includes(pkgRoot)) {
+            roots.push(pkgRoot);
+        }
+    }
     return roots;
 }
 /**
@@ -56,7 +80,7 @@ async function runGate(options) {
     const { resolved, session } = loaded;
     const outputRoot = resolved.outputRoot;
     const runId = resolved.runId;
-    const implRoots = resolveImplRoots(options.projectRoot);
+    const implRoots = await resolveImplRoots(options.projectRoot);
     if (options.expect === "prd-fetched") {
         const prd = await (0, prdArtifacts_1.isPrdFetched)(outputRoot);
         checks.push({ name: "prd-fetched", ...prd });
@@ -115,10 +139,19 @@ async function runGate(options) {
             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")];
+        const installRoot = (0, projectRoots_1.resolveInstallRoot)(options.projectRoot);
+        const openspecRoots = [
+            installRoot,
+            ...(await (0, projectRoots_1.listOpenspecPrdRoots)(installRoot)).map((p) => path_1.default.dirname(path_1.default.dirname(p))),
+        ];
+        const seen = new Set();
         let found = false;
-        for (const root of roots) {
-            if (await (0, openspecGate_1.changeDirExists)(root, changeName)) {
+        for (const root of openspecRoots) {
+            const key = path_1.default.resolve(root);
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            if (await (0, openspecGate_1.changeDirExists)(key, changeName)) {
                 found = true;
                 const st = (0, openspecGate_1.checkOpenspecApplyReady)(root, changeName);
                 checks.push({ name: "openspec-apply-ready", ok: st.applyReady, detail: st.detail });
@@ -156,14 +189,32 @@ async function runGate(options) {
             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);
+        const installRoot = (0, projectRoots_1.resolveInstallRoot)(options.projectRoot);
+        const openspecRoots = [
+            installRoot,
+            ...(await (0, projectRoots_1.listOpenspecPrdRoots)(installRoot)).map((p) => path_1.default.dirname(path_1.default.dirname(p))),
+        ];
+        const seen = new Set();
+        let found = false;
+        for (const root of openspecRoots) {
+            const key = path_1.default.resolve(root);
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            if (await (0, openspecGate_1.changeDirExists)(key, changeName)) {
+                found = true;
+                const st = (0, openspecGate_1.checkOpenspecApplyReady)(key, 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 === "shipped") {
@@ -172,10 +223,19 @@ async function runGate(options) {
             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);
+        const installRoot = (0, projectRoots_1.resolveInstallRoot)(options.projectRoot);
+        const openspecRoots = [
+            installRoot,
+            ...(await (0, projectRoots_1.listOpenspecPrdRoots)(installRoot)).map((p) => path_1.default.dirname(path_1.default.dirname(p))),
+        ];
+        const seen = new Set();
+        for (const root of openspecRoots) {
+            const key = path_1.default.resolve(root);
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            if (await (0, openspecGate_1.changeDirExists)(key, changeName)) {
+                const tasks = await (0, openspecGate_1.checkTasksAllDone)(key, changeName);
                 checks.push({ name: "tasks-done", ...tasks });
                 const marker = await (0, fs_1.readFileIfExists)(path_1.default.join(outputRoot, ".delivery-pass.json"));
                 if (marker) {

package/dist/steps/runPhaseAdvance.js

@@ -7,6 +7,7 @@ exports.runPhaseAdvance = runPhaseAdvance;
 const path_1 = __importDefault(require("path"));
 const runGate_1 = require("./runGate");
 const resolveRun_1 = require("./resolveRun");
+const projectRoots_1 = require("../core/projectRoots");
 const sessionState_1 = require("../core/sessionState");
 const fs_1 = require("../core/fs");
 const gitDiffGuard_1 = require("../core/gitDiffGuard");
@@ -112,9 +113,8 @@ async function runPhaseAdvance(options) {
         };
         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);
+            const installRoot = (0, projectRoots_1.resolveInstallRoot)(options.projectRoot);
+            await (0, fs_1.writeTextFileEnsuredDir)(path_1.default.join(installRoot, ".opsx-active-change"), `${changeName}\n`);
             await writeNextMd(outputRoot, [
                 "## 当前：阶段 C 完成 → 进入 D（实现）",
                 "```bash",
@@ -139,9 +139,8 @@ async function runPhaseAdvance(options) {
             (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 installRoot = (0, projectRoots_1.resolveInstallRoot)(options.projectRoot);
+        const gitRoot = (0, gitDiffGuard_1.resolveGitRoot)(installRoot);
         const head = (0, gitDiffGuard_1.gitDiffNameOnly)(gitRoot).head;
         const next = {
             ...session,

package/dist/steps/runPropose.js

@@ -9,7 +9,7 @@ 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");
+const projectRoots_1 = require("../core/projectRoots");
 /**
  * 创建/校验 openspec change，并检查 apply-ready（不代替 AI 写 proposal 正文，但强制 gate）。
  */
@@ -27,14 +27,8 @@ async function runPropose(options) {
         (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;
-        }
-    }
+    const installRoot = (0, projectRoots_1.resolveInstallRoot)(options.projectRoot);
+    const cwd = await (0, projectRoots_1.resolveOpenspecRoot)(installRoot);
     if (options.dryRun) {
         return { ok: true, detail: `dry-run: would openspec new change ${options.change}` };
     }

package/dist/steps/setupProject.js

@@ -11,6 +11,7 @@ const fs_1 = require("../core/fs");
 const readlinePrompt_1 = require("../core/readlinePrompt");
 const utils_1 = require("../core/utils");
 const opsxDelivery_1 = require("../core/opsxDelivery");
+const projectRoots_1 = require("../core/projectRoots");
 const templates_1 = require("../core/templates");
 const EDITOR_CHOICES = ["claude-code", "cursor", "codex", "openclaw"];
 const PROJECT_CHOICES = ["OMS", "ADI", "欢盟", "AD Tools"];
@@ -219,14 +220,15 @@ async function installOpsxConfig(projectRoot, agent) {
 }
 async function setupProject(options) {
     var _a, _b, _c;
+    const installRoot = (0, projectRoots_1.resolveInstallRoot)(options.projectRoot);
     const defaultAgent = (_a = options.agent) !== null && _a !== void 0 ? _a : "claude-code";
     const selectedAgent = options.yes ? defaultAgent : await askAgent(defaultAgent);
     const defaultKind = (_b = options.projectKind) !== null && _b !== void 0 ? _b : "OMS";
     const selectedKind = options.yes ? defaultKind : await askProjectKind(defaultKind);
-    const defaultBranch = (_c = options.branch) !== null && _c !== void 0 ? _c : pickDefaultBranch(options.projectRoot);
+    const defaultBranch = (_c = options.branch) !== null && _c !== void 0 ? _c : pickDefaultBranch(installRoot);
     const selectedBranch = options.yes ? defaultBranch : await askBranch(defaultBranch);
-    const plannedActions = [];
-    const branches = listLocalBranches(options.projectRoot);
+    const plannedActions = [`installRoot=${installRoot}`];
+    const branches = listLocalBranches(installRoot);
     const branchExists = branches.includes(selectedBranch);
     let branchResult;
     if (options.light) {
@@ -240,9 +242,9 @@ async function setupProject(options) {
             : `would create and checkout branch: ${selectedBranch}`);
     }
     else {
-        branchResult = ensureBranch(options.projectRoot, selectedBranch);
+        branchResult = ensureBranch(installRoot, selectedBranch);
     }
-    let environmentReady = await (0, opsxDelivery_1.isOpsxApplyReady)(options.projectRoot);
+    let environmentReady = await (0, opsxDelivery_1.isOpsxApplyReady)(installRoot);
     let setupExecuted = false;
     let skillInstalled = false;
     let docsSkillInstalled = false;
@@ -255,7 +257,7 @@ async function setupProject(options) {
     }
     else if (!environmentReady) {
         const ensured = await (0, opsxDelivery_1.ensureOpsxWorkflow)({
-            projectRoot: options.projectRoot,
+            projectRoot: installRoot,
             agent: selectedAgent,
             dryRun: options.dryRun,
         });
@@ -267,23 +269,24 @@ async function setupProject(options) {
         plannedActions.push("opsx apply stack already ready");
     }
     if (options.dryRun) {
-        for (const skillPath of allSkillInstallPaths(options.projectRoot)) {
+        for (const skillPath of allSkillInstallPaths(installRoot)) {
             plannedActions.push(`would install skill: ${skillPath}`);
         }
         const { dir } = docSkillDirName(selectedKind);
-        plannedActions.push(`would install docs skill: ${path_1.default.join(options.projectRoot, "docs", dir)}`);
-        plannedActions.push(`would install opsx config: ${path_1.default.join(options.projectRoot, ".opsx", "config.json")}`);
-        plannedActions.push(`would install cursor rule: ${path_1.default.join(options.projectRoot, ".cursor", "rules", "sdd-flow-kit-gates.mdc")}`);
+        plannedActions.push(`would install docs skill: ${path_1.default.join(installRoot, "docs", dir)}`);
+        plannedActions.push(`would install opsx config: ${path_1.default.join(installRoot, ".opsx", "config.json")}`);
+        plannedActions.push(`would install cursor rule: ${path_1.default.join(installRoot, ".cursor", "rules", "sdd-flow-kit-gates.mdc")}`);
     }
     else {
-        await installAgentSkill(options.projectRoot);
-        await installSddCursorRule(options.projectRoot);
+        await installAgentSkill(installRoot);
+        await installSddCursorRule(installRoot);
         skillInstalled = true;
-        await installDocsSkill(options.projectRoot, selectedKind);
+        await installDocsSkill(installRoot, selectedKind);
         docsSkillInstalled = true;
-        await installOpsxConfig(options.projectRoot, selectedAgent);
+        await installOpsxConfig(installRoot, selectedAgent);
         opsxConfigInstalled = true;
-        const repaired = await (0, opsxDelivery_1.repairOpsxDeliveryScripts)(options.projectRoot);
+        const pkgRoot = await (0, projectRoots_1.resolvePackageRoot)(installRoot);
+        const repaired = await (0, opsxDelivery_1.repairOpsxDeliveryScripts)(pkgRoot);
         if (repaired) {
             plannedActions.push("repaired package.json opsx:delivery-pipeline scripts (poquan → opsx)");
         }
@@ -307,7 +310,7 @@ async function setupProject(options) {
         ...plannedActions.map((x) => `- ${x}`),
         "",
     ].join("\n");
-    await (0, fs_1.writeTextFileEnsuredDir)(path_1.default.join(options.projectRoot, ".sdd-flow-kit", "setup-summary.md"), summary);
+    await (0, fs_1.writeTextFileEnsuredDir)(path_1.default.join(installRoot, ".sdd-flow-kit", "setup-summary.md"), summary);
     return {
         agent: selectedAgent,
         projectKind: selectedKind,

package/dist/steps/startFlow.js

@@ -11,6 +11,7 @@ const fs_1 = require("../core/fs");
 const templates_1 = require("../core/templates");
 const inferProject_1 = require("../core/inferProject");
 const sessionState_1 = require("../core/sessionState");
+const projectRoots_1 = require("../core/projectRoots");
 const writeNext_1 = require("../core/writeNext");
 function renderTemplate(template, vars) {
     let out = template;
@@ -22,7 +23,8 @@ function renderTemplate(template, vars) {
 async function startFlowScaffold(options) {
     const now = new Date();
     const runId = `${(0, utils_1.formatYYYYMMDD)(now)}-${options.product}-${options.version}`;
-    const outputRoot = path_1.default.join(options.projectRoot, "openspec", "PRD", runId);
+    const installRoot = (0, projectRoots_1.resolveInstallRoot)(options.projectRoot);
+    const outputRoot = path_1.default.join(installRoot, "openspec", "PRD", runId);
     const sourceDir = path_1.default.join(outputRoot, "source");
     await promises_1.default.mkdir(sourceDir, { recursive: true });
     // 1) Step1: doc-skill 指引（按产品解析脚本路径，支持 monorepo frontend）

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sdd-flow-kit",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "private": false,
   "description": "Cross-agent SDD automated development workflow kit (ADI/ADI-like).",
   "license": "MIT",