kibi-cli 2.2.0 → 2.3.0

package/dist/traceability/analysis-gate.d.ts

@@ -0,0 +1,39 @@
+import type { HunkRange } from "./git-staged.js";
+type LineRange = Readonly<{
+    startLine: number;
+    endLine: number;
+}>;
+export type GateAnalysis<Range extends LineRange> = Readonly<{
+    status: "ok" | "partial" | "unsupported" | "failed";
+    diagnosticCodes: readonly string[];
+    uncoveredRanges: readonly (Range & Readonly<{
+        reason: string;
+    }>)[];
+}>;
+/** What one side of a changed file needs before it can pass. */
+type AnalysisObligation<Range extends LineRange> = Readonly<{
+    kind: "none";
+}> | Readonly<{
+    kind: "blocked";
+    reason: string;
+}> | Readonly<{
+    kind: "unsupported_review";
+}> | Readonly<{
+    kind: "partial_review";
+    ranges: readonly Range[];
+}>;
+/**
+ * The single rule for when incomplete source analysis blocks a change.
+ *
+ * - The before side is historical and cannot be corrected by the author, so it
+ *   is informational and never blocks or needs review.
+ * - On the after side, failed analysis and non-local gaps (syntax, parse,
+ *   timeout, integrity) always block.
+ * - A local gap (a macro, decorator or other declared limitation) matters only
+ *   where it overlaps the changed lines; elsewhere the file was already in that
+ *   state and this change did not touch it.
+ * - Unsupported after-side analysis needs one whole-file review.
+ */
+export declare function analysisObligation<Range extends LineRange>(side: "before" | "after", analysis: GateAnalysis<Range> | null | undefined, newHunkRanges: readonly HunkRange[]): AnalysisObligation<Range>;
+export {};
+//# sourceMappingURL=analysis-gate.d.ts.map

package/dist/traceability/analysis-gate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"analysis-gate.d.ts","sourceRoot":"","sources":["../../src/traceability/analysis-gate.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAUjD,KAAK,SAAS,GAAG,QAAQ,CAAC;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAGlE,MAAM,MAAM,YAAY,CAAC,KAAK,SAAS,SAAS,IAAI,QAAQ,CAAC;IAC3D,MAAM,EAAE,IAAI,GAAG,SAAS,GAAG,aAAa,GAAG,QAAQ,CAAC;IACpD,eAAe,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,eAAe,EAAE,SAAS,CAAC,KAAK,GAAG,QAAQ,CAAC;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC,EAAE,CAAC;CACpE,CAAC,CAAC;AAEH,gEAAgE;AAChE,KAAK,kBAAkB,CAAC,KAAK,SAAS,SAAS,IAC3C,QAAQ,CAAC;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,GAC1B,QAAQ,CAAC;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,GAC7C,QAAQ,CAAC;IAAE,IAAI,EAAE,oBAAoB,CAAA;CAAE,CAAC,GACxC,QAAQ,CAAC;IAAE,IAAI,EAAE,gBAAgB,CAAC;IAAC,MAAM,EAAE,SAAS,KAAK,EAAE,CAAA;CAAE,CAAC,CAAC;AAuBnE;;;;;;;;;;;GAWG;AAEH,wBAAgB,kBAAkB,CAAC,KAAK,SAAS,SAAS,EACxD,IAAI,EAAE,QAAQ,GAAG,OAAO,EACxB,QAAQ,EAAE,YAAY,CAAC,KAAK,CAAC,GAAG,IAAI,GAAG,SAAS,EAChD,aAAa,EAAE,SAAS,SAAS,EAAE,GAClC,kBAAkB,CAAC,KAAK,CAAC,CAqB3B"}

package/dist/traceability/analysis-gate.js

@@ -0,0 +1,51 @@
+/**
+ * Diagnostics that make the whole parse unreliable rather than one region.
+ * A deleted brace can surface as a syntax error far from the edited lines, so
+ * these never narrow to the changed hunks and never accept a residual review.
+ */
+const NON_LOCAL_ANALYSIS_MARKER = /(?:syntax|parse|timeout|timed[\s_-]*out|integrity|checksum|failed|failure|error|input[\s_-]*limit)/i;
+function hasNonLocalAnalysisGap(analysis) {
+    return NON_LOCAL_ANALYSIS_MARKER.test([
+        ...analysis.diagnosticCodes,
+        ...analysis.uncoveredRanges.map((range) => range.reason),
+    ].join("\n"));
+}
+/** Uncovered ranges that overlap a changed line of the after side. */
+function rangesTouchingHunks(ranges, hunks) {
+    return ranges.filter((range) => hunks.some((hunk) => range.startLine <= hunk.end && hunk.start <= range.endLine));
+}
+/**
+ * The single rule for when incomplete source analysis blocks a change.
+ *
+ * - The before side is historical and cannot be corrected by the author, so it
+ *   is informational and never blocks or needs review.
+ * - On the after side, failed analysis and non-local gaps (syntax, parse,
+ *   timeout, integrity) always block.
+ * - A local gap (a macro, decorator or other declared limitation) matters only
+ *   where it overlaps the changed lines; elsewhere the file was already in that
+ *   state and this change did not touch it.
+ * - Unsupported after-side analysis needs one whole-file review.
+ */
+// implements REQ-source-analysis-v2
+export function analysisObligation(side, analysis, newHunkRanges) {
+    if (side === "before" || !analysis || analysis.status === "ok")
+        return { kind: "none" };
+    if (analysis.status === "failed")
+        return { kind: "blocked", reason: "source analysis failed" };
+    if (analysis.status === "unsupported")
+        return { kind: "unsupported_review" };
+    if (analysis.uncoveredRanges.length === 0)
+        return {
+            kind: "blocked",
+            reason: "partial analysis did not report which ranges it left uncovered",
+        };
+    if (hasNonLocalAnalysisGap(analysis))
+        return {
+            kind: "blocked",
+            reason: "a parser, syntax, timeout or integrity diagnostic affects the whole file",
+        };
+    const ranges = rangesTouchingHunks(analysis.uncoveredRanges, newHunkRanges);
+    return ranges.length === 0
+        ? { kind: "none" }
+        : { kind: "partial_review", ranges };
+}

package/dist/traceability/git-change-snapshot.d.ts

@@ -0,0 +1,27 @@
+import type { StagedPath } from "./git-staged.js";
+export type SnapshotGitReader = (args: readonly string[]) => Buffer;
+export interface GitChangeSnapshot {
+    /** Tree at the captured base commit, or the canonical empty tree when unborn. */
+    baseTree: string;
+    /** The single tree written from the captured index (staged snapshots). */
+    headTree: string;
+    /** Captured base commit, or null for an unborn repository. */
+    headCommit: string | null;
+    /** Run a Git command against immutable captured trees/blobs. */
+    readGit(args: readonly string[]): Buffer;
+    /** Read immutable object IDs in one process; no working-tree reads. */
+    readBlobs(oids: readonly string[]): ReadonlyMap<string, Buffer>;
+    /** Reject a changed HEAD or index tree after staged analysis. */
+    assertUnchanged(): void;
+    inventory: StagedPath[];
+}
+/** Capture one immutable tree from the index and inventory only Git objects. */
+export declare function captureStagedSnapshot(workspaceRoot: string): GitChangeSnapshot;
+/**
+ * Capture changes between explicit revisions. The caller chooses `base`; for
+ * merge-impact analysis this is commonly the merge base computed with
+ * `git merge-base target head`. This helper resolves each input once and does
+ * not silently choose a merge base of its own.
+ */
+export declare function captureDiffSnapshot(workspaceRoot: string, base: string, head: string): GitChangeSnapshot;
+//# sourceMappingURL=git-change-snapshot.d.ts.map

package/dist/traceability/git-change-snapshot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-change-snapshot.d.ts","sourceRoot":"","sources":["../../src/traceability/git-change-snapshot.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAIV,UAAU,EAEX,MAAM,iBAAiB,CAAC;AAKzB,MAAM,MAAM,iBAAiB,GAAG,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,KAAK,MAAM,CAAC;AAGpE,MAAM,WAAW,iBAAiB;IAChC,iFAAiF;IACjF,QAAQ,EAAE,MAAM,CAAC;IACjB,0EAA0E;IAC1E,QAAQ,EAAE,MAAM,CAAC;IACjB,8DAA8D;IAC9D,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,gEAAgE;IAChE,OAAO,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAAC;IACzC,uEAAuE;IACvE,SAAS,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChE,iEAAiE;IACjE,eAAe,IAAI,IAAI,CAAC;IACxB,SAAS,EAAE,UAAU,EAAE,CAAC;CACzB;AA4cD,gFAAgF;AAEhF,wBAAgB,qBAAqB,CACnC,aAAa,EAAE,MAAM,GACpB,iBAAiB,CAuBnB;AAED;;;;;GAKG;AAEH,wBAAgB,mBAAmB,CACjC,aAAa,EAAE,MAAM,EACrB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,GACX,iBAAiB,CAyBnB"}

package/dist/traceability/git-change-snapshot.js

@@ -0,0 +1,411 @@
+import { execFileSync, spawnSync } from "node:child_process";
+import { isEntityLanePath, isSymbolsManifestPath } from "../utils/kb-paths.js";
+const GIT_EXEC_MAX_BUFFER = 64 * 1024 * 1024;
+function runGit(root, args) {
+    try {
+        return execFileSync("git", [...args], {
+            cwd: root,
+            encoding: "buffer",
+            maxBuffer: GIT_EXEC_MAX_BUFFER,
+            stdio: ["ignore", "pipe", "ignore"],
+        });
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        throw new Error(`git command failed: git ${args.join(" ")} -> ${detail}`);
+    }
+}
+function gitText(root, args) {
+    return runGit(root, args).toString("utf8").trim();
+}
+function readBlobs(root, oids) {
+    const unique = [...new Set(oids)];
+    if (unique.some((oid) => !/^[a-f0-9]{40,64}$/.test(oid)))
+        throw new Error("Invalid snapshot object ID");
+    const result = new Map();
+    if (unique.length === 0)
+        return result;
+    const output = execFileSync("git", ["cat-file", "--batch"], {
+        cwd: root,
+        input: `${unique.join("\n")}\n`,
+        maxBuffer: GIT_EXEC_MAX_BUFFER,
+        stdio: ["pipe", "pipe", "pipe"],
+    });
+    let offset = 0;
+    for (const oid of unique) {
+        const newline = output.indexOf(10, offset);
+        const header = output
+            .subarray(offset, newline)
+            .toString("ascii")
+            .split(" ");
+        const size = Number(header[2]);
+        if (newline < 0 ||
+            header[0] !== oid ||
+            header[1] !== "blob" ||
+            !Number.isSafeInteger(size) ||
+            size < 0 ||
+            newline + 1 + size >= output.length)
+            throw new Error(`Invalid snapshot blob response: ${oid}`);
+        const start = newline + 1;
+        if (output[start + size] !== 10)
+            throw new Error(`Invalid snapshot blob delimiter: ${oid}`);
+        result.set(oid, output.subarray(start, start + size));
+        offset = start + size + 1;
+    }
+    if (offset !== output.length)
+        throw new Error("Unexpected trailing snapshot blob data");
+    return result;
+}
+function resolveHeadCommit(root) {
+    try {
+        return gitText(root, ["rev-parse", "--verify", "HEAD^{commit}"]);
+    }
+    catch (headError) {
+        const ref = gitText(root, ["symbolic-ref", "-q", "HEAD"]);
+        const presence = spawnSync("git", ["show-ref", "--verify", "--quiet", ref], { cwd: root, stdio: "ignore" });
+        // Only a missing ref is unborn. A present ref pointing to a missing or
+        // non-commit object is corruption, not an empty repository.
+        if (presence.status === 1)
+            return null;
+        throw headError;
+    }
+}
+function emptyTreeOid(root) {
+    return gitText(root, ["hash-object", "-t", "tree", "--stdin"]);
+}
+function treeForCommit(root, commit) {
+    return commit
+        ? gitText(root, ["rev-parse", "--verify", `${commit}^{tree}`])
+        : emptyTreeOid(root);
+}
+function parseNameStatus(input) {
+    const entries = input.toString("utf8").split("\0").filter(Boolean);
+    const rows = [];
+    for (let index = 0; index < entries.length;) {
+        const token = entries[index] ?? "";
+        const tab = token.indexOf("\t");
+        const statusToken = tab >= 0 ? token.slice(0, tab) : token;
+        const inlinePath = tab >= 0 ? token.slice(tab + 1) : undefined;
+        const status = (statusToken[0] ?? "M");
+        const renamed = status === "R" || status === "C";
+        const firstPath = inlinePath ?? entries[index + 1] ?? "";
+        const oldPath = renamed ? firstPath : undefined;
+        const path = renamed ? (entries[index + 2] ?? "") : (firstPath ?? "");
+        rows.push({ status, ...(oldPath !== undefined ? { oldPath } : {}), path });
+        index += inlinePath !== undefined ? 1 : renamed ? 3 : 2;
+    }
+    return rows;
+}
+function literalPathspec(path) {
+    return `:(literal)${path}`;
+}
+function readTreeEntry(root, tree, path) {
+    const output = runGit(root, [
+        "ls-tree",
+        "-r",
+        "-z",
+        tree,
+        "--",
+        literalPathspec(path),
+    ]);
+    const first = output.toString("utf8").split("\0")[0];
+    if (!first)
+        return undefined;
+    const tab = first.indexOf("\t");
+    if (tab < 0)
+        return undefined;
+    const [mode, type, oid] = first.slice(0, tab).split(" ");
+    if (!mode || !type || !oid)
+        return undefined;
+    return { mode, type, oid };
+}
+function readBlob(root, entry) {
+    if (!entry || entry.type !== "blob")
+        return undefined;
+    return runGit(root, ["cat-file", "blob", entry.oid]);
+}
+function decodeText(buffer) {
+    if (buffer.includes(0))
+        return { skipReason: "binary" };
+    try {
+        return {
+            content: new TextDecoder("utf-8", { fatal: true }).decode(buffer),
+        };
+    }
+    catch {
+        return { skipReason: "unsupported_encoding" };
+    }
+}
+function hasSupportedExt(path) {
+    return /\.(?:ts|tsx|js|jsx|mts|cts|mjs|cjs)$/.test(path);
+}
+function isMetadataPath(path) {
+    const normalized = path.replaceAll("\\", "/");
+    const relationshipShard = normalized.startsWith(".kb/relationships/") &&
+        (normalized.endsWith(".yaml") || normalized.endsWith(".yml"));
+    return ((normalized.endsWith(".md") && isEntityLanePath(normalized)) ||
+        relationshipShard ||
+        normalized === ".kb/manifest.json" ||
+        normalized === ".kb/symbols.yaml" ||
+        normalized === ".kb/symbols.yml" ||
+        normalized === ".kb/symbol-coordinates.yaml" ||
+        isSymbolsManifestPath(normalized));
+}
+function analysisFor(path, deleted) {
+    if (deleted)
+        return "file";
+    if (hasSupportedExt(path))
+        return "symbol";
+    if (isMetadataPath(path))
+        return "metadata";
+    return "file";
+}
+function parseHunkSides(diffText) {
+    const oldHunkRanges = [];
+    const hunkRanges = [];
+    const regex = /^@@\s+-(\d+)(?:,(\d+))?\s+\+(\d+)(?:,(\d+))?\s+@@/gm;
+    for (const match of diffText.matchAll(regex)) {
+        const oldStart = Number.parseInt(match[1] ?? "0", 10);
+        const oldCount = match[2] ? Number.parseInt(match[2], 10) : 1;
+        const newStart = Number.parseInt(match[3] ?? "0", 10);
+        const newCount = match[4] ? Number.parseInt(match[4], 10) : 1;
+        if (oldCount > 0) {
+            oldHunkRanges.push({ start: oldStart, end: oldStart + oldCount - 1 });
+        }
+        if (newCount > 0) {
+            hunkRanges.push({ start: newStart, end: newStart + newCount - 1 });
+        }
+    }
+    return { oldHunkRanges, hunkRanges };
+}
+function normalizeRanges(ranges, content) {
+    const lineCount = Math.max(1, (content ?? "").split(/\r?\n/).length);
+    for (const range of ranges) {
+        if (range.end === Number.MAX_SAFE_INTEGER)
+            range.end = lineCount;
+    }
+}
+function diffForPath(root, baseTree, headTree, entry) {
+    const paths = new Set([entry.oldPath, entry.path].filter((path) => path !== undefined));
+    return runGit(root, [
+        "diff",
+        "--no-ext-diff",
+        "--no-color",
+        "-U0",
+        "-M",
+        "-C",
+        "--find-copies-harder",
+        baseTree,
+        headTree,
+        "--",
+        ...[...paths].map(literalPathspec),
+    ]).toString("utf8");
+}
+function skipReasonForMode(mode) {
+    if (mode === "120000")
+        return "symlink";
+    if (mode === "160000")
+        return "submodule";
+    return undefined;
+}
+function buildInventory(root, baseTree, headTree) {
+    const rows = parseNameStatus(runGit(root, [
+        "diff",
+        "--name-status",
+        "-z",
+        "-M",
+        "-C",
+        "--find-copies-harder",
+        "--diff-filter=ACMRTD",
+        baseTree,
+        headTree,
+    ]));
+    return rows.map((row) => {
+        const previousPath = row.oldPath ?? row.path;
+        const oldEntry = readTreeEntry(root, baseTree, previousPath);
+        const newEntry = readTreeEntry(root, headTree, row.path);
+        const oldBlob = readBlob(root, oldEntry);
+        const newBlob = readBlob(root, newEntry);
+        const oldDecoded = oldBlob ? decodeText(oldBlob) : undefined;
+        const newDecoded = newBlob ? decodeText(newBlob) : undefined;
+        const diffText = diffForPath(root, baseTree, headTree, row);
+        const { oldHunkRanges, hunkRanges } = parseHunkSides(diffText);
+        const oldContent = oldDecoded && "content" in oldDecoded ? oldDecoded.content : undefined;
+        const newContent = newDecoded && "content" in newDecoded ? newDecoded.content : undefined;
+        const oldIsPresent = oldEntry !== undefined;
+        const newIsPresent = newEntry !== undefined;
+        if (!oldIsPresent && newIsPresent && hunkRanges.length === 0) {
+            hunkRanges.push({ start: 1, end: Number.MAX_SAFE_INTEGER });
+        }
+        if (oldIsPresent && !newIsPresent && oldHunkRanges.length === 0) {
+            oldHunkRanges.push({ start: 1, end: Number.MAX_SAFE_INTEGER });
+        }
+        normalizeRanges(hunkRanges, newContent);
+        normalizeRanges(oldHunkRanges, oldContent);
+        const gitMode = newEntry?.mode ?? oldEntry?.mode;
+        const previousMode = oldEntry?.mode;
+        const modeSkip = skipReasonForMode(newEntry?.mode ?? (!newIsPresent ? oldEntry?.mode : undefined));
+        const decodeSkip = (newDecoded && "skipReason" in newDecoded
+            ? newDecoded.skipReason
+            : undefined) ??
+            (oldDecoded && "skipReason" in oldDecoded
+                ? oldDecoded.skipReason
+                : undefined);
+        const skipReason = modeSkip ?? decodeSkip;
+        const pathFields = {
+            ...(row.status === "R" && row.oldPath !== undefined
+                ? { oldPath: row.oldPath }
+                : {}),
+            ...(row.status === "C" && row.oldPath !== undefined
+                ? { copyFromPath: row.oldPath }
+                : {}),
+        };
+        if (skipReason) {
+            return {
+                path: row.path,
+                status: row.status,
+                ...pathFields,
+                hunkRanges,
+                oldHunkRanges,
+                diffText,
+                ...(gitMode !== undefined ? { gitMode } : {}),
+                ...(previousMode !== undefined ? { previousMode } : {}),
+                ...(oldContent !== undefined ? { previousContent: oldContent } : {}),
+                analysisDepth: "none",
+                disposition: "skipped",
+                skipReason,
+            };
+        }
+        const deleted = !newIsPresent;
+        const analysisDepth = analysisFor(row.path, deleted);
+        const disposition = analysisDepth === "file" ? "advisory" : "checked";
+        return {
+            path: row.path,
+            status: row.status,
+            ...pathFields,
+            hunkRanges,
+            oldHunkRanges,
+            diffText,
+            ...(newContent !== undefined ? { content: newContent } : {}),
+            ...(oldContent !== undefined ? { previousContent: oldContent } : {}),
+            ...(gitMode !== undefined ? { gitMode } : {}),
+            ...(previousMode !== undefined ? { previousMode } : {}),
+            analysisDepth,
+            disposition,
+        };
+    });
+}
+function translateReadGit(root, args, baseTree, headTree, baseCommit) {
+    if (args[0] === "diff" && args.includes("--cached")) {
+        const translated = args.filter((arg) => arg !== "--cached");
+        const filterIndex = translated.findIndex((arg) => arg.startsWith("--diff-filter="));
+        if (filterIndex >= 0)
+            translated[filterIndex] = "--diff-filter=ACMRTD";
+        const separator = translated.indexOf("--");
+        const insertion = separator < 0 ? translated.length : separator;
+        translated.splice(insertion, 0, baseTree, headTree);
+        return runGit(root, translated);
+    }
+    if (args[0] === "ls-files" && args.includes("--stage")) {
+        const separator = args.indexOf("--");
+        const pathArgs = separator >= 0 ? args.slice(separator + 1) : [];
+        const output = runGit(root, [
+            "ls-tree",
+            "-r",
+            "-z",
+            headTree,
+            ...(pathArgs.length ? ["--", ...pathArgs] : []),
+        ]);
+        const rows = output
+            .toString("utf8")
+            .split("\0")
+            .filter(Boolean)
+            .map((row) => {
+            const tab = row.indexOf("\t");
+            if (tab < 0)
+                return row;
+            const [mode, _type, oid] = row.slice(0, tab).split(" ");
+            return `${mode ?? ""} ${oid ?? ""} 0${row.slice(tab)}`;
+        });
+        return Buffer.from(rows.length ? `${rows.join("\0")}\0` : "");
+    }
+    if (args[0] === "ls-tree" && args.includes("HEAD")) {
+        return runGit(root, args.map((arg) => (arg === "HEAD" ? baseTree : arg)));
+    }
+    if (args[0] === "rev-parse" && args.some((arg) => arg.startsWith("HEAD"))) {
+        const revision = args.find((arg) => arg.startsWith("HEAD")) ?? "HEAD";
+        if (revision === "HEAD^{tree}")
+            return Buffer.from(`${baseTree}\n`);
+        if (revision === "HEAD" || revision === "HEAD^{commit}") {
+            if (!baseCommit) {
+                throw new Error("HEAD does not resolve to a commit in this snapshot");
+            }
+            return Buffer.from(`${baseCommit}\n`);
+        }
+    }
+    if (args[0] === "show") {
+        const spec = args[1] ?? "";
+        if (spec.startsWith(":")) {
+            return runGit(root, ["show", `${headTree}:${spec.slice(1)}`]);
+        }
+        if (spec.startsWith("HEAD:")) {
+            return runGit(root, [
+                "show",
+                `${baseTree}:${spec.slice("HEAD:".length)}`,
+            ]);
+        }
+    }
+    return runGit(root, args);
+}
+function snapshotFromTrees(root, baseTree, headTree, headCommit, readGit, assertUnchanged) {
+    return {
+        baseTree,
+        headTree,
+        headCommit,
+        readGit,
+        readBlobs: (oids) => readBlobs(root, oids),
+        assertUnchanged,
+        inventory: buildInventory(root, baseTree, headTree),
+    };
+}
+/** Capture one immutable tree from the index and inventory only Git objects. */
+// implements REQ-014
+export function captureStagedSnapshot(workspaceRoot) {
+    const headCommit = resolveHeadCommit(workspaceRoot);
+    const baseTree = treeForCommit(workspaceRoot, headCommit);
+    const headTree = gitText(workspaceRoot, ["write-tree"]);
+    const readGit = (args) => translateReadGit(workspaceRoot, args, baseTree, headTree, headCommit);
+    const assertUnchanged = () => {
+        const currentHead = resolveHeadCommit(workspaceRoot);
+        const currentIndexTree = gitText(workspaceRoot, ["write-tree"]);
+        if (currentHead !== headCommit || currentIndexTree !== headTree) {
+            throw new Error("Git index or HEAD changed during staged analysis; retry the operation");
+        }
+    };
+    return snapshotFromTrees(workspaceRoot, baseTree, headTree, headCommit, readGit, assertUnchanged);
+}
+/**
+ * Capture changes between explicit revisions. The caller chooses `base`; for
+ * merge-impact analysis this is commonly the merge base computed with
+ * `git merge-base target head`. This helper resolves each input once and does
+ * not silently choose a merge base of its own.
+ */
+// implements REQ-014
+export function captureDiffSnapshot(workspaceRoot, base, head) {
+    const baseCommit = gitText(workspaceRoot, [
+        "rev-parse",
+        "--verify",
+        "--end-of-options",
+        `${base}^{commit}`,
+    ]);
+    const headCommit = gitText(workspaceRoot, [
+        "rev-parse",
+        "--verify",
+        "--end-of-options",
+        `${head}^{commit}`,
+    ]);
+    const baseTree = treeForCommit(workspaceRoot, baseCommit);
+    const headTree = treeForCommit(workspaceRoot, headCommit);
+    const readGit = (args) => translateReadGit(workspaceRoot, args, baseTree, headTree, baseCommit);
+    return snapshotFromTrees(workspaceRoot, baseTree, headTree, baseCommit, readGit, () => undefined);
+}

package/dist/traceability/git-staged.d.ts

@@ -1,4 +1,4 @@
-export type Status = "A" | "M" | "R" | "D";
+export type Status = "A" | "M" | "R" | "C" | "T" | "D";
 export interface HunkRange {
     start: number;
     end: number;
@@ -16,9 +16,13 @@ export type StagedDisposition = "checked" | "advisory" | "skipped";
 export type StagedSkipReason = "binary" | "unsupported_encoding" | "symlink" | "submodule";
 /** Complete Git-index record used by staged validation before any filtering. */
 export interface StagedPath extends StagedFile {
+    /** Source path for a copy; unlike oldPath, it remains in the tree. */
+    copyFromPath?: string;
     analysisDepth: StagedAnalysisDepth;
     disposition: StagedDisposition;
     gitMode?: string;
+    previousMode?: string;
+    oldHunkRanges?: HunkRange[];
     previousContent?: string;
     skipReason?: StagedSkipReason;
 }

package/dist/traceability/git-staged.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"git-staged.d.ts","sourceRoot":"","sources":["../../src/traceability/git-staged.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,MAAM,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,CAAC;AAE3C,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,SAAS,EAAE,CAAC;IACxB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,MAAM,mBAAmB,GAAG,QAAQ,GAAG,UAAU,GAAG,MAAM,GAAG,MAAM,CAAC;AAC1E,MAAM,MAAM,iBAAiB,GAAG,SAAS,GAAG,UAAU,GAAG,SAAS,CAAC;AACnE,MAAM,MAAM,gBAAgB,GACxB,QAAQ,GACR,sBAAsB,GACtB,SAAS,GACT,WAAW,CAAC;AAEhB,gFAAgF;AAChF,MAAM,WAAW,UAAW,SAAQ,UAAU;IAC5C,aAAa,EAAE,mBAAmB,CAAC;IACnC,WAAW,EAAE,iBAAiB,CAAC;IAC/B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,UAAU,CAAC,EAAE,gBAAgB,CAAC;CAC/B;AAED,KAAK,MAAM,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,KAAK,MAAM,CAAC;AAClE,MAAM,MAAM,aAAa,GAAG,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,KAAK,MAAM,CAAC;AAwChE;;GAEG;AAEH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,MAAM,GACZ,KAAK,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC,CAwB5C;AAsFD;;;;GAIG;AAEH,wBAAgB,kBAAkB,CAChC,IAAI,GAAE,aAAkC,GACvC,UAAU,EAAE,CAuFd;AAED,kFAAkF;AAClF,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,SAAS,UAAU,EAAE,GAC/B,UAAU,EAAE,CAmBd;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAEhC,QAAQ,EAAE,MAAM,EAChB,SAAS,UAAQ,GAChB,SAAS,EAAE,CAuBb;AAED;;GAEG;AAEH,wBAAgB,cAAc,CAAC,IAAI,GAAE,MAAoB,GAAG,UAAU,EAAE,CAwGvE;AAED,eAAe,cAAc,CAAC"}
+{"version":3,"file":"git-staged.d.ts","sourceRoot":"","sources":["../../src/traceability/git-staged.ts"],"names":[],"mappings":"AAKA,MAAM,MAAM,MAAM,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,CAAC;AAEvD,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,SAAS,EAAE,CAAC;IACxB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,MAAM,mBAAmB,GAAG,QAAQ,GAAG,UAAU,GAAG,MAAM,GAAG,MAAM,CAAC;AAC1E,MAAM,MAAM,iBAAiB,GAAG,SAAS,GAAG,UAAU,GAAG,SAAS,CAAC;AACnE,MAAM,MAAM,gBAAgB,GACxB,QAAQ,GACR,sBAAsB,GACtB,SAAS,GACT,WAAW,CAAC;AAEhB,gFAAgF;AAChF,MAAM,WAAW,UAAW,SAAQ,UAAU;IAC5C,sEAAsE;IACtE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,mBAAmB,CAAC;IACnC,WAAW,EAAE,iBAAiB,CAAC;IAC/B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,aAAa,CAAC,EAAE,SAAS,EAAE,CAAC;IAC5B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,UAAU,CAAC,EAAE,gBAAgB,CAAC;CAC/B;AAED,KAAK,MAAM,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,KAAK,MAAM,CAAC;AAClE,MAAM,MAAM,aAAa,GAAG,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,KAAK,MAAM,CAAC;AAgChE;;GAEG;AAEH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,MAAM,GACZ,KAAK,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC,CAwB5C;AAsFD;;;;GAIG;AAEH,wBAAgB,kBAAkB,CAAC,IAAI,CAAC,EAAE,aAAa,GAAG,UAAU,EAAE,CAmGrE;AAED,kFAAkF;AAClF,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,SAAS,UAAU,EAAE,GAC/B,UAAU,EAAE,CAmBd;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAEhC,QAAQ,EAAE,MAAM,EAChB,SAAS,UAAQ,GAChB,SAAS,EAAE,CAuBb;AAED;;GAEG;AAEH,wBAAgB,cAAc,CAAC,IAAI,GAAE,MAAoB,GAAG,UAAU,EAAE,CAwGvE;AAED,eAAe,cAAc,CAAC"}

package/dist/traceability/git-staged.js

@@ -1,6 +1,7 @@
-import { execFileSync, execSync } from "node:child_process";
+import { execSync } from "node:child_process";
 import { isCliTraceOrDebugEnabled } from "../env.js";
 import { isEntityLanePath, isSymbolsManifestPath } from "../utils/kb-paths.js";
+import { captureStagedSnapshot } from "./git-change-snapshot.js";
 // Staged manifests (e.g., .kb/symbols.yaml) can exceed Node's default 1 MiB
 // exec buffer; without a larger bound the staged file is silently skipped and
 // freshness checks compare against stale HEAD state.
@@ -8,13 +9,6 @@ const GIT_EXEC_MAX_BUFFER = 64 * 1024 * 1024;
 function defaultExec(cmd, opts) {
     return execSync(cmd, { ...opts, maxBuffer: GIT_EXEC_MAX_BUFFER });
 }
-function defaultGitArgsExec(args) {
-    return execFileSync("git", args, {
-        encoding: "buffer",
-        maxBuffer: GIT_EXEC_MAX_BUFFER,
-        stdio: ["ignore", "pipe", "ignore"],
-    });
-}
 function runGitArgs(args, exec) {
     try {
         return exec(args);
@@ -138,10 +132,17 @@ function normalizeNewFileHunks(ranges, content) {
  * than the working tree.
  */
 // implements REQ-014
-export function getStagedInventory(exec = defaultGitArgsExec) {
+export function getStagedInventory(exec) {
+    // The normal path reads only immutable tree/blob object IDs captured from the
+    // index. Keep the injectable reader path for existing callers and tests.
+    if (!exec) {
+        const snapshot = captureStagedSnapshot(process.cwd());
+        snapshot.assertUnchanged();
+        return snapshot.inventory;
+    }
     let parsed;
     try {
-        parsed = parseNameStatusNull(runGitArgs(["diff", "--cached", "--name-status", "-z", "--diff-filter=ACMRD"], exec).toString("utf8"));
+        parsed = parseNameStatusNull(runGitArgs(["diff", "--cached", "--name-status", "-z", "--diff-filter=ACMRTDC"], exec).toString("utf8"));
     }
     catch (error) {
         throw new Error(`failed to list staged files: ${String(error)}`);
@@ -149,7 +150,8 @@ export function getStagedInventory(exec = defaultGitArgsExec) {
     return parsed.map((entry) => {
         const status = entry.status[0] || "M";
         const oldPath = status === "R" ? entry.parts[0] : undefined;
-        const path = status === "R"
+        const copyFromPath = status === "C" ? entry.parts[0] : undefined;
+        const path = status === "R" || status === "C"
             ? (entry.parts[1] ?? entry.parts[0] ?? "")
             : (entry.parts[0] ?? "");
         const lookupPath = status === "D" ? (oldPath ?? path) : path;
@@ -162,6 +164,7 @@ export function getStagedInventory(exec = defaultGitArgsExec) {
                 path,
                 status,
                 ...(oldPath ? { oldPath } : {}),
+                ...(copyFromPath ? { copyFromPath } : {}),
                 hunkRanges: [],
                 gitMode,
                 analysisDepth: "none",
@@ -179,6 +182,7 @@ export function getStagedInventory(exec = defaultGitArgsExec) {
                 path,
                 status,
                 ...(oldPath ? { oldPath } : {}),
+                ...(copyFromPath ? { copyFromPath } : {}),
                 hunkRanges,
                 diffText,
                 ...(gitMode ? { gitMode } : {}),
@@ -202,6 +206,7 @@ export function getStagedInventory(exec = defaultGitArgsExec) {
             path,
             status,
             ...(oldPath ? { oldPath } : {}),
+            ...(copyFromPath ? { copyFromPath } : {}),
             hunkRanges,
             diffText,
             ...(content !== undefined ? { content } : {}),