@guanlin4924/devflow-pi 0.1.78 → 0.1.80

package/package.json

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

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

@@ -53,14 +53,17 @@ export default function devflowIntel(pi: ExtensionAPI) {
     label: "Devflow Code Index",
     description: "Scan, validate, audit, or query the deterministic project code index.",
     parameters: z.object({
-      action: z.enum(["scan", "validate", "audit", "query", "relations"]),
+      action: z.enum(["scan", "validate", "audit", "query", "relations", "impact"]),
       term: z.string().optional(),
       object: z.string().optional(),
+      entity: z.string().optional(),
+      changeType: z.enum(["remove_field", "rename_field", "change_type", "optional_to_required", "required_to_optional", "change_nullability", "change_enum"]).optional(),
       snapshot: z.string().optional(),
       depth: z.number().int().min(0).max(20).default(3),
       includeHeuristic: z.boolean().default(false),
       limit: z.number().int().min(1).max(100).default(20),
       changedFiles: z.array(z.string()).default([]),
+      validationLevel: z.enum(["fast", "publish", "full"]).default("publish"),
     }),
     approval: (args) => {
       const action = (args as { action?: string }).action;
@@ -76,8 +79,12 @@ export default function devflowIntel(pi: ExtensionAPI) {
         if (params.changedFiles.length > 0) args.push("--changed-files", ...params.changedFiles);
       } else if (params.action === "validate") {
         args.push("--index", ".planning/code-index");
+        args.push("--level", params.validationLevel);
+        if (params.snapshot) args.push("--snapshot", params.snapshot);
       } else if (params.action === "audit") {
         args.push("--root", ctx.cwd, "--index", ".planning/code-index", "--skill-root", skillRoot);
+        args.push("--level", params.validationLevel === "fast" ? "publish" : params.validationLevel);
+        if (params.snapshot) args.push("--snapshot", params.snapshot);
       } else if (params.action === "query") {
         if (!params.term) {
           return render({ ok: false, exitCode: 2, stdout: "", stderr: "term is required" }, {});
@@ -85,6 +92,13 @@ export default function devflowIntel(pi: ExtensionAPI) {
         args.push("--index", ".planning/code-index", "--term", params.term, "--limit", String(params.limit));
         if (params.snapshot) args.push("--snapshot", params.snapshot);
       } else {
+        if (params.action === "impact") {
+          if (!params.entity) return render({ ok: false, exitCode: 2, stdout: "", stderr: "entity is required" }, {});
+          args.push("--index", ".planning/code-index", "--entity", params.entity, "--depth", String(params.depth), "--limit", String(params.limit));
+          if (params.snapshot) args.push("--snapshot", params.snapshot);
+          if (params.changeType) args.push("--change-type", params.changeType);
+          return render(await run(args, ctx.cwd), { action: params.action });
+        }
         if (!params.object) return render({ ok: false, exitCode: 2, stdout: "", stderr: "object is required" }, {});
         args.push("--index", ".planning/code-index", "--object", params.object, "--depth", String(params.depth), "--limit", String(params.limit));
         if (params.snapshot) args.push("--snapshot", params.snapshot);

package/plugins/devflow-intel/skills/code-index-query/SKILL.md

@@ -32,6 +32,14 @@ devflow_code_index(action="scan")
 devflow_code_index(action="audit")
 ```
 
+Impact analysis uses the same immutable SQLite snapshot:
+
+```text
+devflow_code_index(action="impact", entity="{entity_id}", changeType="remove_field")
+```
+
+The result carries `_meta.snapshot`, coverage, and truncation status. Older structural-only snapshots return an explicit semantic capability-unavailable result; they remain valid for symbol and relation queries.
+
 ## Query Patterns
 
 For more detailed query patterns, read `references/query-patterns.md`.

package/plugins/devflow-intel/skills/workflow-code-index/SKILL.md

@@ -44,8 +44,23 @@ Use the OMP runtime tool:
 devflow_code_index(action="scan")
 devflow_code_index(action="validate")
 devflow_code_index(action="audit")
+devflow_code_index(action="impact", entity="api:orders", changeType="remove_field")
 ```
 
+Validation is staged so large indexes do not block publication on a full
+sidecar audit:
+
+- `validationLevel="fast"` checks the snapshot bundle and generation metadata.
+- `validationLevel="publish"` (the default) adds SQLite quick-checks and
+  SQL-backed symbol/relation referential checks. It is the initialization
+  publish gate and does not load every JSONL sidecar into memory.
+- `validationLevel="full"` additionally validates every JSONL record and the
+  semantic graph. Run it as an explicit audit when complete verification is
+  required.
+
+The same split is available to `audit`: the default publish audit is bounded;
+`validationLevel="full"` performs stale-file and full relation auditing.
+
 For changed-file indexing:
 
 ```text
@@ -66,3 +81,7 @@ Blocking findings are stale file hashes, missing indexed files, dangling `to_id`
 - Do not mark dynamic or string-based matches as `exact`.
 - If adapter support is missing, emit diagnostics and fall back to generic indexing.
 - Query answers must read source files at evidence paths before making factual claims.
+- The root `SNAPSHOT.json` is only a pointer. Queries, validation, audit, and impact resolve it to the immutable `snapshots/{generation}` directory before reading facts.
+- Query results include snapshot and parser provenance. A historical snapshot may be queried with `snapshot`; it is not freshness-checked against the current worktree.
+- `impact` is a typed semantic query. It returns `unavailable` with `semantic_capability_unavailable` when an older structural-only snapshot has no semantic tables; it never executes arbitrary SQL.
+- Query limits are bounded by the runtime. Negative or oversized limits are normalized safely.

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

@@ -65,7 +65,17 @@ def _publish_snapshot(staging: Path, output: Path, counts: Dict[str, int], works
     generation = generation or str(uuid.uuid4())
     immutable_relative = f"snapshots/{generation}"
     snapshot = {
+        # Keep the public snapshot schema stable while exposing the richer
+        # SQLite schema separately.  Older consumers only know schemaVersion=1.
         "schemaVersion": 1,
+        "indexSchemaVersion": 3,
+        "capabilities": {
+            "structural": True,
+            "semantic": True,
+            "fts": True,
+            "relations": True,
+            "provenance": True,
+        },
         "generation": generation,
         "generatedAt": datetime.now(timezone.utc).isoformat(),
         "counts": counts,
@@ -187,13 +197,22 @@ def main(argv=None) -> int:
     scan.add_argument("--changed-files", nargs="*", default=[], help="Optional changed files for incremental refresh.")
     scan.add_argument("--exclude", action="append", default=[], help="Additional directory names to exclude.")
 
-    validate = sub.add_parser("validate", help="Validate JSONL schema.")
+    validate = sub.add_parser("validate", help="Validate an index in staged levels.")
     validate.add_argument("--index", default=".planning/code-index", help="Index directory.")
+    validate.add_argument("--snapshot", help="Immutable generation id.")
+    validate.add_argument(
+        "--level",
+        choices=("fast", "publish", "full"),
+        default="publish",
+        help="fast bundle checks, publish gate checks, or full JSONL/semantic audit",
+    )
 
     audit = sub.add_parser("audit", help="Audit stale files and relation integrity.")
     audit.add_argument("--root", default=".", help="Project root.")
     audit.add_argument("--index", default=".planning/code-index", help="Index directory.")
     audit.add_argument("--skill-root", default=".skills", help="Optional skill root for project-binding checks.")
+    audit.add_argument("--snapshot", help="Immutable generation id.")
+    audit.add_argument("--level", choices=("publish", "full"), default="publish")
 
     query = sub.add_parser("query", help="Search symbols using SQLite FTS or LIKE fallback.")
     query.add_argument("--index", default=".planning/code-index", help="Index directory.")
@@ -335,6 +354,12 @@ def command_scan(args) -> int:
                 registry_capabilities() if registry_capabilities else {},
             )
             workspace_state["generatedAt"] = datetime.now(timezone.utc).isoformat()
+            workspace_state["scanScope"] = {
+                "exclude": sorted(set(args.exclude)),
+                "codebases": [
+                    {"name": item.name, "path": str(item.root)} for item in codebases
+                ],
+            }
             workspace_state["semanticExtractor"] = SEMANTIC_EXTRACTOR_VERSION
             workspace_state["extractorSetHash"] = _hash_lines([*workspace_state.get("extractors", []), SEMANTIC_EXTRACTOR_VERSION])
             progress.emit("semantic", "building semantic facts")
@@ -387,47 +412,114 @@ def command_scan(args) -> int:
         return 0
 
 
-def command_validate(args) -> int:
-    output = Path(args.index).resolve()
-    selected = _selected_generation(output, None)
-    errors = []
+def _validate_publish_gate(selected: Path, snapshot: Dict[str, object]) -> List[str]:
+    """Run bounded checks required before publishing a generation.
+
+    This deliberately uses SQLite for referential checks.  The previous
+    implementation loaded every JSONL sidecar before it could decide whether
+    a snapshot was publishable, which made large projects spend minutes at
+    100% CPU in a validation process.
+    """
+    errors = _validate_snapshot_bundle(selected, snapshot)
+    if errors:
+        return errors
+    index = selected / "index.sqlite"
     try:
-        snapshot = _load_snapshot(selected)
-        files, symbols, relations, diagnostics = _load_tuple(selected)
-        errors.extend(validate_index(files, symbols, relations, diagnostics))
-        conn = sqlite3.connect(str(selected / "index.sqlite"))
+        conn = sqlite3.connect(str(index))
         try:
+            quick = conn.execute("PRAGMA quick_check").fetchone()
+            if not quick or quick[0] != "ok":
+                errors.append(f"sqlite quick_check failed: {quick[0] if quick else 'no result'}")
             snapshot_id = snapshot.get("generation")
-            row = conn.execute("SELECT snapshot_id FROM analysis_snapshots WHERE snapshot_id=?", (snapshot_id,)).fetchone()
-            if not row:
-                errors.append(f"semantic schema missing snapshot {snapshot_id}")
-            dangling = conn.execute("""
-              SELECT COUNT(*) FROM semantic_flows f
-              WHERE f.snapshot_id=? AND (
-                (NOT EXISTS (SELECT 1 FROM entity_versions e WHERE e.snapshot_id=f.snapshot_id AND e.logical_id=f.source_id)
-                 AND NOT EXISTS (SELECT 1 FROM symbols s WHERE s.id=f.source_id))
-                OR
-                (NOT EXISTS (SELECT 1 FROM entity_versions e WHERE e.snapshot_id=f.snapshot_id AND e.logical_id=f.target_id)
-                 AND NOT EXISTS (SELECT 1 FROM symbols s WHERE s.id=f.target_id))
-              )
-            """, (snapshot_id,)).fetchone()[0]
-            if dangling:
-                errors.append(f"semantic flows have {dangling} dangling source or target nodes")
-            binding_dangling = conn.execute("""
-              SELECT COUNT(*) FROM feature_bindings b
-              WHERE b.snapshot_id=? AND (
-                NOT EXISTS (SELECT 1 FROM entity_versions e WHERE e.snapshot_id=b.snapshot_id AND e.logical_id=b.feature_id)
-                OR NOT EXISTS (SELECT 1 FROM entity_versions e WHERE e.snapshot_id=b.snapshot_id AND e.logical_id=b.entity_id)
-              )
-            """, (snapshot_id,)).fetchone()[0]
-            if binding_dangling:
-                errors.append(f"feature bindings have {binding_dangling} dangling feature or entity nodes")
+            tables = _table_names(conn)
+            required = {"analysis_snapshots", "code_files", "symbols", "relations", "diagnostics"}
+            missing = sorted(required - tables)
+            if missing:
+                errors.append(f"index missing required tables: {', '.join(missing)}")
+            elif not conn.execute("SELECT 1 FROM analysis_snapshots WHERE snapshot_id=? LIMIT 1", (snapshot_id,)).fetchone():
+                errors.append(f"snapshot metadata missing generation {snapshot_id}")
+
+            if {"relations", "symbols"}.issubset(tables):
+                dangling = conn.execute("""
+                    SELECT COUNT(*) FROM relations r
+                    LEFT JOIN symbols s ON s.id=r.from_id
+                    WHERE s.id IS NULL
+                """).fetchone()[0]
+                if dangling:
+                    errors.append(f"relations have {dangling} missing source symbols")
+                dangling = conn.execute("""
+                    SELECT COUNT(*) FROM relations r
+                    LEFT JOIN symbols s ON s.id=r.to_id
+                    WHERE r.to_id IS NOT NULL AND s.id IS NULL AND (r.to_external IS NULL OR r.to_external='')
+                """).fetchone()[0]
+                if dangling:
+                    errors.append(f"relations have {dangling} missing target symbols")
         finally:
             conn.close()
+    except (OSError, sqlite3.Error) as exc:
+        errors.append(str(exc))
+    return errors
+
+
+def _validate_semantic_graph(conn: sqlite3.Connection, snapshot_id: str, tables: set[str]) -> List[str]:
+    errors: List[str] = []
+    semantic_tables = {"semantic_flows", "entity_versions", "feature_bindings", "coverage_metrics"}
+    if not semantic_tables.issubset(tables):
+        missing = ", ".join(sorted(semantic_tables - tables))
+        errors.append(f"full validation unavailable: missing semantic tables: {missing}")
+        return errors
+    dangling = conn.execute("""
+      SELECT COUNT(*) FROM semantic_flows f
+      WHERE f.snapshot_id=? AND (
+        (NOT EXISTS (SELECT 1 FROM entity_versions e WHERE e.snapshot_id=f.snapshot_id AND e.logical_id=f.source_id)
+         AND NOT EXISTS (SELECT 1 FROM symbols s WHERE s.id=f.source_id))
+        OR
+        (NOT EXISTS (SELECT 1 FROM entity_versions e WHERE e.snapshot_id=f.snapshot_id AND e.logical_id=f.target_id)
+         AND NOT EXISTS (SELECT 1 FROM symbols s WHERE s.id=f.target_id))
+      )
+    """, (snapshot_id,)).fetchone()[0]
+    if dangling:
+        errors.append(f"semantic flows have {dangling} dangling source or target nodes")
+    binding_dangling = conn.execute("""
+      SELECT COUNT(*) FROM feature_bindings b
+      WHERE b.snapshot_id=? AND (
+        NOT EXISTS (SELECT 1 FROM entity_versions e WHERE e.snapshot_id=b.snapshot_id AND e.logical_id=b.feature_id)
+        OR NOT EXISTS (SELECT 1 FROM entity_versions e WHERE e.snapshot_id=b.snapshot_id AND e.logical_id=b.entity_id)
+      )
+    """, (snapshot_id,)).fetchone()[0]
+    if binding_dangling:
+        errors.append(f"feature bindings have {binding_dangling} dangling feature or entity nodes")
+    return errors
+
+
+def command_validate(args) -> int:
+    output = Path(args.index).resolve()
+    selected = _selected_generation(output, getattr(args, "snapshot", None))
+    level = getattr(args, "level", "publish")
+    errors: List[str] = []
+    try:
+        snapshot = _load_snapshot(selected)
+        print(f"[code-index][validate] level={level} snapshot={snapshot.get('generation', 'unknown')}", file=sys.stderr, flush=True)
+        if level == "fast":
+            errors.extend(_validate_snapshot_bundle(selected, snapshot))
+        else:
+            errors.extend(_validate_publish_gate(selected, snapshot))
+        if level == "full" and not errors:
+            print("[code-index][validate] full JSONL schema validation", file=sys.stderr, flush=True)
+            files, symbols, relations, diagnostics = _load_tuple(selected)
+            errors.extend(validate_index(files, symbols, relations, diagnostics))
+            if not errors:
+                conn = sqlite3.connect(str(selected / "index.sqlite"))
+                try:
+                    errors.extend(_validate_semantic_graph(conn, str(snapshot.get("generation")), _table_names(conn)))
+                finally:
+                    conn.close()
     except (OSError, sqlite3.Error, ValueError) as exc:
         errors.append(str(exc))
     for error in errors:
         print(error, file=sys.stderr)
+    if not errors:
+        print(f"Index validation passed ({level}).")
     return 1 if errors else 0
 def command_query(args) -> int:
     output = Path(args.index).resolve()
@@ -438,6 +530,11 @@ def command_query(args) -> int:
             print(f"Missing index: {index}", file=sys.stderr)
             return 1
         snapshot = _load_snapshot(selected)
+        bundle_errors = _validate_snapshot_bundle(selected, snapshot)
+        if bundle_errors:
+            print(bundle_errors[0], file=sys.stderr)
+            return 1
+        limit = _bounded_limit(getattr(args, "limit", 20), 1000)
         files = read_jsonl(selected / INDEX_FILES["files"])
         if not getattr(args, "snapshot", None) and not _query_is_fresh(output.parent.parent, snapshot, files):
             print("Stale code index: refresh required before query.", file=sys.stderr)
@@ -445,30 +542,38 @@ def command_query(args) -> int:
         conn = sqlite3.connect(str(index))
         conn.row_factory = sqlite3.Row
         try:
+            symbol_columns = {row[1] for row in conn.execute("PRAGMA table_info(symbols)")}
+            provenance = ", parser, content_hash, metadata_json" if {"parser", "content_hash", "metadata_json"}.issubset(symbol_columns) else ", NULL AS parser, NULL AS content_hash, NULL AS metadata_json"
             try:
                 rows = conn.execute(
-                    """
-                    SELECT id, codebase, kind, name, qualified_name, path, line_start, line_end
+                    f"""
+                    SELECT id, codebase, kind, name, qualified_name, path, line_start, line_end,
+                           {provenance[2:]}
                     FROM symbols_fts
                     JOIN symbols USING(id)
                     WHERE symbols_fts MATCH ?
                     LIMIT ?
                     """,
-                    (args.term, args.limit),
+                    (args.term, limit),
                 ).fetchall()
             except sqlite3.OperationalError:
                 like = f"%{args.term}%"
                 rows = conn.execute(
-                    """
-                    SELECT id, codebase, kind, name, qualified_name, path, line_start, line_end
+                    f"""
+                    SELECT id, codebase, kind, name, qualified_name, path, line_start, line_end,
+                           {provenance[2:]}
                     FROM symbols
                     WHERE name LIKE ? OR qualified_name LIKE ? OR path LIKE ?
                     LIMIT ?
                     """,
-                    (like, like, like, args.limit),
+                    (like, like, like, limit),
                 ).fetchall()
             for row in rows:
-                print(json.dumps(dict(row), ensure_ascii=False, sort_keys=True))
+                item = dict(row)
+                item["snapshot"] = snapshot.get("generation")
+                item["parser"] = item.get("parser") or "unknown"
+                item["confidence"] = item.get("confidence") or confidence_for_parser(item["parser"], "symbol")
+                print(json.dumps(item, ensure_ascii=False, sort_keys=True))
         finally:
             conn.close()
     return 0
@@ -476,14 +581,22 @@ def command_query(args) -> int:
 
 def command_relations(args) -> int:
     output = Path(args.index).resolve()
-    depth = max(0, min(args.depth, 20)); limit = max(1, min(args.limit, 1000))
+    depth = max(0, min(args.depth, 20)); limit = _bounded_limit(args.limit, 1000)
     with _index_lock(output, exclusive=False):
         selected = _selected_generation(output, getattr(args, "snapshot", None))
         snapshot = _load_snapshot(selected); files = read_jsonl(selected / INDEX_FILES["files"])
+        bundle_errors = _validate_snapshot_bundle(selected, snapshot)
+        if bundle_errors:
+            print(bundle_errors[0], file=sys.stderr); return 1
         if not getattr(args, "snapshot", None) and not _query_is_fresh(output.parent.parent, snapshot, files):
             print("Stale code index: refresh required before query.", file=sys.stderr); return 1
         conn = sqlite3.connect(str(selected / "index.sqlite")); conn.row_factory = sqlite3.Row
         try:
+            symbol_columns = {row[1] for row in conn.execute("PRAGMA table_info(symbols)")}
+            parser_expr = "s.parser" if "parser" in symbol_columns else "NULL"
+            hash_expr = "s.content_hash" if "content_hash" in symbol_columns else "NULL"
+            to_parser_expr = "t.parser" if "parser" in symbol_columns else "NULL"
+            to_hash_expr = "t.content_hash" if "content_hash" in symbol_columns else "NULL"
             if depth == 0:
                 print(json.dumps({"_meta": {"snapshot": snapshot.get("generation"), "depthLimit": 0, "resultLimit": limit, "truncated": False}}, ensure_ascii=False, sort_keys=True))
                 return 0
@@ -496,14 +609,21 @@ def command_relations(args) -> int:
                 SELECT r.from_id,r.relation_type,r.to_id,r.to_external,r.evidence_path,r.evidence_line,r.confidence,g.depth+1,g.visited || COALESCE(r.to_id,'') || ','
                 FROM graph g JOIN relations r ON r.from_id=g.to_id
                 WHERE g.depth < ? AND r.to_id IS NOT NULL {confidence} AND instr(g.visited, ',' || r.to_id || ',')=0
-              ) SELECT * FROM graph ORDER BY depth,from_id,relation_type,to_id LIMIT ?
+              ) SELECT graph.*, s.path AS from_path, s.name AS from_name, {parser_expr} AS from_parser,
+                       {hash_expr} AS from_content_hash, t.path AS to_path, t.name AS to_name,
+                       {to_parser_expr} AS to_parser, {to_hash_expr} AS to_content_hash
+                  FROM graph
+                  LEFT JOIN symbols s ON s.id=graph.from_id
+                  LEFT JOIN symbols t ON t.id=graph.to_id
+                  ORDER BY depth,from_id,relation_type,to_id LIMIT ?
             """, (args.object, depth, limit + 1)).fetchall()
             truncated = len(rows) > limit
             for row in rows[:limit]:
                 item = dict(row)
+                item["snapshot"] = snapshot.get("generation")
                 if getattr(args, "change_type", None):
                     item["impact_kind"] = args.change_type
-                    item["severity"] = _impact_severity(args.change_type, item["flow_type"])
+                    item["severity"] = _impact_severity(args.change_type, item.get("flow_type", "relation"))
                 print(json.dumps(item, ensure_ascii=False, sort_keys=True))
             print(json.dumps({"_meta": {"snapshot": snapshot.get("generation"), "depthLimit": depth, "resultLimit": limit, "truncated": truncated}}, ensure_ascii=False, sort_keys=True))
         finally: conn.close()
@@ -523,10 +643,13 @@ def _impact_severity(change_type: str, flow_type: str) -> str:
 
 def command_impact(args) -> int:
     output = Path(args.index).resolve()
-    depth = max(0, min(args.depth, 20)); limit = max(1, min(args.limit, 2000))
+    depth = max(0, min(args.depth, 20)); limit = _bounded_limit(args.limit, 2000)
     with _index_lock(output, exclusive=False):
         selected = _selected_generation(output, getattr(args, "snapshot", None))
         snapshot = _load_snapshot(selected)
+        bundle_errors = _validate_snapshot_bundle(selected, snapshot)
+        if bundle_errors:
+            print(bundle_errors[0], file=sys.stderr); return 1
         if not getattr(args, "snapshot", None):
             files = read_jsonl(selected / INDEX_FILES["files"])
             if not _query_is_fresh(output.parent.parent, snapshot, files):
@@ -534,6 +657,11 @@ def command_impact(args) -> int:
                 return 1
         conn = sqlite3.connect(str(selected / "index.sqlite")); conn.row_factory = sqlite3.Row
         try:
+            tables = _table_names(conn)
+            semantic_tables = {"semantic_flows", "entity_versions", "feature_bindings", "coverage_metrics"}
+            if not semantic_tables.issubset(tables):
+                print(json.dumps({"_meta": {"snapshot": snapshot.get("generation"), "status": "unavailable", "reason": "semantic_capability_unavailable", "coverage": {"status": "unknown"}, "truncated": False}}, ensure_ascii=False, sort_keys=True))
+                return 0
             rows = conn.execute("""
               WITH RECURSIVE graph(node_id, flow_type, source_path, line_start, confidence, depth, visited) AS (
                 SELECT CASE WHEN source_id=? THEN target_id ELSE source_id END, flow_type, source_path, line_start, confidence, 1, ',' || ? || ','
@@ -545,7 +673,12 @@ def command_impact(args) -> int:
                 WHERE g.depth < ? AND instr(g.visited, ',' || CASE WHEN f.source_id=g.node_id THEN f.target_id ELSE f.source_id END || ',')=0
               ) SELECT * FROM graph LIMIT ?
             """, (args.entity, args.entity, snapshot.get("generation"), args.entity, args.entity, snapshot.get("generation"), depth, limit + 1)).fetchall()
-            for row in rows[:limit]: print(json.dumps(dict(row), ensure_ascii=False, sort_keys=True))
+            for row in rows[:limit]:
+                item = dict(row); item["snapshot"] = snapshot.get("generation")
+                if getattr(args, "change_type", None):
+                    item["impact_kind"] = args.change_type
+                    item["severity"] = _impact_severity(args.change_type, item.get("flow_type", "relation"))
+                print(json.dumps(item, ensure_ascii=False, sort_keys=True))
             coverage_row = conn.execute("SELECT * FROM coverage_metrics WHERE snapshot_id=?", (snapshot.get("generation"),)).fetchone()
             coverage = dict(coverage_row) if coverage_row else {"status": "unknown"}
             print(json.dumps({"_meta": {"snapshot": snapshot.get("generation"), "coverage": coverage, "depthLimit": depth, "truncated": len(rows) > limit}}, ensure_ascii=False, sort_keys=True))
@@ -556,16 +689,39 @@ def command_impact(args) -> int:
 
 def _selected_generation(output: Path, generation: str | None) -> Path:
     if not generation:
+        root_snapshot = _load_snapshot(output)
+        current = root_snapshot.get("generation") if root_snapshot else None
+        if current is not None:
+            if not re.fullmatch(r"[0-9a-f-]{36}", str(current), re.I):
+                raise ValueError(f"invalid current snapshot generation: {current}")
+            current = str(current)
+            _validate_generation_pointer(output, root_snapshot, current)
+            selected = output / "snapshots" / current
+            if not selected.is_dir():
+                raise ValueError(f"current snapshot directory is missing: {selected}")
+            selected_snapshot = _load_snapshot(selected)
+            _validate_generation_pointer(selected, selected_snapshot, current)
+            return selected
+        # Legacy indexes predating immutable snapshots remain readable.
         return output
     if not re.fullmatch(r"[0-9a-f-]{36}", generation, re.I):
         raise ValueError("invalid snapshot generation")
     selected = output / "snapshots" / generation
     snapshot = _load_snapshot(selected)
-    if snapshot.get("generation") != generation:
-        raise ValueError(f"unknown snapshot generation: {generation}")
+    _validate_generation_pointer(selected, snapshot, generation)
     return selected
 
 
+def _validate_generation_pointer(selected: Path, snapshot: Dict[str, object], expected: str) -> None:
+    if snapshot.get("generation") != expected:
+        raise ValueError(f"snapshot generation mismatch: expected={expected}, metadata={snapshot.get('generation')}")
+    expected_path = f"snapshots/{expected}"
+    if snapshot.get("immutablePath") != expected_path:
+        raise ValueError(
+            f"snapshot immutablePath mismatch: expected={expected_path}, metadata={snapshot.get('immutablePath')}"
+        )
+
+
 def _load_snapshot(output: Path) -> Dict[str, object]:
     path = output / SNAPSHOT_FILE
     if not path.exists():
@@ -573,6 +729,49 @@ def _load_snapshot(output: Path) -> Dict[str, object]:
     return json.loads(path.read_text(encoding="utf-8"))
 
 
+def _bounded_limit(value, maximum: int) -> int:
+    try:
+        value = int(value)
+    except (TypeError, ValueError):
+        value = 20
+    return max(1, min(value, maximum))
+
+
+def _table_names(conn: sqlite3.Connection) -> set[str]:
+    return {row[0] for row in conn.execute("SELECT name FROM sqlite_master WHERE type IN ('table','virtual table')")}
+
+
+def _validate_snapshot_bundle(selected: Path, snapshot: Dict[str, object]) -> List[str]:
+    errors: List[str] = []
+    generation = snapshot.get("generation")
+    if not generation:
+        return [f"snapshot metadata missing generation in {selected}"]
+    if selected.parent.name == "snapshots":
+        try:
+            _validate_generation_pointer(selected, snapshot, selected.name)
+        except ValueError as exc:
+            errors.append(str(exc))
+    required = [SNAPSHOT_FILE, "index.sqlite", *INDEX_FILES.values()]
+    for name in required:
+        if not (selected / name).is_file():
+            errors.append(f"snapshot {generation} missing artifact {name}")
+    index = selected / "index.sqlite"
+    if index.is_file():
+        try:
+            conn = sqlite3.connect(str(index))
+            try:
+                tables = _table_names(conn)
+                if "analysis_snapshots" in tables:
+                    row = conn.execute("SELECT snapshot_id FROM analysis_snapshots LIMIT 1").fetchone()
+                    if row and row[0] != generation:
+                        errors.append(f"snapshot generation mismatch: metadata={generation}, sqlite={row[0]}")
+            finally:
+                conn.close()
+        except sqlite3.Error as exc:
+            errors.append(f"invalid sqlite snapshot {generation}: {exc}")
+    return errors
+
+
 def _query_is_fresh(root: Path, snapshot: Dict[str, object], files: List[dict]) -> bool:
     workspace = snapshot.get("workspace") if isinstance(snapshot, dict) else None
     if not isinstance(workspace, dict):
@@ -591,7 +790,9 @@ def _query_is_fresh(root: Path, snapshot: Dict[str, object], files: List[dict])
             return False
     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))
+        scope = workspace.get("scanScope") if isinstance(workspace.get("scanScope"), dict) else {}
+        excludes = scope.get("exclude", []) if isinstance(scope, dict) else []
+        current_paths = sorted(_workspace_rel(root, item) for item in scan_files(root, excludes=excludes))
         expected_paths_hash = workspace.get("discoveredPathsHash") or workspace.get("indexedPathsHash")
         if _hash_lines(current_paths) != expected_paths_hash:
             return False
@@ -603,10 +804,46 @@ def command_audit(args) -> int:
     root = Path(args.root).resolve()
     output = Path(args.index).resolve()
     with _index_lock(output, exclusive=True):
-        files, symbols, relations, diagnostics = _load_tuple(output)
+        selected = _selected_generation(output, getattr(args, "snapshot", None))
+        snapshot = _load_snapshot(selected)
+        bundle_errors = _validate_snapshot_bundle(selected, snapshot)
+        if bundle_errors:
+            for error in bundle_errors:
+                print(error, file=sys.stderr)
+            return 1
         findings = []
-        findings.extend(audit_stale(root, files))
-        findings.extend(audit_relations(symbols, relations))
+        level = getattr(args, "level", "publish")
+        if level == "full":
+            files, symbols, relations, diagnostics = _load_tuple(selected)
+            findings.extend(audit_stale(root, files))
+            findings.extend(audit_relations(symbols, relations))
+        else:
+            # The publish audit is intentionally bounded and SQL-backed.  A
+            # full stale/content audit remains available explicitly via
+            # --level full and should not block initialization publication.
+            try:
+                conn = sqlite3.connect(str(selected / "index.sqlite"))
+                try:
+                    tables = _table_names(conn)
+                    if {"relations", "symbols"}.issubset(tables):
+                        row = conn.execute("""
+                            SELECT COUNT(*) FROM relations r
+                            LEFT JOIN symbols s ON s.id=r.from_id
+                            WHERE s.id IS NULL
+                        """).fetchone()
+                        if row and row[0]:
+                            findings.append({"severity": "error", "kind": "dangling_relation", "message": f"{row[0]} relations have missing source symbols"})
+                        row = conn.execute("""
+                            SELECT COUNT(*) FROM relations r
+                            LEFT JOIN symbols s ON s.id=r.to_id
+                            WHERE r.to_id IS NOT NULL AND s.id IS NULL AND (r.to_external IS NULL OR r.to_external='')
+                        """).fetchone()
+                        if row and row[0]:
+                            findings.append({"severity": "error", "kind": "dangling_relation", "message": f"{row[0]} relations have missing target symbols"})
+                finally:
+                    conn.close()
+            except sqlite3.Error as exc:
+                findings.append({"severity": "error", "kind": "sqlite_error", "message": str(exc)})
         skill_root = Path(args.skill_root)
         if skill_root.exists():
             findings.extend(audit_project_binding([skill_root / "workflow-code-index", skill_root / "code-index-query"]))

package/src/constants.ts

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

package/src/project-initializer.ts

@@ -220,8 +220,8 @@ async function buildCodeIndex(context: ProjectContext, config: ScanConfigInput):
   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, "code-index scan");
-  await runProcess(["python3", script, "validate", "--index", output], context.root, "code-index validate");
-  await runProcess(["python3", script, "audit", "--root", context.root, "--index", output, "--skill-root", path.resolve(import.meta.dir, "../plugins/devflow-intel/skills")], context.root, "code-index audit");
+  await runProcess(["python3", script, "validate", "--index", output, "--level", "publish"], context.root, "code-index validate");
+  await runProcess(["python3", script, "audit", "--root", context.root, "--index", output, "--skill-root", path.resolve(import.meta.dir, "../plugins/devflow-intel/skills"), "--level", "publish"], context.root, "code-index audit");
   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");