@guanlin4924/devflow-pi 0.1.62 → 0.1.63

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,111 @@
+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";
+
+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");
+}
+
+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;
+}
+
+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 outputs = renderDocuments(context, facts, organized.text, collections); 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(); }
+}

package/src/project-migration.ts

@@ -0,0 +1,66 @@
+import { createHash, randomUUID } from "node:crypto";
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+import { InitializationStore } from "./initialization-store.ts";
+import type { ProjectContext } from "./project-context.ts";
+
+function hash(content: Uint8Array | string): string { return `sha256:${createHash("sha256").update(content).digest("hex")}`; }
+function relativeSource(context: ProjectContext, source: string): string {
+  const absolute = path.resolve(context.root, source); const relative = path.relative(context.root, absolute).replaceAll("\\", "/");
+  if (!relative || relative === ".." || relative.startsWith("../") || path.isAbsolute(relative)) throw new Error(`Legacy source escapes project root: ${source}`);
+  return relative;
+}
+
+export async function importLegacyInitialization(context: ProjectContext, sources: string[], requestId = `legacy-import-${randomUUID()}`): Promise<{ runId: string; snapshotId: string; imports: string[] }> {
+  if (!sources.length) throw new Error("At least one legacy source is required");
+  const documents = await Promise.all(sources.map(async source => {
+    const relative = relativeSource(context, source); const content = await readFile(path.join(context.root, relative));
+    return { relative, contentHash: hash(content), size: content.byteLength };
+  }));
+  const store = await InitializationStore.open(context);
+  try {
+    const workspace = await store.registerWorkspace();
+    const config = store.putScanConfig({ mode: "fast", repositories: [{ name: "legacy-materials", relativePath: ".", role: "other" }], requiredKinds: ["evidence"], adapterVersions: { "legacy-import": "1" } });
+    const input = store.createInputSnapshot(workspace.id, config.id, documents.map(item => ({ repository: "legacy-materials", path: item.relative, contentHash: item.contentHash, size: item.size })), true);
+    const run = store.startRun({ workspaceId: workspace.id, configId: config.id, inputSnapshotId: input.id, requestId });
+    if (!run.reused) store.recordCollection(run.id, run.leaseToken, {
+      kind: "evidence", status: "complete", adapter: "legacy-import@1",
+      facts: documents.map(item => ({ kind: "evidence" as const, objectKey: `historical:${item.relative}`, value: { sourcePath: item.relative, contentHash: item.contentHash, materialType: path.extname(item.relative).slice(1) || "text", importedAs: "historical", observed: false, approved: false }, evidenceLevel: "historical" as const, sourcePath: item.relative, sourceFingerprint: item.contentHash, extractor: "legacy-import@1", confidence: "exact" as const })),
+    });
+    const snapshot = run.reused && store.getRun(run.id)?.publishedSnapshotId
+      ? { snapshotId: String(store.getRun(run.id)!.publishedSnapshotId) }
+      : store.publishRun(run.id, run.leaseToken, { completeness: "partial", updateCurrent: false });
+    const imports = documents.map(item => store.registerHistoricalImport(workspace.id, item.relative, item.contentHash, snapshot.snapshotId));
+    const authority = store.getAuthority();
+    if (authority.authority === "legacy") store.switchAuthority("shadow", authority.revision);
+    return { runId: run.id, snapshotId: snapshot.snapshotId, imports };
+  } finally { store.close(); }
+}
+
+export async function exportInitializationSnapshot(context: ProjectContext, snapshotId: string, targetPath: string): Promise<{ path: string; contentHash: string }> {
+  const absolute = path.resolve(context.root, targetPath);
+  if (absolute !== context.root && !absolute.startsWith(`${context.root}${path.sep}`)) throw new Error("Export path escapes project root");
+  const store = await InitializationStore.open(context);
+  try {
+    const facts: unknown[] = []; let after: string | undefined; let snapshot: unknown;
+    do {
+      const page = store.queryContext({ snapshotId, after, limit: 500 }) as any; snapshot ??= page.snapshot; facts.push(...page.facts); after = page.nextCursor ?? undefined;
+      if (facts.length > 100_000) throw new Error("Snapshot export exceeds 100,000 facts");
+    } while (after);
+    const content = `${JSON.stringify({ version: 1, exportedAt: new Date().toISOString(), snapshot, facts }, null, 2)}\n`;
+    await mkdir(path.dirname(absolute), { recursive: true }); const temporary = `${absolute}.${randomUUID()}.tmp`;
+    await writeFile(temporary, content, { encoding: "utf8", flag: "wx" }); await rename(temporary, absolute);
+    return { path: absolute, contentHash: hash(content) };
+  } finally { store.close(); }
+}
+
+export async function switchInitializationAuthority(context: ProjectContext, authority: "legacy" | "shadow" | "database", expectedRevision: number, options: { compatibilityExport?: string } = {}): Promise<{ authority: string; revision: number }> {
+  const store = await InitializationStore.open(context);
+  try {
+    const current = store.getAuthority();
+    if (current.authority === "database" && authority === "legacy" && !options.compatibilityExport) throw new Error("Rollback to legacy authority requires a verified compatibility export");
+    if (options.compatibilityExport) await readFile(path.resolve(context.root, options.compatibilityExport));
+    return store.switchAuthority(authority, expectedRevision);
+  } finally { store.close(); }
+}