kibi-cli 2.22.1 → 2.23.0

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

@@ -1,5 +1,8 @@
 import { execFileSync, spawnSync } from "node:child_process";
-import { isEntityLanePath, isSymbolsManifestPath } from "../utils/kb-paths.js";
+import { mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { ENTITY_LANES, isEntityLanePath, isKbKnowledgePath, isSymbolsManifestPath, } from "../utils/kb-paths.js";
 const GIT_EXEC_MAX_BUFFER = 64 * 1024 * 1024;
 function runGit(root, args) {
     try {
@@ -368,12 +371,188 @@ function snapshotFromTrees(root, baseTree, headTree, headCommit, readGit, assert
         inventory: buildInventory(root, baseTree, headTree),
     };
 }
+/** The commits named by MERGE_HEAD while a merge commit is being made. */
+function pendingMergeParents(root) {
+    let mergeHeadPath;
+    try {
+        mergeHeadPath = gitText(root, ["rev-parse", "--git-path", "MERGE_HEAD"]);
+    }
+    catch {
+        return [];
+    }
+    let text;
+    try {
+        text = readFileSync(path.resolve(root, mergeHeadPath), "utf8");
+    }
+    catch {
+        return [];
+    }
+    return text
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter((line) => /^[a-f0-9]{40,64}$/.test(line));
+}
+function changedPaths(root, from, to) {
+    return runGit(root, ["diff", "--name-only", "-z", "--no-renames", from, to])
+        .toString("utf8")
+        .split("\0")
+        .filter(Boolean);
+}
+/**
+ * For a staged merge commit, the tree the merge is judged against: HEAD
+ * with every path the merge takes unchanged from a merged parent replaced
+ * by that staged content. Diffing it against the staged tree leaves only
+ * what the merge itself wrote, so debt inherited from the merged branch is
+ * not charged to the merge. Null when no merge is in progress or nothing
+ * is inherited.
+ */
+// implements REQ-014
+export function mergeResolutionBase(root, baseTree, headTree, parents) {
+    if (parents.length === 0)
+        return null;
+    const changed = changedPaths(root, baseTree, headTree);
+    if (changed.length === 0)
+        return null;
+    const inherited = new Set();
+    for (const parent of parents) {
+        const parentTree = treeForCommit(root, parent);
+        const differs = new Set(changedPaths(root, parentTree, headTree));
+        for (const file of changed) {
+            if (!differs.has(file))
+                inherited.add(file);
+        }
+    }
+    if (inherited.size === 0)
+        return null;
+    const paths = [...inherited].sort();
+    const listed = runGit(root, [
+        "ls-tree",
+        "-r",
+        "-z",
+        "--full-tree",
+        headTree,
+        "--",
+        ...paths.map(literalPathspec),
+    ])
+        .toString("utf8")
+        .split("\0")
+        .filter(Boolean);
+    const present = new Set();
+    const entries = [];
+    for (const row of listed) {
+        const tab = row.indexOf("\t");
+        if (tab < 0)
+            continue;
+        const [mode, , oid] = row.slice(0, tab).split(" ");
+        const file = row.slice(tab + 1);
+        present.add(file);
+        entries.push(`${mode} ${oid}\t${file}`);
+    }
+    const zero = "0".repeat(baseTree.length);
+    for (const file of paths) {
+        // Deleted on the merged side and absent from the staged tree.
+        if (!present.has(file))
+            entries.push(`0 ${zero}\t${file}`);
+    }
+    return {
+        baseTree: writeTreeWithEntries(root, baseTree, entries, "kibi-merge-base-"),
+        inherited: paths,
+    };
+}
+/** Write `baseTree` with `--index-info` entries applied in a scratch index. */
+function writeTreeWithEntries(root, baseTree, entries, prefix) {
+    const scratch = mkdtempSync(path.join(tmpdir(), prefix));
+    const env = { ...process.env, GIT_INDEX_FILE: path.join(scratch, "index") };
+    try {
+        const git = (args, input) => execFileSync("git", [...args], {
+            cwd: root,
+            env,
+            maxBuffer: GIT_EXEC_MAX_BUFFER,
+            ...(input !== undefined ? { input } : {}),
+            stdio: ["pipe", "pipe", "ignore"],
+        });
+        git(["read-tree", baseTree]);
+        git(["update-index", "-z", "--index-info"], `${entries.join("\0")}\0`);
+        return git(["write-tree"]).toString("utf8").trim();
+    }
+    finally {
+        rmSync(scratch, { recursive: true, force: true });
+    }
+}
+function renamedPaths(root, from, to) {
+    return parseNameStatus(runGit(root, [
+        "diff",
+        "--name-status",
+        "-z",
+        "-M",
+        "--diff-filter=R",
+        from,
+        to,
+    ])).flatMap((row) => row.status === "R" && row.oldPath !== undefined
+        ? [{ from: row.oldPath, to: row.path }]
+        : []);
+}
+/**
+ * True when `from -> to` moves one knowledge file from outside the canonical
+ * layout into the same kind of canonical `.kb/` location: an entity lane
+ * file into the same lane, or a symbols manifest / coordinates file onto the
+ * canonical file of the same name (`.yml` and `.yaml` alike).
+ */
+function isKnowledgeRelocation(from, to) {
+    if (isKbKnowledgePath(from) || !isKbKnowledgePath(to))
+        return false;
+    if (isSymbolsManifestPath(to)) {
+        const stem = (file) => path.posix.basename(file).replace(/\.ya?ml$/, "");
+        return stem(from) === stem(to);
+    }
+    const lane = to.split("/")[1] ?? "";
+    return (ENTITY_LANES.includes(lane) &&
+        `/${from}`.includes(`/${lane}/`));
+}
+/**
+ * For a staged snapshot, the tree a commit that relocates knowledge files
+ * into `.kb/` is judged against: `baseTree` with each relocated file's
+ * committed content placed at its new path and the old path removed.
+ * Diffing it against the staged tree leaves only the edits the commit made
+ * inside those files, so findings that already existed at the old path are
+ * not charged to the move. Every other change, including an edit to a file
+ * that was already canonical, is diffed as before. Null when nothing is
+ * relocated.
+ */
+// implements REQ-014
+export function renameResolutionBase(root, baseTree, headTree) {
+    const zero = "0".repeat(baseTree.length);
+    const renames = [];
+    const entries = [];
+    for (const rename of renamedPaths(root, baseTree, headTree)) {
+        if (!isKnowledgeRelocation(rename.from, rename.to))
+            continue;
+        const source = readTreeEntry(root, baseTree, rename.from);
+        if (source?.type !== "blob")
+            continue;
+        renames.push(rename);
+        entries.push(`0 ${zero}\t${rename.from}`);
+        entries.push(`${source.mode} ${source.oid}\t${rename.to}`);
+    }
+    if (renames.length === 0)
+        return null;
+    return {
+        baseTree: writeTreeWithEntries(root, baseTree, entries, "kibi-rename-base-"),
+        renames: renames.sort((left, right) => left.to.localeCompare(right.to)),
+    };
+}
 /** 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 commitTree = treeForCommit(workspaceRoot, headCommit);
+    const merge = headCommit
+        ? mergeResolutionBase(workspaceRoot, commitTree, headTree, pendingMergeParents(workspaceRoot))
+        : null;
+    const mergeTree = merge?.baseTree ?? commitTree;
+    const relocation = renameResolutionBase(workspaceRoot, mergeTree, headTree);
+    const baseTree = relocation?.baseTree ?? mergeTree;
     const readGit = (args) => translateReadGit(workspaceRoot, args, baseTree, headTree, headCommit);
     const assertUnchanged = () => {
         const currentHead = resolveHeadCommit(workspaceRoot);
@@ -382,7 +561,12 @@ export function captureStagedSnapshot(workspaceRoot) {
             throw new Error("Git index or HEAD changed during staged analysis; retry the operation");
         }
     };
-    return snapshotFromTrees(workspaceRoot, baseTree, headTree, headCommit, readGit, assertUnchanged);
+    const snapshot = snapshotFromTrees(workspaceRoot, baseTree, headTree, headCommit, readGit, assertUnchanged);
+    return {
+        ...snapshot,
+        ...(merge ? { mergeInherited: merge.inherited } : {}),
+        ...(relocation ? { renameResolved: relocation.renames } : {}),
+    };
 }
 /**
  * Capture changes between explicit revisions. The caller chooses `base`; for

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

@@ -1 +1 @@
-{"version":3,"file":"staged-diagnostics.d.ts","sourceRoot":"","sources":["../../src/traceability/staged-diagnostics.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AACnE,OAAO,EAGL,KAAK,kBAAkB,EAKxB,MAAM,qBAAqB,CAAC;AAQ7B,MAAM,MAAM,sBAAsB,GAC9B,8BAA8B,GAC9B,wBAAwB,GACxB,8BAA8B,GAC9B,+BAA+B,GAC/B,iCAAiC,GACjC,oCAAoC,GACpC,gCAAgC,GAChC,0BAA0B,GAC1B,2BAA2B,GAC3B,6BAA6B,GAC7B,yBAAyB,GACzB,wCAAwC,GACxC,wBAAwB,CAAC;AAE7B,MAAM,WAAW,oBAAqB,SAAQ,iBAAiB;IAC7D,uDAAuD;IACvD,EAAE,EAAE,sBAAsB,CAAC;IAC3B,QAAQ,EAAE,iBAAiB,CAAC,UAAU,CAAC,CAAC;IACxC,iEAAiE;IACjE,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IACzB,gDAAgD;IAChD,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACxB,2CAA2C;IAC3C,OAAO,EAAE,MAAM,CAAC;IAChB,0CAA0C;IAC1C,UAAU,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC7B;AAwID,wBAAgB,wCAAwC,CACtD,QAAQ,EAAE,kBAAkB,GAC3B,oBAAoB,CAoBtB;AAED;;;;;;GAMG;AACH,wBAAgB,4BAA4B,CAC1C,QAAQ,EAAE,kBAAkB,EAC5B,mBAAmB,GAAE,MAAmC,GACvD,oBAAoB,EAAE,CAiDxB"}
+{"version":3,"file":"staged-diagnostics.d.ts","sourceRoot":"","sources":["../../src/traceability/staged-diagnostics.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AACnE,OAAO,EAGL,KAAK,kBAAkB,EAKxB,MAAM,qBAAqB,CAAC;AAQ7B,MAAM,MAAM,sBAAsB,GAC9B,8BAA8B,GAC9B,wBAAwB,GACxB,8BAA8B,GAC9B,+BAA+B,GAC/B,iCAAiC,GACjC,oCAAoC,GACpC,gCAAgC,GAChC,0BAA0B,GAC1B,2BAA2B,GAC3B,6BAA6B,GAC7B,yBAAyB,GACzB,wCAAwC,GACxC,wBAAwB,CAAC;AAE7B,MAAM,WAAW,oBAAqB,SAAQ,iBAAiB;IAC7D,uDAAuD;IACvD,EAAE,EAAE,sBAAsB,CAAC;IAC3B,QAAQ,EAAE,iBAAiB,CAAC,UAAU,CAAC,CAAC;IACxC,iEAAiE;IACjE,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IACzB,gDAAgD;IAChD,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACxB,2CAA2C;IAC3C,OAAO,EAAE,MAAM,CAAC;IAChB,0CAA0C;IAC1C,UAAU,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC7B;AAsID,wBAAgB,wCAAwC,CACtD,QAAQ,EAAE,kBAAkB,GAC3B,oBAAoB,CAoBtB;AAED;;;;;;GAMG;AACH,wBAAgB,4BAA4B,CAC1C,QAAQ,EAAE,kBAAkB,EAC5B,mBAAmB,GAAE,MAAmC,GACvD,oBAAoB,EAAE,CAiDxB"}

package/dist/traceability/staged-diagnostics.js

@@ -8,13 +8,12 @@ function deriveCoordinatesPath(symbolsManifestPath) {
 function formatFileList(paths) {
     return paths.join(", ");
 }
-/** Max symbol names rendered per detail line before "+N more". */
-const MAX_DETAIL_NAMES = 6;
+/**
+ * Every name, in order: the gate output is the list a person works through,
+ * so it is never cut short.
+ */
 function formatNameList(names) {
-    const shown = names.slice(0, MAX_DETAIL_NAMES);
-    const overflow = names.length - shown.length;
-    const rendered = shown.join(", ");
-    return overflow > 0 ? `${rendered} … and ${overflow} more` : rendered;
+    return names.join(", ");
 }
 function symbolsManifestFileDetails(evidence, paths) {
     const pathSet = new Set(paths);

package/dist/traceability/staged-inventory-drift.d.ts

@@ -0,0 +1,24 @@
+import type { ExtractionResult } from "../extractors/markdown.js";
+/** A staged requirement whose semantic inventory no longer matches its prose. */
+export declare const STAGED_INVENTORY_DRIFT_RULE = "semantic-inventory-drift";
+export type StagedInventoryDriftViolation = Readonly<{
+    rule: typeof STAGED_INVENTORY_DRIFT_RULE;
+    entityId: string;
+    source: string;
+    message: string;
+    errors: readonly string[];
+}>;
+/**
+ * The staged requirements that declare a semantic inventory contract (now
+ * or in the base tree) whose inventory no longer matches their prose. The
+ * next `kibi sync` refuses them under the proposition-complete boundary;
+ * the gate applies the same test, so drift is caught at the commit that
+ * introduces it instead of after a later merge. Requirements without a
+ * contract are left to sync, which decides from its own baseline.
+ */
+export declare function stagedInventoryDriftViolations(input: {
+    stagedPaths: ReadonlySet<string>;
+    snapshotEntities: readonly ExtractionResult[];
+    readBase: (path: string) => string | null;
+}): StagedInventoryDriftViolation[];
+//# sourceMappingURL=staged-inventory-drift.d.ts.map

package/dist/traceability/staged-inventory-drift.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"staged-inventory-drift.d.ts","sourceRoot":"","sources":["../../src/traceability/staged-inventory-drift.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAKlE,iFAAiF;AAEjF,eAAO,MAAM,2BAA2B,6BAA6B,CAAC;AAGtE,MAAM,MAAM,6BAA6B,GAAG,QAAQ,CAAC;IACnD,IAAI,EAAE,OAAO,2BAA2B,CAAC;IACzC,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;CAC3B,CAAC,CAAC;AAgCH;;;;;;;GAOG;AAEH,wBAAgB,8BAA8B,CAAC,KAAK,EAAE;IACpD,WAAW,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IACjC,gBAAgB,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAC9C,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;CAC3C,GAAG,6BAA6B,EAAE,CA8BlC"}

package/dist/traceability/staged-inventory-drift.js

@@ -0,0 +1,84 @@
+/*
+ Kibi — repo-local, per-branch, queryable long-term memory for software projects
+ Copyright (C) 2026 Piotr Franczyk
+
+ This program is free software: you can redistribute it and/or modify
+ it under the terms of the GNU Affero General Public License as published by
+ the Free Software Foundation, either version 3 of the License, or
+ (at your option) any later version.
+
+ This program is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ GNU Affero General Public License for more details.
+
+ You should have received a copy of the GNU Affero General Public License
+ along with this program.  If not, see <https://www.gnu.org/licenses/>.
+*/
+import { extractFromMarkdownString } from "../extractors/markdown.js";
+import { analyzeSemanticAdvisorInput } from "../operations/semantic-advisor/analyze-prose.js";
+import { validateSemanticInventoryBoundary } from "../operations/semantic-advisor/ingestion-boundary.js";
+/** A staged requirement whose semantic inventory no longer matches its prose. */
+// implements REQ-kibi-proposition-complete-ingestion
+export const STAGED_INVENTORY_DRIFT_RULE = "semantic-inventory-drift";
+function advertisesContract(entity) {
+    return (entity.semantic_inventory_version !== undefined ||
+        entity.semantic_source_hash !== undefined ||
+        entity.semantic_inventory !== undefined);
+}
+function payloadOf(result) {
+    return {
+        type: result.entity.type,
+        id: result.entity.id,
+        properties: result.entity,
+        relationships: result.relationships,
+    };
+}
+function baseResult(path, readBase) {
+    const content = readBase(path);
+    if (content === null)
+        return null;
+    try {
+        return extractFromMarkdownString(content, path);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The staged requirements that declare a semantic inventory contract (now
+ * or in the base tree) whose inventory no longer matches their prose. The
+ * next `kibi sync` refuses them under the proposition-complete boundary;
+ * the gate applies the same test, so drift is caught at the commit that
+ * introduces it instead of after a later merge. Requirements without a
+ * contract are left to sync, which decides from its own baseline.
+ */
+// implements REQ-kibi-proposition-complete-ingestion
+export function stagedInventoryDriftViolations(input) {
+    const violations = [];
+    for (const result of input.snapshotEntities) {
+        if (result.entity.type !== "req")
+            continue;
+        const source = result.entity.source;
+        if (!input.stagedPaths.has(source))
+            continue;
+        const payload = payloadOf(result);
+        const semantic = analyzeSemanticAdvisorInput({ payload });
+        const boundary = validateSemanticInventoryBoundary(payload, result.relationships, semantic.receipt);
+        if (boundary.errors.length === 0)
+            continue;
+        const base = baseResult(source, input.readBase);
+        const enforce = advertisesContract(result.entity) ||
+            (base !== null && advertisesContract(base.entity));
+        if (!enforce)
+            continue;
+        violations.push({
+            rule: STAGED_INVENTORY_DRIFT_RULE,
+            entityId: result.entity.id,
+            source,
+            errors: boundary.errors,
+            message: `${result.entity.id} (${source}): the semantic inventory does not match the requirement's prose, so the next kibi sync rejects it: ${boundary.errors.join("; ")}. Run 'kibi migrate' to re-derive it, or kb_model mode analyze with the complete prose and keep its inventory contract.`,
+        });
+    }
+    return violations.sort((left, right) => left.entityId.localeCompare(right.entityId));
+}

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":"AAEA,OAAO,KAAK,EACV,oBAAoB,EAErB,MAAM,iBAAiB,CAAC;AAKzB,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;AAqTD,wBAAgB,2BAA2B,CAAC,OAAO,EAAE;IACnD,mBAAmB,EAAE,MAAM,CAAC;IAC5B,WAAW,EAAE,UAAU,EAAE,CAAC;IAC1B,WAAW,EAAE,UAAU,EAAE,CAAC;IAC1B,YAAY,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;IACnD,aAAa,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,oBAAoB,CAAC;CAC7E,GAAG,+BAA+B,CAoLlC;AAED,wBAAgB,4CAA4C,CAAC,OAAO,EAAE;IACpE,WAAW,EAAE,UAAU,EAAE,CAAC;IAC1B,WAAW,EAAE,UAAU,EAAE,CAAC;IAC1B,YAAY,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;CACpD,GAAG,qCAAqC,CAqExC"}
+{"version":3,"file":"staged-symbols-manifest.d.ts","sourceRoot":"","sources":["../../src/traceability/staged-symbols-manifest.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,oBAAoB,EAErB,MAAM,iBAAiB,CAAC;AAKzB,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;AAoTD,wBAAgB,2BAA2B,CAAC,OAAO,EAAE;IACnD,mBAAmB,EAAE,MAAM,CAAC;IAC5B,WAAW,EAAE,UAAU,EAAE,CAAC;IAC1B,WAAW,EAAE,UAAU,EAAE,CAAC;IAC1B,YAAY,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;IACnD,aAAa,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,oBAAoB,CAAC;CAC7E,GAAG,+BAA+B,CAoLlC;AAED,wBAAgB,4CAA4C,CAAC,OAAO,EAAE;IACpE,WAAW,EAAE,UAAU,EAAE,CAAC;IAC1B,WAAW,EAAE,UAAU,EAAE,CAAC;IAC1B,YAAY,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;CACpD,GAAG,qCAAqC,CAqExC"}

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

@@ -281,8 +281,7 @@ function diffSymbolEvidence(sourcePath, expectedSymbols, stagedSymbols) {
     if (missing.length === 0 && extra.length === 0) {
         return null;
     }
-    // Keep the complete lists: human-facing renderers truncate (with an
-    // accurate "… and N more"), while JSON evidence carries every name.
+    // Keep the complete lists: the gate output names every symbol.
     return {
         path: sourcePath,
         expectedCount: expectedSymbols.length,

package/dist/utils/content-freshness.d.ts

@@ -9,5 +9,14 @@ export declare function confirmSourceNewerReasons(workspaceRoot: string, storePa
     kept: Reason[];
     dropped: Reason[];
 };
+/**
+ * The `meta` freshness block reporting operations return (kb_graph,
+ * kb_find_gaps, kb_coverage) comes straight from Prolog, which compares file
+ * times only. Apply the same content confirmation kb_status does, so a
+ * checkout or `touch` that changed no byte is not reported as stale.
+ */
+export declare function confirmMetaFreshness<T extends {
+    readonly meta?: Readonly<Record<string, unknown>>;
+}>(payload: T, workspaceRoot: string): T;
 export {};
 //# sourceMappingURL=content-freshness.d.ts.map

package/dist/utils/content-freshness.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"content-freshness.d.ts","sourceRoot":"","sources":["../../src/utils/content-freshness.ts"],"names":[],"mappings":"AAYA,uDAAuD;AACvD,eAAO,MAAM,yBAAyB,EAAE,WAAW,CAAC,MAAM,CAIxD,CAAC;AAEH,KAAK,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;AAyJhD;;;GAGG;AAEH,wBAAgB,yBAAyB,CACvC,aAAa,EAAE,MAAM,EACrB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,SAAS,MAAM,EAAE,GACzB;IAAE,IAAI,EAAE,MAAM,EAAE,CAAC;IAAC,OAAO,EAAE,MAAM,EAAE,CAAA;CAAE,CAkBvC"}
+{"version":3,"file":"content-freshness.d.ts","sourceRoot":"","sources":["../../src/utils/content-freshness.ts"],"names":[],"mappings":"AAYA,uDAAuD;AACvD,eAAO,MAAM,yBAAyB,EAAE,WAAW,CAAC,MAAM,CAIxD,CAAC;AAEH,KAAK,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;AAyJhD;;;GAGG;AAEH,wBAAgB,yBAAyB,CACvC,aAAa,EAAE,MAAM,EACrB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,SAAS,MAAM,EAAE,GACzB;IAAE,IAAI,EAAE,MAAM,EAAE,CAAC;IAAC,OAAO,EAAE,MAAM,EAAE,CAAA;CAAE,CAkBvC;AAED;;;;;GAKG;AAEH,wBAAgB,oBAAoB,CAClC,CAAC,SAAS;IAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;CAAE,EAC/D,OAAO,EAAE,CAAC,EAAE,aAAa,EAAE,MAAM,GAAG,CAAC,CAoCtC"}

package/dist/utils/content-freshness.js

@@ -169,3 +169,36 @@ export function confirmSourceNewerReasons(workspaceRoot, storePath, reasons) {
     }
     return { kept, dropped };
 }
+/**
+ * The `meta` freshness block reporting operations return (kb_graph,
+ * kb_find_gaps, kb_coverage) comes straight from Prolog, which compares file
+ * times only. Apply the same content confirmation kb_status does, so a
+ * checkout or `touch` that changed no byte is not reported as stale.
+ */
+// implements REQ-cli-status-pre-first-sync
+export function confirmMetaFreshness(payload, workspaceRoot) {
+    const meta = payload.meta;
+    if (meta === undefined ||
+        typeof meta.kbPath !== "string" ||
+        !Array.isArray(meta.staleReasons))
+        return payload;
+    const reasons = meta.staleReasons.filter((reason) => record(reason) !== null);
+    const { kept, dropped } = confirmSourceNewerReasons(workspaceRoot, meta.kbPath, reasons);
+    if (dropped.length === 0)
+        return payload;
+    const allConfirmed = kept.length === 0 &&
+        meta.staleReasonsTruncated !== true &&
+        meta.syncState === "stale";
+    return {
+        ...payload,
+        meta: {
+            ...meta,
+            staleReasons: kept,
+            // A truncated list counts more reasons than it carries.
+            staleReasonCount: Math.max(kept.length, (typeof meta.staleReasonCount === "number"
+                ? meta.staleReasonCount
+                : reasons.length) - dropped.length),
+            ...(allConfirmed ? { syncState: "fresh", dirty: false } : {}),
+        },
+    };
+}

package/dist/utils/merge-driver-setup.d.ts

@@ -0,0 +1,10 @@
+/** How to route the authored manifests to `kibi merge-driver`. */
+export declare const MERGE_DRIVER_SETUP = "Add to .gitattributes: \".kb/symbols.yaml merge=kibi\" and \".kb/relationships/*.yaml merge=kibi\"; then run: git config merge.kibi.driver \"npm exec --no -- kibi merge-driver %O %A %B\" (see docs/cli-reference.md#kibi-merge-driver-base-current-other).";
+/**
+ * What keeps Git from resolving `.kb/symbols.yaml` with `kibi merge-driver`:
+ * the attribute that routes the file to it, and the driver command. Empty
+ * when both are set, and null outside a Git work tree or while the
+ * manifest holds no symbol records (nothing to conflict on yet).
+ */
+export declare function manifestMergeDriverGaps(cwd: string): string[] | null;
+//# sourceMappingURL=merge-driver-setup.d.ts.map

package/dist/utils/merge-driver-setup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"merge-driver-setup.d.ts","sourceRoot":"","sources":["../../src/utils/merge-driver-setup.ts"],"names":[],"mappings":"AAsBA,kEAAkE;AAElE,eAAO,MAAM,kBAAkB,iQAC2N,CAAC;AAwB3P;;;;;GAKG;AAEH,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,IAAI,CAiBpE"}

package/dist/utils/merge-driver-setup.js

@@ -0,0 +1,69 @@
+/*
+ Kibi — repo-local, per-branch, queryable long-term memory for software projects
+ Copyright (C) 2026 Piotr Franczyk
+
+ This program is free software: you can redistribute it and/or modify
+ it under the terms of the GNU Affero General Public License as published by
+ the Free Software Foundation, either version 3 of the License, or
+ (at your option) any later version.
+
+ This program is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ GNU Affero General Public License for more details.
+
+ You should have received a copy of the GNU Affero General Public License
+ along with this program.  If not, see <https://www.gnu.org/licenses/>.
+*/
+import { execFileSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import path from "node:path";
+/** How to route the authored manifests to `kibi merge-driver`. */
+// implements REQ-cli-doctor
+export const MERGE_DRIVER_SETUP = 'Add to .gitattributes: ".kb/symbols.yaml merge=kibi" and ".kb/relationships/*.yaml merge=kibi"; then run: git config merge.kibi.driver "npm exec --no -- kibi merge-driver %O %A %B" (see docs/cli-reference.md#kibi-merge-driver-base-current-other).';
+function gitOutput(cwd, args) {
+    try {
+        return execFileSync("git", [...args], {
+            cwd,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+        }).trim();
+    }
+    catch {
+        return null;
+    }
+}
+function hasSymbolRecords(cwd) {
+    try {
+        return /^\s*-\s+id\s*:/m.test(readFileSync(path.join(cwd, ".kb", "symbols.yaml"), "utf8"));
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * What keeps Git from resolving `.kb/symbols.yaml` with `kibi merge-driver`:
+ * the attribute that routes the file to it, and the driver command. Empty
+ * when both are set, and null outside a Git work tree or while the
+ * manifest holds no symbol records (nothing to conflict on yet).
+ */
+// implements REQ-cli-doctor
+export function manifestMergeDriverGaps(cwd) {
+    if (gitOutput(cwd, ["rev-parse", "--is-inside-work-tree"]) !== "true") {
+        return null;
+    }
+    if (!hasSymbolRecords(cwd))
+        return null;
+    const attribute = gitOutput(cwd, [
+        "check-attr",
+        "merge",
+        "--",
+        ".kb/symbols.yaml",
+    ]);
+    const routed = attribute?.endsWith(": merge: kibi") === true;
+    const driver = gitOutput(cwd, ["config", "--get", "merge.kibi.driver"]);
+    return [
+        ...(routed ? [] : [".kb/symbols.yaml is not routed to merge=kibi"]),
+        ...(driver ? [] : ["merge.kibi.driver is not set"]),
+    ];
+}

package/dist/utils/rule-registry.generated.d.ts

@@ -1,6 +1,6 @@
 export declare const GENERATED_RULES: readonly [{
     readonly name: "must-priority-coverage";
-    readonly description: "Every must-priority requirement must have a scenario and a test";
+    readonly description: "Every current must-priority requirement (not superseded, retired, or closed without the implemented tag) must have a scenario and a test";
     readonly enforcementClass: "canonical";
     readonly category: "coverage";
 }, {

package/dist/utils/rule-registry.generated.js

@@ -10,7 +10,7 @@
 export const GENERATED_RULES = [
     {
         name: "must-priority-coverage",
-        description: "Every must-priority requirement must have a scenario and a test",
+        description: "Every current must-priority requirement (not superseded, retired, or closed without the implemented tag) must have a scenario and a test",
         enforcementClass: "canonical",
         category: "coverage",
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kibi-cli",
-  "version": "2.22.1",
+  "version": "2.23.0",
   "type": "module",
   "description": "Kibi CLI for knowledge base management",
   "engines": {
@@ -235,7 +235,7 @@
     "fast-glob": "^3.2.12",
     "gray-matter": "^4.0.3",
     "js-yaml": "^4.1.0",
-    "kibi-core": "^0.22.0",
+    "kibi-core": "^0.22.1",
     "kibi-plugin-builtin": "^0.5.2",
     "kibi-plugin-sdk": "^0.5.0",
     "kibi-swipl": "^1.0.1",

package/src/public/impact/analyzer.ts

@@ -11,6 +11,7 @@ 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 { isTraceabilityRelationshipType } from "../symbol-granularity.js";
 import {
   createSemanticReviewDiagnostics,
   createSymbolGranularityDiagnostics,
@@ -153,7 +154,18 @@ export async function analyzeChangedFileImpact(
             manifestResults: activeManifestResults,
             symbolsByFile,
           }),
-          ...createSemanticReviewDiagnostics({ symbolsByFile }),
+          ...createSemanticReviewDiagnostics({
+            symbolsByFile,
+            linkedSourceFiles: new Set(
+              activeManifestResults
+                .filter((result) =>
+                  result.relationships.some((relationship) =>
+                    isTraceabilityRelationshipType(relationship.type),
+                  ),
+                )
+                .map((result) => result.sourceFile as string),
+            ),
+          }),
         ];
   const maxDiagnostics = options.maxDiagnostics;
   const cappedDiagnostics =

package/src/public/impact/diagnostics.ts

@@ -81,6 +81,12 @@ function getGranularSymbolsForSourceFile(
   };
 }
 
+function hasTraceabilityLinks(symbol: ExtractedSymbol): boolean {
+  return (symbol.relationships ?? []).some((relationship) =>
+    isTraceabilityRelationshipType(relationship.type),
+  );
+}
+
 function formatRelationshipTargets(symbol: ExtractedSymbol): string {
   const targets = [
     ...new Set(
@@ -183,15 +189,26 @@ export function createSemanticReviewDiagnostics(
       if (!isChangedBehavioralReviewCandidate(symbol)) continue;
 
       const linkedTargets = formatRelationshipTargets(symbol);
+      const file = symbol.location.file;
+      // In a file no requirement owns at all, the changed behavior has no
+      // recorded intent, so the review is "record it", not "compare it with
+      // its links". Elsewhere a coarser symbol of the file may still own it.
+      const unlinked =
+        !hasTraceabilityLinks(symbol) &&
+        !(options.linkedSourceFiles?.has(file) ?? false);
       diagnostics.push({
         id: "symbol_semantic_review_needed",
         severity: "warning",
         blocking: false,
         category: "symbol",
-        files: [symbol.location.file],
+        files: [file],
         docs: ["docs/symbol-traceability-taxonomy.md"],
-        message: `Changed behavioral symbol ${symbol.name} needs semantic review against linked Kibi coverage: ${linkedTargets}`,
-        suggestion: `Use kb_search and kb_query for ${symbol.location.file}, then verify that ${linkedTargets} actually describe and test the changed behavior or UI copy. Update Kibi links or requirements/tests while the edit context is fresh.`,
+        message: unlinked
+          ? `Changed behavioral symbol ${symbol.name} is in a file no requirement owns, so no recorded intent covers the behavior it has after this change`
+          : `Changed behavioral symbol ${symbol.name} needs semantic review against linked Kibi coverage: ${linkedTargets}`,
+        suggestion: unlinked
+          ? `If the change adds or alters behavior, record it with the change: kb_search({query:"<the behavior>", sourceLocations:[{path:"${file}"}]}) for a requirement that already describes it and link ${symbol.name} to it; if none does, kb_upsert a requirement with a scenario and link the symbol with implements. If behavior is unchanged (a refactor, renaming), say so in the final report instead.`
+          : `Use kb_search and kb_query for ${file}, then verify that ${linkedTargets} actually describe and test the changed behavior or UI copy. Update Kibi links or requirements/tests while the edit context is fresh.`,
       });
     }
   }

package/src/public/impact/types.ts

@@ -49,6 +49,8 @@ export type SymbolGranularityDiagnosticsOptions = {
 
 export type SemanticReviewDiagnosticsOptions = {
   readonly symbolsByFile: SymbolsByFile;
+  /** Source files where some manifest symbol carries a traceability link. */
+  readonly linkedSourceFiles?: ReadonlySet<string>;
 };
 
 export type SymbolQualityDiagnosticsOptions = {