kibi-cli 2.1.0 → 2.3.0

package/schema/validation.pl

@@ -42,8 +42,10 @@ validate_property_type(Type, Prop, Value) :-
 % check_kind(Kind, Value) succeeds if Value matches Kind
 check_kind(atom, V) :- atom(V).
 check_kind(string, V) :- string(V).
+check_kind(atom_or_string, V) :- atom(V) ; string(V).
 check_kind(datetime, V) :- string(V). % accept ISO strings for now
 check_kind(list, V) :- is_list(V).
+check_kind(list_or_json, V) :- is_list(V) ; string(V) ; atom(V).
 check_kind(uri, V) :- string(V).
 check_kind(integer, V) :- integer(V).
 check_kind(number, V) :- number(V).
@@ -59,11 +61,24 @@ validate_entity_shape(fact, Props) :-
     !,
     valid_optional_fact_enums(Props),
     valid_polarity_in_props(Props),
+    valid_claim_provenance(Props),
     ( memberchk(fact_kind=RawKind, Props) -> validate_fact_shape(RawKind, Props) ; true ).
+validate_entity_shape(test, Props) :-
+    !,
+    valid_optional_test_enums(Props),
+    forall(member(Key=_, Props), \+ is_fact_only_field(Key)).
+validate_entity_shape(req, Props) :-
+    !,
+    forall(member(Key=_, Props), \+ is_fact_only_field(Key)),
+    forall(member(Key=_, Props), \+ is_test_only_field(Key)).
 validate_entity_shape(Type, Props) :-
     Type \= fact,
-    % Non-fact entities cannot have fact-only fields
-    forall(member(Key=_Val, Props), \+ is_fact_only_field(Key)).
+    Type \= test,
+    Type \= req,
+    % Non-fact/non-test entities cannot have type-specific fields
+    forall(member(Key=_, Props), \+ is_fact_only_field(Key)),
+    forall(member(Key=_, Props), \+ is_test_only_field(Key)),
+    forall(member(Key=_, Props), Key \= logic_claims).
 
 % is_fact_only_field(+Key) - true if Key is a fact-specific field
 is_fact_only_field(fact_kind).
@@ -82,12 +97,39 @@ is_fact_only_field(closed_world).
 is_fact_only_field(valid_from).
 is_fact_only_field(valid_to).
 is_fact_only_field(canonical_key).
+is_fact_only_field(claim_key).
+is_fact_only_field(claim_text).
+is_fact_only_field(predicate_name).
+is_fact_only_field(predicate_namespace).
+is_fact_only_field(predicate_arity).
+is_fact_only_field(argument_names).
+is_fact_only_field(argument_types).
+is_fact_only_field(argument_descriptions).
+is_fact_only_field(argument_constants).
+is_fact_only_field(argument_aliases).
+is_fact_only_field(aliases).
+is_fact_only_field(examples).
+is_fact_only_field(predicate_args).
+is_fact_only_field(rule_ir).
+is_fact_only_field(rule_hash).
+is_fact_only_field(rule_schema_id).
+is_fact_only_field(rule_name).
+is_fact_only_field(semantic_key).
+is_fact_only_field(claim_span_start).
+is_fact_only_field(claim_span_end).
+
+% is_test_only_field(+Key) - true if Key is a test-specific field
+is_test_only_field(verification_scope).
+is_test_only_field(verification_perspective).
+is_test_only_field(proof_contract).
+is_test_only_field(proof_bindings).
+is_test_only_field(proof_receipts).
 
 % validate_fact_shape(+Kind, +Props)
 validate_fact_shape(subject, Props) :-
     memberchk(subject_key=_Val, Props),
     valid_optional_fact_enums(Props),
-    valid_polarity_in_props(Props).
+    valid_strict_polarity_in_props(Props), !.
 validate_fact_shape(property_value, Props) :-
     memberchk(subject_key=_Subject, Props),
     memberchk(property_key=_Property, Props),
@@ -98,48 +140,104 @@ validate_fact_shape(property_value, Props) :-
     exactly_one_value_field(Props),
     value_type_matches_field(VT, Props),
     valid_optional_fact_enums(Props),
-    valid_polarity_in_props(Props).
+    valid_strict_polarity_in_props(Props), !.
 validate_fact_shape(observation, Props) :-
-    % Observation facts are allowed but don't require full strict property tuple yet
     valid_optional_fact_enums(Props),
-    valid_polarity_in_props(Props).
+    valid_polarity_in_props(Props), !.
 validate_fact_shape(meta, Props) :-
     % Meta facts are allowed but don't require full strict property tuple yet
     valid_optional_fact_enums(Props),
-    valid_polarity_in_props(Props).
+    valid_polarity_in_props(Props), !.
+validate_fact_shape(predicate_schema, Props) :-
+    memberchk(predicate_name=_Name, Props),
+    memberchk(predicate_arity=Arity, Props),
+    Arity >= 1,
+    memberchk(argument_names=ArgumentNames, Props),
+    memberchk(argument_types=ArgumentTypes, Props),
+    same_length(ArgumentNames, ArgumentTypes),
+    length(ArgumentNames, Arity),
+    valid_optional_fact_enums(Props),
+    valid_polarity_in_props(Props), !.
+validate_fact_shape(predicate, Props) :-
+    memberchk(predicate_name=_Name, Props),
+    memberchk(predicate_args=Args, Props),
+    Args \= [],
+    memberchk(canonical_key=_CanonicalKey, Props),
+    valid_optional_fact_enums(Props),
+    valid_predicate_polarity_in_props(Props), !.
+validate_fact_shape(rule_schema, Props) :-
+    memberchk(rule_name=_Name, Props),
+    memberchk(argument_names=ArgumentNames, Props),
+    memberchk(argument_types=ArgumentTypes, Props),
+    same_length(ArgumentNames, ArgumentTypes),
+    valid_optional_fact_enums(Props),
+    valid_polarity_in_props(Props), !.
+validate_fact_shape(rule, Props) :-
+    memberchk(rule_ir=RuleIr, Props),
+    nonempty_claim_value(RuleIr),
+    memberchk(rule_hash=_Hash, Props),
+    memberchk(rule_schema_id=_SchemaId, Props),
+    memberchk(semantic_key=_SemanticKey, Props),
+    valid_optional_fact_enums(Props),
+    valid_polarity_in_props(Props), !.
 validate_fact_shape(Kind, _Props) :-
     % Unknown fact_kind values fail validation
-    \+ memberchk(Kind, [subject, property_value, observation, meta]),
+    \+ memberchk(Kind, [subject, property_value, observation, meta, predicate_schema, predicate, rule_schema, rule]),
     fail.
 
 % valid_operator(+Op)
-valid_operator(eq).
-valid_operator(neq).
-valid_operator(lt).
-valid_operator(lte).
-valid_operator(gt).
-valid_operator(gte).
+valid_operator(Op) :- memberchk(Op, [eq, neq, lt, lte, gt, gte]), !.
 
 % valid_value_type(+VT)
-valid_value_type(string).
-valid_value_type(int).
-valid_value_type(number).
-valid_value_type(bool).
+valid_value_type(ValueType) :- memberchk(ValueType, [string, int, number, bool]), !.
 
 % valid_polarity_in_props(+Props)
 % Validates polarity if present; succeeds if no polarity in props
 valid_polarity_in_props(Props) :-
     ( memberchk(polarity=P, Props) -> valid_polarity(P) ; true ).
 
+valid_strict_polarity_in_props(Props) :-
+    ( memberchk(polarity=P, Props) -> valid_strict_polarity(P) ; true ).
+
+valid_predicate_polarity_in_props(Props) :-
+    ( memberchk(polarity=P, Props) -> valid_predicate_polarity(P) ; true ).
+
+% claim_key and claim_text form one auditable provenance pair.
+valid_claim_provenance(Props) :-
+    (   memberchk(claim_key=Key, Props)
+    ->  memberchk(claim_text=Text, Props),
+        nonempty_claim_value(Key),
+        nonempty_claim_value(Text)
+    ;   \+ memberchk(claim_text=_, Props)
+    ).
+
+nonempty_claim_value(Value) :- string(Value), Value \= "", !.
+nonempty_claim_value(Value) :- atom(Value), Value \= '', !.
+
 % valid_optional_fact_enums(+Props)
 % Validates enum-typed fact fields whenever they are present
 valid_optional_fact_enums(Props) :-
     ( memberchk(operator=Op, Props) -> valid_operator(Op) ; true ),
     ( memberchk(value_type=VT, Props) -> valid_value_type(VT) ; true ).
 
+% valid_optional_test_enums(+Props)
+% Validates enum-typed test fields whenever they are present
+valid_optional_test_enums(Props) :-
+    ( memberchk(verification_scope=Scope, Props) -> valid_verification_scope(Scope) ; true ),
+    ( memberchk(verification_perspective=Perspective, Props) -> valid_verification_perspective(Perspective) ; true ).
+
 % valid_polarity(+P)
-valid_polarity(require).
-valid_polarity(forbid).
+valid_polarity(Polarity) :- memberchk(Polarity, [require, forbid, assert, deny]), !.
+
+valid_strict_polarity(Polarity) :- memberchk(Polarity, [require, forbid]), !.
+
+valid_predicate_polarity(Polarity) :- memberchk(Polarity, [assert, deny]), !.
+
+% valid_verification_scope(+Scope)
+valid_verification_scope(Scope) :- memberchk(Scope, [unit, integration, end_to_end]), !.
+
+% valid_verification_perspective(+Perspective)
+valid_verification_perspective(Perspective) :- memberchk(Perspective, [internal, consumer]), !.
 
 % exactly_one_value_field(+Props)
 exactly_one_value_field(Props) :-

package/src/public/diagnostic-usage.ts

@@ -2,6 +2,11 @@ import { createHash, randomUUID } from "node:crypto";
 import { appendFileSync, mkdirSync } from "node:fs";
 import path from "node:path";
 
+import {
+  appendPayloadCountField,
+  normalizeResultPayload,
+} from "./operations/result-envelope.js";
+
 export interface DiagnosticUsageInput {
   readonly workspaceRoot: string;
   readonly tool: string;
@@ -20,16 +25,6 @@ function isRecord(value: unknown): value is Record<string, unknown> {
   return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
 
-function resultRecord(result: unknown): Record<string, unknown> | undefined {
-  if (!isRecord(result)) return undefined;
-  if (isRecord(result.structuredContent)) return result.structuredContent;
-  // CLI JSON operations return the same versioned KibiResult envelope as MCP
-  // structuredContent.  Unwrap its data before deriving operation-specific
-  // telemetry fields (coverage/proof fields in particular).
-  if (result.kibiProtocol === 1 && isRecord(result.data)) return result.data;
-  return result;
-}
-
 function stringArray(value: unknown): string[] {
   return Array.isArray(value)
     ? value.filter((item): item is string => typeof item === "string")
@@ -188,11 +183,7 @@ export function deriveDiagnosticUsageFields(
     }
   }
 
-  const structured = resultRecord(result);
-  const envelope =
-    isRecord(structured) && structured.kibiProtocol === 1
-      ? structured
-      : undefined;
+  const { envelope, data: structured } = normalizeResultPayload(result);
   if (envelope) {
     fields.protocol_version = envelope.kibiProtocol;
     fields.result_version =
@@ -214,18 +205,19 @@ export function deriveDiagnosticUsageFields(
     fields.unsafe_original_retry = telemetry?.unsafe_original_retry === true;
   }
   if (tool === "kb_query" || tool === "kb_search") {
-    const resultCount = Number(structured?.count ?? 0);
-    fields.result_count = resultCount;
-    fields.zero_results = resultCount === 0;
-    fields.result_summary =
-      resultCount === 0 ? "0 results" : `${resultCount} results`;
+    appendPayloadCountField(fields, "result_count", "results", structured);
+    if (typeof fields.result_count === "number") {
+      fields.zero_results = fields.result_count === 0;
+    }
   }
   if (tool === "kb_check") {
-    const count = Number(structured?.count ?? 0);
-    fields.violation_count = count;
+    appendPayloadCountField(
+      fields,
+      "violation_count",
+      "violations",
+      structured,
+    );
     fields.requested_rules = Array.isArray(args.rules) ? args.rules : [];
-    fields.result_summary =
-      count === 0 ? "0 violations" : `${count} violations`;
   }
   if (tool === "kb_coverage" && structured) {
     appendCoverageFields(fields, args, structured);

package/src/public/impact/analyzer.ts

@@ -1,4 +1,14 @@
 import * as path from "node:path";
+import {
+  createMaintenanceSourceAnalysisService,
+  readSnapshotSourceConfig,
+} from "../../plugins/maintenance-source-analysis.js";
+import {
+  analyzeSourceChanges,
+  assertSourceAnalysisGate,
+} from "../../plugins/source-change-analysis.js";
+import { captureStagedSnapshot } from "../../traceability/git-change-snapshot.js";
+import { readSnapshotKnowledge } from "../../traceability/snapshot-knowledge.js";
 import type { ExtractedSymbol } from "../../traceability/symbol-extract.js";
 import { extractSymbolsFromStagedFileAsync } from "../../traceability/symbol-extract.js";
 import {
@@ -9,6 +19,7 @@ import {
   createImpactManifestLookup,
   readImpactManifestResults,
 } from "./manifest.js";
+import { normalizeSourceFile } from "./source-changes.js";
 import { collectSourceChanges, uniqueSorted } from "./source-changes.js";
 import {
   buildNextActions,
@@ -25,16 +36,73 @@ export async function analyzeChangedFileImpact(
   options: ChangedFileImpactOptions,
 ): Promise<ChangedFileImpactResult> {
   const workspaceRoot = path.resolve(options.workspaceRoot);
-  const sourceChanges = collectSourceChanges({ ...options, workspaceRoot });
-  const sourceFiles = uniqueSorted(sourceChanges.map((change) => change.file));
-  const manifestResults = readImpactManifestResults(workspaceRoot);
+  const snapshot = options.staged
+    ? captureStagedSnapshot(workspaceRoot)
+    : undefined;
+  const filter = new Set(
+    (options.sourceFiles ?? []).map((file) =>
+      normalizeSourceFile(workspaceRoot, file),
+    ),
+  );
+  const snapshotAnalysisInventory = snapshot
+    ? snapshot.inventory.filter(
+        (file) => filter.size === 0 || filter.has(file.path),
+      )
+    : undefined;
+  const snapshotSourceInventory = snapshot
+    ? snapshot.inventory.filter(
+        (file) =>
+          file.analysisDepth !== "metadata" &&
+          !file.skipReason &&
+          file.content !== undefined &&
+          (filter.size === 0 || filter.has(file.path)),
+      )
+    : undefined;
+  const sourceChanges = snapshot
+    ? (snapshotSourceInventory ?? []).map((file) => ({
+        file: file.path,
+        status: file.status,
+        hunkRanges: file.hunkRanges,
+        content: file.content ?? "",
+      }))
+    : collectSourceChanges({ ...options, workspaceRoot });
+  const service = createMaintenanceSourceAnalysisService(
+    workspaceRoot,
+    snapshot ? readSnapshotSourceConfig(snapshot) : undefined,
+  );
+  const analyses = snapshot
+    ? await analyzeSourceChanges(snapshotAnalysisInventory ?? [], service)
+    : undefined;
+  if (analyses)
+    assertSourceAnalysisGate(snapshotAnalysisInventory ?? [], analyses);
+  const sourceFiles = uniqueSorted(
+    snapshot
+      ? snapshot.inventory
+          .filter(
+            (file) =>
+              file.analysisDepth !== "metadata" &&
+              (filter.size === 0 || filter.has(file.path)),
+          )
+          .map((file) => file.path)
+      : sourceChanges.map((change) => change.file),
+  );
+  const manifestResults = snapshot
+    ? readSnapshotKnowledge(
+        snapshot.readGit,
+        snapshot.headTree,
+        snapshot.readBlobs,
+      ).filter((result) => result.entity.type === "symbol")
+    : readImpactManifestResults(workspaceRoot);
   const manifestLookup = createImpactManifestLookup(manifestResults);
   const symbolsByFile = new Map<string, ExtractedSymbol[]>();
   const sourceContentByFile = new Map<string, string>();
+  const sourceSymbolsByFile = new Map<string, ExtractedSymbol[]>();
 
   for (const change of sourceChanges) {
     sourceContentByFile.set(change.file, change.content);
-    // Maintenance path: builtin-only (do not pass registry / workspaceRoot).
+    const analysis =
+      analyses?.get(change.file)?.after ??
+      (await service.analyzeTextV2(change.file, change.content));
     const extracted = await extractSymbolsFromStagedFileAsync(
       {
         path: change.file,
@@ -43,8 +111,21 @@ export async function analyzeChangedFileImpact(
         content: change.content,
       },
       manifestLookup,
-      {},
+      { analyzeText: async () => analysis },
+    );
+    const allSymbols = await extractSymbolsFromStagedFileAsync(
+      {
+        path: change.file,
+        status: change.status,
+        content: change.content,
+        hunkRanges: [
+          { start: 1, end: Math.max(1, change.content.split("\n").length) },
+        ],
+      },
+      manifestLookup,
+      { analyzeText: async () => analysis },
     );
+    sourceSymbolsByFile.set(change.file, allSymbols);
     symbolsByFile.set(
       change.file,
       extracted.filter((symbol) => symbol.hunkRanges.length > 0),
@@ -65,6 +146,7 @@ export async function analyzeChangedFileImpact(
             manifestResults: activeManifestResults,
             symbolsByFile,
             sourceContentByFile,
+            sourceSymbolsByFile,
             workspaceRoot,
           }),
           ...createSymbolQualityDiagnostics({
@@ -79,6 +161,7 @@ export async function analyzeChangedFileImpact(
       ? impactDiagnostics.slice(0, maxDiagnostics)
       : impactDiagnostics;
 
+  snapshot?.assertUnchanged();
   return {
     impactDiagnostics: cappedDiagnostics,
     sourceFiles,

package/src/public/impact/diagnostics.ts

@@ -74,11 +74,13 @@ function getGranularSymbolsForSourceFile(
   readonly candidateSymbols: readonly ExtractedSymbol[];
   readonly sourceSymbols: readonly ExtractedSymbol[];
 } {
-  const sourceSymbols = readSourceSymbols(
-    sourceFile,
-    options.sourceContentByFile,
-    options.workspaceRoot ?? process.cwd(),
-  );
+  const sourceSymbols = options.sourceSymbolsByFile
+    ? (options.sourceSymbolsByFile.get(sourceFile) ?? [])
+    : readSourceSymbols(
+        sourceFile,
+        options.sourceContentByFile,
+        options.workspaceRoot ?? process.cwd(),
+      );
   const changedSymbols = options.symbolsByFile.get(sourceFile);
 
   return {

package/src/public/impact/full-kb-quality.ts

@@ -568,22 +568,10 @@ export async function loadKbExtractionResults(
       prolog.queryEntities.bind(prolog),
     );
   } else {
-    const entityResult = await prolog.query(
-      "findall([Id,Type,Props], kb_entity(Id, Type, Props), Results)",
-    );
-    if (entityResult.success) {
-      entities = entityResult.bindings.Results
-        ? parseListOfLists(entityResult.bindings.Results).map(
-            parseEntityFromList,
-          )
-        : [];
-    } else if (isOutputCapacityError(entityResult.error)) {
-      entities = await loadBoundedEntityProjection(prolog);
-    } else {
-      throw new Error(
-        `Full KB entity projection query failed: ${entityResult.error ?? "Unknown error"}`,
-      );
-    }
+    // Never probe with an unbounded all-entities findall: receipt histories
+    // make that answer grow without limit, and an overflow terminates the
+    // interactive Prolog process that serves every later query.
+    entities = await loadBoundedEntityProjection(prolog);
   }
   const relationships = new Map<string, ExtractionResult["relationships"]>();
 

package/src/public/impact/manifest.ts

@@ -2,6 +2,7 @@ import { existsSync } from "node:fs";
 import * as path from "node:path";
 import { extractFromManifest } from "../../extractors/manifest.js";
 import type { ExtractionResult } from "../../extractors/markdown.js";
+import { createManifestLookupSentinelKey } from "../../traceability/symbol-extract.js";
 import type { ManifestLookup } from "../../traceability/symbol-extract.js";
 import { CANONICAL_ENTITY_PATHS } from "../../utils/kb-paths.js";
 import { isTraceabilityRelationshipType } from "../symbol-granularity.js";
@@ -42,10 +43,22 @@ export function createImpactManifestLookup(
   manifestResults: readonly ExtractionResult[],
 ): ManifestLookup {
   const manifestLookup: ManifestLookup = new Map();
+  manifestLookup.set(createManifestLookupSentinelKey(".kb/symbols.yaml"), {
+    id: "__captured_manifest__",
+    relationships: [],
+  });
+  const ambiguous = new Set<string>();
 
   for (const result of manifestResults) {
     const sourceFile = result.sourceFile ?? result.entity.source;
-    manifestLookup.set(`${sourceFile}:${result.entity.title}`, {
+    const key = `${sourceFile}:${result.entity.title}`;
+    if (ambiguous.has(key)) continue;
+    if (manifestLookup.has(key)) {
+      manifestLookup.delete(key);
+      ambiguous.add(key);
+      continue;
+    }
+    manifestLookup.set(key, {
       id: result.entity.id,
       relationships: toTraceabilityRelationships(result.relationships),
     });

package/src/public/impact/source-changes.ts

@@ -1,6 +1,7 @@
-import { execSync } from "node:child_process";
-import { existsSync, readFileSync } from "node:fs";
+import { execFileSync, execSync } from "node:child_process";
+import { existsSync, lstatSync, readFileSync, realpathSync } from "node:fs";
 import * as path from "node:path";
+import { isQualifiedSourcePath } from "../../plugins/source-classification.js";
 import type { HunkRange } from "../../traceability/git-staged.js";
 import {
   getStagedFiles,
@@ -9,19 +10,8 @@ import {
 import { hasMeaningfulSourceDiff } from "./diff-meaning.js";
 import type { ChangedFileImpactOptions, SourceChange } from "./types.js";
 
-const SOURCE_EXTENSIONS = new Set([
-  ".ts",
-  ".tsx",
-  ".js",
-  ".jsx",
-  ".mts",
-  ".cts",
-  ".mjs",
-  ".cjs",
-]);
-
 function isSupportedSourcePath(filePath: string): boolean {
-  return SOURCE_EXTENSIONS.has(path.extname(filePath));
+  return isQualifiedSourcePath(filePath);
 }
 
 export function normalizeSourceFile(
@@ -38,12 +28,12 @@ export function uniqueSorted(values: Iterable<string>): string[] {
   return [...new Set(values)].sort();
 }
 
-function escapeGitPath(filePath: string): string {
-  return filePath.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
-}
-
-function runGit(workspaceRoot: string, command: string): string {
-  return execSync(command, { cwd: workspaceRoot, encoding: "utf8" });
+function runGit(workspaceRoot: string, args: readonly string[]): string {
+  return execFileSync("git", [...args], {
+    cwd: workspaceRoot,
+    encoding: "utf8",
+    env: { ...process.env, GIT_LITERAL_PATHSPECS: "1" },
+  });
 }
 
 function readWorkingTreeSource(
@@ -51,8 +41,24 @@ function readWorkingTreeSource(
   sourceFile: string,
 ): string | null {
   const absolutePath = path.resolve(workspaceRoot, sourceFile);
-  if (!existsSync(absolutePath)) return null;
-  return readFileSync(absolutePath, "utf8");
+  const relative = path.relative(workspaceRoot, absolutePath);
+  if (!relative || relative.startsWith("..") || path.isAbsolute(relative))
+    throw new Error("Source path must remain inside the workspace");
+  if (!existsSync(absolutePath) || !lstatSync(absolutePath).isFile())
+    return null;
+  const actualRelative = path.relative(
+    realpathSync(workspaceRoot),
+    realpathSync(absolutePath),
+  );
+  if (actualRelative.startsWith("..") || path.isAbsolute(actualRelative))
+    throw new Error("Source path escapes the workspace");
+  const bytes = readFileSync(absolutePath);
+  if (bytes.includes(0)) return null;
+  try {
+    return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+  } catch {
+    return null;
+  }
 }
 
 function fullFileHunk(content: string): HunkRange[] {
@@ -62,9 +68,9 @@ function fullFileHunk(content: string): HunkRange[] {
 function getWorkingTreeDiffSourceFiles(workspaceRoot: string): string[] {
   try {
     return uniqueSorted(
-      runGit(workspaceRoot, "git diff --name-only --diff-filter=ACMR")
-        .split(/\r?\n/)
-        .map((filePath) => normalizeSourceFile(workspaceRoot, filePath.trim()))
+      runGit(workspaceRoot, ["diff", "--name-only", "-z", "--diff-filter=ACMR"])
+        .split("\0")
+        .map((filePath) => normalizeSourceFile(workspaceRoot, filePath))
         .filter((filePath) => filePath.length > 0)
         .filter(isSupportedSourcePath),
     );
@@ -78,10 +84,7 @@ function getWorkingTreeHunks(
   sourceFile: string,
 ): HunkRange[] {
   try {
-    const diffText = runGit(
-      workspaceRoot,
-      `git diff -U0 -- "${escapeGitPath(sourceFile)}"`,
-    );
+    const diffText = runGit(workspaceRoot, ["diff", "-U0", "--", sourceFile]);
     return parseHunksFromDiff(diffText);
   } catch {
     return [];
@@ -104,6 +107,7 @@ function getStagedSourceChanges(
     .flatMap((file): SourceChange[] => {
       if (file.content === undefined || file.hunkRanges.length === 0) return [];
       if (
+        !/\.(pyi?|go|rs)$/.test(file.path) &&
         file.diffText !== undefined &&
         !hasMeaningfulSourceDiff(file.diffText)
       ) {
@@ -132,11 +136,12 @@ function getWorkingTreeSourceChanges(
   return sourceFiles.flatMap((sourceFile): SourceChange[] => {
     const content = readWorkingTreeSource(workspaceRoot, sourceFile);
     if (content === null) return [];
-    const diffText = runGit(
-      workspaceRoot,
-      `git diff -U0 -- "${escapeGitPath(sourceFile)}"`,
-    );
-    if (!hasMeaningfulSourceDiff(diffText)) return [];
+    const diffText = runGit(workspaceRoot, ["diff", "-U0", "--", sourceFile]);
+    if (
+      !/\.(pyi?|go|rs)$/.test(sourceFile) &&
+      !hasMeaningfulSourceDiff(diffText)
+    )
+      return [];
     const hunkRanges = getWorkingTreeHunks(workspaceRoot, sourceFile);
     if (hunkRanges.length === 0) return [];
     return [{ file: sourceFile, status: "M", hunkRanges, content }];

package/src/public/impact/types.ts

@@ -39,6 +39,11 @@ export type SymbolGranularityDiagnosticsOptions = {
   readonly activeEntityIds?: ReadonlySet<string>;
   readonly symbolsByFile: SymbolsByFile;
   readonly sourceContentByFile?: ReadonlyMap<string, string>;
+  /** Complete snapshot analysis; when supplied, filesystem fallback is forbidden. */
+  readonly sourceSymbolsByFile?: ReadonlyMap<
+    string,
+    readonly ExtractedSymbol[]
+  >;
   readonly workspaceRoot?: string;
 };
 

package/src/public/operations/catalog.ts

@@ -6,6 +6,7 @@ import {
 import { planBootstrapSpec } from "./specs/bootstrap.js";
 import { checkSpec } from "./specs/check.js";
 import { querySpec, searchSpec, statusSpec } from "./specs/discovery.js";
+import { prepareImpactReviewSpec } from "./specs/impact-review-preparation.js";
 import {
   modelRequirementSpec,
   suggestPredicatesSpec,
@@ -49,6 +50,7 @@ export const OPERATION_CATALOG = [
   upsertSpec,
   deleteSpec,
   checkSpec,
+  prepareImpactReviewSpec,
   sparqlRemoteSpec,
   compileIntentSpec,
   applyPlanSpec,