@guanlin4924/devflow-pi 0.1.93 → 0.1.94

package/README.md

@@ -31,7 +31,7 @@ devflow-pi
 /usage-stats
 ```
 
-`/devflow project-init` 会先读取当前项目已有的 `.planning/PROJECT.md` 与 `.planning/navigation/INDEX.md`：仅回填仍存在于项目根目录内的已登记前后端路径，删除或越界的历史路径会被忽略。随后可选择复用已有边界、复用边界并重建索引，或手动覆盖。初始化模式使用选择器提供“只读规划（默认）”和“写入初始化”；选择后者并确认，只会创建 Devflow 的 `.planning/` 与 `.context/` 初始化产物，不会修改业务源码、依赖或项目配置。
+`/devflow project-init` 会先读取当前项目已有的 `.devflow/planning/PROJECT.md` 与 `.devflow/planning/navigation/INDEX.md`：仅回填仍存在于项目根目录内的已登记前后端路径，删除或越界的历史路径会被忽略。随后可选择复用已有边界、复用边界并重建索引，或手动覆盖。初始化模式使用选择器提供“只读规划（默认）”和“写入初始化”；选择后者并确认，只会创建 Devflow 的 `.devflow/planning/` 与 `.devflow/context/` 初始化产物，不会修改业务源码、依赖或项目配置。
 
 用量统计默认只读取当前项目的隔离会话：`/usage-stats`。需要明确查看历史 OMP 会话时，使用 `/usage-stats omp`，或加筛选条件：`/usage-stats omp --from 2026-08-01 --to 2026-08-10`。历史统计保留真实会话路径，不再把不同项目的长会话文件合并成 `main`；统计只使用 assistant message 的原始 usage，不虚构工具调用成本分摊。
 
@@ -40,7 +40,7 @@ devflow-pi
 专项 Pi 的隔离边界：
 
 - 项目身份位于 `<project>/.devflow/project.json`；
-- 流程状态和代码索引仍位于 `<project>/.planning/`；
+- 流程状态和代码索引仍位于 `<project>/.devflow/planning/`；
 - Session 位于 `~/.devflow-pi/sessions/<projectId>/`；
 - 模型认证默认复用 `~/.omp/agent/`，但不复用官方 OMP Session；
 - 只显式加载产品内六个插件根，不自动混入用户或项目的环境 Extension；
@@ -92,7 +92,7 @@ skills:
 
 Devflow 会在输入框上方显示“当前 Feature 交付链路”：它基于只读状态快照展示已知步骤、当前节点、完成数、工作流/执行状态、当前允许的操作，以及安全恢复方案。使用 `/devflow control` 打开交互式控制台：它只会在状态检查器允许时提供启动当前步骤、审查并批准推进、安全恢复或取消当前 Feature；每个有写入影响的操作都会重新读取状态并沿用已有确认流程。面板不提供重试或重置当前节点，避免破坏 revision、checkpoint 和证据链。
 
-正式节点经用户批准后，Devflow 会把已校验的状态和产物引用固化为内容校验的 handoff，再自动创建干净 Session 执行下一节点。交接期间工作流冻结；只有新 Session 成功认领并消费同一份 handoff 后才解除冻结。Devflow 不使用 OMP 的模型摘要 handoff，因此 `.planning/STATE.md` 仍是唯一流程事实源。
+正式节点经用户批准后，Devflow 会把已校验的状态和产物引用固化为内容校验的 handoff，再自动创建干净 Session 执行下一节点。交接期间工作流冻结；只有新 Session 成功认领并消费同一份 handoff 后才解除冻结。Devflow 不使用 OMP 的模型摘要 handoff，因此 `.devflow/planning/STATE.md` 仍是唯一流程事实源。
 
 ### 需求验收测试与 TDD 证据链
 
@@ -110,10 +110,10 @@ Devflow 会在输入框上方显示“当前 Feature 交付链路”：它基于
 - `tdd_required` 任务必须先由 Core 记录准备快照，再记录 RED（命中预期失败）、同一目标的 GREEN 和回归；缺失或环境失败不算完成。
 - API、跨数据域、边界、迁移、工作负载与架构风险会派生相应的 `api`、`permission`、`boundary`、`migration`、`performance`、`resilience` TC 义务。
 - 每个 TC 还要声明证明策略：`replay` 用组件/页面/API/集成的稳定回放；`causal` 用已定位的首个偏差加 HAR、控制台、DOM 快照、截图或日志等受控文件证明，Core 会记录文件哈希；`observation` 用于尚不可复现、也未能证明根因的问题，只能保持阻塞并带观测计划。后两者都不能被“AI 已复现”或 Markdown 自述放行。
-- 代码完成后，`workflow-run-acceptance-tests` 只能运行绑定到冻结 TC、且已在初始化 `.planning/toolchain.md` 发现的测试运行器命令。任何失败、未执行、人工待执行或环境阻塞用例都会阻止 CP-4。
+- 代码完成后，`workflow-run-acceptance-tests` 只能运行绑定到冻结 TC、且已在初始化 `.devflow/planning/toolchain.md` 发现的测试运行器命令。任何失败、未执行、人工待执行或环境阻塞用例都会阻止 CP-4。
 - 验收不是代码完成后的临时手工检查。它是需求基线在编码前派生并冻结的完整测试集，覆盖主流程、异常、边界、权限、迁移、兼容、韧性和工作负载义务；代码只能补充执行适配信息，不能改变测试意图。
 - 验收失败不会创建另一套人工台账，而是进入 `acceptance-remediation`：诊断 → 修复 → code-index 刷新 → 原冻结 `TC-*` 重跑。
-- CP-4 通过后只进入一个 `workflow-release-closeout` 步骤，统一写入 `.planning/milestones/current-CLOSEOUT.md` 并更新项目状态、导航和版本记录。
+- CP-4 通过后只进入一个 `workflow-release-closeout` 步骤，统一写入 `.devflow/planning/milestones/current-CLOSEOUT.md` 并更新项目状态、导航和版本记录。
 
 正常使用不需要记忆底层命令：在 Devflow 工作流中按步骤继续即可。需要排查时，可用 `devflow_acceptance_tests` 查看冻结套件，或由工作流调用 `devflow_tdd_evidence` 与 `devflow_run_acceptance_tests` 生成 Core-owned 证据；不要手写“已测试”来替代结果文件。
 
@@ -146,7 +146,7 @@ npm install -g @guanlin4924/devflow-pi@latest
 
 ## 核心不变量
 
-- `.planning/STATE.md`、workflow 和 artifact registry 只允许 Devflow 工具写入。
+- `.devflow/planning/STATE.md`、workflow 和 artifact registry 只允许 Devflow 工具写入。
 - 子 agent 不更新控制面，只返回证据、结构化审查结果或隔离 patch。
 - 索引是加速器，不是真相源；过期时回退到 LSP、搜索、源码和测试。
 - 人工 checkpoint 不得在 headless 模式静默通过。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guanlin4924/devflow-pi",
-  "version": "0.1.93",
+  "version": "0.1.94",
   "type": "module",
   "description": "Devflow 专项研发 Pi，基于固定版本 OMP Runtime 组装研发状态机、代码智能、设计、实现与质量门禁。",
   "license": "UNLICENSED",

package/plugins/devflow-core/extensions/devflow-core.ts

@@ -16,6 +16,7 @@ import { runProjectInitialization } from "../../../src/project-initializer.ts";
 import { projectControlDatabasePath } from "../../../src/paths.ts";
 import { generateProjectDocuments } from "../../../src/project-documents.ts";
 import { exportInitializationSnapshot, importLegacyInitialization, switchInitializationAuthority } from "../../../src/project-migration.ts";
+import { migrateLegacyProjectLayout } from "../../../src/project-layout.ts";
 
 
 export type DevflowIntent = "idle" | "explain-state" | "project-init" | "requirement-draft" | "workflow-execute";
@@ -351,7 +352,7 @@ export function discoverExistingProjectInitialization(cwd: string, options: { al
     }
   }
   if (!options.allowLegacyImport) return null;
-  const sources = [".planning/PROJECT.md", ".planning/navigation/INDEX.md"];
+  const sources = [".devflow/planning/PROJECT.md", ".devflow/planning/navigation/INDEX.md"];
   const records: Array<ExistingProjectInitialization> = [];
   for (const sourcePath of sources) {
     const absolute = path.join(cwd, sourcePath);
@@ -531,13 +532,13 @@ type DoctorContext = {
 };
 
 const CONTROL_PATHS = [
-  ".planning/STATE.md",
-  ".planning/.next-intent",
-  ".planning/.devflow.lock",
-  ".planning/artifacts/index.yaml",
+  ".devflow/planning/STATE.md",
+  ".devflow/planning/.next-intent",
+  ".devflow/planning/.devflow.lock",
+  ".devflow/planning/artifacts/index.yaml",
 ];
 
-const CONTROL_PREFIXES = [".planning/workflows/", ".planning/contracts/", ".planning/evidence/", ".planning/review-runs/"];
+const CONTROL_PREFIXES = [".devflow/planning/workflows/", ".devflow/planning/contracts/", ".devflow/planning/evidence/", ".devflow/planning/review-runs/"];
 
 const REQUIRED_EXTENSION_TOOLS = [
   "devflow_doctor",
@@ -703,16 +704,63 @@ function assertRuntimeProjectBoundary(cwd: string): void {
   if (configured && realpathSync(configured) !== resolvedCwd) {
     throw new Error(`Devflow project-root mismatch: session=${resolvedCwd}, configured=${configured}`);
   }
-  const planningRoot = path.join(resolvedCwd, ".planning");
+  const legacyPlanning = path.join(resolvedCwd, ".planning");
+  const legacyContext = path.join(resolvedCwd, ".context");
+  const planningMarkers = ["STATE.md", "PROJECT.md", ".devflow.lock", "navigation/INDEX.md", "code-index/INDEX.md", "workflows", "contracts", "evidence", "review-runs", "requirements", "features", "handoffs", "artifacts", "phase-ownership.yaml"];
+  const contextMarkers = ["spec/index.md", "index.md", "project/index.md", "knowledge/index.md"];
+  const legacyMarker = planningMarkers.some(relative => existsSync(path.join(legacyPlanning, relative)))
+    || contextMarkers.some(relative => existsSync(path.join(legacyContext, relative)));
+  const activeLegacy = ["STATE.md", "workflows", "contracts", "evidence", "review-runs", "requirements", "features", "handoffs", "artifacts", "phase-ownership.yaml"]
+    .find(relative => existsSync(path.join(legacyPlanning, relative)));
+  if (legacyMarker) {
+    const manifestPath = path.join(resolvedCwd, ".devflow", "project.json");
+    let manifestValid = false;
+    try {
+      const manifest = JSON.parse(readFileSync(manifestPath, "utf8")) as Record<string, unknown>;
+      manifestValid = manifest.schemaVersion === 1
+        && typeof manifest.projectId === "string" && /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(manifest.projectId)
+        && typeof manifest.name === "string" && manifest.name.trim().length > 0
+        && typeof manifest.createdAt === "string" && Number.isFinite(Date.parse(manifest.createdAt))
+        && [undefined, 1, 2].includes(manifest.layoutVersion as undefined | number);
+    } catch { /* reported below */ }
+    if (!manifestValid) throw new Error("DEVFLOW_LEGACY_LAYOUT_CONFIRMATION_REQUIRED: valid .devflow/project.json is required before legacy layout migration");
+    let migrationCompletePrecheck = false;
+    try {
+      const marker = JSON.parse(readFileSync(path.join(resolvedCwd, ".devflow", "layout-migration.json"), "utf8")) as Record<string, unknown>;
+      migrationCompletePrecheck = marker.schemaVersion === 1 && marker.status === "complete" && Array.isArray(marker.migrated);
+    } catch { /* reported by the normal conflict checks below */ }
+    if (activeLegacy && !migrationCompletePrecheck) {
+      throw new Error(`DEVFLOW_ACTIVE_LEGACY_LAYOUT: .planning/${activeLegacy} requires dedicated control-plane migration`);
+    }
+    const canonicalExists = existsSync(path.join(resolvedCwd, ".devflow", "planning")) || existsSync(path.join(resolvedCwd, ".devflow", "context"));
+    const migrationComplete = (() => {
+      try {
+        const marker = JSON.parse(readFileSync(path.join(resolvedCwd, ".devflow", "layout-migration.json"), "utf8")) as Record<string, unknown>;
+        return marker.schemaVersion === 1 && marker.status === "complete" && Array.isArray(marker.migrated);
+      } catch { return false; }
+    })();
+    if (manifestValid && (() => {
+      try { return (JSON.parse(readFileSync(manifestPath, "utf8")) as Record<string, unknown>).layoutVersion === 2; } catch { return false; }
+    })() && migrationComplete) {
+      const planningLegacy = planningMarkers.some(relative => existsSync(path.join(legacyPlanning, relative)));
+      const contextLegacy = contextMarkers.some(relative => existsSync(path.join(legacyContext, relative)));
+      if ((planningLegacy && !existsSync(path.join(resolvedCwd, ".devflow", "planning"))) || (contextLegacy && !existsSync(path.join(resolvedCwd, ".devflow", "context")))) {
+        throw new Error("DEVFLOW_LEGACY_REINTRODUCTION: v2 project will not backfill a missing canonical directory");
+      }
+    }
+    if (canonicalExists && !migrationComplete) throw new Error("DEVFLOW_LAYOUT_CONFLICT: canonical and legacy layouts coexist without a completed migration marker");
+    if (!canonicalExists) throw new Error("DEVFLOW_LAYOUT_MIGRATION_REQUIRED: run project initialization to migrate legacy read-only artifacts");
+  }
+  const planningRoot = path.join(resolvedCwd, ".devflow/planning");
   if (existsSync(planningRoot) && lstatSync(planningRoot).isSymbolicLink()) {
     throw new Error(`Refusing symlinked Devflow planning root: ${planningRoot}`);
   }
   for (const relative of [
-    ".planning/STATE.md",
-    ".planning/.devflow.lock",
-    ".planning/workflows",
-    ".planning/artifacts",
-    ".planning/review-runs",
+    ".devflow/planning/STATE.md",
+    ".devflow/planning/.devflow.lock",
+    ".devflow/planning/workflows",
+    ".devflow/planning/artifacts",
+    ".devflow/planning/review-runs",
   ]) {
     const target = path.join(resolvedCwd, relative);
     try {
@@ -744,29 +792,29 @@ function safeControlPath(cwd: string, raw: string | undefined, kind: "state" | "
   const relative = normalizedProjectPath(raw, cwd);
   const allowed =
     kind === "state"
-      ? relative === ".planning/STATE.md"
-      : Boolean(relative?.startsWith(".planning/workflows/") && relative.endsWith(".yaml"));
+      ? relative === ".devflow/planning/STATE.md"
+      : Boolean(relative?.startsWith(".devflow/planning/workflows/") && relative.endsWith(".yaml"));
   if (!relative || !allowed) throw new Error(`Invalid ${kind} control path: ${raw}`);
   return relative;
 }
 
 function isCanonicalRequirementGraphPath(filePath: string): boolean {
-  return /^\.planning\/requirements\/[^/\\\x00-\x1F\x7F]+\/(?:governance|evidence|definitions|behavior-graph|requirement-graph|slices|acceptance|tests|traceability|graph\.meta)\.json$/u.test(filePath)
-    || /^\.planning\/requirements\/[^/\\\x00-\x1F\x7F]+\/(?:context\/[^/\\]+\.json|control-events\.jsonl)$/u.test(filePath);
+  return /^\.devflow\/planning\/requirements\/[^/\\\x00-\x1F\x7F]+\/(?:governance|evidence|definitions|behavior-graph|requirement-graph|slices|acceptance|tests|traceability|graph\.meta)\.json$/u.test(filePath)
+    || /^\.devflow\/planning\/requirements\/[^/\\\x00-\x1F\x7F]+\/(?:context\/[^/\\]+\.json|control-events\.jsonl)$/u.test(filePath);
 }
 
 function isCoreOwnedGovernancePath(filePath: string): boolean {
   // 规范需求图谱只能由 Core 的 devflow_requirement_graph writer 写入；the
   // same ownership extends to its views, machine evidence, and audit records.
   return isCanonicalRequirementGraphPath(filePath)
-    || /^\.planning\/evidence\/[^/\\\x00-\x1F\x7F]+\/[^/\\]+\.machine\.json$/u.test(filePath)
-    || /^\.planning\/contracts\/[^/\\\x00-\x1F\x7F]+\/(?:EC-[A-Fa-f0-9]+\.json|control-events\.jsonl)$/u.test(filePath)
-    || filePath.startsWith(".planning/review-runs/")
-    || /^\.planning\/phases\/[^/\\\x00-\x1F\x7F]+\/REVIEW\.md$/u.test(filePath);
+    || /^\.devflow\/planning\/evidence\/[^/\\\x00-\x1F\x7F]+\/[^/\\]+\.machine\.json$/u.test(filePath)
+    || /^\.devflow\/planning\/contracts\/[^/\\\x00-\x1F\x7F]+\/(?:EC-[A-Fa-f0-9]+\.json|control-events\.jsonl)$/u.test(filePath)
+    || filePath.startsWith(".devflow/planning/review-runs/")
+    || /^\.devflow\/planning\/phases\/[^/\\\x00-\x1F\x7F]+\/REVIEW\.md$/u.test(filePath);
 }
 
 function planningFeatureFromPath(filePath: string): string | null {
-  const match = filePath.match(/^\.planning\/(?:requirements|features)\/([^/\\\x00-\x1F\x7F]+)(?:\/|$)/u);
+  const match = filePath.match(/^\.devflow\/planning\/(?:requirements|features)\/([^/\\\x00-\x1F\x7F]+)(?:\/|$)/u);
   return match?.[1] ?? null;
 }
 
@@ -1083,8 +1131,8 @@ function projectInitializationDirective(summary: string): string {
   return [
     "<devflow-project-initialization-directive>",
     "用户已批准完整项目初始化。现在处于执行模式；不要再创建 Todo、不要读取或写入 xd://devflow_contract。",
-    "执行 skill://workflow-project-context，按已确认的项目边界建立 .planning/PROJECT.md、.planning/navigation/INDEX.md、.context/spec/index.md，并按用户选择建立 full 代码索引。",
-    "只写项目初始化所需的 .planning/ 与 .context/ 控制产物；不得改动业务源码、依赖或配置。完成后运行项目初始化校验，报告生成文件和验证结果并停止，等待用户审查。",
+    "执行 skill://workflow-project-context，按已确认的项目边界建立 .devflow/planning/PROJECT.md、.devflow/planning/navigation/INDEX.md、.devflow/context/spec/index.md，并按用户选择建立 full 代码索引。",
+    "只写项目初始化所需的 .devflow/planning/ 与 .devflow/context/ 控制产物；不得改动业务源码、依赖或配置。完成后运行项目初始化校验，报告生成文件和验证结果并停止，等待用户审查。",
     summary,
     "</devflow-project-initialization-directive>",
   ].join("\n");
@@ -1177,7 +1225,7 @@ export function isShellControlMutation(toolName: string, input: unknown): boolea
     /workflow-orchestrator\/scripts\/(?:advance_state|init_state|init_workflow|sync_artifacts|requirement_graph|machine_evidence|execution_contract)\.rb[^\n]*--write/.test(
       command,
     );
-  const namesControlPath = [...CONTROL_PATHS, ...CONTROL_PREFIXES].some(item => command.includes(item)) || /\.planning\/requirements\//.test(command);
+  const namesControlPath = [...CONTROL_PATHS, ...CONTROL_PREFIXES].some(item => command.includes(item)) || /\.devflow\/planning\/requirements\//.test(command);
   // `2>` and `2>>` only redirect stderr. They frequently accompany read-only
   // probes of control-plane files and must not be treated as a file mutation.
   // Keep bare `>`/`>>` and explicit stdout `1>`/`1>>` guarded.
@@ -1424,7 +1472,7 @@ export default function devflowCore(pi: ExtensionAPI) {
     const feature = activeContract.feature;
     const step = activeContract.step;
     if (!/^[\p{L}\p{N}._-]{1,160}$/u.test(feature) || !/^[\p{L}\p{N}._-]{1,160}$/u.test(step)) return;
-    const directory = path.join(cwd, ".planning", "evidence", feature);
+    const directory = path.join(cwd, ".devflow/planning", "evidence", feature);
     const attempt = typeof extra.attempt === "number" && Number.isInteger(extra.attempt) && extra.attempt >= 0
       ? extra.attempt
       : undefined;
@@ -1619,7 +1667,7 @@ export default function devflowCore(pi: ExtensionAPI) {
             ? (rawStep as { id: string }).id
             : undefined;
       if (!feature || !step) return undefined;
-      const contractsDir = path.join(cwd, ".planning", "contracts", feature);
+      const contractsDir = path.join(cwd, ".devflow/planning", "contracts", feature);
       if (!existsSync(contractsDir)) return undefined;
       const candidates = readdirSync(contractsDir)
         .filter(name => name.startsWith("EC-") && name.endsWith(".json"))
@@ -1755,7 +1803,7 @@ export default function devflowCore(pi: ExtensionAPI) {
       `初始化方式：${modeSummary}`,
     ].join("\n");
     const consequence = mode === "apply"
-      ? "确认后会创建 Devflow 的 .planning/ 与 .context/ 初始化产物；不会修改业务源码、依赖或项目配置。"
+      ? "确认后会创建 Devflow 的 .devflow/planning/ 与 .devflow/context/ 初始化产物；不会修改业务源码、依赖或项目配置。"
       : "确认后只进入只读规划，不会创建工作流或写入项目文件。";
     const confirmed = await ctx.ui.confirm("确认项目初始化范围", `${summary}\n\n${consequence}`);
     if (!confirmed) {
@@ -2004,7 +2052,7 @@ export default function devflowCore(pi: ExtensionAPI) {
   const runtimeBootstrapAuthorizations = new Set<string>();
 
   async function enqueueControlledRolloverRequest(cwd: string, rolloverId: string, sourceSessionId: string) {
-    const requestPath = path.join(cwd, ".planning", "rollover-request.json");
+    const requestPath = path.join(cwd, ".devflow/planning", "rollover-request.json");
     const temporary = `${requestPath}.${randomUUID()}.tmp`;
     await writeFile(temporary, JSON.stringify({ schema_version: 1, rollover_id: rolloverId, source_session_id: sourceSessionId }) + "\n", "utf8");
     await rename(temporary, requestPath);
@@ -2403,6 +2451,12 @@ export default function devflowCore(pi: ExtensionAPI) {
   pi.on("session_start", async (_event, ctx) => {
     projectRoot = ctx.cwd;
     sessionId = randomUUID();
+    try {
+      await migrateLegacyProjectLayout(ctx.cwd);
+    } catch (error) {
+      ctx.ui.notify(error instanceof Error ? error.message : String(error), "error");
+      return;
+    }
     const result = await runHook(ctx.cwd, "start.py", {
       session_id: sessionId,
       cwd: ctx.cwd,
@@ -2736,7 +2790,7 @@ export default function devflowCore(pi: ExtensionAPI) {
         text: [
           "<devflow-planner-directive>",
           "用户已确认项目初始化的输入。你现在是 Planner，只允许只读分析和派发 project-scout / requirements-auditor / contract-auditor。",
-          "不得创建 .planning 文件、不得调用状态迁移、不得执行实现。",
+          "不得创建 .devflow/planning 文件、不得调用状态迁移、不得执行实现。",
           "先输出：已知事实、待验证点、最少侦察任务和必须由用户决定的问题。没有证据时写 unknown。",
           initialization.summary,
           "</devflow-planner-directive>",
@@ -2841,7 +2895,7 @@ export default function devflowCore(pi: ExtensionAPI) {
           "--root", ctx.cwd,
           "--feature", activeContract.feature,
           "--step", activeContract.step,
-          "--contract", `.planning/contracts/${activeContract.feature}/${activeContract.contractId}.json`,
+          "--contract", `.devflow/planning/contracts/${activeContract.feature}/${activeContract.contractId}.json`,
           "--obligations", "[]",
           "--review-agent", "devflow-code-reviewer",
           "--stage", "entry",
@@ -3625,7 +3679,7 @@ export default function devflowCore(pi: ExtensionAPI) {
     async execute(_id, params, _signal, _onUpdate, ctx) {
       const feature = normalizeContractSegment(params.feature, "feature");
       const taskId = normalizeContractSegment(params.taskId, "taskId");
-      const root = path.join(ctx.cwd, ".planning", "evidence", feature);
+      const root = path.join(ctx.cwd, ".devflow/planning", "evidence", feature);
       const destination = path.join(root, `${taskId}.json`);
       const validatePack = (pack: unknown): string[] => {
         if (!pack || typeof pack !== "object" || Array.isArray(pack)) return ["pack must be an object"];
@@ -3718,7 +3772,7 @@ export default function devflowCore(pi: ExtensionAPI) {
         const written = await runRuby(ctx.cwd, "workflow-orchestrator/scripts/execution_contract.rb", createArgs);
         if (!controlPlaneSucceeded(written)) return renderResult(written, { action: input.action });
         const writtenPayload = parseJsonResult(written);
-        const destination = typeof writtenPayload?.path === "string" ? writtenPayload.path : ".planning/contracts/";
+        const destination = typeof writtenPayload?.path === "string" ? writtenPayload.path : ".devflow/planning/contracts/";
         contract.contractPath = destination;
         activeContract = contract;
         contractAgentCalls = 0;
@@ -4264,7 +4318,7 @@ export default function devflowCore(pi: ExtensionAPI) {
           [
             "<devflow-planner-directive>",
             "用户已确认项目初始化的输入。你现在是 Planner，只允许只读分析和派发 project-scout / requirements-auditor / contract-auditor。",
-            "不得创建 .planning 文件、不得调用状态迁移、不得执行实现。",
+            "不得创建 .devflow/planning 文件、不得调用状态迁移、不得执行实现。",
             "先输出：已知事实、待验证点、最少侦察任务和必须由用户决定的问题。没有证据时写 unknown。",
             initialization.summary,
             "</devflow-planner-directive>",

package/plugins/devflow-core/runtime/hooks/context_sync_gate.py

@@ -34,11 +34,11 @@ def _run_light_sync(root: Path, files: list[str], timeout: int) -> tuple[bool, s
             "--root",
             str(root),
             "--output",
-            ".planning/code-index",
+            ".devflow/planning/code-index",
             "--changed-files",
             *files,
         ],
-        [sys.executable, str(script), "validate", "--index", ".planning/code-index"],
+        [sys.executable, str(script), "validate", "--index", ".devflow/planning/code-index"],
         [
             sys.executable,
             str(script),
@@ -46,7 +46,7 @@ def _run_light_sync(root: Path, files: list[str], timeout: int) -> tuple[bool, s
             "--root",
             str(root),
             "--index",
-            ".planning/code-index",
+            ".devflow/planning/code-index",
         ],
     ]
     output = []

package/plugins/devflow-core/runtime/hooks/hook_common.py

@@ -11,6 +11,7 @@ import re
 import subprocess
 import tempfile
 import time
+from datetime import datetime
 from contextlib import contextmanager
 from pathlib import Path
 from typing import Any, Iterator
@@ -26,16 +27,16 @@ DEFAULT_POLICY: dict[str, Any] = {
     "mode": "strict",
     "protected_roots": [],
     "required_evidence": [
-        ".planning/rules/INDEX.md",
-        ".context/spec/index.md",
-        ".planning/navigation/INDEX.md",
+        ".devflow/planning/rules/INDEX.md",
+        ".devflow/context/spec/index.md",
+        ".devflow/planning/navigation/INDEX.md",
     ],
-    "optional_evidence": [".planning/code-index/INDEX.md"],
+    "optional_evidence": [".devflow/planning/code-index/INDEX.md"],
     "allowed_before_gate": [
         "AGENTS.md",
         "README.md",
-        ".planning/**",
-        ".context/**",
+        ".devflow/planning/**",
+        ".devflow/context/**",
         ".agent-gates/**",
         ".omp/**",
         ".skills/**",
@@ -46,6 +47,8 @@ DEFAULT_POLICY: dict[str, Any] = {
         "light_timeout_seconds": 120,
         "full_file_threshold": 30,
         "ignore": [
+            ".devflow/planning/**",
+            ".devflow/context/**",
             ".planning/**",
             ".context/**",
             ".agent-gates/**",
@@ -122,18 +125,69 @@ def cli_dir_name() -> str:
     return ".omp"
 
 
+def assert_project_layout_ready(root: Path) -> None:
+    legacy_planning = root / ".planning"
+    legacy_context = root / ".context"
+    planning_markers = ("STATE.md", "PROJECT.md", ".devflow.lock", "navigation/INDEX.md", "code-index/INDEX.md", "workflows", "contracts", "evidence", "review-runs", "requirements", "features", "handoffs", "artifacts", "phase-ownership.yaml")
+    context_markers = ("spec/index.md", "index.md", "project/index.md", "knowledge/index.md")
+    legacy_markers = [legacy_planning / item for item in planning_markers] + [legacy_context / item for item in context_markers]
+    if not any(item.exists() for item in legacy_markers):
+        return
+    try:
+        manifest = json.loads((root / ".devflow/project.json").read_text(encoding="utf-8"))
+        created_at = str(manifest.get("createdAt", "")).replace("Z", "+00:00")
+        datetime.fromisoformat(created_at)
+        valid_manifest = (
+            manifest.get("schemaVersion") == 1
+            and re.fullmatch(r"[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}", str(manifest.get("projectId", "")), re.I)
+            and bool(str(manifest.get("name", "")).strip())
+            and manifest.get("layoutVersion") in (None, 1, 2)
+        )
+    except (OSError, ValueError, TypeError, json.JSONDecodeError):
+        valid_manifest = False
+        manifest = {}
+    if not valid_manifest:
+        raise RuntimeError("DEVFLOW_LEGACY_LAYOUT_CONFIRMATION_REQUIRED: valid project manifest required")
+    try:
+        marker = json.loads((root / ".devflow/layout-migration.json").read_text(encoding="utf-8"))
+        migration_complete = marker.get("schemaVersion") == 1 and marker.get("status") == "complete" and isinstance(marker.get("migrated"), list)
+    except (OSError, TypeError, json.JSONDecodeError):
+        migration_complete = False
+    for relative in ("STATE.md", "workflows", "contracts", "evidence", "review-runs", "requirements", "features", "handoffs", "artifacts", "phase-ownership.yaml"):
+        if (legacy_planning / relative).exists() and not migration_complete:
+            raise RuntimeError(f"DEVFLOW_ACTIVE_LEGACY_LAYOUT: .planning/{relative} requires dedicated control-plane migration")
+    canonical_exists = (root / ".devflow/planning").exists() or (root / ".devflow/context").exists()
+    if manifest.get("layoutVersion") == 2 and not migration_complete:
+        raise RuntimeError("DEVFLOW_LEGACY_REINTRODUCTION: v2 project cannot import legacy layout")
+    if manifest.get("layoutVersion") == 2 and migration_complete:
+        planning_legacy = any((legacy_planning / item).exists() for item in planning_markers)
+        context_legacy = any((legacy_context / item).exists() for item in context_markers)
+        if (planning_legacy and not (root / ".devflow/planning").exists()) or (context_legacy and not (root / ".devflow/context").exists()):
+            raise RuntimeError("DEVFLOW_LEGACY_REINTRODUCTION: v2 project will not backfill a missing canonical directory")
+    if canonical_exists and not migration_complete:
+        raise RuntimeError("DEVFLOW_LAYOUT_CONFLICT: canonical and legacy layouts coexist without migration marker")
+    if not canonical_exists:
+        raise RuntimeError("DEVFLOW_LAYOUT_MIGRATION_REQUIRED: run project initialization")
+
+
 def project_root(event: dict[str, Any] | None = None) -> Path:
     event = event or {}
     explicit = os.environ.get("OMP_PROJECT_DIR")
     candidate = Path(explicit or event.get("cwd") or os.getcwd()).expanduser().resolve()
     if candidate.is_file():
         candidate = candidate.parent
+    # The project manifest is the authoritative root marker. Generated
+    # directories are deliberately ignored because a nested business module
+    # may legitimately use the same names.
     for current in (candidate, *candidate.parents):
-        if any(
-            (current / marker).exists()
-            for marker in (".omp", ".agent-gates", ".planning", ".skills")
-        ):
+        if (current / ".devflow" / "project.json").is_file():
+            assert_project_layout_ready(current)
+            return current
+    for current in (candidate, *candidate.parents):
+        if (current / ".git").exists():
+            assert_project_layout_ready(current)
             return current
+    assert_project_layout_ready(candidate)
     return candidate
 
 
@@ -274,7 +328,7 @@ def path_matches(path: str, patterns: list[str]) -> bool:
 
 
 def _navigation_codebase_roots(root: Path) -> list[str]:
-    path = root / ".planning/navigation/INDEX.md"
+    path = root / ".devflow/planning/navigation/INDEX.md"
     try:
         text = path.read_text(encoding="utf-8")
     except (FileNotFoundError, PermissionError):

package/plugins/devflow-core/runtime/hooks/start.py

@@ -29,15 +29,15 @@ def detect_cli_dir(project_dir: Path) -> str:
 def load_config(project_dir: Path, cli_dir: str) -> dict:
     defaults = {
         "sources": {
-            "state": ".planning/STATE.md",
-            "workflow": ".context/workflow.md",
+            "state": ".devflow/planning/STATE.md",
+            "workflow": ".devflow/context/workflow.md",
             "indexes": [
-                ".planning/rules/INDEX.md",
-                ".context/spec/index.md",
-                ".planning/navigation/INDEX.md",
-                ".planning/code-index/INDEX.md",
+                ".devflow/planning/rules/INDEX.md",
+                ".devflow/context/spec/index.md",
+                ".devflow/planning/navigation/INDEX.md",
+                ".devflow/planning/code-index/INDEX.md",
             ],
-            "lessons": ".context/lessons/README.md",
+            "lessons": ".devflow/context/lessons/README.md",
             "commands": f"{cli_dir}/commands/start.md",
         }
     }
@@ -196,7 +196,7 @@ def main():
 
     # 项目身份
     project_name = project_dir.name
-    project_md = read_file(project_dir / ".planning" / "PROJECT.md")
+    project_md = read_file(project_dir / ".devflow/planning" / "PROJECT.md")
     for line in project_md.split("\n"):
         if line.startswith("- **Name**:"):
             project_name = line.split(":")[-1].strip()
@@ -205,13 +205,13 @@ def main():
     output.write(
         "<session-context>\n"
         f"你正在 {project_name} 项目中进行研发工作。\n"
-        "该项目使用 .planning/ 跟踪研发流水线进度，状态写入和上下文同步由 OMP extension 强制执行。\n"
+        "该项目使用 .devflow/planning/ 跟踪研发流水线进度，状态写入和上下文同步由 OMP extension 强制执行。\n"
         "索引只用于加速定位；发现索引缺失或过期时，直接回退到 LSP、搜索和源码，并报告降级状态。\n"
         "</session-context>\n\n"
     )
 
     # 跨 clear 意图
-    intent_path = project_dir / ".planning" / ".next-intent"
+    intent_path = project_dir / ".devflow/planning" / ".next-intent"
     intent = {}
     if intent_path.exists():
         try:
@@ -229,7 +229,7 @@ def main():
         output.write("\n</intent>\n\n")
 
     # Pipeline 状态
-    state_path = sources.get("state", ".planning/STATE.md")
+    state_path = sources.get("state", ".devflow/planning/STATE.md")
     state_text = load_state_section(project_dir, state_path)
     if state_text:
         output.write("<pipeline-state>\n")
@@ -237,7 +237,7 @@ def main():
         output.write("\n</pipeline-state>\n\n")
 
     # 研发流程
-    workflow_path = sources.get("workflow", ".context/workflow.md")
+    workflow_path = sources.get("workflow", ".devflow/context/workflow.md")
     workflow_text = read_file(project_dir / workflow_path)
     if workflow_text:
         output.write("<workflow>\n")
@@ -254,7 +254,7 @@ def main():
         output.write("</index-entrypoints>\n\n")
 
     # 经验教训
-    lessons_path = sources.get("lessons", ".context/lessons/README.md")
+    lessons_path = sources.get("lessons", ".devflow/context/lessons/README.md")
     lessons_text = read_file(project_dir / lessons_path)
     if lessons_text and lessons_text.strip():
         output.write("<lessons>\n")

package/plugins/devflow-core/skills/wireframe-proposal/SKILL.md

@@ -7,8 +7,8 @@ description: Generate or revise a low-fidelity wireframe proposal from controlle
 
 Read the controlled requirement baseline and the wireframe schema/registry. Produce exactly two candidate files:
 
-- .planning/features/{feature}/proposal.yaml
-- .planning/features/{feature}/questions.yaml
+- .devflow/planning/features/{feature}/proposal.yaml
+- .devflow/planning/features/{feature}/questions.yaml
 
 Use only registered element types and screen-level requirement_refs. Keep IDs stable during revision. Do not add API fields, coordinates, CSS, nested children, or approval fields. Emit valid YAML only and never claim that the proposal is validated or approved. The validator and Core decide legality, fingerprints, and approval.
 

package/plugins/devflow-core/skills/wireframe-validate/SKILL.md

@@ -11,10 +11,10 @@ Run the bundled validator through Core's `devflow_skill_script` tool:
 devflow_skill_script(
   script="wireframe-validate",
   args=[
-    "--proposal", ".planning/features/<feature>/proposal.yaml",
-    "--traceability", ".planning/requirements/<feature>/traceability.json",
-    "--questions", ".planning/features/<feature>/questions.yaml",
-    "--canonical-out", ".planning/features/<feature>/canonical.json"
+    "--proposal", ".devflow/planning/features/<feature>/proposal.yaml",
+    "--traceability", ".devflow/planning/requirements/<feature>/traceability.json",
+    "--questions", ".devflow/planning/features/<feature>/questions.yaml",
+    "--canonical-out", ".devflow/planning/features/<feature>/canonical.json"
   ]
 )
 ```