kibi-cli 1.0.1 → 2.1.0

package/dist/traceability/staged-file-coverage.js

@@ -0,0 +1,284 @@
+import { execFileSync } from "node:child_process";
+import { load as parseYaml } from "js-yaml";
+import { extractFromManifestString } from "../extractors/manifest.js";
+import { extractFromMarkdownString } from "../extractors/markdown.js";
+import { CANONICAL_ENTITY_PATHS, isEntityLanePath } from "../utils/kb-paths.js";
+export const STAGED_FILE_COVERAGE_RESULT_VERSION = "kibi.staged-file-coverage.v1";
+function defaultGitReader(args) {
+    return execFileSync("git", args, {
+        encoding: "buffer",
+        maxBuffer: 64 * 1024 * 1024,
+        stdio: ["ignore", "pipe", "ignore"],
+    });
+}
+function readRequired(reader, args) {
+    try {
+        return reader(args).toString("utf8");
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`git command failed: git ${args.join(" ")} -> ${message}`);
+    }
+}
+function manifestEntries(content) {
+    if (!content?.trim())
+        return [];
+    try {
+        return extractFromManifestString(content, CANONICAL_ENTITY_PATHS.symbols);
+    }
+    catch {
+        return [];
+    }
+}
+function parseRelationships(content) {
+    if (!content?.trim())
+        return [];
+    try {
+        const parsed = parseYaml(content);
+        if (!Array.isArray(parsed?.relationships))
+            return [];
+        return parsed.relationships.flatMap((value) => {
+            if (!value || typeof value !== "object")
+                return [];
+            const row = value;
+            return typeof row.type === "string" &&
+                typeof row.from === "string" &&
+                typeof row.to === "string"
+                ? [{ type: row.type, from: row.from, to: row.to }]
+                : [];
+        });
+    }
+    catch {
+        return [];
+    }
+}
+function headKbPaths(reader) {
+    try {
+        if (reader(["rev-parse", "--verify", "HEAD"]).toString("utf8").trim() === "") {
+            return new Set();
+        }
+    }
+    catch {
+        // A repository with an unborn branch has no committed knowledge yet.
+        return new Set();
+    }
+    const output = readRequired(reader, [
+        "ls-tree",
+        "-r",
+        "--name-only",
+        "-z",
+        "HEAD",
+        "--",
+        ".kb",
+    ]);
+    return new Set(output.split("\0").filter(Boolean));
+}
+function effectiveRelationshipFiles(inventory, headPaths, reader) {
+    const head = new Map();
+    for (const path of [...headPaths].sort()) {
+        if (!path.startsWith(".kb/relationships/"))
+            continue;
+        head.set(path, readRequired(reader, ["show", `HEAD:${path}`]));
+    }
+    const effective = new Map(head);
+    for (const entry of inventory) {
+        if (!entry.path.startsWith(".kb/relationships/"))
+            continue;
+        if (entry.oldPath)
+            effective.delete(entry.oldPath);
+        if (entry.status === "D")
+            effective.delete(entry.path);
+        else if (entry.content !== undefined)
+            effective.set(entry.path, entry.content);
+    }
+    return { head, effective };
+}
+function effectiveRequirementIds(inventory, headPaths, reader) {
+    const files = new Map();
+    for (const path of [...headPaths].sort()) {
+        if (!path.startsWith(".kb/requirements/") || !path.endsWith(".md")) {
+            continue;
+        }
+        files.set(path, readRequired(reader, ["show", `HEAD:${path}`]));
+    }
+    for (const entry of inventory) {
+        if (entry.oldPath)
+            files.delete(entry.oldPath);
+        if (!entry.path.startsWith(".kb/requirements/") ||
+            !entry.path.endsWith(".md")) {
+            continue;
+        }
+        if (entry.status === "D")
+            files.delete(entry.path);
+        else if (entry.content !== undefined)
+            files.set(entry.path, entry.content);
+    }
+    const ids = new Set();
+    for (const [path, content] of files) {
+        try {
+            const result = extractFromMarkdownString(content, path);
+            if (result.entity.type === "req")
+                ids.add(result.entity.id);
+        }
+        catch {
+            // Malformed staged entity markdown is reported by the staged validator.
+        }
+    }
+    return ids;
+}
+function relationshipSet(files) {
+    return [...files.values()].flatMap(parseRelationships);
+}
+function stagedManifestContent(inventory) {
+    const file = inventory.find((entry) => entry.path === CANONICAL_ENTITY_PATHS.symbols ||
+        entry.path === ".kb/symbols.yml");
+    if (!file)
+        return undefined;
+    return file.status === "D" ? null : (file.content ?? null);
+}
+function sourcePaths(entry) {
+    return new Set([entry.path, ...(entry.oldPath ? [entry.oldPath] : [])]);
+}
+function entriesForPaths(entries, paths) {
+    return entries.filter((entry) => {
+        const source = entry.sourceFile ?? entry.entity.source;
+        return (typeof source === "string" && paths.has(source.replaceAll("\\", "/")));
+    });
+}
+function relevantEntityEvidence(inventory, requirementIds) {
+    return inventory.flatMap((entry) => {
+        if (entry.status === "D" ||
+            entry.content === undefined ||
+            !entry.path.endsWith(".md") ||
+            !isEntityLanePath(entry.path)) {
+            return [];
+        }
+        try {
+            const parsed = extractFromMarkdownString(entry.content, entry.path);
+            return parsed.entity.type === "req" &&
+                requirementIds.has(parsed.entity.id)
+                ? [entry.path]
+                : [];
+        }
+        catch {
+            return [];
+        }
+    });
+}
+function stableEntry(entry) {
+    return JSON.stringify({
+        id: entry.entity.id,
+        title: entry.entity.title,
+        sourceFile: entry.sourceFile,
+        relationships: entry.relationships
+            .map((relationship) => ({
+            type: relationship.type,
+            from: relationship.from,
+            to: relationship.to,
+        }))
+            .sort((a, b) => JSON.stringify(a).localeCompare(JSON.stringify(b))),
+    });
+}
+function changedManifestEvidence(paths, headEntries, effectiveEntries, inventory) {
+    const staged = stagedManifestContent(inventory);
+    if (staged === undefined)
+        return [];
+    const before = entriesForPaths(headEntries, paths).map(stableEntry).sort();
+    const after = entriesForPaths(effectiveEntries, paths)
+        .map(stableEntry)
+        .sort();
+    return JSON.stringify(before) === JSON.stringify(after)
+        ? []
+        : [CANONICAL_ENTITY_PATHS.symbols];
+}
+function changedRelationshipEvidence(symbolIds, headFiles, effectiveFiles) {
+    const paths = new Set([...headFiles.keys(), ...effectiveFiles.keys()]);
+    return [...paths].filter((path) => {
+        const select = (content) => parseRelationships(content ?? null)
+            .filter((row) => row.type === "implements" && symbolIds.has(row.from))
+            .map((row) => `${row.from}\0${row.to}`)
+            .sort();
+        return (JSON.stringify(select(headFiles.get(path))) !==
+            JSON.stringify(select(effectiveFiles.get(path))));
+    });
+}
+/** Resolve advisory file-level ownership from committed knowledge plus staged evidence. */
+export function analyzeStagedFileCoverage(inventory, reader = defaultGitReader) {
+    const headPaths = headKbPaths(reader);
+    const headManifest = headPaths.has(CANONICAL_ENTITY_PATHS.symbols)
+        ? readRequired(reader, ["show", `HEAD:${CANONICAL_ENTITY_PATHS.symbols}`])
+        : null;
+    const stagedManifest = stagedManifestContent(inventory);
+    const headEntries = manifestEntries(headManifest);
+    const effectiveEntries = manifestEntries(stagedManifest === undefined ? headManifest : stagedManifest);
+    const relationshipFiles = effectiveRelationshipFiles(inventory, headPaths, reader);
+    const actualRequirementIds = effectiveRequirementIds(inventory, headPaths, reader);
+    const headRelationships = relationshipSet(relationshipFiles.head);
+    const effectiveRelationships = relationshipSet(relationshipFiles.effective);
+    const files = [];
+    const diagnostics = [];
+    for (const entry of inventory) {
+        const paths = sourcePaths(entry);
+        const headOwned = entriesForPaths(headEntries, paths);
+        const effectiveOwned = entriesForPaths(effectiveEntries, paths);
+        const owned = [...headOwned, ...effectiveOwned];
+        const symbolIds = new Set(owned.map((item) => item.entity.id));
+        const inlineRelationships = owned.flatMap((item) => item.relationships);
+        const requirementIds = [
+            ...new Set([
+                ...inlineRelationships,
+                ...headRelationships,
+                ...effectiveRelationships,
+            ]
+                .filter((row) => row.type === "implements" &&
+                symbolIds.has(row.from) &&
+                actualRequirementIds.has(row.to))
+                .map((row) => row.to)),
+        ].sort();
+        const evidencePaths = [
+            ...new Set([
+                ...changedManifestEvidence(paths, headEntries, effectiveEntries, inventory),
+                ...changedRelationshipEvidence(symbolIds, relationshipFiles.head, relationshipFiles.effective),
+                ...relevantEntityEvidence(inventory, new Set(requirementIds)),
+            ]),
+        ].sort();
+        files.push({
+            path: entry.path,
+            ...(entry.oldPath ? { oldPath: entry.oldPath } : {}),
+            status: entry.status,
+            analysisDepth: entry.analysisDepth,
+            disposition: entry.disposition,
+            ...(entry.skipReason ? { reason: entry.skipReason } : {}),
+            requirementIds,
+            evidencePaths,
+            providerId: entry.analysisDepth === "symbol" ? "ts-morph" : null,
+        });
+        if (entry.analysisDepth !== "file")
+            continue;
+        if (requirementIds.length === 0) {
+            diagnostics.push({
+                id: "staged_file_ownership_missing",
+                severity: "warning",
+                blocking: false,
+                path: entry.path,
+                message: `Staged text file has no source-linked requirement ownership: ${entry.path}`,
+                suggestion: "Review the change and add an authored file/module symbol with an implements relationship when it affects product behavior.",
+                requirementIds: [],
+                evidencePaths: [],
+            });
+        }
+        else if (evidencePaths.length === 0) {
+            diagnostics.push({
+                id: "staged_file_impact_review_needed",
+                severity: "warning",
+                blocking: false,
+                path: entry.path,
+                message: `Review staged impact for ${entry.path}; existing ownership links to ${requirementIds.join(", ")} but no matching KB evidence changed.`,
+                suggestion: "Confirm the linked requirements still describe the behavior, then stage the relevant requirement or ownership evidence when semantics changed.",
+                requirementIds,
+                evidencePaths: [],
+            });
+        }
+    }
+    return { version: STAGED_FILE_COVERAGE_RESULT_VERSION, files, diagnostics };
+}

package/dist/traceability/staged-impact-contract.js

@@ -41,7 +41,7 @@ export const KIBI_IMPACT_DIAGNOSTICS = {
         title: "Behavior edit requires staged Kibi impact evidence",
         resolution: [
             "Query Kibi via visible MCP tools or the trusted project-local CLI (peer surfaces): use kb_search for discovery, then kb_query for exact follow-up.",
-            "MCP writes update KB state but do not stage tracked evidence; also stage related KB entity markdown under .kb/, authored .kb/symbols.yaml metadata, or refreshed .kb/symbol-coordinates.yaml.",
+            "MCP writes update KB state but do not stage tracked evidence; also stage related KB entity markdown under .kb/, authored .kb/symbols.yaml metadata (the Detail lines name the symbols lacking evidence), or refreshed .kb/symbol-coordinates.yaml.",
             "Re-run or let the hook run kibi check --staged.",
         ],
     },
@@ -49,9 +49,9 @@ export const KIBI_IMPACT_DIAGNOSTICS = {
         id: "symbols_manifest_stale",
         title: "Symbol coordinates evidence is stale for changed extraction output",
         resolution: [
-            "Refresh symbol coordinates for the changed source file with kibi sync --refresh-symbol-coordinates.",
-            "Stage .kb/symbol-coordinates.yaml in the same change as the behavior edit, and stage .kb/symbols.yaml only if migration cleanup changed it.",
-            "Re-run or let the hook run kibi check --staged.",
+            "Read the Detail lines: they name the extracted symbols the staged .kb/symbols.yaml evidence does not cover.",
+            "Author .kb/symbols.yaml entries for the uncovered symbols (kibi upsert, with implements/covered_by links), then refresh symbol coordinates with kibi sync --refresh-symbol-coordinates.",
+            "Stage .kb/symbol-coordinates.yaml and .kb/symbols.yaml in the same change as the behavior edit, then re-run or let the hook run kibi check --staged.",
         ],
     },
     kibi_impact_override_missing_rationale: {

package/dist/traceability/staged-symbols-manifest.d.ts

@@ -1,8 +1,16 @@
+import { type ParsedCoordinateArtifact } from "../extractors/symbol-coordinates.js";
+import type { KibiImpactSymbolsManifestFileDetail } from "./evidence-model.js";
 import type { StagedFile } from "./git-staged.js";
 export interface StagedSymbolsManifestAssessment {
     state: "fresh" | "stale" | "missing" | "not_required";
     sourcePaths: string[];
     path: string;
+    /**
+     * Per-file extraction-vs-evidence diffs for the source paths whose symbol
+     * output changed. Lets diagnostics name the uncovered symbols instead of
+     * reporting a bare "stale" verdict.
+     */
+    fileDetails?: KibiImpactSymbolsManifestFileDetail[];
 }
 export interface StagedAuthoredSymbolsManifestEvidence {
     path: string;
@@ -12,6 +20,11 @@ export interface StagedAuthoredSymbolsManifestEvidence {
     }>;
     changedEntityIds: string[];
 }
+export declare function parsedCoordinateOrNull(parse: () => ParsedCoordinateArtifact): ParsedCoordinateArtifact | null;
+export declare function manifestRecordSourcePath(record: {
+    sourceFile?: unknown;
+    source?: unknown;
+}): string | null;
 export declare function assessStagedSymbolsManifest(options: {
     symbolsManifestPath: string;
     sourceFiles: StagedFile[];

package/dist/traceability/staged-symbols-manifest.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"staged-symbols-manifest.d.ts","sourceRoot":"","sources":["../../src/traceability/staged-symbols-manifest.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AA0ClD,MAAM,WAAW,+BAA+B;IAC9C,KAAK,EAAE,OAAO,GAAG,OAAO,GAAG,SAAS,GAAG,cAAc,CAAC;IACtD,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,qCAAqC;IACpD,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,KAAK,CAAC;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC,CAAC;IAC5D,gBAAgB,EAAE,MAAM,EAAE,CAAC;CAC5B;AAuTD,wBAAgB,2BAA2B,CAAC,OAAO,EAAE;IACnD,mBAAmB,EAAE,MAAM,CAAC;IAC5B,WAAW,EAAE,UAAU,EAAE,CAAC;IAC1B,WAAW,EAAE,UAAU,EAAE,CAAC;CAC3B,GAAG,+BAA+B,CAgGlC;AAED,wBAAgB,4CAA4C,CAAC,OAAO,EAAE;IACpE,WAAW,EAAE,UAAU,EAAE,CAAC;IAC1B,WAAW,EAAE,UAAU,EAAE,CAAC;CAC3B,GAAG,qCAAqC,CAmExC"}
+{"version":3,"file":"staged-symbols-manifest.d.ts","sourceRoot":"","sources":["../../src/traceability/staged-symbols-manifest.ts"],"names":[],"mappings":"AAMA,OAAO,EACL,KAAK,wBAAwB,EAG9B,MAAM,qCAAqC,CAAC;AAI7C,OAAO,KAAK,EAAE,mCAAmC,EAAE,MAAM,qBAAqB,CAAC;AAC/E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AA0ClD,MAAM,WAAW,+BAA+B;IAC9C,KAAK,EAAE,OAAO,GAAG,OAAO,GAAG,SAAS,GAAG,cAAc,CAAC;IACtD,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,WAAW,CAAC,EAAE,mCAAmC,EAAE,CAAC;CACrD;AAED,MAAM,WAAW,qCAAqC;IACpD,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,KAAK,CAAC;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC,CAAC;IAC5D,gBAAgB,EAAE,MAAM,EAAE,CAAC;CAC5B;AA6ED,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,MAAM,wBAAwB,GACpC,wBAAwB,GAAG,IAAI,CAOjC;AAED,wBAAgB,wBAAwB,CAAC,MAAM,EAAE;IAC/C,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB,GAAG,MAAM,GAAG,IAAI,CAMhB;AAqSD,wBAAgB,2BAA2B,CAAC,OAAO,EAAE;IACnD,mBAAmB,EAAE,MAAM,CAAC;IAC5B,WAAW,EAAE,UAAU,EAAE,CAAC;IAC1B,WAAW,EAAE,UAAU,EAAE,CAAC;CAC3B,GAAG,+BAA+B,CAgLlC;AAED,wBAAgB,4CAA4C,CAAC,OAAO,EAAE;IACpE,WAAW,EAAE,UAAU,EAAE,CAAC;IAC1B,WAAW,EAAE,UAAU,EAAE,CAAC;CAC3B,GAAG,qCAAqC,CAmExC"}

package/dist/traceability/staged-symbols-manifest.js

@@ -1,4 +1,4 @@
-import { execSync } from "node:child_process";
+import { execFileSync } from "node:child_process";
 import * as path from "node:path";
 import { extractManifestSymbolRecordsString, } from "../extractors/manifest.js";
 import { mergeCoordinatesWithManifest, parseCoordinateArtifact as parseStrict, } from "../extractors/symbol-coordinates.js";
@@ -38,14 +38,27 @@ function resolveRelativeManifestPaths(symbolsManifestPath) {
         coordinatesPath: toRepoRelativePath(coordinatesPath),
     };
 }
-function readHeadFileContent(filePath) {
+function readHeadFileContent(filePath, cache) {
+    const normalizedPath = filePath.replace(/\\/g, "/");
+    const cacheKey = `${process.cwd()}\u0000${normalizedPath}`;
+    if (cache?.has(cacheKey)) {
+        return cache.get(cacheKey) ?? null;
+    }
     try {
-        return execSync(`git show HEAD:${filePath}`, {
+        // Use argv-based git invocation so a source path cannot alter the command.
+        // The manifest can exceed a shell helper's small default maxBuffer; without
+        // the raised limit the read fails with ENOBUFS and is silently treated as
+        // missing, which permanently reports the coordinates manifest as stale.
+        const content = execFileSync("git", ["show", `HEAD:${normalizedPath}`], {
             encoding: "utf8",
             stdio: ["pipe", "pipe", "pipe"],
+            maxBuffer: 64 * 1024 * 1024,
         });
+        cache?.set(cacheKey, content);
+        return content;
     }
     catch {
+        cache?.set(cacheKey, null);
         return null;
     }
 }
@@ -60,6 +73,22 @@ function parseManifestRecords(content, filePath) {
         return null;
     }
 }
+export function parsedCoordinateOrNull(parse) {
+    try {
+        const parsed = parse();
+        return parsed.status === "invalid" ? null : parsed;
+    }
+    catch {
+        return null;
+    }
+}
+export function manifestRecordSourcePath(record) {
+    return typeof record.sourceFile === "string"
+        ? record.sourceFile
+        : typeof record.source === "string"
+            ? record.source
+            : null;
+}
 function parseCoordinateArtifact(content) {
     // An absent artifact must not masquerade as an empty authoritative one:
     // inline authored coordinates stay comparable until the artifact exists.
@@ -68,13 +97,7 @@ function parseCoordinateArtifact(content) {
     if (content === null || content === undefined) {
         return null;
     }
-    try {
-        const parsed = parseStrict(content);
-        return parsed.status === "invalid" ? null : parsed;
-    }
-    catch {
-        return null;
-    }
+    return parsedCoordinateOrNull(() => parseStrict(content));
 }
 function normalizeNumber(value) {
     return typeof value === "number" ? value : null;
@@ -114,7 +137,7 @@ function normalizeRelationships(relationships) {
         .sort((left, right) => JSON.stringify(left).localeCompare(JSON.stringify(right)));
 }
 function normalizeManifestSymbolsForSourceFile(records, sourceFile) {
-    return records
+    const symbols = records
         .filter((record) => {
         if (isDocumentedCoarseRecord(record)) {
             return false;
@@ -135,6 +158,11 @@ function normalizeManifestSymbolsForSourceFile(records, sourceFile) {
         sourceEndColumn: normalizeNumber(record.sourceEndColumn),
     }))
         .sort(compareNormalizedSymbols);
+    // Several logical records may own the same declaration. Only identical
+    // validated spans collapse; a stale duplicate still carries null coordinates
+    // and must remain visible to the equality check.
+    return symbols.filter((symbol, index) => index === 0 ||
+        JSON.stringify(symbol) !== JSON.stringify(symbols[index - 1]));
 }
 function normalizeAuthoredManifestSymbolsForSourceFile(records, sourceFile) {
     return records
@@ -209,8 +237,8 @@ function signaturesEqual(left, right) {
 function uniqueSorted(paths) {
     return Array.from(new Set(paths)).sort();
 }
-function mergeManifestRecordsWithCoordinates(manifestRecords, coordinateArtifact) {
-    return mergeCoordinatesWithManifest(manifestRecords ?? [], coordinateArtifact);
+function mergeManifestRecordsWithCoordinates(manifestRecords, coordinateArtifact, options = {}) {
+    return mergeCoordinatesWithManifest(manifestRecords ?? [], coordinateArtifact, options);
 }
 function getEffectiveManifestRecords(options) {
     const { headCoordinateArtifact, headManifestRecords, paths, stagedFiles } = options;
@@ -229,28 +257,69 @@ function getEffectiveManifestRecords(options) {
         stagedCoordinateArtifact,
     };
 }
+/** Max missing/extra symbol titles surfaced per file before "+N more". */
+const MAX_DETAIL_ITEMS = 6;
+function diffSymbolEvidence(sourcePath, expectedSymbols, stagedSymbols) {
+    const stagedTitles = new Set(stagedSymbols.map((symbol) => symbol.title));
+    const expectedTitles = new Set(expectedSymbols.map((symbol) => symbol.title));
+    const missing = expectedSymbols
+        .filter((symbol) => !stagedTitles.has(symbol.title))
+        .map((symbol) => ({ title: symbol.title, line: symbol.sourceLine ?? 0 }))
+        .sort((left, right) => left.title.localeCompare(right.title));
+    const extra = stagedSymbols
+        .filter((symbol) => !expectedTitles.has(symbol.title))
+        .map((symbol) => symbol.title)
+        .sort();
+    // Pure coordinate drift (titles unchanged) has no symbol-level remedy to
+    // name; leave the detail out so the diagnostic stays verdict + refresh.
+    if (missing.length === 0 && extra.length === 0) {
+        return null;
+    }
+    return {
+        path: sourcePath,
+        expectedCount: expectedSymbols.length,
+        coveredCount: stagedSymbols.length,
+        missing: missing.slice(0, MAX_DETAIL_ITEMS),
+        extra: extra.slice(0, MAX_DETAIL_ITEMS),
+    };
+}
 export function assessStagedSymbolsManifest(options) {
     const { sourceFiles, stagedFiles, symbolsManifestPath } = options;
     const paths = resolveRelativeManifestPaths(symbolsManifestPath);
-    const headManifestRecords = parseManifestRecords(readHeadFileContent(paths.symbolsPath), paths.symbolsPath);
-    const headCoordinateArtifact = parseCoordinateArtifact(readHeadFileContent(paths.coordinatesPath));
+    // Scope HEAD memoization to one assessment. A long-lived CLI process may
+    // assess several commits in the same checkout; a process-global cache would
+    // otherwise reuse content from the previous HEAD.
+    const headFileContentCache = new Map();
+    const readAssessmentHeadFileContent = (filePath) => readHeadFileContent(filePath, headFileContentCache);
+    const headManifestRecords = parseManifestRecords(readAssessmentHeadFileContent(paths.symbolsPath), paths.symbolsPath);
+    const headCoordinateArtifact = parseCoordinateArtifact(readAssessmentHeadFileContent(paths.coordinatesPath));
     const { stagedCoordinatesFile, stagedCoordinateArtifact, stagedManifestRecords, } = getEffectiveManifestRecords({
         stagedFiles,
         paths,
         headManifestRecords,
         headCoordinateArtifact,
     });
-    const baselineMergedRecords = mergeManifestRecordsWithCoordinates(headManifestRecords, headCoordinateArtifact);
-    const stagedMergedRecords = mergeManifestRecordsWithCoordinates(stagedManifestRecords, stagedCoordinateArtifact);
+    const stagedSourceText = new Map(stagedFiles.map((stagedFile) => [
+        stagedFile.path.replace(/\\/g, "/"),
+        typeof stagedFile.content === "string" ? stagedFile.content : null,
+    ]));
+    const resolveStagedSourceText = (sourceFile) => {
+        const normalizedSourceFile = sourceFile.replace(/\\/g, "/");
+        return stagedSourceText.has(normalizedSourceFile)
+            ? (stagedSourceText.get(normalizedSourceFile) ?? null)
+            : readAssessmentHeadFileContent(sourceFile);
+    };
+    const baselineMergedRecords = mergeManifestRecordsWithCoordinates(headManifestRecords, headCoordinateArtifact, 
+    // Existing bindings must also be valid for the proposed source. Comparing
+    // them against HEAD would miss body edits that leave spans unchanged.
+    { resolveSourceText: resolveStagedSourceText });
+    const stagedMergedRecords = mergeManifestRecordsWithCoordinates(stagedManifestRecords, stagedCoordinateArtifact, { resolveSourceText: resolveStagedSourceText });
     const requiredRefreshPaths = [];
     const freshPaths = new Set();
+    const symbolDetails = [];
     for (const sourceFile of sourceFiles) {
         const manifestRecordsForFile = (stagedManifestRecords ?? []).filter((record) => {
-            const recordSource = typeof record.sourceFile === "string"
-                ? record.sourceFile
-                : typeof record.source === "string"
-                    ? record.source
-                    : null;
+            const recordSource = manifestRecordSourcePath(record);
             return recordSource === sourceFile.path;
         });
         const coarseCovered = manifestRecordsForFile.length > 0 &&
@@ -258,16 +327,39 @@ export function assessStagedSymbolsManifest(options) {
         if (coarseCovered) {
             continue;
         }
-        const expectedSymbols = normalizeExpectedSymbolsForStagedFile(sourceFile);
+        const recordsByTitle = new Map();
+        for (const record of manifestRecordsForFile) {
+            if (typeof record.title !== "string")
+                continue;
+            const records = recordsByTitle.get(record.title) ?? [];
+            records.push(record);
+            recordsByTitle.set(record.title, records);
+        }
+        // A coarse anchor is allowed to stand in for its extracted declaration
+        // only when every authored record with that title is explicitly coarse.
+        // If a granular record shares the title, keep the declaration in the
+        // equality check so a duplicate anchor cannot hide stale coordinates.
+        const coarseTitles = new Set([...recordsByTitle.entries()]
+            .filter(([, records]) => records.every(isDocumentedCoarseRecord))
+            .map(([title]) => title));
+        const expectedSymbols = normalizeExpectedSymbolsForStagedFile(sourceFile).filter((symbol) => !coarseTitles.has(symbol.title));
         const baselineSymbols = normalizeManifestSymbolsForSourceFile(baselineMergedRecords, sourceFile.path);
         if (signaturesEqual(expectedSymbols, baselineSymbols)) {
             continue;
         }
         requiredRefreshPaths.push(sourceFile.path);
-        if (!stagedCoordinatesFile || stagedCoordinateArtifact === null) {
+        // Without a usable staged coordinate artifact there is nothing to diff
+        // against: every extracted symbol counts as uncovered evidence.
+        const stagedSymbols = stagedCoordinateArtifact === null
+            ? []
+            : normalizeManifestSymbolsForSourceFile(stagedMergedRecords, sourceFile.path);
+        const detail = diffSymbolEvidence(sourceFile.path, expectedSymbols, stagedSymbols);
+        if (detail !== null) {
+            symbolDetails.push(detail);
+        }
+        if (!stagedCoordinatesFile) {
             continue;
         }
-        const stagedSymbols = normalizeManifestSymbolsForSourceFile(stagedMergedRecords, sourceFile.path);
         if (signaturesEqual(expectedSymbols, stagedSymbols)) {
             freshPaths.add(sourceFile.path);
         }
@@ -283,10 +375,29 @@ export function assessStagedSymbolsManifest(options) {
     if (sourcePaths.every((sourcePath) => freshPaths.has(sourcePath))) {
         return { state: "fresh", sourcePaths, path: paths.coordinatesPath };
     }
+    // Details are only meaningful for the states whose diagnostics fire; a
+    // fresh refresh carries no uncovered symbols by definition, and the stale
+    // state cites only the non-fresh paths, so details follow that filter.
+    const nonFreshDetails = symbolDetails.filter((detail) => !freshPaths.has(detail.path));
+    const detailSpread = nonFreshDetails.length > 0
+        ? {
+            fileDetails: nonFreshDetails.sort((left, right) => left.path.localeCompare(right.path)),
+        }
+        : {};
     if (!stagedCoordinatesFile) {
-        return { state: "missing", sourcePaths, path: paths.coordinatesPath };
+        return {
+            state: "missing",
+            sourcePaths,
+            path: paths.coordinatesPath,
+            ...detailSpread,
+        };
     }
-    return { state: "stale", sourcePaths, path: paths.coordinatesPath };
+    return {
+        state: "stale",
+        sourcePaths: sourcePaths.filter((sourcePath) => !freshPaths.has(sourcePath)),
+        path: paths.coordinatesPath,
+        ...detailSpread,
+    };
 }
 export function collectStagedAuthoredSymbolsManifestEvidence(options) {
     const { sourceFiles, stagedFiles } = options;

package/dist/traceability/symbol-extract.d.ts

@@ -1,5 +1,10 @@
+import type { SourceAnalysisResult as SdkSourceAnalysisResult } from "kibi-plugin-sdk";
+import { isPrivateClassMember } from "../extractors/symbols-ts.js";
 import { type SymbolKind, type SymbolRole } from "../public/symbol-granularity.js";
 import type { HunkRange, StagedFile } from "./git-staged.js";
+type SourceAnalysisResult = SdkSourceAnalysisResult & {
+    providerId?: string | null;
+};
 type TraceabilityRelationship = {
     type: string;
     to: string;
@@ -24,6 +29,23 @@ export interface ManifestLookupEntry {
 }
 export type ManifestLookup = Map<string, ManifestLookupEntry>;
 export declare function createManifestLookupSentinelKey(manifestPath: string): string;
-export declare function extractSymbolsFromStagedFile(stagedFile: StagedFile, manifestLookup?: ManifestLookup): ExtractedSymbol[];
-export {};
+export type ExtractSymbolsOptions = Readonly<{
+    /**
+     * Host-owned analysis. Prefer SourceAnalysisService / capability registry.
+     * When omitted, falls back to the builtin ts-morph provider for parity.
+     */
+    analyzeText?: (filePath: string, content: string) => SourceAnalysisResult | null | Promise<SourceAnalysisResult | null>;
+}>;
+export declare function extractSymbolsFromStagedFile(stagedFile: StagedFile, manifestLookup?: ManifestLookup, options?: ExtractSymbolsOptions): ExtractedSymbol[];
+/**
+ * Async staged symbol extraction. Defaults to deterministic builtin analysis.
+ * Pass an explicit `registry` only from allowlisted async surfaces that compose
+ * replace/augment/shadow (e.g. symbol repair). Maintenance paths (`check`,
+ * impact, sync, status, proof) must omit `registry` so external extractors
+ * never participate.
+ */
+export declare function extractSymbolsFromStagedFileAsync(stagedFile: StagedFile, manifestLookup: ManifestLookup | undefined, options: ExtractSymbolsOptions & Readonly<{
+    registry?: import("../plugins/registry.js").CapabilityRegistry;
+}>): Promise<ExtractedSymbol[]>;
+export { isPrivateClassMember };
 //# sourceMappingURL=symbol-extract.d.ts.map

package/dist/traceability/symbol-extract.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"symbol-extract.d.ts","sourceRoot":"","sources":["../../src/traceability/symbol-extract.ts"],"names":[],"mappings":"AAGA,OAAO,EACL,KAAK,UAAU,EACf,KAAK,UAAU,EAEhB,MAAM,iCAAiC,CAAC;AACzC,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAE7D,KAAK,wBAAwB,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,CAAC;AAU7D,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,UAAU,CAAC;IACjB,IAAI,EAAE,UAAU,CAAC;IACjB,QAAQ,EAAE;QACR,IAAI,EAAE,MAAM,CAAC;QACb,SAAS,EAAE,MAAM,CAAC;QAClB,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC;IACF,UAAU,EAAE,SAAS,EAAE,CAAC;IACxB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,aAAa,CAAC,EAAE,wBAAwB,EAAE,CAAC;CAC5C;AAED,MAAM,WAAW,mBAAmB;IAClC,EAAE,EAAE,MAAM,CAAC;IACX,aAAa,CAAC,EAAE,wBAAwB,EAAE,CAAC;CAC5C;AAED,MAAM,MAAM,cAAc,GAAG,GAAG,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC;AAE9D,wBAAgB,+BAA+B,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAG5E;AAmOD,wBAAgB,4BAA4B,CAE1C,UAAU,EAAE,UAAU,EACtB,cAAc,CAAC,EAAE,cAAc,GAC9B,eAAe,EAAE,CA2SnB"}
+{"version":3,"file":"symbol-extract.d.ts","sourceRoot":"","sources":["../../src/traceability/symbol-extract.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,oBAAoB,IAAI,uBAAuB,EAAE,MAAM,iBAAiB,CAAC;AAEvF,OAAO,EAEL,oBAAoB,EACrB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EACL,KAAK,UAAU,EACf,KAAK,UAAU,EAEhB,MAAM,iCAAiC,CAAC;AACzC,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAE7D,KAAK,oBAAoB,GAAG,uBAAuB,GAAG;IACpD,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B,CAAC;AAEF,KAAK,wBAAwB,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,CAAC;AAU7D,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,UAAU,CAAC;IACjB,IAAI,EAAE,UAAU,CAAC;IACjB,QAAQ,EAAE;QACR,IAAI,EAAE,MAAM,CAAC;QACb,SAAS,EAAE,MAAM,CAAC;QAClB,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC;IACF,UAAU,EAAE,SAAS,EAAE,CAAC;IACxB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,aAAa,CAAC,EAAE,wBAAwB,EAAE,CAAC;CAC5C;AAED,MAAM,WAAW,mBAAmB;IAClC,EAAE,EAAE,MAAM,CAAC;IACX,aAAa,CAAC,EAAE,wBAAwB,EAAE,CAAC;CAC5C;AAED,MAAM,MAAM,cAAc,GAAG,GAAG,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC;AAE9D,wBAAgB,+BAA+B,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAG5E;AAyND,MAAM,MAAM,qBAAqB,GAAG,QAAQ,CAAC;IAC3C;;;OAGG;IACH,WAAW,CAAC,EAAE,CACZ,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,KACZ,oBAAoB,GAAG,IAAI,GAAG,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC,CAAC;CACzE,CAAC,CAAC;AAWH,wBAAgB,4BAA4B,CAE1C,UAAU,EAAE,UAAU,EACtB,cAAc,CAAC,EAAE,cAAc,EAC/B,OAAO,CAAC,EAAE,qBAAqB,GAC9B,eAAe,EAAE,CAkCnB;AAED;;;;;;GAMG;AAEH,wBAAsB,iCAAiC,CACrD,UAAU,EAAE,UAAU,EACtB,cAAc,EAAE,cAAc,GAAG,SAAS,EAC1C,OAAO,EAAE,qBAAqB,GAC5B,QAAQ,CAAC;IACP,QAAQ,CAAC,EAAE,OAAO,wBAAwB,EAAE,kBAAkB,CAAC;CAChE,CAAC,GACH,OAAO,CAAC,eAAe,EAAE,CAAC,CA8B5B;AAwCD,OAAO,EAAE,oBAAoB,EAAE,CAAC"}