@guanlin4924/devflow-pi 0.1.62 → 0.1.64

package/src/paths.ts

@@ -32,6 +32,15 @@ export function projectSessionDir(projectId: string): string {
   return path.join(devflowHome(), "sessions", projectId);
 }
 
+export function projectDataDir(projectId: string): string {
+  if (!/^[0-9a-f-]{36}$/i.test(projectId)) throw new Error(`Invalid project id: ${projectId}`);
+  return path.join(devflowHome(), "projects", projectId);
+}
+
+export function projectControlDatabasePath(projectId: string): string {
+  return path.join(projectDataDir(projectId), "control.db");
+}
+
 export function ompSdkManifestPath(): string {
   return fileURLToPath(import.meta.resolve("@oh-my-pi/pi-coding-agent/package.json"));
 }

package/src/project-context.ts

@@ -3,6 +3,8 @@ import { access, lstat, mkdir, readFile, realpath, readdir, rename, writeFile }
 import path from "node:path";
 
 import { PROJECT_SCHEMA_VERSION } from "./constants.ts";
+import { InitializationStore } from "./initialization-store.ts";
+import { projectControlDatabasePath } from "./paths.ts";
 
 export interface ProjectManifest {
   schemaVersion: number;
@@ -16,6 +18,8 @@ export interface ProjectContext {
   manifestPath: string;
   manifest: ProjectManifest;
   planningRoot: string;
+  workspaceId: string;
+  controlDatabasePath: string;
 }
 
 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;
@@ -132,7 +136,18 @@ export async function loadProjectContext(root: string): Promise<ProjectContext>
   const manifestPath = path.join(canonicalRoot, ".devflow", "project.json");
   const manifest = validateManifest(JSON.parse(await readFile(manifestPath, "utf8")), manifestPath);
   const planningRoot = await assertPlanningBoundary(canonicalRoot);
-  return { root: canonicalRoot, manifestPath, manifest, planningRoot };
+  return attachInitializationStore({ root: canonicalRoot, manifestPath, manifest, planningRoot });
+}
+
+async function attachInitializationStore(context: Omit<ProjectContext, "workspaceId" | "controlDatabasePath">): Promise<ProjectContext> {
+  const store = await InitializationStore.open(context);
+  try {
+    const workspace = await store.registerWorkspace();
+    store.putScanConfig({ mode: "full", repositories: [{ name: context.manifest.name, relativePath: ".", role: "other" }] });
+    return { ...context, workspaceId: workspace.id, controlDatabasePath: projectControlDatabasePath(context.manifest.projectId) };
+  } finally {
+    store.close();
+  }
 }
 
 async function atomicWriteJson(target: string, value: unknown): Promise<void> {
@@ -160,7 +175,7 @@ export async function initializeProject(root: string): Promise<{ context: Projec
   };
   await atomicWriteJson(manifestPath, manifest);
   return {
-    context: { root: canonicalRoot, manifestPath, manifest, planningRoot },
+    context: await attachInitializationStore({ root: canonicalRoot, manifestPath, manifest, planningRoot }),
     created: true,
   };
 }

package/src/project-documents.ts

@@ -0,0 +1,243 @@
+import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
+
+import { InitializationStore } from "./initialization-store.ts";
+import type { ProjectContext } from "./project-context.ts";
+
+export interface LowTierDocumentOrganizer {
+  role: string;
+  model: string;
+  organize(input: { document: string; project: string; knownFacts: string[]; unknowns: string[] }): Promise<string>;
+}
+
+export type DocumentGenerationMode = "low-tier-model" | "template";
+export type DocumentGenerationResult = { targetPath: string; status: "complete" | "conflict" | "failed"; outputPath?: string; error?: string };
+
+type Fact = { kind: string; repository: string; objectKey: string; value: Record<string, unknown>; evidenceLevel: string };
+const TEMPLATE_VERSION = "project-context-v2";
+const KNOWLEDGE_DOCUMENT_TYPES = [
+  "requirements",
+  "product-design",
+  "architecture",
+  "frontend-tech",
+  "backend-tech",
+  "test-cases",
+  "api",
+] as const;
+type KnowledgeDocumentType = typeof KNOWLEDGE_DOCUMENT_TYPES[number];
+
+function markdownCell(value: unknown): string {
+  return String(value ?? "未确认").replaceAll("|", "\\|").replace(/[\r\n]+/g, " ");
+}
+function sha(value: string): string { return `sha256:${createHash("sha256").update(value).digest("hex")}`; }
+async function currentHash(target: string): Promise<string | null> {
+  try { return sha(await readFile(target, "utf8")); } catch { return null; }
+}
+function safeNarrative(value: string): string {
+  const text = value.trim();
+  if (!text) return "现有数据不足以确认更多项目用途。";
+  if (text.includes("```") || /\b(?:schema_version|snapshotId|runId|sha256:|CREATE TABLE)\b/i.test(text)) throw new Error("Model output contains internal structure or unsupported machine details");
+  return text;
+}
+function table(headers: string[], rows: unknown[][]): string {
+  return [`| ${headers.join(" | ")} |`, `|${headers.map(() => "---").join("|")}|`, ...rows.map(row => `| ${row.map(markdownCell).join(" | ")} |`)].join("\n");
+}
+function yamlString(value: string): string { return JSON.stringify(value); }
+function frontmatter(fields: Record<string, string | boolean | string[] | null | undefined>): string {
+  const lines = ["---"];
+  for (const [key, value] of Object.entries(fields)) {
+    if (value === undefined || value === null) continue;
+    if (Array.isArray(value)) lines.push(`${key}: [${value.map(yamlString).join(", ")}]`);
+    else if (typeof value === "boolean") lines.push(`${key}: ${value ? "true" : "false"}`);
+    else lines.push(`${key}: ${yamlString(value)}`);
+  }
+  lines.push("---", "");
+  return lines.join("\n");
+}
+function documentTitle(type: KnowledgeDocumentType): string {
+  return ({
+    "requirements": "需求文档",
+    "product-design": "产品与交互设计",
+    "architecture": "架构设计",
+    "frontend-tech": "前端技术方案",
+    "backend-tech": "后端技术方案",
+    "test-cases": "用例与验收",
+    "api": "API 文档",
+  } satisfies Record<KnowledgeDocumentType, string>)[type];
+}
+function codeIndexGeneration(snapshot: { indexRef?: unknown }): string | undefined {
+  const indexRef = snapshot.indexRef as Record<string, unknown> | undefined;
+  return typeof indexRef?.generation === "string" ? indexRef.generation : undefined;
+}
+
+async function narrative(context: ProjectContext, document: string, facts: Fact[], mode: DocumentGenerationMode, organizer?: LowTierDocumentOrganizer): Promise<{ text: string; modelRole?: string }> {
+  const knownFacts = facts.slice(0, 80).map(fact => `${fact.kind}: ${Object.values(fact.value).filter(value => typeof value === "string" || typeof value === "number").slice(0, 3).join(" / ")}`);
+  const unknowns = facts.filter(fact => fact.evidenceLevel === "candidate").map(fact => fact.objectKey).slice(0, 20);
+  if (mode === "template") return { text: "以下内容由固定项目上下文快照整理。源码静态声明不代表运行环境已启用，未确认项保持未确认。", modelRole: "template" };
+  if (!organizer) throw new Error("Low-tier document generation was requested but no organizer is configured");
+  if (!/low|small|mini|flash|lite/i.test(`${organizer.role} ${organizer.model}`)) throw new Error("Document organizer is not configured as a low-tier model");
+  return { text: safeNarrative(await organizer.organize({ document, project: context.manifest.name, knownFacts, unknowns })), modelRole: `${organizer.role}:${organizer.model}` };
+}
+
+function renderDocuments(context: ProjectContext, facts: Fact[], intro: string, collections: Array<{ repository?: string; kind?: string; status?: string; diagnostics?: unknown[] }>): Array<{ targetPath: string; body: string }> {
+  const assets = facts.filter(fact => fact.kind === "asset");
+  const technologies = facts.filter(fact => fact.kind === "technology");
+  const commands = facts.filter(fact => fact.kind === "toolchain");
+  const rules = facts.filter(fact => fact.kind === "rule");
+  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: [
+    `# ${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") });
+  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: [
+      `# ${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: [
+    "# 项目初始化报告", "", 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])),
+    "", "## 未知项", "", ...((facts.some(fact => fact.evidenceLevel === "candidate") ? facts.filter(fact => fact.evidenceLevel === "candidate").slice(0, 30).map(fact => `- ${markdownCell(fact.objectKey)}：候选，尚未核对`) : ["未记录候选未知项。"])), "",
+  ].join("\n") });
+  return outputs;
+}
+
+function projectKnowledgeBody(context: ProjectContext, type: KnowledgeDocumentType, facts: Fact[], intro: string, snapshotId: string, generation?: string): string {
+  const apis = facts.filter(fact => fact.kind === "api");
+  const pages = facts.filter(fact => fact.kind === "page");
+  const models = facts.filter(fact => fact.kind === "data_model");
+  const tech = facts.filter(fact => fact.kind === "technology");
+  const commands = facts.filter(fact => fact.kind === "toolchain");
+  const integrations = facts.filter(fact => fact.kind === "integration");
+  const repositoryNames = [...new Set(facts.map(fact => fact.repository).filter(Boolean))].sort();
+  const header = frontmatter({
+    type: `project-${type}`,
+    scope: "project",
+    project: context.manifest.name,
+    status: "draft",
+    source_snapshot: snapshotId,
+    code_index_generation: generation,
+    managed: true,
+  });
+  const evidence = [
+    "",
+    "## 证据绑定",
+    "",
+    `- 初始化快照：${snapshotId}`,
+    `- 代码索引 generation：${generation ?? "未生成或已跳过"}`,
+    "- 本文档由项目初始化创建骨架，人工确认前均为 draft。",
+    "",
+  ].join("\n");
+  if (type === "requirements") return `${header}# 项目总体需求\n\n${intro}\n\n## 项目范围\n\n${table(["代码库", "扫描事实数"], repositoryNames.map(repository => [repository, facts.filter(fact => fact.repository === repository).length]))}\n\n## 已观察业务能力\n\n${table(["类型", "对象"], [...pages, ...apis, ...models].slice(0, 80).map(fact => [fact.kind, fact.value.route ?? fact.value.path ?? fact.value.name ?? fact.objectKey]))}\n\n## 待人工补充\n\n- 项目目标与非目标\n- 用户角色与核心流程\n- 业务约束与优先级\n${evidence}`;
+  if (type === "product-design") return `${header}# 项目产品与交互设计\n\n${intro}\n\n## 已发现页面/入口\n\n${table(["代码库", "页面或入口"], pages.slice(0, 100).map(fact => [fact.repository, fact.value.route ?? fact.value.componentPath ?? fact.objectKey]))}\n\n## 待人工补充\n\n- 信息架构\n- 页面状态与异常态\n- 文案、权限与可访问性约束\n${evidence}`;
+  if (type === "architecture") return `${header}# 项目架构设计\n\n${intro}\n\n## 已观察结构\n\n${table(["代码库", "事实类型", "对象"], facts.filter(fact => ["api", "data_model", "integration", "capability"].includes(fact.kind)).slice(0, 120).map(fact => [fact.repository, fact.kind, fact.value.path ?? fact.value.name ?? fact.value.host ?? fact.objectKey]))}\n\n## 待人工补充\n\n- 系统边界与部署关系\n- 模块职责与依赖方向\n- 数据流、风险与降级策略\n${evidence}`;
+  if (type === "frontend-tech") return `${header}# 项目前端技术方案\n\n${intro}\n\n## 已观察前端技术\n\n${table(["声明", "来源"], tech.filter(fact => /react|vue|vite|router|zustand|tailwind|typescript|eslint|vitest/i.test(String(fact.value.name ?? fact.value.extension ?? ""))).slice(0, 120).map(fact => [fact.value.name ?? fact.value.extension, fact.value.declaration ?? fact.value.path ?? "文件统计"]))}\n\n## 待人工补充\n\n- 路由、状态管理与组件边界\n- API 调用约定\n- 构建、测试与发布规则\n${evidence}`;
+  if (type === "backend-tech") return `${header}# 项目后端技术方案\n\n${intro}\n\n## 已观察后端事实\n\n${table(["类型", "对象"], [...apis, ...models, ...integrations].slice(0, 120).map(fact => [fact.kind, fact.value.path ?? fact.value.name ?? fact.value.host ?? fact.objectKey]))}\n\n## 待人工补充\n\n- handler/service/repository 分层\n- 数据库迁移与任务调度规则\n- 鉴权、错误码、日志与监控\n${evidence}`;
+  if (type === "test-cases") return `${header}# 项目用例与验收\n\n${intro}\n\n## 已发现测试/命令线索\n\n${table(["代码库", "名称", "命令或路径"], commands.slice(0, 120).map(fact => [fact.repository, fact.value.name ?? "test-definition", fact.value.command ?? fact.value.testDefinition ?? fact.objectKey]))}\n\n## 待人工补充\n\n- 核心主流程验收用例\n- 异常路径与权限用例\n- 回归范围与自动化策略\n${evidence}`;
+  return `${header}# 项目 API 文档\n\n${intro}\n\n## 已发现 API 声明\n\n${table(["代码库", "方法", "路径"], apis.slice(0, 160).map(fact => [fact.repository, fact.value.method ?? "未确认", fact.value.path ?? fact.objectKey]))}\n\n## 待人工补充\n\n- 认证与公共请求头\n- 通用响应结构与错误码\n- 兼容性与废弃策略\n${evidence}`;
+}
+
+function requirementTemplateBody(context: ProjectContext, type: KnowledgeDocumentType, snapshotId: string, generation?: string): string {
+  const header = frontmatter({
+    type: `requirement-${type}`,
+    scope: "requirement",
+    project: context.manifest.name,
+    requirement_id: "REQ-TEMPLATE",
+    status: "template",
+    source_snapshot: snapshotId,
+    code_index_generation: generation,
+    related_paths: [],
+    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`;
+}
+
+function renderKnowledgeDocuments(context: ProjectContext, facts: Fact[], intro: string, snapshot: { id?: unknown; indexRef?: unknown }): Array<{ targetPath: string; body: string }> {
+  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/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, 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) });
+  return outputs;
+}
+
+function renderDocumentIndex(context: ProjectContext, snapshot: { id?: unknown; indexRef?: unknown }, outputs: Array<{ targetPath: string }>): { targetPath: string; body: string } {
+  const snapshotId = String(snapshot.id ?? "");
+  const generation = codeIndexGeneration(snapshot);
+  const documents = outputs
+    .filter(output => output.targetPath.startsWith(".context/"))
+    .map(output => {
+      const parts = output.targetPath.split("/");
+      const file = parts.at(-1) ?? "";
+      const scope = parts[1] === "project" ? "project" : parts[1] === "requirements" ? "requirement" : "project";
+      const type = output.targetPath === ".context/index.md" ? "knowledge-index"
+        : 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,
+        status: parts.includes("_template") ? "template" : "draft",
+        managed: true,
+        sourceSnapshot: snapshotId,
+        codeIndexGeneration: generation ?? null,
+      };
+    });
+  return {
+    targetPath: ".planning/document-index.json",
+    body: `${JSON.stringify({ schemaVersion: 1, project: context.manifest.name, projectId: context.manifest.projectId, sourceSnapshot: snapshotId, codeIndexGeneration: generation ?? null, documents }, null, 2)}\n`,
+  };
+}
+
+export async function generateProjectDocuments(context: ProjectContext, snapshotId: string, options: { mode: DocumentGenerationMode; organizer?: LowTierDocumentOrganizer }): Promise<DocumentGenerationResult[]> {
+  const store = await InitializationStore.open(context);
+  try {
+    const facts: Fact[] = []; let after: string | undefined; let runId: string | undefined;
+    do {
+      const page = store.queryContext({ snapshotId, limit: 500, after }) as { snapshot: { runId: string }; facts: Fact[]; truncated: boolean; nextCursor: string | null };
+      runId = page.snapshot.runId;
+      facts.push(...page.facts); after = page.nextCursor ?? undefined;
+      if (facts.length > 50_000) throw new Error("Document manifest exceeds the bounded 50,000 fact limit");
+    } 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) });
+    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; }
+    const snapshotMeta = (store.queryContext({ snapshotId, limit: 1 }) as { snapshot: { id?: unknown; indexRef?: unknown } }).snapshot;
+    const outputs = [...renderDocuments(context, facts, organized.text, collections), ...renderKnowledgeDocuments(context, facts, organized.text, snapshotMeta)];
+    outputs.push(renderDocumentIndex(context, snapshotMeta, outputs));
+    const results: DocumentGenerationResult[] = [];
+    for (const output of outputs) {
+      const job = store.createDocumentJob(snapshotId, { targetPath: output.targetPath, ownership: "generated", templateVersion: TEMPLATE_VERSION, modelRole: organized.modelRole, input: facts.map(fact => fact.objectKey) });
+      try {
+        const knownHash = store.latestDocumentHash(output.targetPath);
+        const existingHash = await currentHash(`${context.root}/${output.targetPath}`);
+        const expected = existingHash && !knownHash ? "unmanaged-existing-file" : knownHash ?? undefined;
+        const written = await store.writeDocument(job, output.body, { expectedCurrentHash: expected });
+        results.push({ targetPath: output.targetPath, status: written.status, outputPath: written.path });
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error); store.failDocumentJob(job, message);
+        results.push({ targetPath: output.targetPath, status: "failed", error: message });
+      }
+    }
+    return results;
+  } finally { store.close(); }
+}

package/src/project-initializer.ts

@@ -0,0 +1,251 @@
+import { createHash } from "node:crypto";
+import { readFile, readdir, stat } from "node:fs/promises";
+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";
+
+const DEFAULT_EXCLUDED = new Set([".git", ".devflow", ".planning", "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 };
+type ScanDiagnostic = { repository: string; path: string; reason: "symlink" | "excluded" | "too_large" | "unreadable"; message?: string };
+export type InitializationProgress = { runId: string; snapshotId?: string; completeness?: "complete" | "partial"; diagnostics: string[]; documents?: Array<{ targetPath: string; status: string; outputPath?: string; error?: string }> };
+
+function digest(value: string | Uint8Array): string { return `sha256:${createHash("sha256").update(value).digest("hex")}`; }
+function extension(file: string): string { return path.extname(file).toLowerCase(); }
+function globMatches(value: string, pattern: string): boolean {
+  const compile = (candidate: string) => candidate.replace(/[.+^${}()|[\]\\]/g, "\\$&").replaceAll("**", "\0").replaceAll("*", "[^/]*").replaceAll("\0", ".*");
+  return new RegExp(`^${compile(pattern)}$`).test(value)
+    || (pattern.startsWith("**/") && new RegExp(`^${compile(pattern.slice(3))}$`).test(value));
+}
+function redactCommand(command: unknown): string {
+  if (typeof command !== "string") return "";
+  return command
+    .replace(/\b([A-Z0-9_]*(?:TOKEN|SECRET|PASSWORD|PASSWD|API_KEY)[A-Z0-9_]*)=([^\s]+)/gi, "$1=<redacted>")
+    .replace(/(--?(?:token|secret|password|passwd|api[-_]?key))(?:=|\s+)([^\s]+)/gi, "$1=<redacted>")
+    .replace(/(authorization\s*[:=]\s*bearer\s+)([^\s]+)/gi, "$1<redacted>")
+    .replace(/(https?:\/\/)[^\s/@:]+:[^\s/@]+@/gi, "$1<redacted>@");
+}
+function source(file: SourceFile, kind: FactKind, objectKey: string, value: Record<string, unknown>, extractor: string, line?: number): FactInput {
+  return { kind, objectKey, repository: file.repository, value, evidenceLevel: "observed", sourcePath: file.path, sourceLine: line, sourceFingerprint: file.contentHash, extractor, confidence: "heuristic" };
+}
+
+async function walk(repository: string, repositoryRoot: string, includes: string[], excludes: string[], diagnostics: ScanDiagnostic[], relative = ""): Promise<SourceFile[]> {
+  const directory = path.join(repositoryRoot, relative);
+  let entries;
+  try { entries = await readdir(directory, { withFileTypes: true }); }
+  catch (error) { diagnostics.push({ repository, path: relative || ".", reason: "unreadable", message: error instanceof Error ? error.message : String(error) }); return []; }
+  const result: SourceFile[] = [];
+  for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+    if (entry.isSymbolicLink()) { diagnostics.push({ repository, path: path.join(relative, entry.name), reason: "symlink" }); continue; }
+    if (DEFAULT_EXCLUDED.has(entry.name)) continue;
+    const child = path.join(relative, entry.name);
+    const normalized = child.replaceAll("\\", "/");
+    if (excludes.some(pattern => globMatches(normalized, pattern) || globMatches(`${normalized}/`, pattern))) { if (diagnostics.length < 1000) diagnostics.push({ repository, path: normalized, reason: "excluded" }); continue; }
+    if (entry.isDirectory()) { result.push(...await walk(repository, repositoryRoot, includes, excludes, diagnostics, child)); continue; }
+    if (!entry.isFile()) continue;
+    if (includes.length && !includes.some(pattern => globMatches(normalized, pattern))) continue;
+    const absolute = path.join(repositoryRoot, child); const info = await stat(absolute);
+    if (info.size > 2 * 1024 * 1024) { diagnostics.push({ repository, path: normalized, reason: "too_large" }); continue; }
+    let bytes: Buffer;
+    try { bytes = await readFile(absolute); }
+    catch (error) { diagnostics.push({ repository, path: normalized, reason: "unreadable", message: error instanceof Error ? error.message : String(error) }); continue; }
+    result.push({ repository, path: child.replaceAll("\\", "/"), absolute, size: info.size, contentHash: digest(bytes), text: TEXT_EXTENSIONS.has(extension(child)) ? bytes.toString("utf8") : undefined });
+  }
+  return result;
+}
+
+async function gitRevision(root: string): Promise<string | null> {
+  const child = Bun.spawn(["git", "-C", root, "rev-parse", "HEAD"], { stdout: "pipe", stderr: "ignore" });
+  if (await child.exited !== 0) return null;
+  const revision = (await new Response(child.stdout).text()).trim();
+  return /^[0-9a-f]{40,64}$/i.test(revision) ? revision : null;
+}
+
+async function scan(context: ProjectContext, config: ScanConfigInput): Promise<{ files: SourceFile[]; diagnostics: ScanDiagnostic[]; repositoryVersions: Array<{ repository: string; revision: string | null }> }> {
+  const all: SourceFile[] = [];
+  const diagnostics: ScanDiagnostic[] = [];
+  const repositoryVersions: Array<{ repository: string; revision: string | null }> = [];
+  const includes = config.includes ?? ["**/*"];
+  const excludes = config.excludes ?? [".git/**", ".planning/**", ".devflow/**"];
+  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}`);
+    repositoryVersions.push({ repository: repository.name, revision: await gitRevision(root) });
+    all.push(...await walk(repository.name, root, includes, excludes, diagnostics));
+  }
+  return { files: all.sort((a, b) => `${a.repository}/${a.path}`.localeCompare(`${b.repository}/${b.path}`)), diagnostics, repositoryVersions };
+}
+
+function frozenManifest(scanResult: Awaited<ReturnType<typeof scan>>): Array<{ repository: string; path: string; contentHash: string; size?: number }> {
+  return [
+    ...scanResult.files.map(({ repository, path: sourcePath, contentHash, size }) => ({ repository, path: sourcePath, contentHash, size })),
+    ...scanResult.repositoryVersions.filter(item => item.revision).map(item => ({ repository: item.repository, path: "@source/git-head", contentHash: digest(item.revision!), size: item.revision!.length })),
+  ];
+}
+
+function lineMatches(file: SourceFile, expression: RegExp): Array<{ line: number; match: RegExpMatchArray }> {
+  return (file.text ?? "").split(/\r?\n/).flatMap((text, index) => {
+    const match = text.match(expression); return match ? [{ line: index + 1, match }] : [];
+  });
+}
+
+function collect(files: SourceFile[], context: ProjectContext, config: ScanConfigInput): Map<FactKind, FactInput[]> {
+  const facts = new Map<FactKind, FactInput[]>(FACT_KINDS.map(kind => [kind, []]));
+  const extensions = new Map<string, number>();
+  for (const file of files) {
+    facts.get("asset")!.push(source(file, "asset", `file:${file.repository}:${file.path}`, { path: file.path, repository: file.repository, size: file.size, extension: extension(file.path) || null }, "filesystem@1"));
+    const extensionKey = `${file.repository}\0${extension(file.path) || "none"}`;
+    extensions.set(extensionKey, (extensions.get(extensionKey) ?? 0) + 1);
+    for (const { line, match } of lineMatches(file, /\b(?:app|router)\.(get|post|put|patch|delete)\s*\(\s*["'`]([^"'`]+)/i)) {
+      facts.get("api")!.push(source(file, "api", `route:${match[1].toUpperCase()}:${match[2]}`, { method: match[1].toUpperCase(), path: match[2], runtimeVerified: false }, "static-route@1", line));
+    }
+    for (const { line, match } of lineMatches(file, /@(Get|Post|Put|Patch|Delete)Mapping\s*\(\s*["'`]([^"'`]+)/i)) {
+      facts.get("api")!.push(source(file, "api", `route:${match[1].toUpperCase()}:${match[2]}`, { method: match[1].toUpperCase(), path: match[2], framework: "spring", runtimeVerified: false }, "static-route@1", line));
+    }
+    for (const { line, match } of lineMatches(file, /^\s*(get|post|put|patch|delete)\s+["'`]([^"'`]+)/i)) {
+      facts.get("api")!.push(source(file, "api", `route:${match[1].toUpperCase()}:${match[2]}`, { method: match[1].toUpperCase(), path: match[2], framework: "rails", runtimeVerified: false }, "static-route@1", line));
+    }
+    for (const { line, match } of lineMatches(file, /\bHandleFunc\s*\(\s*["'`]([^"'`]+)/)) {
+      facts.get("api")!.push(source(file, "api", `route:ANY:${match[1]}`, { method: null, path: match[1], framework: "go-http", runtimeVerified: false }, "static-route@1", line));
+    }
+    for (const { line, match } of lineMatches(file, /(?:path\s*[:=]|<Route[^>]+path=)\s*["'`]([^"'`]+)["'`]/i)) {
+      facts.get("page")!.push(source(file, "page", `page:${match[1]}`, { route: match[1], renderedVerified: false }, "static-page@1", line));
+    }
+    const role = config.repositories.find(item => item.name === file.repository)?.role;
+    const pageMatch = file.path.match(/(?:^|\/)(?:pages|app)\/(.+?)\.(?:tsx?|jsx?|vue)$/i);
+    if (role === "frontend" && pageMatch) facts.get("page")!.push(source(file, "page", `page-file:${file.repository}:${file.path}`, { route: `/${pageMatch[1].replace(/\/index$/, "").replace(/\[(.+?)\]/g, ":$1")}`, componentPath: file.path, renderedVerified: false }, "filesystem-page@1"));
+    for (const { line, match } of lineMatches(file, /\bCREATE\s+TABLE\s+(?:IF\s+NOT\s+EXISTS\s+)?["'`]?([A-Za-z_][\w.]*)/i)) {
+      facts.get("data_model")!.push(source(file, "data_model", `model:${match[1]}`, { name: match[1], sourceType: extension(file.path) === ".sql" ? "migration" : "code" }, "static-model@1", line));
+    }
+    for (const { line, match } of lineMatches(file, /^\s*class\s+([A-Za-z_]\w*)\s*(?:extends\s+(?:Model|Entity)|\([^)]*(?:Model|Entity|Base)[^)]*\))/i)) {
+      facts.get("data_model")!.push(source(file, "data_model", `model:${file.repository}:${match[1]}`, { name: match[1], sourceType: "code" }, "static-model@1", line));
+    }
+    for (const { line, match } of lineMatches(file, /https?:\/\/([^\s/"'`]+)/i)) {
+      const host = match[1].replace(/^.*@/, "").toLowerCase();
+      facts.get("integration")!.push(source(file, "integration", `host:${host}`, { host, enabledInEnvironment: null }, "static-integration@1", line));
+    }
+    for (const { line, match } of lineMatches(file, /\b(?:cron|schedule|subscribe|consumer)\s*\(/i)) {
+      facts.get("integration")!.push(source(file, "integration", `task:${file.repository}:${file.path}:${line}`, { kind: match[0].split("(")[0].trim().toLowerCase(), enabledInEnvironment: null }, "static-task@1", line));
+    }
+    for (const { line, match } of lineMatches(file, /(?:process\.env\.|os\.getenv\s*\(\s*["']|ENV\s*\[\s*["']|System\.getenv\s*\(\s*["'])([A-Za-z_][A-Za-z0-9_]*)/)) {
+      facts.get("integration")!.push(source(file, "integration", `config:${file.repository}:${match[1]}`, { name: match[1], valueStored: false, enabledInEnvironment: null }, "static-config@1", line));
+    }
+    if (/(^|\/)(AGENTS|CLAUDE|CONTRIBUTING)\.md$/i.test(file.path) || /(^|\/)\.cursorrules$/i.test(file.path)) {
+      facts.get("rule")!.push(source(file, "rule", `rule:${file.repository}:${file.path}`, { path: file.path, scope: file.repository, explicit: true }, "rule-file@1"));
+    }
+    if (path.basename(file.path) === "package.json" && file.text) {
+      try {
+        const manifest = JSON.parse(file.text) as Record<string, any>;
+        for (const group of ["dependencies", "devDependencies", "peerDependencies"]) for (const name of Object.keys(manifest[group] ?? {})) {
+          facts.get("technology")!.push(source(file, "technology", `dependency:${file.repository}:${name}`, { name, declaration: group, locked: false }, "package-json@1"));
+        }
+        for (const [name, command] of Object.entries(manifest.scripts ?? {})) facts.get("toolchain")!.push(source(file, "toolchain", `command:${file.repository}:${name}`, { name, command: redactCommand(command), workingDirectory: path.dirname(file.path), executed: false }, "package-json@1"));
+      } catch { /* diagnostics are attached by the caller's collection status */ }
+    }
+    if (/^(?:package-lock\.json|bun\.lockb?|pnpm-lock\.yaml|yarn\.lock|poetry\.lock|Gemfile\.lock)$/i.test(path.basename(file.path))) facts.get("technology")!.push(source(file, "technology", `lockfile:${file.repository}:${file.path}`, { path: file.path, locked: true }, "lockfile@1"));
+    if (/(?:^|\/)(?:test|tests|spec|__tests__)(?:\/|$)|\.(?:test|spec)\.[^.]+$/i.test(file.path)) facts.get("toolchain")!.push(source(file, "toolchain", `test-definition:${file.repository}:${file.path}`, { testDefinition: file.path, executed: false }, "test-discovery@1"));
+  }
+  for (const [key, count] of extensions) {
+    const [repository, ext] = key.split("\0");
+    facts.get("technology")!.push({ kind: "technology", repository, objectKey: `language-extension:${ext}`, value: { extension: ext, fileCount: count }, evidenceLevel: "candidate", extractor: "extension-summary@1", confidence: "heuristic" });
+  }
+  for (const repository of config.repositories) {
+    facts.get("evidence")!.push({ kind: "evidence", repository: repository.name, objectKey: "input-policy", value: { source: "local-static", discoveredCommandsExecuted: false, gitMetadataRead: true, secretsStored: false }, evidenceLevel: "explicit_rule", extractor: "initializer@1", confidence: "exact" });
+    facts.get("capability")!.push({ kind: "capability", repository: repository.name, objectKey: "collector:static@1", value: { supported: ["asset", "technology", "api", "page", "data_model", "integration", "rule", "toolchain"], limitations: ["static declarations only", "dynamic behavior unresolved", "no environment enablement inference"], project: context.manifest.name }, evidenceLevel: "explicit_rule", extractor: "initializer@1", confidence: "exact" });
+  }
+  return facts;
+}
+
+async function runProcess(argv: string[], cwd: string): Promise<{ stdout: string; stderr: string }> {
+  const child = Bun.spawn(argv, { cwd, stdout: "pipe", stderr: "pipe" });
+  const [exitCode, stdout, stderr] = await Promise.all([child.exited, new Response(child.stdout).text(), new Response(child.stderr).text()]);
+  if (exitCode !== 0) throw new Error(`${path.basename(argv[1] ?? argv[0])} failed (${exitCode}): ${(stderr || stdout).trim()}`);
+  return { stdout: stdout.trim(), stderr: stderr.trim() };
+}
+
+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";
+  const codebases = config.repositories.flatMap(repository => ["--codebase", `${repository.name}:${path.resolve(context.root, repository.relativePath)}:${repository.role}`]);
+  await runProcess(["python3", script, "scan", "--root", context.root, "--output", output, ...codebases], context.root);
+  await runProcess(["python3", script, "validate", "--index", output], context.root);
+  await runProcess(["python3", script, "audit", "--root", context.root, "--index", output, "--skill-root", path.resolve(import.meta.dir, "../plugins/devflow-intel/skills")], context.root);
+  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");
+  return { path: output, generation: snapshot.generation, immutablePath: snapshot.immutablePath, snapshotHash: digest(bytes), status: "complete" };
+}
+
+export async function runProjectInitialization(context: ProjectContext, input: { config?: ScanConfigInput; requestId?: string; documentMode?: "low-tier-model" | "template" | "none"; organizer?: import("./project-documents.ts").LowTierDocumentOrganizer; switchAuthority?: boolean } = {}): Promise<InitializationProgress> {
+  const config: ScanConfigInput = input.config ?? { mode: "full", repositories: [{ name: context.manifest.name, relativePath: ".", role: "other" }], requiredKinds: [...FACT_KINDS], adapterVersions: { static: "1" } };
+  const store = await InitializationStore.open(context); const diagnostics: string[] = [];
+  let activeRun: { id: string; leaseToken: string } | undefined;
+  try {
+    const workspace = await store.registerWorkspace(); const storedConfig = store.putScanConfig(config);
+    const initialScan = await scan(context, config); const files = initialScan.files;
+    const manifest = frozenManifest(initialScan);
+    const inputSnapshot = store.createInputSnapshot(workspace.id, storedConfig.id, manifest, false);
+    const run = store.startRun({ workspaceId: workspace.id, configId: storedConfig.id, inputSnapshotId: inputSnapshot.id, requestId: input.requestId });
+    activeRun = run;
+    if (run.reused) return { runId: run.id, snapshotId: store.getRun(run.id)?.publishedSnapshotId as string | undefined, diagnostics };
+    const grouped = collect(files, context, config); const required = new Set(config.requiredKinds ?? FACT_KINDS);
+    for (const repository of config.repositories) for (const kind of FACT_KINDS) {
+      const repositoryFacts = grouped.get(kind)!.filter(fact => fact.repository === repository.name);
+      const requiredKind = required.has(kind);
+      const applicable = kind === "page"
+        ? repository.role === "frontend" || repository.role === "other"
+        : kind === "api" || kind === "data_model"
+          ? repository.role === "backend" || repository.role === "other"
+          : true;
+      const repositoryDiagnostics = initialScan.diagnostics.filter(item => item.repository === repository.name);
+      const hasBlockingScanFailure = repositoryDiagnostics.some(item => item.reason === "unreadable");
+      const status = !requiredKind
+        ? "skipped"
+        : !applicable
+          ? "not_applicable"
+          : hasBlockingScanFailure
+            ? "partial"
+            : "complete";
+      store.recordCollection(run.id, run.leaseToken, {
+        repository: repository.name,
+        kind,
+        status,
+        adapter: "static@1",
+        capability: { static: true, applicable, completeAbsenceIsObserved: status === "complete" && repositoryFacts.length === 0, scanDiagnostics: repositoryDiagnostics.length },
+        diagnostics: repositoryDiagnostics,
+        facts: status === "complete" ? repositoryFacts : [],
+      });
+    }
+    const indexRef = config.mode === "full" ? await buildCodeIndex(context, config) : { status: "skipped", reason: "explicit_fast_mode" };
+    const after = await scan(context, config);
+    const afterManifest = frozenManifest(after);
+    const verified = store.createInputSnapshot(workspace.id, storedConfig.id, afterManifest, false);
+    if (verified.fingerprint !== inputSnapshot.fingerprint) throw new Error("Source changed during initialization; refusing to publish mixed input");
+    store.confirmInputSnapshot(inputSnapshot.id, inputSnapshot.fingerprint);
+    const published = store.publishRun(run.id, run.leaseToken, { expectedRevision: undefined, indexRef });
+    if (input.switchAuthority !== false) {
+      const authority = store.getAuthority();
+      if (authority.authority === "legacy") store.switchAuthority("database", authority.revision);
+    }
+    const result = store.queryContext({ snapshotId: published.snapshotId, limit: 1 }) as any;
+    const documentMode = input.documentMode ?? "template";
+    let documents: InitializationProgress["documents"];
+    if (documentMode !== "none") {
+      try {
+        documents = await (await import("./project-documents.ts")).generateProjectDocuments(context, published.snapshotId, { mode: documentMode, organizer: input.organizer });
+      } 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 }];
+      }
+    }
+    return { runId: run.id, snapshotId: published.snapshotId, completeness: result.snapshot.completeness, diagnostics, documents };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    diagnostics.push(message);
+    if (activeRun) store.failRun(activeRun.id, activeRun.leaseToken, message);
+    throw error;
+  } finally { store.close(); }
+}