@guanlin4924/devflow-pi 0.1.92 → 0.1.94

package/src/project-context.ts

@@ -5,9 +5,11 @@ import path from "node:path";
 import { PROJECT_SCHEMA_VERSION } from "./constants.ts";
 import { InitializationStore } from "./initialization-store.ts";
 import { projectControlDatabasePath } from "./paths.ts";
+import { DEVFLOW_MANIFEST, migrateLegacyProjectLayout, PLANNING_DIRECTORY, projectLayout } from "./project-layout.ts";
 
 export interface ProjectManifest {
   schemaVersion: number;
+  layoutVersion: number;
   projectId: string;
   name: string;
   createdAt: string;
@@ -23,11 +25,12 @@ export interface ProjectContext {
 }
 
 const PROJECT_ID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+const PROJECT_LAYOUT_VERSION = 2;
 const CONTROL_BOUNDARY_PATHS = [
-  ".planning/STATE.md",
-  ".planning/.devflow.lock",
-  ".planning/workflows",
-  ".planning/artifacts",
+  `${PLANNING_DIRECTORY}/STATE.md`,
+  `${PLANNING_DIRECTORY}/.devflow.lock`,
+  `${PLANNING_DIRECTORY}/workflows`,
+  `${PLANNING_DIRECTORY}/artifacts`,
 ];
 
 async function assertNoSymlinkDescendants(target: string): Promise<void> {
@@ -58,7 +61,7 @@ async function canonicalDirectory(candidate: string): Promise<string> {
 async function nearestManifest(start: string): Promise<string | null> {
   let current = await canonicalDirectory(start);
   while (true) {
-    const manifest = path.join(current, ".devflow", "project.json");
+    const manifest = path.join(current, DEVFLOW_MANIFEST);
     if (await exists(manifest)) return current;
     const parent = path.dirname(current);
     if (parent === current) return null;
@@ -95,18 +98,21 @@ function validateManifest(value: unknown, manifestPath: string): ProjectManifest
   if (record.schemaVersion !== PROJECT_SCHEMA_VERSION) {
     throw new Error(`Unsupported project schema in ${manifestPath}: ${String(record.schemaVersion)}`);
   }
+  if (record.layoutVersion !== undefined && record.layoutVersion !== 1 && record.layoutVersion !== PROJECT_LAYOUT_VERSION) {
+    throw new Error(`Unsupported project layout in ${manifestPath}: ${String(record.layoutVersion)}`);
+  }
   if (typeof record.projectId !== "string" || !PROJECT_ID_PATTERN.test(record.projectId)) {
     throw new Error(`Invalid projectId in ${manifestPath}`);
   }
   if (typeof record.name !== "string" || !record.name || typeof record.createdAt !== "string") {
     throw new Error(`Incomplete project manifest: ${manifestPath}`);
   }
-  return record as unknown as ProjectManifest;
+  return { ...record, layoutVersion: Number(record.layoutVersion ?? 1) } as unknown as ProjectManifest;
 }
 
 export async function assertPlanningBoundary(root: string): Promise<string> {
   const canonicalRoot = await canonicalDirectory(root);
-  const planningRoot = path.join(canonicalRoot, ".planning");
+  const planningRoot = projectLayout(canonicalRoot).planningRoot;
   const stat = await lstat(planningRoot).catch(() => null);
   if (stat?.isSymbolicLink()) throw new Error(`Refusing symlinked planning root: ${planningRoot}`);
   if (stat && !stat.isDirectory()) throw new Error(`Planning root is not a directory: ${planningRoot}`);
@@ -133,8 +139,16 @@ export async function assertPlanningBoundary(root: string): Promise<string> {
 
 export async function loadProjectContext(root: string): Promise<ProjectContext> {
   const canonicalRoot = await canonicalDirectory(root);
-  const manifestPath = path.join(canonicalRoot, ".devflow", "project.json");
-  const manifest = validateManifest(JSON.parse(await readFile(manifestPath, "utf8")), manifestPath);
+  const manifestPath = projectLayout(canonicalRoot).manifestPath;
+  const manifestValue = JSON.parse(await readFile(manifestPath, "utf8")) as Record<string, unknown>;
+  validateManifest(manifestValue, manifestPath);
+  await migrateLegacyProjectLayout(canonicalRoot);
+  if (manifestValue.layoutVersion !== PROJECT_LAYOUT_VERSION) {
+    manifestValue.layoutVersion = PROJECT_LAYOUT_VERSION;
+    await atomicWriteJson(manifestPath, manifestValue);
+  }
+  const manifest = validateManifest(manifestValue, manifestPath);
+  await mkdir(projectLayout(canonicalRoot).planningRoot, { recursive: true });
   const planningRoot = await assertPlanningBoundary(canonicalRoot);
   if (!(await exists(projectControlDatabasePath(manifest.projectId)))) throw new Error("Project initialization database is not registered; run explicit project initialization first");
   return attachInitializationStore({ root: canonicalRoot, manifestPath, manifest, planningRoot });
@@ -160,22 +174,30 @@ async function atomicWriteJson(target: string, value: unknown): Promise<void> {
 
 export async function initializeProject(root: string): Promise<{ context: ProjectContext; created: boolean }> {
   const canonicalRoot = await canonicalDirectory(root);
-  const devflowDir = path.join(canonicalRoot, ".devflow");
-  const planningRoot = path.join(canonicalRoot, ".planning");
-  await assertPlanningBoundary(canonicalRoot);
+  const { devflowRoot: devflowDir, manifestPath, planningRoot } = projectLayout(canonicalRoot);
   await mkdir(devflowDir, { recursive: true });
-  await mkdir(planningRoot, { recursive: true });
-  const manifestPath = path.join(devflowDir, "project.json");
+  await assertPlanningBoundary(canonicalRoot);
   if (await exists(manifestPath)) {
     return { context: await loadProjectContext(canonicalRoot), created: false };
   }
   const manifest: ProjectManifest = {
     schemaVersion: PROJECT_SCHEMA_VERSION,
+    // Establish a v1-compatible pending identity while legacy material is
+    // assessed; only commit v2 after migration succeeds.
+    layoutVersion: 1,
     projectId: randomUUID(),
     name: path.basename(canonicalRoot),
     createdAt: new Date().toISOString(),
   };
   await atomicWriteJson(manifestPath, manifest);
+  // Explicit initialization establishes project identity before attempting a
+  // legacy-layout migration. This prevents a tracked v1 project with no local
+  // manifest from being permanently skipped, while active/conflicting legacy
+  // control state still fails closed in migrateLegacyProjectLayout.
+  await migrateLegacyProjectLayout(canonicalRoot);
+  manifest.layoutVersion = PROJECT_LAYOUT_VERSION;
+  await atomicWriteJson(manifestPath, manifest);
+  await mkdir(planningRoot, { recursive: true });
   const bootstrapStore = await InitializationStore.open({ root: canonicalRoot, manifest });
   try { await bootstrapStore.registerWorkspace(); } finally { bootstrapStore.close(); }
   return {

package/src/project-documents.ts

@@ -152,9 +152,9 @@ function classifyDocument(document: SourceDocument): DocumentClassification {
 function shouldInspectDocument(relativePath: string): boolean {
   if (!/\.(?:md|mdx|txt|adoc|rst|yaml|yml|json)$/i.test(relativePath)) return false;
   if (/^(?:\.git|node_modules|dist|build|coverage|vendor|target)\//.test(relativePath)) return false;
-  if (/^\.planning\/code-index\//.test(relativePath)) return false;
-  if (/^\.context\/requirements\/_template\//.test(relativePath)) return false;
-  return /^(?:README|docs\/|features\/|requirements\/|\.context\/|\.planning\/requirements\/|\.planning\/features\/|test-environment-guide|skit\/docs\/|text\/)/i.test(relativePath);
+  if (/^\.devflow\/planning\/code-index\//.test(relativePath)) return false;
+  if (/^\.devflow\/context\/requirements\/_template\//.test(relativePath)) return false;
+  return /^(?:README|docs\/|features\/|requirements\/|\.devflow\/context\/|\.devflow\/planning\/requirements\/|\.devflow\/planning\/features\/|test-environment-guide|skit\/docs\/|text\/)/i.test(relativePath);
 }
 async function discoverSourceDocuments(root: string): Promise<DocumentKnowledge> {
   const documents: SourceDocument[] = [];
@@ -232,7 +232,7 @@ function knowledgePagePath(type: KnowledgePageType, titleOrId: string): string {
     incident: "incidents",
     lesson: "lessons",
   } satisfies Record<KnowledgePageType, string>)[type];
-  return `.context/knowledge/${folder}/${slug(titleOrId)}.md`;
+  return `.devflow/context/knowledge/${folder}/${slug(titleOrId)}.md`;
 }
 function sourceTable(items: Array<{ source: SourceDocument; classification: DocumentClassification }>): string {
   if (!items.length) return "未发现可归类的已有文档。";
@@ -305,24 +305,24 @@ function renderDocuments(context: ProjectContext, facts: Fact[], intro: string,
   const capabilities = facts.filter(fact => fact.kind === "capability");
   const repositories = [...new Set(facts.map(fact => fact.repository).filter(Boolean))].sort();
   const outputs: Array<{ targetPath: string; body: string }> = [];
-  outputs.push({ targetPath: ".planning/PROJECT.md", body: [
+  outputs.push({ targetPath: ".devflow/planning/PROJECT.md", body: [
     `# ${context.manifest.name}`, "", intro, "", "## 代码库组成", "",
     table(["代码库", "文件数量", "已观察能力"], repositories.map(repository => [repository, assets.filter(fact => fact.repository === repository).length, [...new Set(facts.filter(fact => fact.repository === repository && ["api", "page", "data_model", "integration"].includes(fact.kind)).map(fact => fact.kind))].join("、") || "未发现"])),
     "", "## 技术概况", "", table(["声明", "来源类型"], technologies.slice(0, 100).map(fact => [fact.value.name ?? fact.value.extension, fact.value.declaration ?? "文件统计"])),
     "", "## 已知边界", "", "当前信息来自本地静态扫描。接口声明不证明服务可访问，页面声明不证明运行时渲染，命令声明不表示已经执行。", "",
   ].join("\n") });
-  outputs.push({ targetPath: ".planning/toolchain.md", body: ["# 工具链", "", intro, "", table(["代码库", "名称", "命令", "工作目录", "执行状态"], commands.map(fact => [fact.repository, fact.value.name, fact.value.command, fact.value.workingDirectory || ".", "仅发现，未执行"])), ""].join("\n") });
-  outputs.push({ targetPath: ".planning/navigation/INDEX.md", body: ["# 项目导航", "", intro, "", table(["代码库", "导航说明", "扫描文件数"], repositories.map(repository => [repository, `.planning/navigation/${repository.replace(/[^\p{L}\p{N}._-]/gu, "-")}.md`, assets.filter(fact => fact.repository === repository).length])), ""].join("\n") });
+  outputs.push({ targetPath: ".devflow/planning/toolchain.md", body: ["# 工具链", "", intro, "", table(["代码库", "名称", "命令", "工作目录", "执行状态"], commands.map(fact => [fact.repository, fact.value.name, fact.value.command, fact.value.workingDirectory || ".", "仅发现，未执行"])), ""].join("\n") });
+  outputs.push({ targetPath: ".devflow/planning/navigation/INDEX.md", body: ["# 项目导航", "", intro, "", table(["代码库", "导航说明", "扫描文件数"], repositories.map(repository => [repository, `.devflow/planning/navigation/${repository.replace(/[^\p{L}\p{N}._-]/gu, "-")}.md`, assets.filter(fact => fact.repository === repository).length])), ""].join("\n") });
   for (const repository of repositories) {
     const local = facts.filter(fact => fact.repository === repository);
-    outputs.push({ targetPath: `.planning/navigation/${repository.replace(/[^\p{L}\p{N}._-]/gu, "-")}.md`, body: [
+    outputs.push({ targetPath: `.devflow/planning/navigation/${repository.replace(/[^\p{L}\p{N}._-]/gu, "-")}.md`, body: [
       `# ${repository} 导航`, "", intro, "", "## 文件与入口", "",
       table(["路径", "类型"], local.filter(fact => fact.kind === "asset").slice(0, 200).map(fact => [fact.value.path, fact.value.extension || "无扩展名"])),
       "", "## 已发现能力", "", table(["类型", "对象"], local.filter(fact => ["api", "page", "data_model", "integration"].includes(fact.kind)).slice(0, 200).map(fact => [fact.kind, fact.value.path ?? fact.value.route ?? fact.value.name ?? fact.value.host ?? "未确认"])), "",
     ].join("\n") });
   }
-  outputs.push({ targetPath: ".planning/rules/INDEX.md", body: ["# 项目规则来源", "", intro, "", table(["代码库", "规则文件", "性质"], rules.map(fact => [fact.repository, fact.value.path, fact.value.explicit ? "显式规则" : "惯例候选"])), "", "未登记的惯例候选不会自动成为强制规则。", ""].join("\n") });
-  outputs.push({ targetPath: ".planning/initialization/report.md", body: [
+  outputs.push({ targetPath: ".devflow/planning/rules/INDEX.md", body: ["# 项目规则来源", "", intro, "", table(["代码库", "规则文件", "性质"], rules.map(fact => [fact.repository, fact.value.path, fact.value.explicit ? "显式规则" : "惯例候选"])), "", "未登记的惯例候选不会自动成为强制规则。", ""].join("\n") });
+  outputs.push({ targetPath: ".devflow/planning/initialization/report.md", body: [
     "# 项目初始化报告", "", intro, "", "## 数据可用范围", "",
     table(["采集器", "支持范围", "限制"], capabilities.map(fact => [fact.objectKey, Array.isArray(fact.value.supported) ? fact.value.supported.join("、") : "未确认", Array.isArray(fact.value.limitations) ? fact.value.limitations.join("；") : "未确认"])),
     "", "## 分项采集状态", "", table(["代码库", "专题", "状态", "诊断数"], collections.map(item => [item.repository || "全局", item.kind, item.status, item.diagnostics?.length ?? 0])),
@@ -383,13 +383,13 @@ function requirementTemplateBody(context: ProjectContext, type: KnowledgeDocumen
     related_apis: [],
     managed: true,
   });
-  return `${header}# ${documentTitle(type)}\n\n本文件是需求级文档模板。创建具体需求时复制到 \`.context/requirements/REQ-xxx-短名/${type === "requirements" ? "requirement" : type}.md\`，并把 frontmatter 中的 \`requirement_id\`、\`status\`、关联路径和 API 补全。\n\n## 当前结论\n\n- 待补充。\n\n## 证据与约束\n\n- 初始化快照：${snapshotId}\n- 代码索引 generation：${generation ?? "未生成或已跳过"}\n- 需求级内容必须引用项目级文档和实际源码证据，不能只凭推断确认。\n\n## 待补充\n\n- 背景与目标\n- 范围与非目标\n- 设计决策\n- 验收条件\n`;
+  return `${header}# ${documentTitle(type)}\n\n本文件是需求级文档模板。创建具体需求时复制到 \`.devflow/context/requirements/REQ-xxx-短名/${type === "requirements" ? "requirement" : type}.md\`，并把 frontmatter 中的 \`requirement_id\`、\`status\`、关联路径和 API 补全。\n\n## 当前结论\n\n- 待补充。\n\n## 证据与约束\n\n- 初始化快照：${snapshotId}\n- 代码索引 generation：${generation ?? "未生成或已跳过"}\n- 需求级内容必须引用项目级文档和实际源码证据，不能只凭推断确认。\n\n## 待补充\n\n- 背景与目标\n- 范围与非目标\n- 设计决策\n- 验收条件\n`;
 }
 
 function inboxRequirementBody(context: ProjectContext, source: SourceDocument, classification: DocumentClassification, snapshotId: string, generation?: string): Array<{ targetPath: string; body: string }> {
   const requirementId = classification.requirementId ?? source.id;
   const folder = `${requirementId}-${slug(source.title)}`;
-  const base = `.context/requirements/_inbox/${folder}`;
+  const base = `.devflow/context/requirements/_inbox/${folder}`;
   const documentType = classification.documentType === "unknown" ? "requirements" : classification.documentType;
   const body = `${frontmatter({ type: documentType === "requirements" ? "requirement-spec" : `requirement-${documentType}`, scope: "requirement", project: context.manifest.name, requirement_id: requirementId, status: "inbox", source_snapshot: snapshotId, code_index_generation: generation, source_documents: [source.path], managed: true })}# ${source.title}\n\n本文档由初始化阶段从已有资料归档而来，尚未确认是否为正式需求。\n\n## 来源摘要\n\n${source.excerpt || "无可用摘要。"}\n\n## 来源文档\n\n${table(["来源", "标题", "内容哈希"], [[source.path, source.title, source.contentHash]])}\n\n## 归类信息\n\n- 类型：${classification.documentType}\n- 置信度：${classification.confidence}\n- 理由：${classification.reasons.join("；")}\n\n## 待确认\n\n- 是否转为正式 REQ 编号\n- 是否拆分为多个需求\n- 是否补齐产品、技术、API 与用例文档\n`;
   return [
@@ -449,7 +449,7 @@ function buildKnowledgePages(knowledge: DocumentKnowledge, facts: Fact[]): Knowl
   const allSourceRefs = [...new Set([...pages.values()].flatMap(page => page.sourceRefs).filter(ref => ref.startsWith("source-")))];
   pages.set("synthesis-project-overview", {
     id: "synthesis-project-overview",
-    path: ".context/knowledge/synthesis/project-overview.md",
+    path: ".devflow/context/knowledge/synthesis/project-overview.md",
     type: "synthesis",
     title: "项目知识总览",
     status: "draft",
@@ -513,7 +513,7 @@ function bugKnowledgeTemplates(context: ProjectContext, snapshotId: string, gene
   const common = { project: context.manifest.name, status: "template", source_snapshot: snapshotId, code_index_generation: generation, managed: true };
   return [
     {
-      targetPath: ".context/knowledge/bugs/_template.md",
+      targetPath: ".devflow/context/knowledge/bugs/_template.md",
       body: `${frontmatter({ ...common, type: "bug-report", id: "BUG-TEMPLATE", title: "BUG 模板", source_refs: [], related_requirements: [], related_code_facts: [], related_fixes: [], regression_tests: [], confidence: "manual" })}# BUG 模板
 
 ## Symptom
@@ -546,7 +546,7 @@ function bugKnowledgeTemplates(context: ProjectContext, snapshotId: string, gene
 `,
     },
     {
-      targetPath: ".context/knowledge/fixes/_template.md",
+      targetPath: ".devflow/context/knowledge/fixes/_template.md",
       body: `${frontmatter({ ...common, type: "bug-fix", id: "FIX-TEMPLATE", title: "FIX 模板", bug_refs: [], changed_code_facts: [], regression_tests: [], confidence: "manual" })}# FIX 模板
 
 ## Change Summary
@@ -571,7 +571,7 @@ function bugKnowledgeTemplates(context: ProjectContext, snapshotId: string, gene
 `,
     },
     {
-      targetPath: ".context/knowledge/incidents/_template.md",
+      targetPath: ".devflow/context/knowledge/incidents/_template.md",
       body: `${frontmatter({ ...common, type: "incident", id: "INC-TEMPLATE", title: "INCIDENT 模板", related_bugs: [], related_fixes: [], related_code_facts: [], confidence: "manual" })}# INCIDENT 模板
 
 ## Timeline
@@ -596,7 +596,7 @@ function bugKnowledgeTemplates(context: ProjectContext, snapshotId: string, gene
 `,
     },
     {
-      targetPath: ".context/knowledge/lessons/_template.md",
+      targetPath: ".devflow/context/knowledge/lessons/_template.md",
       body: `${frontmatter({ ...common, type: "lesson", id: "LESSON-TEMPLATE", title: "LESSON 模板", related_bugs: [], related_fixes: [], related_code_facts: [], confidence: "manual" })}# LESSON 模板
 
 ## Lesson
@@ -633,9 +633,9 @@ function initializationInterfaceContracts(): InterfaceContract[] {
           name: "scan",
           purpose: "执行项目初始化扫描并发布上下文快照。",
           request: { action: "scan", mode: "full|fast", repositories: [{ name: "app", path: ".", role: "frontend|backend|shared|other" }], requiredKinds: FACT_KINDS, documentMode: "template|none", requestId: "stable-id" },
-          response: { runId: "uuid", snapshotId: "uuid", completeness: "complete|partial", database: "<control.db>", projectId: "uuid", workspaceId: "uuid", planningRoot: ".planning", diagnostics: [], documents: [{ targetPath: ".context/project/api.md", status: "complete|conflict|failed" }] },
+          response: { runId: "uuid", snapshotId: "uuid", completeness: "complete|partial", database: "<control.db>", projectId: "uuid", workspaceId: "uuid", planningRoot: ".devflow/planning", diagnostics: [], documents: [{ targetPath: ".devflow/context/project/api.md", status: "complete|conflict|failed" }] },
           reads: ["source tree", ".devflow/project.json"],
-          writes: ["control.db", ".planning/code-index/", ".planning/document-index.json", ".planning/knowledge-index.json", ".context/", ".planning/PROJECT.md"],
+          writes: ["control.db", ".devflow/planning/code-index/", ".devflow/planning/document-index.json", ".devflow/planning/knowledge-index.json", ".devflow/context/", ".devflow/planning/PROJECT.md"],
         },
         {
           name: "query",
@@ -657,9 +657,9 @@ function initializationInterfaceContracts(): InterfaceContract[] {
           name: "generate-docs",
           purpose: "针对已发布快照重试生成文档投影。",
           request: { action: "generate-docs", snapshotId: "uuid" },
-          response: [{ targetPath: ".context/project/api.md", status: "complete|conflict|failed", outputPath: "path" }],
-          reads: ["control.db", ".planning/code-index/", "source documents"],
-          writes: [".context/", ".planning/document-index.json", ".planning/knowledge-index.json"],
+          response: [{ targetPath: ".devflow/context/project/api.md", status: "complete|conflict|failed", outputPath: "path" }],
+          reads: ["control.db", ".devflow/planning/code-index/", "source documents"],
+          writes: [".devflow/context/", ".devflow/planning/document-index.json", ".devflow/planning/knowledge-index.json"],
         },
         {
           name: "config",
@@ -712,7 +712,7 @@ function initializationInterfaceContracts(): InterfaceContract[] {
         {
           name: "import-legacy",
           purpose: "把旧版初始化产物导入数据库控制面。",
-          request: { action: "import-legacy", sources: [".planning/PROJECT.md"], requestId: "stable-id" },
+          request: { action: "import-legacy", sources: [".devflow/planning/PROJECT.md"], requestId: "stable-id" },
           response: { runId: "uuid", snapshotId: "uuid", imports: [] },
           reads: ["legacy initialization files"],
           writes: ["control.db"],
@@ -720,7 +720,7 @@ function initializationInterfaceContracts(): InterfaceContract[] {
         {
           name: "export",
           purpose: "把指定初始化快照导出为兼容文件。",
-          request: { action: "export", snapshotId: "uuid", targetPath: ".planning/project-context-export.json" },
+          request: { action: "export", snapshotId: "uuid", targetPath: ".devflow/planning/project-context-export.json" },
           response: { path: "path", contentHash: "sha256:..." },
           reads: ["control.db"],
           writes: ["targetPath"],
@@ -744,7 +744,7 @@ function initializationInterfaceContracts(): InterfaceContract[] {
         {
           name: "backup",
           purpose: "备份初始化控制数据库和内容状态。",
-          request: { action: "backup", targetPath: ".planning/backups/initialization.db" },
+          request: { action: "backup", targetPath: ".devflow/planning/backups/initialization.db" },
           response: { backup: "absolute-path" },
           reads: ["control.db", "managed initialization documents"],
           writes: ["targetPath", "targetPath.manifest.json"],
@@ -752,7 +752,7 @@ function initializationInterfaceContracts(): InterfaceContract[] {
         {
           name: "restore",
           purpose: "从已验证备份恢复初始化控制数据库。",
-          request: { action: "restore", targetPath: ".planning/backups/initialization.db" },
+          request: { action: "restore", targetPath: ".devflow/planning/backups/initialization.db" },
           response: { restored: true, database: "control.db" },
           reads: ["targetPath", "targetPath.manifest.json"],
           writes: ["control.db"],
@@ -803,7 +803,7 @@ function initializationInterfaceContracts(): InterfaceContract[] {
             gaps: [],
             recommendedNextAction: "query|diff|generate-docs|scan|human-review|none",
           },
-          reads: [".planning/interface-index.json", ".planning/knowledge-index.json", ".planning/code-index/", ".context/knowledge/", "control interfaces"],
+          reads: [".devflow/planning/interface-index.json", ".devflow/planning/knowledge-index.json", ".devflow/planning/code-index/", ".devflow/context/knowledge/", "control interfaces"],
           writes: ["initialization projections through tools only"],
         },
       ],
@@ -818,11 +818,11 @@ function initializationInterfaceContracts(): InterfaceContract[] {
       actions: [
         {
           name: "scan/validate/audit/query",
-          purpose: "生成并查询 .planning/code-index/ 机器代码事实。",
-          request: { action: "scan|validate|audit|query", index: ".planning/code-index", root: "." },
+          purpose: "生成并查询 .devflow/planning/code-index/ 机器代码事实。",
+          request: { action: "scan|validate|audit|query", index: ".devflow/planning/code-index", root: "." },
           response: { generation: "uuid", files: "jsonl", symbols: "jsonl", relations: "jsonl", diagnostics: "jsonl" },
           reads: ["source tree"],
-          writes: [".planning/code-index/"],
+          writes: [".devflow/planning/code-index/"],
         },
       ],
     },
@@ -846,18 +846,18 @@ function initializationInterfaceContracts(): InterfaceContract[] {
     },
     {
       id: "artifact-knowledge-index",
-      name: ".planning/knowledge-index.json",
+      name: ".devflow/planning/knowledge-index.json",
       kind: "artifact",
-      path: ".planning/knowledge-index.json",
+      path: ".devflow/planning/knowledge-index.json",
       purpose: "知识页、来源文档、需求、代码事实和预留 BUG 节点的桥接索引。",
       approval: "read",
       actions: [
         {
           name: "read",
           purpose: "让 LLM 或工具快速发现知识层节点和绑定关系。",
-          request: { path: ".planning/knowledge-index.json" },
-          response: { schemaVersion: 1, bundleRoot: ".context/knowledge", pages: [], reservedBugKnowledgeNodes: [] },
-          reads: [".planning/knowledge-index.json"],
+          request: { path: ".devflow/planning/knowledge-index.json" },
+          response: { schemaVersion: 1, bundleRoot: ".devflow/context/knowledge", pages: [], reservedBugKnowledgeNodes: [] },
+          reads: [".devflow/planning/knowledge-index.json"],
           writes: [],
         },
       ],
@@ -912,8 +912,8 @@ function renderInterfaceOutputs(context: ProjectContext, snapshot: { id?: unknow
   const generation = codeIndexGeneration(snapshot);
   const contracts = initializationInterfaceContracts();
   const outputs: Array<{ targetPath: string; body: string }> = [];
-  outputs.push({ targetPath: ".context/knowledge/interfaces/index.md", body: `${frontmatter({ type: "interface-index", title: "初始化接口目录", project: context.manifest.name, status: "draft", source_snapshot: snapshotId, code_index_generation: generation, managed: true })}# 初始化接口目录\n\n${contracts.map(contract => `- [${contract.name}](./${slug(contract.id)}.md) — ${contract.purpose}`).join("\n")}\n` });
-  for (const contract of contracts) outputs.push({ targetPath: `.context/knowledge/interfaces/${slug(contract.id)}.md`, body: renderInterfaceContract(context, contract, snapshotId, generation) });
+  outputs.push({ targetPath: ".devflow/context/knowledge/interfaces/index.md", body: `${frontmatter({ type: "interface-index", title: "初始化接口目录", project: context.manifest.name, status: "draft", source_snapshot: snapshotId, code_index_generation: generation, managed: true })}# 初始化接口目录\n\n${contracts.map(contract => `- [${contract.name}](./${slug(contract.id)}.md) — ${contract.purpose}`).join("\n")}\n` });
+  for (const contract of contracts) outputs.push({ targetPath: `.devflow/context/knowledge/interfaces/${slug(contract.id)}.md`, body: renderInterfaceContract(context, contract, snapshotId, generation) });
   return { outputs, contracts };
 }
 
@@ -923,9 +923,9 @@ function renderOpenWikiKnowledge(context: ProjectContext, facts: Fact[], snapsho
   const pages = buildKnowledgePages(knowledge, facts);
   const sourceByRef = new Map(knowledge.sources.map(source => [sourcePageId(source), source] as const));
   const outputs: Array<{ targetPath: string; body: string }> = [];
-  outputs.push({ targetPath: ".context/knowledge/index.md", body: `${frontmatter({ type: "knowledge-bundle-index", title: `${context.manifest.name} Knowledge`, project: context.manifest.name, status: "draft", source_snapshot: snapshotId, code_index_generation: generation, managed: true })}# ${context.manifest.name} Knowledge\n\n## Sources\n\n${pages.filter(page => page.type === "source-summary").map(page => `- [${page.title}](./sources/${path.basename(page.path)})`).join("\n") || "- 暂无"}\n\n## Entities\n\n${pages.filter(page => page.type === "entity").map(page => `- [${page.title}](./entities/${path.basename(page.path)})`).join("\n") || "- 暂无"}\n\n## Concepts\n\n${pages.filter(page => page.type === "concept").map(page => `- [${page.title}](./concepts/${path.basename(page.path)})`).join("\n") || "- 暂无"}\n\n## Requirements\n\n${pages.filter(page => page.type === "requirement").map(page => `- [${page.title}](./requirements/${path.basename(page.path)})`).join("\n") || "- 暂无"}\n\n## Synthesis\n\n${pages.filter(page => page.type === "synthesis").map(page => `- [${page.title}](./synthesis/${path.basename(page.path)})`).join("\n") || "- 暂无"}\n\n## Bugs / Fixes / Incidents / Lessons\n\n- [BUG 模板](./bugs/_template.md)\n- [FIX 模板](./fixes/_template.md)\n- [INCIDENT 模板](./incidents/_template.md)\n- [LESSON 模板](./lessons/_template.md)\n` });
-  outputs.push({ targetPath: ".context/knowledge/log.md", body: `${frontmatter({ type: "knowledge-log", title: "Knowledge Operation Log", project: context.manifest.name, status: "draft", source_snapshot: snapshotId, code_index_generation: generation, managed: true })}# Knowledge Operation Log\n\n- 初始化生成 OpenWiki 风格知识层。\n- 原始文档保持在项目原位置，source-summary 记录摘要和引用。\n- 代码事实来自 \`.planning/code-index/\`，桥接关系写入 \`.planning/knowledge-index.json\`。\n` });
-  outputs.push({ targetPath: ".context/knowledge/raw/README.md", body: `${frontmatter({ type: "raw-source-readme", title: "Raw Source Policy", project: context.manifest.name, status: "draft", managed: true })}# Raw Source Policy\n\n本目录保留给后续需要复制或归档的原始资料。当前初始化默认不复制原文，只在 source-summary 中记录原路径和内容哈希，避免制造第二份权威原文。\n` });
+  outputs.push({ targetPath: ".devflow/context/knowledge/index.md", body: `${frontmatter({ type: "knowledge-bundle-index", title: `${context.manifest.name} Knowledge`, project: context.manifest.name, status: "draft", source_snapshot: snapshotId, code_index_generation: generation, managed: true })}# ${context.manifest.name} Knowledge\n\n## Sources\n\n${pages.filter(page => page.type === "source-summary").map(page => `- [${page.title}](./sources/${path.basename(page.path)})`).join("\n") || "- 暂无"}\n\n## Entities\n\n${pages.filter(page => page.type === "entity").map(page => `- [${page.title}](./entities/${path.basename(page.path)})`).join("\n") || "- 暂无"}\n\n## Concepts\n\n${pages.filter(page => page.type === "concept").map(page => `- [${page.title}](./concepts/${path.basename(page.path)})`).join("\n") || "- 暂无"}\n\n## Requirements\n\n${pages.filter(page => page.type === "requirement").map(page => `- [${page.title}](./requirements/${path.basename(page.path)})`).join("\n") || "- 暂无"}\n\n## Synthesis\n\n${pages.filter(page => page.type === "synthesis").map(page => `- [${page.title}](./synthesis/${path.basename(page.path)})`).join("\n") || "- 暂无"}\n\n## Bugs / Fixes / Incidents / Lessons\n\n- [BUG 模板](./bugs/_template.md)\n- [FIX 模板](./fixes/_template.md)\n- [INCIDENT 模板](./incidents/_template.md)\n- [LESSON 模板](./lessons/_template.md)\n` });
+  outputs.push({ targetPath: ".devflow/context/knowledge/log.md", body: `${frontmatter({ type: "knowledge-log", title: "Knowledge Operation Log", project: context.manifest.name, status: "draft", source_snapshot: snapshotId, code_index_generation: generation, managed: true })}# Knowledge Operation Log\n\n- 初始化生成 OpenWiki 风格知识层。\n- 原始文档保持在项目原位置，source-summary 记录摘要和引用。\n- 代码事实来自 \`.devflow/planning/code-index/\`，桥接关系写入 \`.devflow/planning/knowledge-index.json\`。\n` });
+  outputs.push({ targetPath: ".devflow/context/knowledge/raw/README.md", body: `${frontmatter({ type: "raw-source-readme", title: "Raw Source Policy", project: context.manifest.name, status: "draft", managed: true })}# Raw Source Policy\n\n本目录保留给后续需要复制或归档的原始资料。当前初始化默认不复制原文，只在 source-summary 中记录原路径和内容哈希，避免制造第二份权威原文。\n` });
   outputs.push(...bugKnowledgeTemplates(context, snapshotId, generation));
   for (const page of pages) outputs.push({ targetPath: page.path, body: renderKnowledgePage(context, page, sourceByRef, snapshotId, generation) });
   return { outputs, pages };
@@ -935,12 +935,12 @@ function renderKnowledgeDocuments(context: ProjectContext, facts: Fact[], intro:
   const snapshotId = String(snapshot.id ?? "");
   const generation = codeIndexGeneration(snapshot);
   const outputs: Array<{ targetPath: string; body: string }> = [];
-  outputs.push({ targetPath: ".context/index.md", body: `${frontmatter({ type: "knowledge-index", scope: "project", project: context.manifest.name, status: "draft", source_snapshot: snapshotId, code_index_generation: generation, managed: true })}# ${context.manifest.name} 项目知识库\n\n## 项目级文档\n\n${KNOWLEDGE_DOCUMENT_TYPES.map(type => `- [${documentTitle(type)}](/project/${type}.md)`).join("\n")}\n\n## 需求级文档\n\n- 新需求使用 [.context/requirements/_template/index.md](/requirements/_template/index.md) 作为文档包模板。\n\n## 机器索引\n\n- 文档索引：\`.planning/document-index.json\`\n- 代码索引：\`.planning/code-index/\`\n` });
-  outputs.push({ targetPath: ".context/spec/index.md", body: `${frontmatter({ type: "compat-spec-index", scope: "project", project: context.manifest.name, status: "compat", source_snapshot: snapshotId, code_index_generation: generation, managed: true })}# 兼容 Spec 入口\n\n本文件是项目初始化的兼容入口，用于旧流程查找 \`.context/spec/index.md\`。新的权威入口如下：\n\n- 项目知识库：[../index.md](../index.md)\n- 项目级文档：[../project/index.md](../project/index.md)\n- OpenWiki 风格知识层：[../knowledge/index.md](../knowledge/index.md)\n- 初始化接口目录：[../knowledge/interfaces/index.md](../knowledge/interfaces/index.md)\n- 文档索引：\`.planning/document-index.json\`\n- 知识索引：\`.planning/knowledge-index.json\`\n- 接口索引：\`.planning/interface-index.json\`\n- 代码索引：\`.planning/code-index/\`\n\n此兼容入口不表示需求、设计或 API 已批准；人工确认前所有生成内容保持 draft/compat 状态。\n` });
-  outputs.push({ targetPath: ".context/project/index.md", body: `${frontmatter({ type: "project-document-index", scope: "project", project: context.manifest.name, status: "draft", source_snapshot: snapshotId, code_index_generation: generation, managed: true })}# 项目级文档\n\n${KNOWLEDGE_DOCUMENT_TYPES.map(type => `- [${documentTitle(type)}](./${type}.md)`).join("\n")}\n` });
-  for (const type of KNOWLEDGE_DOCUMENT_TYPES) outputs.push({ targetPath: `.context/project/${type}.md`, body: projectKnowledgeBody(context, type, facts, intro, snapshotId, knowledge, generation) });
-  outputs.push({ targetPath: ".context/requirements/_template/index.md", body: `${frontmatter({ type: "requirement-document-index", scope: "requirement", project: context.manifest.name, requirement_id: "REQ-TEMPLATE", status: "template", source_snapshot: snapshotId, code_index_generation: generation, managed: true })}# 需求级文档模板\n\n${KNOWLEDGE_DOCUMENT_TYPES.map(type => `- [${documentTitle(type)}](./${type === "requirements" ? "requirement" : type}.md)`).join("\n")}\n` });
-  for (const type of KNOWLEDGE_DOCUMENT_TYPES) outputs.push({ targetPath: `.context/requirements/_template/${type === "requirements" ? "requirement" : type}.md`, body: requirementTemplateBody(context, type, snapshotId, generation) });
+  outputs.push({ targetPath: ".devflow/context/index.md", body: `${frontmatter({ type: "knowledge-index", scope: "project", project: context.manifest.name, status: "draft", source_snapshot: snapshotId, code_index_generation: generation, managed: true })}# ${context.manifest.name} 项目知识库\n\n## 项目级文档\n\n${KNOWLEDGE_DOCUMENT_TYPES.map(type => `- [${documentTitle(type)}](/project/${type}.md)`).join("\n")}\n\n## 需求级文档\n\n- 新需求使用 [.devflow/context/requirements/_template/index.md](/requirements/_template/index.md) 作为文档包模板。\n\n## 机器索引\n\n- 文档索引：\`.devflow/planning/document-index.json\`\n- 代码索引：\`.devflow/planning/code-index/\`\n` });
+  outputs.push({ targetPath: ".devflow/context/spec/index.md", body: `${frontmatter({ type: "compat-spec-index", scope: "project", project: context.manifest.name, status: "compat", source_snapshot: snapshotId, code_index_generation: generation, managed: true })}# 兼容 Spec 入口\n\n本文件是项目初始化的兼容入口，用于旧流程查找 \`.devflow/context/spec/index.md\`。新的权威入口如下：\n\n- 项目知识库：[../index.md](../index.md)\n- 项目级文档：[../project/index.md](../project/index.md)\n- OpenWiki 风格知识层：[../knowledge/index.md](../knowledge/index.md)\n- 初始化接口目录：[../knowledge/interfaces/index.md](../knowledge/interfaces/index.md)\n- 文档索引：\`.devflow/planning/document-index.json\`\n- 知识索引：\`.devflow/planning/knowledge-index.json\`\n- 接口索引：\`.devflow/planning/interface-index.json\`\n- 代码索引：\`.devflow/planning/code-index/\`\n\n此兼容入口不表示需求、设计或 API 已批准；人工确认前所有生成内容保持 draft/compat 状态。\n` });
+  outputs.push({ targetPath: ".devflow/context/project/index.md", body: `${frontmatter({ type: "project-document-index", scope: "project", project: context.manifest.name, status: "draft", source_snapshot: snapshotId, code_index_generation: generation, managed: true })}# 项目级文档\n\n${KNOWLEDGE_DOCUMENT_TYPES.map(type => `- [${documentTitle(type)}](./${type}.md)`).join("\n")}\n` });
+  for (const type of KNOWLEDGE_DOCUMENT_TYPES) outputs.push({ targetPath: `.devflow/context/project/${type}.md`, body: projectKnowledgeBody(context, type, facts, intro, snapshotId, knowledge, generation) });
+  outputs.push({ targetPath: ".devflow/context/requirements/_template/index.md", body: `${frontmatter({ type: "requirement-document-index", scope: "requirement", project: context.manifest.name, requirement_id: "REQ-TEMPLATE", status: "template", source_snapshot: snapshotId, code_index_generation: generation, managed: true })}# 需求级文档模板\n\n${KNOWLEDGE_DOCUMENT_TYPES.map(type => `- [${documentTitle(type)}](./${type === "requirements" ? "requirement" : type}.md)`).join("\n")}\n` });
+  for (const type of KNOWLEDGE_DOCUMENT_TYPES) outputs.push({ targetPath: `.devflow/context/requirements/_template/${type === "requirements" ? "requirement" : type}.md`, body: requirementTemplateBody(context, type, snapshotId, generation) });
   for (const item of knowledge.classifications.filter(item => item.scope === "requirement" && item.confidence !== "exact").slice(0, 100)) {
     const source = knowledge.sources.find(source => source.id === item.sourceDocumentId);
     if (source) outputs.push(...inboxRequirementBody(context, source, item, snapshotId, generation));
@@ -952,21 +952,21 @@ function renderDocumentIndex(context: ProjectContext, snapshot: { id?: unknown;
   const snapshotId = String(snapshot.id ?? "");
   const generation = codeIndexGeneration(snapshot);
   const documents = outputs
-    .filter(output => output.targetPath.startsWith(".context/"))
+    .filter(output => output.targetPath.startsWith(".devflow/context/"))
     .map(output => {
       const parts = output.targetPath.split("/");
       const file = parts.at(-1) ?? "";
-      const scope: IndexedDocumentScope = parts[1] === "project" ? "project" : parts[1] === "requirements" ? "requirement" : parts[1] === "knowledge" ? "knowledge" : "project";
-      const type = output.targetPath === ".context/index.md" ? "knowledge-index"
-        : output.targetPath === ".context/knowledge/index.md" ? "knowledge-bundle-index"
-          : scope === "knowledge" ? `knowledge-${parts[2] === "log.md" ? "log" : parts[2] ?? "page"}`
+      const scope: IndexedDocumentScope = parts[2] === "project" ? "project" : parts[2] === "requirements" ? "requirement" : parts[2] === "knowledge" ? "knowledge" : "project";
+      const type = output.targetPath === ".devflow/context/index.md" ? "knowledge-index"
+        : output.targetPath === ".devflow/context/knowledge/index.md" ? "knowledge-bundle-index"
+          : scope === "knowledge" ? `knowledge-${parts[3] === "log.md" ? "log" : parts[3] ?? "page"}`
         : scope === "project" ? `project-${file.replace(/\.md$/, "")}`
           : `requirement-${file.replace(/^requirement\.md$/, "requirements").replace(/\.md$/, "")}`;
       return {
         path: output.targetPath,
         type,
         scope,
-        requirementId: scope === "requirement" ? (parts[2] === "_template" ? "REQ-TEMPLATE" : parts[2]) : undefined,
+        requirementId: scope === "requirement" ? (parts[3] === "_template" ? "REQ-TEMPLATE" : parts[3]) : undefined,
         status: parts.includes("_template") ? "template" : parts.includes("_inbox") ? "inbox" : "draft",
         managed: true,
         sourceSnapshot: snapshotId,
@@ -974,7 +974,7 @@ function renderDocumentIndex(context: ProjectContext, snapshot: { id?: unknown;
       };
     });
   return {
-    targetPath: ".planning/document-index.json",
+    targetPath: ".devflow/planning/document-index.json",
     body: `${JSON.stringify({
       schemaVersion: 2,
       project: context.manifest.name,
@@ -993,14 +993,14 @@ function renderKnowledgeIndex(context: ProjectContext, snapshot: { id?: unknown;
   const snapshotId = String(snapshot.id ?? "");
   const generation = codeIndexGeneration(snapshot);
   return {
-    targetPath: ".planning/knowledge-index.json",
+    targetPath: ".devflow/planning/knowledge-index.json",
     body: `${JSON.stringify({
       schemaVersion: 1,
       project: context.manifest.name,
       projectId: context.manifest.projectId,
       sourceSnapshot: snapshotId,
       codeIndexGeneration: generation ?? null,
-      bundleRoot: ".context/knowledge",
+      bundleRoot: ".devflow/context/knowledge",
       sourceDocuments: knowledge.sources,
       classifications: knowledge.classifications,
       pages: pages.map(page => ({
@@ -1015,10 +1015,10 @@ function renderKnowledgeIndex(context: ProjectContext, snapshot: { id?: unknown;
         confidence: page.confidence,
       })),
       reservedBugKnowledgeNodes: [
-        { id: "BUG-TEMPLATE", path: ".context/knowledge/bugs/_template.md", type: "bug-report", purpose: "问题现象、影响、复现、根因和回归绑定模板" },
-        { id: "FIX-TEMPLATE", path: ".context/knowledge/fixes/_template.md", type: "bug-fix", purpose: "修复动作、变更原因、变更文件和回归覆盖模板" },
-        { id: "INC-TEMPLATE", path: ".context/knowledge/incidents/_template.md", type: "incident", purpose: "事故时间线、影响、缓解和后续行动模板" },
-        { id: "LESSON-TEMPLATE", path: ".context/knowledge/lessons/_template.md", type: "lesson", purpose: "可复用排障经验和检查规则模板" },
+        { id: "BUG-TEMPLATE", path: ".devflow/context/knowledge/bugs/_template.md", type: "bug-report", purpose: "问题现象、影响、复现、根因和回归绑定模板" },
+        { id: "FIX-TEMPLATE", path: ".devflow/context/knowledge/fixes/_template.md", type: "bug-fix", purpose: "修复动作、变更原因、变更文件和回归覆盖模板" },
+        { id: "INC-TEMPLATE", path: ".devflow/context/knowledge/incidents/_template.md", type: "incident", purpose: "事故时间线、影响、缓解和后续行动模板" },
+        { id: "LESSON-TEMPLATE", path: ".devflow/context/knowledge/lessons/_template.md", type: "lesson", purpose: "可复用排障经验和检查规则模板" },
       ],
       interfaces: interfaces.map(item => ({ id: item.id, name: item.name, kind: item.kind, path: item.path, purpose: item.purpose, approval: item.approval, actions: item.actions.map(action => action.name) })),
     }, null, 2)}\n`,
@@ -1029,7 +1029,7 @@ function renderInterfaceIndex(context: ProjectContext, snapshot: { id?: unknown;
   const snapshotId = String(snapshot.id ?? "");
   const generation = codeIndexGeneration(snapshot);
   return {
-    targetPath: ".planning/interface-index.json",
+    targetPath: ".devflow/planning/interface-index.json",
     body: `${JSON.stringify({
       schemaVersion: 1,
       project: context.manifest.name,
@@ -1068,7 +1068,7 @@ export async function generateProjectDocuments(context: ProjectContext, snapshot
     } while (after);
     const run = runId ? store.getRun(runId) as { collections?: Array<{ repository?: string; kind?: string; status?: string; diagnostics?: unknown[] }> } | null : null;
     const collections = run?.collections ?? [];
-    const batchJob = store.createDocumentJob(snapshotId, { targetPath: ".planning/initialization/report.md", ownership: "generated", templateVersion: TEMPLATE_VERSION, modelRole: options.organizer ? `${options.organizer.role}:${options.organizer.model}` : options.mode, input: facts.map(fact => fact.objectKey) });
+    const batchJob = store.createDocumentJob(snapshotId, { targetPath: ".devflow/planning/initialization/report.md", ownership: "generated", templateVersion: TEMPLATE_VERSION, modelRole: options.organizer ? `${options.organizer.role}:${options.organizer.model}` : options.mode, input: facts.map(fact => fact.objectKey) });
     let organized;
     try { organized = await narrative(context, "project-initialization", facts, options.mode, options.organizer); }
     catch (error) { store.failDocumentJob(batchJob, error instanceof Error ? error.message : String(error)); throw error; }

package/src/project-initializer.ts

@@ -4,8 +4,9 @@ import path from "node:path";
 
 import { FACT_KINDS, InitializationStore, type FactInput, type FactKind, type ScanConfigInput } from "./initialization-store.ts";
 import type { ProjectContext } from "./project-context.ts";
+import { DEVFLOW_SCAN_EXCLUDES, PLANNING_DIRECTORY } from "./project-layout.ts";
 
-const DEFAULT_EXCLUDED = new Set([".git", ".devflow", ".planning", "node_modules", "dist", "build", "coverage", "target", "vendor", ".next", ".nuxt"]);
+const DEFAULT_EXCLUDED = new Set([".git", ".devflow", ".planning", ".context", "node_modules", "dist", "build", "coverage", "target", "vendor", ".next", ".nuxt"]);
 const TEXT_EXTENSIONS = new Set([".ts", ".tsx", ".js", ".jsx", ".py", ".rb", ".go", ".java", ".kt", ".rs", ".php", ".sql", ".json", ".yaml", ".yml", ".toml", ".md"]);
 
 type SourceFile = { repository: string; path: string; absolute: string; contentHash: string; size: number; text?: string };
@@ -78,7 +79,7 @@ async function scan(context: ProjectContext, config: ScanConfigInput): Promise<{
   const diagnostics: ScanDiagnostic[] = [];
   const repositoryVersions: Array<{ repository: string; revision: string | null }> = [];
   const includes = config.includes ?? ["**/*"];
-  const excludes = config.excludes ?? [".git/**", ".planning/**", ".devflow/**"];
+  const excludes = [...new Set([...DEVFLOW_SCAN_EXCLUDES, ...(config.excludes ?? [])])];
   for (const repository of config.repositories) {
     const root = path.resolve(context.root, repository.relativePath);
     if (!path.isAbsolute(repository.relativePath) && root !== context.root && !root.startsWith(`${context.root}${path.sep}`)) throw new Error(`Repository escapes project root: ${repository.relativePath}`);
@@ -217,26 +218,39 @@ async function runProcess(argv: string[], cwd: string, label = path.basename(arg
 
 async function buildCodeIndex(context: ProjectContext, config: ScanConfigInput): Promise<Record<string, unknown>> {
   const script = path.resolve(import.meta.dir, "../plugins/devflow-intel/skills/workflow-code-index/scripts/code_index.py");
-  const output = `.planning/.code-index-pending-${randomUUID()}`;
+  const output = `${PLANNING_DIRECTORY}/.code-index-pending-${randomUUID()}`;
   const codebases = config.repositories.flatMap(repository => ["--codebase", `${repository.name}:${path.resolve(context.root, repository.relativePath)}:${repository.role}`]);
   const scopeArgs = [
     ...(config.includes ?? ["**/*"]).flatMap(pattern => ["--include", pattern]),
-    ...(config.excludes ?? [".git/**", ".planning/**", ".devflow/**"]).flatMap(pattern => ["--exclude", pattern]),
+    ...([...new Set([...DEVFLOW_SCAN_EXCLUDES, ...(config.excludes ?? [])])]).flatMap(pattern => ["--exclude", pattern]),
     "--max-file-size", String(config.maxFileSize ?? 2 * 1024 * 1024),
   ];
   await runProcess(["python3", script, "scan", "--root", context.root, "--output", output, ...scopeArgs, ...codebases], context.root, "code-index scan");
-  await runProcess(["python3", script, "validate", "--index", output, "--level", "publish"], context.root, "code-index validate");
-  await runProcess(["python3", script, "audit", "--root", context.root, "--index", output, "--skill-root", path.resolve(import.meta.dir, "../plugins/devflow-intel/skills"), "--level", "publish"], context.root, "code-index audit");
+  try {
+    await runProcess(["python3", script, "validate", "--index", output, "--level", "publish"], context.root, "code-index validate");
+    await runProcess(["python3", script, "audit", "--root", context.root, "--index", output, "--skill-root", path.resolve(import.meta.dir, "../plugins/devflow-intel/skills"), "--level", "publish"], context.root, "code-index audit");
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return {
+      path: `${PLANNING_DIRECTORY}/code-index`,
+      stagingPath: output,
+      status: "degraded",
+      reason: "code_index_publish_failed",
+      fallback: "bounded_source_search",
+      diagnostics: [message],
+    };
+  }
   const snapshotPath = path.join(context.root, output, "SNAPSHOT.json");
   const bytes = await readFile(snapshotPath); const snapshot = JSON.parse(bytes.toString("utf8")) as Record<string, unknown>;
   if (!snapshot.generation || !snapshot.immutablePath) throw new Error("Code index did not publish an immutable generation");
   const workspace = (snapshot.workspace ?? {}) as Record<string, unknown>;
-  return { path: ".planning/code-index", stagingPath: output, generation: snapshot.generation, immutablePath: snapshot.immutablePath, snapshotHash: digest(bytes), contentManifestHash: workspace.contentManifestHash, repositoryRevision: workspace.repositoryRevision, status: "complete" };
+  return { path: `${PLANNING_DIRECTORY}/code-index`, stagingPath: output, generation: snapshot.generation, immutablePath: snapshot.immutablePath, snapshotHash: digest(bytes), contentManifestHash: workspace.contentManifestHash, repositoryRevision: workspace.repositoryRevision, status: "complete" };
 }
 
 async function promoteCodeIndex(context: ProjectContext, indexRef: Record<string, unknown>): Promise<() => Promise<void>> {
+  if (indexRef.status !== "complete") return async () => {};
   const stagingPath = typeof indexRef.stagingPath === "string" ? path.resolve(context.root, indexRef.stagingPath) : null;
-  const target = path.resolve(context.root, ".planning/code-index");
+  const target = path.resolve(context.root, PLANNING_DIRECTORY, "code-index");
   if (!stagingPath) return async () => {};
   const previous = `${target}.previous-${randomUUID()}`;
   const existing = await stat(target).catch(() => null);
@@ -340,7 +354,7 @@ export async function runProjectInitialization(context: ProjectContext, input: {
       } catch (error) {
         const message = error instanceof Error ? error.message : String(error);
         diagnostics.push(`Document generation failed independently: ${message}`);
-        documents = [{ targetPath: ".planning/initialization/report.md", status: "failed", error: message }];
+        documents = [{ targetPath: ".devflow/planning/initialization/report.md", status: "failed", error: message }];
       }
     }
     return {