@guanlin4924/devflow-pi 0.1.69 → 0.1.71

package/package.json

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

package/plugins/devflow-core/skills/workflow-project-context/SKILL.md

@@ -209,6 +209,8 @@ Run the database validator with identifiers returned by the scan:
 devflow_skill_script(script="project-context-db-validate", args=["--database", "<control.db>", "--project-id", "<project-id>", "--workspace-id", "<workspace-id>", "--run-id", "<run-id>"])
 ```
 
+The `--database` value must come from `devflow_project_context(action="scan").database` or the loaded project context `controlDatabasePath`. Never guess `./control.db`, `.devflow/control.db`, `.planning/code-index/index.sqlite`, an OMP agent database, or any SQLite found by searching user directories. Code-index SQLite is not the initialization control database and does not contain the initialization `schema_meta` table.
+
 Completion requires a stable immutable input, matching context snapshot, accounted required categories, evidence for observed facts, a registered immutable index in full mode, revision-safe pointer publication, and separate document statuses. Workflow `STATE` and other non-initialization authorities must remain unchanged.
 
 Report partial, unsupported, skipped, failed, and unknown coverage honestly. Initialization success does not mean tests passed, services ran, designs were approved, or requirements were delivered.

package/plugins/devflow-intel/skills/workflow-code-index/scripts/adapters/python_ast.py

@@ -116,6 +116,8 @@ class _PythonVisitor(ast.NodeVisitor):
 
     @staticmethod
     def _signature(node):
+        if isinstance(node, ast.ClassDef):
+            return f"{node.name}()"
         arguments = [argument.arg for argument in [*node.args.posonlyargs, *node.args.args, *node.args.kwonlyargs]]
         if node.args.vararg:
             arguments.append(f"*{node.args.vararg.arg}")

package/plugins/devflow-intel/skills/workflow-code-index/scripts/code_index.py

@@ -97,13 +97,15 @@ def _publish_snapshot(staging: Path, output: Path, counts: Dict[str, int], works
         os.close(directory_fd)
 
 
-def _workspace_state(root: Path, files: List[dict], changed: Set[str]) -> Dict[str, object]:
+def _workspace_state(root: Path, files: List[dict], changed: Set[str], discovered_paths: Iterable[str] | None = None) -> Dict[str, object]:
     indexed_paths = sorted(record["path"] for record in files)
+    discovered = sorted(set(discovered_paths or indexed_paths))
     source_manifest_hash = _hash_lines(f"{record['path']}\0{record['content_hash']}" for record in files)
     return {
         "repositoryRevision": _git_output(root, ["rev-parse", "HEAD"]),
         "contentManifestHash": source_manifest_hash,
         "indexedPathsHash": _hash_lines(indexed_paths),
+        "discoveredPathsHash": _hash_lines(discovered),
         "dirtyPathsAtBuild": sorted(changed),
         "extractors": sorted(set(record.get("parser", "unknown") for record in files)),
         "capabilities": {
@@ -210,12 +212,14 @@ def command_scan(args) -> int:
 
         files, symbols, relations, diagnostics = _existing_after_removal(existing, changed)
         indexed_paths = {record["path"] for record in files}
+        discovered_paths: Set[str] = set()
 
         for codebase in codebases:
             if not codebase.root.exists():
                 diagnostics.append(_diagnostic(codebase.name, "", 1, "warning", "skipped_file", f"codebase root does not exist: {codebase.root}", "discovery@1"))
                 continue
             all_files = scan_files(codebase.root, excludes=args.exclude)
+            discovered_paths.update(_workspace_rel(root, path) for path in all_files)
             if changed:
                 all_files = [path for path in all_files if _workspace_rel(root, path) in changed]
             manifests = [path for path in all_files if path.name in {"package.json", "go.mod", "Cargo.toml", "pyproject.toml", "requirements.txt", "composer.json", "pubspec.yaml"}]
@@ -280,7 +284,7 @@ def command_scan(args) -> int:
                     "relations": len(relations),
                     "diagnostics": len(diagnostics),
                 },
-                _workspace_state(root, files, changed),
+                _workspace_state(root, files, changed, discovered_paths),
             )
         finally:
             shutil.rmtree(staging, ignore_errors=True)
@@ -406,7 +410,8 @@ def _query_is_fresh(root: Path, snapshot: Dict[str, object], files: List[dict])
     indexed_paths = sorted(record["path"] for record in files)
     if not any(path.startswith("../") for path in indexed_paths):
         current_paths = sorted(_workspace_rel(root, item) for item in scan_files(root))
-        if _hash_lines(current_paths) != workspace.get("indexedPathsHash"):
+        expected_paths_hash = workspace.get("discoveredPathsHash") or workspace.get("indexedPathsHash")
+        if _hash_lines(current_paths) != expected_paths_hash:
             return False
     return True
 

package/src/constants.ts

@@ -1,5 +1,5 @@
 export const PRODUCT_NAME = "Devflow Pi";
-export const PRODUCT_VERSION = "0.1.69";
+export const PRODUCT_VERSION = "0.1.71";
 export const PROJECT_SCHEMA_VERSION = 1;
 export const OMP_RUNTIME_VERSION = "17.2.7";
 

package/src/initialization-store.ts

@@ -1,5 +1,6 @@
 import { createHash, randomUUID } from "node:crypto";
 import { copyFile, cp, mkdir, readFile, realpath, stat, writeFile, rename, rm } from "node:fs/promises";
+import { existsSync, readFileSync } from "node:fs";
 import path from "node:path";
 import { Database } from "bun:sqlite";
 
@@ -263,12 +264,33 @@ export class InitializationStore {
         await writeFile(migrationBackup, db.serialize(), { flag: "wx" });
       }
     }
-    db.transaction(() => {
+    const migrate = db.transaction(() => {
       db.exec(SCHEMA);
+      const ensureColumn = (table: string, column: string, definition: string) => {
+        const columns = db.query(`PRAGMA table_info(${table})`).all() as Array<{ name: string }>;
+        if (!columns.some(item => item.name === column)) db.exec(`ALTER TABLE ${table} ADD COLUMN ${column} ${definition}`);
+      };
+      ensureColumn("context_snapshots", "index_ref_json", "TEXT");
+      ensureColumn("document_jobs", "model_role", "TEXT");
+      ensureColumn("document_jobs", "output_hash", "TEXT");
+      ensureColumn("document_jobs", "conflict_path", "TEXT");
+      ensureColumn("document_jobs", "error", "TEXT");
       const meta = db.query("SELECT version FROM schema_meta LIMIT 1").get() as { version: number } | null;
-      if (!meta) db.query("INSERT INTO schema_meta(version) VALUES (?)").run(INITIALIZATION_SCHEMA_VERSION);
-      else if (meta.version < INITIALIZATION_SCHEMA_VERSION) db.query("UPDATE schema_meta SET version=?").run(INITIALIZATION_SCHEMA_VERSION);
-    })();
+      if (!meta) {
+        db.query("INSERT INTO schema_meta(version) VALUES (?)").run(INITIALIZATION_SCHEMA_VERSION);
+      } else {
+        let version = meta.version;
+        if (version < 2) {
+          db.exec("CREATE INDEX IF NOT EXISTS idx_input_snapshots_project ON input_snapshots(project_id, workspace_id, config_id)");
+          db.exec("CREATE INDEX IF NOT EXISTS idx_document_jobs_status ON document_jobs(status, updated_at)");
+          version = 2;
+        }
+        db.query("UPDATE schema_meta SET version=?").run(version);
+      }
+      const verified = db.query("SELECT version FROM schema_meta LIMIT 1").get() as { version: number };
+      if (verified.version !== INITIALIZATION_SCHEMA_VERSION) throw new Error(`Initialization schema migration stopped at ${verified.version}`);
+    });
+    try { migrate(); } catch (error) { db.close(); throw new Error(`Initialization database migration failed: ${error instanceof Error ? error.message : String(error)}`); }
     db.query("INSERT OR IGNORE INTO projects(id,name,created_at) VALUES (?,?,?)").run(context.manifest.projectId, context.manifest.name, now());
     db.query("INSERT OR IGNORE INTO authority_state(project_id,authority,revision,switched_at) VALUES (?,?,?,?)").run(context.manifest.projectId, "legacy", 0, now());
     return new InitializationStore(context, databasePath, db);
@@ -311,13 +333,23 @@ export class InitializationStore {
     return { id, revision: row.revision, created: true };
   }
 
-  createInputSnapshot(workspaceId: string, configId: string, files: Array<{ repository: string; path: string; contentHash: string; size?: number }>, stable = true): { id: string; fingerprint: string; created: boolean } {
+  createInputSnapshot(workspaceId: string, configId: string, files: Array<{ repository: string; path: string; contentHash: string; size?: number }>, stable = false): { id: string; fingerprint: string; created: boolean } {
+    const binding = this.db.query(`SELECT w.id AS workspaceId,c.id AS configId,w.project_id AS workspaceProject,c.project_id AS configProject,c.config_json AS config
+      FROM workspaces w JOIN scan_configs c ON c.project_id=w.project_id
+      WHERE w.id=? AND c.id=? AND w.project_id=?`).get(workspaceId, configId, this.context.manifest.projectId) as { workspaceId: string; configId: string; workspaceProject: string; configProject: string; config: string } | null;
+    if (!binding) throw new Error("Input snapshot workspace and scan config do not belong to the same project boundary");
+    const configured = new Map((parse<ScanConfigInput>(binding.config).repositories ?? []).map(repository => [repository.name, repository.relativePath]));
+    for (const file of files) {
+      if (!configured.has(file.repository)) throw new Error(`Input snapshot repository is not configured: ${file.repository}`);
+      const base = configured.get(file.repository)!;
+      if (base !== "." && !path.isAbsolute(base) && file.path !== base && !file.path.startsWith(`${base.replace(/\\/g, "/").replace(/\/$/, "")}/`)) throw new Error(`Input snapshot path is outside repository: ${file.repository}/${file.path}`);
+    }
     const normalized = files.map(file => ({ ...file, path: validateRelative(file.path) })).sort((a, b) => `${a.repository}/${a.path}`.localeCompare(`${b.repository}/${b.path}`));
     const manifestJson = canonicalJson(normalized);
     const fingerprint = hash(manifestJson);
     const existing = this.db.query("SELECT id,stable FROM input_snapshots WHERE workspace_id=? AND config_id=? AND fingerprint=?").get(workspaceId, configId, fingerprint) as { id: string; stable: number } | null;
     if (existing) {
-      if (stable && !existing.stable) this.db.query("UPDATE input_snapshots SET stable=1 WHERE id=?").run(existing.id);
+      if (stable && !existing.stable) throw new Error("Existing input snapshot is unstable; confirm it explicitly before publishing");
       return { id: existing.id, fingerprint, created: false };
     }
     const id = randomUUID();
@@ -369,27 +401,39 @@ export class InitializationStore {
   recordCollection(runId: string, leaseToken: string, input: { repository?: string; kind: FactKind; status: CoverageStatus; adapter: string; capability?: Record<string, unknown>; diagnostics?: unknown[]; facts?: FactInput[] }): void {
     this.assertWritableRun(runId, leaseToken);
     const transaction = this.db.transaction(() => {
-      this.db.query("INSERT INTO collection_results(id,run_id,repository,kind,status,adapter,capability_json,diagnostics_json,created_at) VALUES (?,?,?,?,?,?,?,?,?) ON CONFLICT(run_id,repository,kind) DO UPDATE SET status=excluded.status,adapter=excluded.adapter,capability_json=excluded.capability_json,diagnostics_json=excluded.diagnostics_json").run(randomUUID(), runId, input.repository ?? "", input.kind, input.status, input.adapter, canonicalJson(input.capability ?? {}), canonicalJson(input.diagnostics ?? []), now());
+      const repository = input.repository ?? "";
+      this.db.query("DELETE FROM evidence WHERE fact_id IN (SELECT id FROM facts WHERE run_id=? AND repository=? AND kind=?)").run(runId, repository, input.kind);
+      this.db.query("DELETE FROM facts WHERE run_id=? AND repository=? AND kind=?").run(runId, repository, input.kind);
+      this.db.query("INSERT INTO collection_results(id,run_id,repository,kind,status,adapter,capability_json,diagnostics_json,created_at) VALUES (?,?,?,?,?,?,?,?,?) ON CONFLICT(run_id,repository,kind) DO UPDATE SET status=excluded.status,adapter=excluded.adapter,capability_json=excluded.capability_json,diagnostics_json=excluded.diagnostics_json,created_at=excluded.created_at").run(randomUUID(), runId, repository, input.kind, input.status, input.adapter, canonicalJson(input.capability ?? {}), canonicalJson(input.diagnostics ?? []), now());
       for (const fact of input.facts ?? []) {
         if (fact.kind !== input.kind) throw new Error(`Fact kind ${fact.kind} does not match collection ${input.kind}`);
         if (!fact.objectKey || !fact.extractor) throw new Error("Facts require objectKey and extractor");
         if (fact.evidenceLevel === "observed" && !fact.sourcePath) throw new Error("Observed facts require source evidence");
         validateFactShape(fact);
         const factId = randomUUID();
-        this.db.query("INSERT INTO facts(id,run_id,kind,object_key,repository,value_json,evidence_level,extractor,confidence,created_at) VALUES (?,?,?,?,?,?,?,?,?,?) ON CONFLICT(run_id,kind,repository,object_key) DO UPDATE SET value_json=excluded.value_json,evidence_level=excluded.evidence_level,extractor=excluded.extractor,confidence=excluded.confidence").run(factId, runId, fact.kind, fact.objectKey, fact.repository ?? input.repository ?? "", canonicalJson(fact.value), fact.evidenceLevel, fact.extractor, fact.confidence ?? "inferred", now());
-        const stored = this.db.query("SELECT id FROM facts WHERE run_id=? AND kind=? AND repository=? AND object_key=?").get(runId, fact.kind, fact.repository ?? input.repository ?? "", fact.objectKey) as { id: string };
+        this.db.query("INSERT INTO facts(id,run_id,kind,object_key,repository,value_json,evidence_level,extractor,confidence,created_at) VALUES (?,?,?,?,?,?,?,?,?,?)").run(factId, runId, fact.kind, fact.objectKey, fact.repository ?? repository, canonicalJson(fact.value), fact.evidenceLevel, fact.extractor, fact.confidence ?? "inferred", now());
+        const stored = { id: factId };
         if (fact.sourcePath) this.db.query("INSERT OR IGNORE INTO evidence(id,fact_id,source_path,source_line,source_fingerprint,method,created_at) VALUES (?,?,?,?,?,?,?)").run(randomUUID(), stored.id, validateRelative(fact.sourcePath), fact.sourceLine ?? null, fact.sourceFingerprint ?? "unavailable", fact.extractor, now());
       }
     });
     transaction();
   }
 
-  cancelRun(runId: string): boolean {
-    return this.db.query("UPDATE initialization_runs SET status='cancelled',updated_at=? WHERE id=? AND status IN ('preparing','collecting','validating')").run(now(), runId).changes === 1;
+  cancelRun(runId: string, leaseToken: string, expectedRevision: number): boolean {
+    const row = this.db.query("SELECT status,lease_token AS leaseToken,lease_expires_at AS expires,workspace_id AS workspaceId,config_id AS configId FROM initialization_runs WHERE id=?").get(runId) as { status: RunStatus; leaseToken: string; expires: string; workspaceId: string; configId: string } | null;
+    if (!row) throw new Error(`Unknown initialization run: ${runId}`);
+    if (row.leaseToken !== leaseToken) throw new Error("Initialization lease token mismatch");
+    if (Date.parse(row.expires) < Date.now()) throw new Error("Initialization lease expired; recover the run before cancelling");
+    const current = this.db.query("SELECT revision FROM current_context WHERE workspace_id=? AND config_id=?").get(row.workspaceId, row.configId) as { revision: number } | null;
+    if (expectedRevision !== (current?.revision ?? 0)) throw new Error("Initialization run revision conflict");
+    const timestamp = now();
+    return this.db.query("UPDATE initialization_runs SET status='cancelled',updated_at=? WHERE id=? AND lease_token=? AND lease_expires_at>? AND status IN ('preparing','collecting','validating')").run(timestamp, runId, leaseToken, timestamp).changes === 1;
   }
 
   failRun(runId: string, leaseToken: string, error: string): boolean {
-    return this.db.query("UPDATE initialization_runs SET status='failed',error=?,updated_at=? WHERE id=? AND lease_token=? AND status IN ('preparing','collecting','validating')").run(error.slice(0, 4000), now(), runId, leaseToken).changes === 1;
+    this.assertWritableRun(runId, leaseToken);
+    const timestamp = now();
+    return this.db.query("UPDATE initialization_runs SET status='failed',error=?,updated_at=? WHERE id=? AND lease_token=? AND lease_expires_at>? AND status IN ('preparing','collecting','validating')").run(error.slice(0, 4000), timestamp, runId, leaseToken, timestamp).changes === 1;
   }
 
   recoverRun(runId: string, leaseMs = 15 * 60_000): { leaseToken: string } {
@@ -399,11 +443,12 @@ export class InitializationStore {
     if (["failed", "finished"].includes(row.status)) throw new Error(`Run cannot be recovered from ${row.status}`);
     if (Date.parse(row.expires) >= Date.now()) throw new Error("Run lease is still active");
     const leaseToken = randomUUID();
-    this.db.query("UPDATE initialization_runs SET lease_token=?,lease_expires_at=?,updated_at=? WHERE id=?").run(leaseToken, new Date(Date.now() + leaseMs).toISOString(), now(), runId);
+    const changed = this.db.query("UPDATE initialization_runs SET lease_token=?,lease_expires_at=?,updated_at=? WHERE id=? AND lease_expires_at<? AND status IN ('preparing','collecting','validating')").run(leaseToken, new Date(Date.now() + leaseMs).toISOString(), now(), runId, now());
+    if (changed.changes !== 1) throw new Error("Initialization run recovery conflict");
     return { leaseToken };
   }
 
-  publishRun(runId: string, leaseToken: string, options: { expectedRevision?: number; completeness?: "complete" | "partial"; indexRef?: Record<string, unknown>; updateCurrent?: boolean } = {}): { snapshotId: string; revision: number } {
+  publishRun(runId: string, leaseToken: string, options: { expectedRevision: number; completeness?: "complete" | "partial"; indexRef?: Record<string, unknown>; updateCurrent?: boolean }): { snapshotId: string; revision: number } {
     const run = this.assertWritableRun(runId, leaseToken);
     const input = this.db.query("SELECT stable,fingerprint FROM input_snapshots WHERE id=?").get(run.inputSnapshotId) as { stable: number; fingerprint: string };
     if (!input.stable) throw new Error("Cannot publish an unstable input snapshot");
@@ -422,12 +467,31 @@ export class InitializationStore {
     if (completeness === "complete" && blockers.length) throw new Error(`Required collection coverage is incomplete: ${blockers.join(", ")}`);
     const current = this.db.query("SELECT revision FROM current_context WHERE workspace_id=? AND config_id=?").get(run.workspaceId, run.configId) as { revision: number } | null;
     const revision = (current?.revision ?? 0) + 1;
-    if (options.expectedRevision !== undefined && options.expectedRevision !== (current?.revision ?? 0)) throw new Error(`Current context revision conflict: expected ${options.expectedRevision}, actual ${current?.revision ?? 0}`);
+    if (options.expectedRevision !== (current?.revision ?? 0)) throw new Error(`Current context revision conflict: expected ${options.expectedRevision}, actual ${current?.revision ?? 0}`);
+    if (options.indexRef) {
+      if (options.indexRef.inputFingerprint !== input.fingerprint || options.indexRef.workspaceId !== run.workspaceId || options.indexRef.configId !== run.configId) throw new Error("Index reference does not match initialization input snapshot");
+      if (options.indexRef.status === "complete" && (typeof options.indexRef.generation !== "string" || typeof options.indexRef.snapshotHash !== "string")) throw new Error("Complete index references require generation and snapshot hash");
+      if (options.indexRef.status === "complete") {
+        if (typeof options.indexRef.contentManifestHash !== "string" || typeof options.indexRef.repositoryRevision !== "string") throw new Error("Complete index references require content manifest and repository revision");
+        const indexRoot = path.resolve(this.context.root, String(options.indexRef.stagingPath ?? options.indexRef.path ?? ".planning/code-index"));
+        const immutable = path.resolve(indexRoot, String(options.indexRef.immutablePath ?? `snapshots/${options.indexRef.generation}`));
+        const snapshotFile = path.join(immutable, "SNAPSHOT.json");
+        if (!existsSync(snapshotFile)) throw new Error("Complete index reference does not point to an immutable generation");
+        const actual = hash(readFileSync(snapshotFile));
+        if (actual !== options.indexRef.snapshotHash) throw new Error("Code index snapshot hash does not match index reference");
+        const payload = JSON.parse(readFileSync(snapshotFile, "utf8")) as { generation?: string };
+        if (payload.generation !== options.indexRef.generation) throw new Error("Code index generation does not match SNAPSHOT.json");
+        const workspace = (payload as any).workspace ?? {};
+        if (workspace.contentManifestHash !== options.indexRef.contentManifestHash) throw new Error("Code index content manifest does not match index reference");
+        if (workspace.repositoryRevision !== options.indexRef.repositoryRevision) throw new Error("Code index repository revision does not match index reference");
+      }
+    }
     const facts = this.db.query("SELECT kind,repository,object_key,value_json,evidence_level,extractor,confidence FROM facts WHERE run_id=? ORDER BY kind,repository,object_key").all(runId);
     const snapshotId = randomUUID();
     const transaction = this.db.transaction(() => {
       this.db.query("UPDATE initialization_runs SET status='validating',updated_at=? WHERE id=? AND lease_token=?").run(now(), runId, leaseToken);
-      this.db.query("INSERT INTO context_snapshots(id,project_id,workspace_id,config_id,input_snapshot_id,run_id,completeness,content_hash,index_ref_json,created_at) VALUES (?,?,?,?,?,?,?,?,?,?)").run(snapshotId, this.context.manifest.projectId, run.workspaceId, run.configId, run.inputSnapshotId, runId, completeness, hash(canonicalJson(facts)), options.indexRef ? canonicalJson(options.indexRef) : null, now());
+      const persistedIndexRef = options.indexRef ? Object.fromEntries(Object.entries(options.indexRef).filter(([key]) => key !== "stagingPath")) : null;
+      this.db.query("INSERT INTO context_snapshots(id,project_id,workspace_id,config_id,input_snapshot_id,run_id,completeness,content_hash,index_ref_json,created_at) VALUES (?,?,?,?,?,?,?,?,?,?)").run(snapshotId, this.context.manifest.projectId, run.workspaceId, run.configId, run.inputSnapshotId, runId, completeness, hash(canonicalJson(facts)), persistedIndexRef ? canonicalJson(persistedIndexRef) : null, now());
       if (options.updateCurrent === false) {
         // Shadow imports are immutable and queryable without becoming current.
       } else if (current) {
@@ -484,6 +548,11 @@ export class InitializationStore {
     return this.queryContext({ workspaceId, configId: current.configId, ...input });
   }
 
+  currentRevision(workspaceId: string, configId: string): number {
+    const row = this.db.query("SELECT revision FROM current_context WHERE workspace_id=? AND config_id=?").get(workspaceId, configId) as { revision: number } | null;
+    return row?.revision ?? 0;
+  }
+
   getInitializationConfiguration(workspaceId: string): Record<string, unknown> {
     const row = this.db.query(`SELECT c.id,c.revision,c.content_hash AS contentHash,c.config_json AS config
       FROM scan_configs c LEFT JOIN current_context p ON p.config_id=c.id AND p.workspace_id=?
@@ -498,11 +567,14 @@ export class InitializationStore {
 
   compareSnapshots(fromSnapshotId: string, toSnapshotId: string): Record<string, unknown> {
     if (fromSnapshotId === toSnapshotId) return { comparable: true, fromSnapshotId, toSnapshotId, added: [], changed: [], disappeared: [] };
-    const snapshots = this.db.query("SELECT id,config_id AS configId FROM context_snapshots WHERE id IN (?,?)").all(fromSnapshotId, toSnapshotId) as Array<{ id: string; configId: string }>;
+    const snapshots = this.db.query("SELECT id,project_id AS projectId,workspace_id AS workspaceId,config_id AS configId,input_snapshot_id AS inputSnapshotId FROM context_snapshots WHERE id IN (?,?)").all(fromSnapshotId, toSnapshotId) as Array<{ id: string; projectId: string; workspaceId: string; configId: string; inputSnapshotId: string }>;
     if (snapshots.length !== 2) throw new Error("Both context snapshots must exist");
     const fromMeta = snapshots.find(item => item.id === fromSnapshotId)!;
     const toMeta = snapshots.find(item => item.id === toSnapshotId)!;
+    if (fromMeta.projectId !== toMeta.projectId || fromMeta.workspaceId !== toMeta.workspaceId) return { comparable: false, reason: "workspace_changed", added: [], changed: [], disappeared: [] };
     if (fromMeta.configId !== toMeta.configId) return { comparable: false, reason: "scan_config_changed", added: [], changed: [], disappeared: [] };
+    const manifests = this.db.query("SELECT id,manifest_json AS manifest FROM input_snapshots WHERE id IN (?,?)").all(fromMeta.inputSnapshotId, toMeta.inputSnapshotId) as Array<{ id: string; manifest: string }>;
+    if (manifests.length !== 2) return { comparable: false, reason: "input_snapshot_missing", added: [], changed: [], disappeared: [] };
     const rows = (snapshotId: string) => this.db.query(`SELECT f.kind,f.repository,f.object_key AS objectKey,f.value_json AS value
       FROM facts f JOIN context_snapshots s ON s.run_id=f.run_id WHERE s.id=?`).all(snapshotId) as Array<{ kind: string; repository: string; objectKey: string; value: string }>;
     const key = (row: { kind: string; repository: string; objectKey: string }) => `${row.kind}\0${row.repository}\0${row.objectKey}`;
@@ -539,7 +611,8 @@ export class InitializationStore {
     const job = this.db.query("SELECT target_path AS targetPath,ownership,status FROM document_jobs WHERE id=?").get(jobId) as { targetPath: string; ownership: string; status: string } | null;
     if (!job) throw new Error(`Unknown document job: ${jobId}`);
     if (job.ownership === "human") throw new Error("Human-owned documents cannot be generated");
-    this.db.query("UPDATE document_jobs SET status='generating',error=NULL,updated_at=? WHERE id=? AND status IN ('queued','failed','pending_review')").run(now(), jobId);
+    const claimed = this.db.query("UPDATE document_jobs SET status='generating',error=NULL,updated_at=? WHERE id=? AND status IN ('queued','failed','pending_review')").run(now(), jobId);
+    if (claimed.changes !== 1) throw new Error(`Document job is no longer writable: ${jobId}`);
     const target = path.resolve(this.context.root, job.targetPath);
     if (target !== this.context.root && !target.startsWith(`${this.context.root}${path.sep}`)) throw new Error("Document path escapes project root");
     let existing: string | null = null;
@@ -559,7 +632,8 @@ export class InitializationStore {
     }
     await mkdir(path.dirname(target), { recursive: true });
     const temporary = `${target}.${randomUUID()}.tmp`; await writeFile(temporary, output, { encoding: "utf8", flag: "wx" }); await rename(temporary, target);
-    this.db.query("UPDATE document_jobs SET status='complete',output_hash=?,updated_at=? WHERE id=?").run(hash(output), now(), jobId);
+    const completed = this.db.query("UPDATE document_jobs SET status='complete',output_hash=?,updated_at=? WHERE id=? AND status='generating'").run(hash(output), now(), jobId);
+    if (completed.changes !== 1) throw new Error(`Document job completion conflict: ${jobId}`);
     return { status: "complete", path: target };
   }
 

package/src/project-context.ts

@@ -136,15 +136,17 @@ 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);
+  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 });
 }
 
 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) };
+    const location = await realpath(context.root);
+    const workspace = store.listWorkspaces().find(item => item.location === location);
+    if (!workspace) throw new Error("Project workspace is not registered; run explicit project initialization first");
+    return { ...context, workspaceId: String(workspace.id), controlDatabasePath: projectControlDatabasePath(context.manifest.projectId) };
   } finally {
     store.close();
   }
@@ -174,6 +176,8 @@ export async function initializeProject(root: string): Promise<{ context: Projec
     createdAt: new Date().toISOString(),
   };
   await atomicWriteJson(manifestPath, manifest);
+  const bootstrapStore = await InitializationStore.open({ root: canonicalRoot, manifest });
+  try { await bootstrapStore.registerWorkspace(); } finally { bootstrapStore.close(); }
   return {
     context: await attachInitializationStore({ root: canonicalRoot, manifestPath, manifest, planningRoot }),
     created: true,

package/src/project-documents.ts

@@ -77,6 +77,10 @@ function table(headers: string[], rows: unknown[][]): string {
 }
 function yamlString(value: string): string { return JSON.stringify(value); }
 function frontmatter(fields: Record<string, string | boolean | string[] | null | undefined>): string {
+  if (fields.source_snapshot && !fields.snapshot_id) fields.snapshot_id = fields.source_snapshot;
+  if (fields.source_snapshot) fields.generated = true;
+  if (fields.source_snapshot && !fields.generated_at) fields.generated_at = new Date().toISOString();
+  if (fields.source_snapshot && !fields.source_revision) fields.source_revision = fields.code_index_generation ?? "unknown";
   const lines = ["---"];
   for (const [key, value] of Object.entries(fields)) {
     if (value === undefined || value === null) continue;
@@ -629,7 +633,7 @@ 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", 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: ".planning", diagnostics: [], documents: [{ targetPath: ".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"],
         },
@@ -932,6 +936,7 @@ function renderKnowledgeDocuments(context: ProjectContext, facts: Fact[], intro:
   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` });

package/src/project-initializer.ts

@@ -1,5 +1,5 @@
-import { createHash } from "node:crypto";
-import { readFile, readdir, stat } from "node:fs/promises";
+import { createHash, randomUUID } from "node:crypto";
+import { readFile, readdir, stat, rename, rm } from "node:fs/promises";
 import path from "node:path";
 
 import { FACT_KINDS, InitializationStore, type FactInput, type FactKind, type ScanConfigInput } from "./initialization-store.ts";
@@ -10,7 +10,17 @@ const TEXT_EXTENSIONS = new Set([".ts", ".tsx", ".js", ".jsx", ".py", ".rb", ".g
 
 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 }> };
+export type InitializationProgress = {
+  runId: string;
+  snapshotId?: string;
+  completeness?: "complete" | "partial";
+  diagnostics: string[];
+  documents?: Array<{ targetPath: string; status: string; outputPath?: string; error?: string }>;
+  database: string;
+  projectId: string;
+  workspaceId: string;
+  planningRoot: 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(); }
@@ -167,7 +177,7 @@ async function runProcess(argv: string[], cwd: string): Promise<{ stdout: string
 
 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 output = `.planning/.code-index-pending-${randomUUID()}`;
   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);
@@ -175,7 +185,29 @@ async function buildCodeIndex(context: ProjectContext, config: ScanConfigInput):
   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" };
+  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" };
+}
+
+async function promoteCodeIndex(context: ProjectContext, indexRef: Record<string, unknown>): Promise<() => Promise<void>> {
+  const stagingPath = typeof indexRef.stagingPath === "string" ? path.resolve(context.root, indexRef.stagingPath) : null;
+  const target = path.resolve(context.root, ".planning/code-index");
+  if (!stagingPath) return async () => {};
+  const previous = `${target}.previous-${randomUUID()}`;
+  const existing = await stat(target).catch(() => null);
+  if (existing) await rename(target, previous);
+  try {
+    await rename(stagingPath, target);
+    delete indexRef.stagingPath;
+    return async () => {
+      await rm(target, { recursive: true, force: true });
+      if (existing) await rename(previous, target);
+    };
+  } catch (error) {
+    await rm(target, { recursive: true, force: true }).catch(() => {});
+    if (existing) await rename(previous, target).catch(() => {});
+    throw error;
+  }
 }
 
 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> {
@@ -189,7 +221,15 @@ export async function runProjectInitialization(context: ProjectContext, input: {
     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 };
+    if (run.reused) return {
+      runId: run.id,
+      snapshotId: store.getRun(run.id)?.publishedSnapshotId as string | undefined,
+      diagnostics,
+      database: context.controlDatabasePath,
+      projectId: context.manifest.projectId,
+      workspaceId: context.workspaceId,
+      planningRoot: context.planningRoot,
+    };
     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);
@@ -218,13 +258,22 @@ export async function runProjectInitialization(context: ProjectContext, input: {
         facts: status === "complete" ? repositoryFacts : [],
       });
     }
-    const indexRef = config.mode === "full" ? await buildCodeIndex(context, config) : { status: "skipped", reason: "explicit_fast_mode" };
+    const indexRef = config.mode === "full"
+      ? { ...(await buildCodeIndex(context, config)), inputFingerprint: inputSnapshot.fingerprint, workspaceId: workspace.id, configId: storedConfig.id }
+      : { status: "skipped", reason: "explicit_fast_mode", inputFingerprint: inputSnapshot.fingerprint, workspaceId: workspace.id, configId: storedConfig.id };
     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 });
+    const rollbackIndex = await promoteCodeIndex(context, indexRef);
+    let published: { snapshotId: string; revision: number };
+    try {
+      published = store.publishRun(run.id, run.leaseToken, { expectedRevision: store.currentRevision(workspace.id, storedConfig.id), indexRef });
+    } catch (error) {
+      await rollbackIndex();
+      throw error;
+    }
     if (input.switchAuthority !== false) {
       const authority = store.getAuthority();
       if (authority.authority === "legacy") store.switchAuthority("database", authority.revision);
@@ -241,7 +290,17 @@ export async function runProjectInitialization(context: ProjectContext, input: {
         documents = [{ targetPath: ".planning/initialization/report.md", status: "failed", error: message }];
       }
     }
-    return { runId: run.id, snapshotId: published.snapshotId, completeness: result.snapshot.completeness, diagnostics, documents };
+    return {
+      runId: run.id,
+      snapshotId: published.snapshotId,
+      completeness: result.snapshot.completeness,
+      diagnostics,
+      documents,
+      database: context.controlDatabasePath,
+      projectId: context.manifest.projectId,
+      workspaceId: context.workspaceId,
+      planningRoot: context.planningRoot,
+    };
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
     diagnostics.push(message);

package/src/project-migration.ts

@@ -22,7 +22,8 @@ export async function importLegacyInitialization(context: ProjectContext, source
   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 input = store.createInputSnapshot(workspace.id, config.id, documents.map(item => ({ repository: "legacy-materials", path: item.relative, contentHash: item.contentHash, size: item.size })), false);
+    store.confirmInputSnapshot(input.id, input.fingerprint);
     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",
@@ -30,7 +31,7 @@ export async function importLegacyInitialization(context: ProjectContext, source
     });
     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 });
+      : store.publishRun(run.id, run.leaseToken, { expectedRevision: 0, 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);