kibi-cli 2.39.0 → 2.40.0

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":"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;IAC3B,MAAM,CAAC,EAAE,IAAI,GAAG,SAAS,GAAG,aAAa,GAAG,QAAQ,CAAC;CACtD,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;AA0ND,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;;;GAGG;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,CAuB5B;AA0DD,OAAO,EAAE,oBAAoB,EAAE,CAAC"}
+{"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;AAMvF,OAAO,EAEL,oBAAoB,EACrB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EACL,KAAK,UAAU,EACf,KAAK,UAAU,EAEhB,MAAM,iCAAiC,CAAC;AAEzC,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAE7D,KAAK,oBAAoB,GAAG,uBAAuB,GAAG;IACpD,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,MAAM,CAAC,EAAE,IAAI,GAAG,SAAS,GAAG,aAAa,GAAG,QAAQ,CAAC;CACtD,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;AAuND,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;;;GAGG;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,CA4B5B;AAED,KAAK,aAAa,GAAG;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAE5D;;;GAGG;AAEH,wBAAgB,4BAA4B,CAAC,QAAQ,EAAE;IACrD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,SAAS;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAC1C,eAAe,CAAC,EAAE,SAAS,CAAC,aAAa,GAAG;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,EAAE,CAAC;CACnE,GAAG,OAAO,CAeV;AA4DD,OAAO,EAAE,oBAAoB,EAAE,CAAC"}

package/dist/traceability/symbol-extract.js

@@ -1,7 +1,9 @@
 import { createHash } from "node:crypto";
 import { readManifestWithCoordinateOverlay } from "../extractors/manifest.js";
+import { declarationTitleAliases, matchDeclarationTitle, } from "../extractors/symbol-title-match.js";
 import { createTsMorphSourceAnalysisProvider, isPrivateClassMember, } from "../extractors/symbols-ts.js";
 import { inferSymbolRole, } from "../public/symbol-granularity.js";
+import { analysisObligation } from "./analysis-gate.js";
 const TRACEABILITY_RELATIONSHIP_TYPES = new Set([
     "implements",
     "covered_by",
@@ -103,7 +105,7 @@ function extractRelationshipsFromManifestRecord(record) {
     }
     return relationships;
 }
-function buildSymbolResult(stagedFile, name, kind, span, inlineReqLinks, manifestLookup) {
+function buildSymbolResult(stagedFile, name, kind, span, inlineReqLinks, manifestLookup, nestedSpans = []) {
     const { id, relationships } = resolveSymbolTraceability(stagedFile.path, name, manifestLookup);
     const manifestReqLinks = getRequirementLinks(relationships);
     const mergedReqLinks = inlineReqLinks.length > 0 ? inlineReqLinks : manifestReqLinks;
@@ -117,7 +119,7 @@ function buildSymbolResult(stagedFile, name, kind, span, inlineReqLinks, manifes
             startLine: span.startLine,
             endLine: span.endLine,
         },
-        hunkRanges: intersectingHunks(span.startLine, span.endLine, stagedFile.hunkRanges),
+        hunkRanges: ownedHunks(span, nestedSpans, stagedFile.hunkRanges),
         reqLinks: mergedReqLinks,
         ...(relationships !== undefined ? { relationships } : {}),
     };
@@ -215,11 +217,33 @@ export async function extractSymbolsFromStagedFileAsync(stagedFile, manifestLook
     else {
         analysis = analyzeWithBuiltinFallback(stagedFile.path, content);
     }
+    // A local gap (a macro, an include, a dynamic definition) does not hide the
+    // declarations the parser placed, so those are validated; a changed line
+    // that no placed declaration contains is reviewed at file level instead.
+    if (analysis && partialAnalysisSymbolsUsable(analysis))
+        return symbolsFromAnalysis(stagedFile, analysis, manifestLookup);
     if (analysis?.status === "failed" || analysis?.status === "partial") {
         throw new Error(`Source analysis ${analysis.status} for ${stagedFile.path}; complete symbol validation is unavailable`);
     }
     return symbolsFromAnalysis(stagedFile, analysis, manifestLookup);
 }
+/**
+ * Whether a partial result still places its declarations: every gap is local
+ * (no parser, timeout or integrity finding) and no output cap hid symbols.
+ */
+// implements REQ-cli-staged-impact-enforcement
+export function partialAnalysisSymbolsUsable(analysis) {
+    if (analysis.status !== "partial")
+        return false;
+    const codes = (analysis.diagnostics ?? []).map((item) => item.code);
+    if (codes.some((code) => /LIMIT/i.test(code)))
+        return false;
+    return (analysisObligation("after", {
+        status: "partial",
+        diagnosticCodes: codes,
+        uncoveredRanges: analysis.uncoveredRanges ?? [],
+    }, []).kind !== "blocked");
+}
 function symbolsFromAnalysis(stagedFile, analysis, manifestLookup) {
     if (!analysis)
         return [];
@@ -234,8 +258,9 @@ function symbolsFromAnalysis(stagedFile, analysis, manifestLookup) {
     }
     const results = [];
     for (const symbol of analysis.symbols) {
+        const nested = nestedSpans(symbol, analysis.symbols);
         try {
-            results.push(buildSymbolResult(stagedFile, sourceSymbolLocator(symbol, analysis.symbols, stagedFile.path, manifestLookup), symbol.kind, { startLine: symbol.startLine, endLine: symbol.endLine }, parseReqDirectives(symbol.directiveText ?? ""), manifestLookup));
+            results.push(buildSymbolResult(stagedFile, sourceSymbolLocator(symbol, analysis.symbols, stagedFile.path, manifestLookup), symbol.kind, { startLine: symbol.startLine, endLine: symbol.endLine }, parseReqDirectives(symbol.directiveText ?? ""), manifestLookup, nested));
         }
         catch (error) {
             if (analysis.status !== undefined)
@@ -252,13 +277,37 @@ function symbolsFromAnalysis(stagedFile, analysis, manifestLookup) {
     return results;
 }
 export { isPrivateClassMember };
-function intersectingHunks(startLine, endLine, hunks) {
-    const out = [];
-    for (const h of hunks) {
-        if (rangesIntersect(startLine, endLine, h.start, h.end))
-            out.push(h);
-    }
-    return out;
+/** Spans of the other declarations strictly inside a declaration's span. */
+function nestedSpans(symbol, symbols) {
+    return symbols
+        .filter((other) => other !== symbol &&
+        symbol.startLine <= other.startLine &&
+        other.endLine <= symbol.endLine &&
+        (other.startLine !== symbol.startLine ||
+            other.endLine !== symbol.endLine))
+        .sort((left, right) => left.startLine - right.startLine);
+}
+/**
+ * Hunks with a changed line inside the span that no nested declaration
+ * contains: a line inside a member changes the member, not its class.
+ */
+function ownedHunks(span, nested, hunks) {
+    return hunks.filter((hunk) => {
+        if (!rangesIntersect(span.startLine, span.endLine, hunk.start, hunk.end))
+            return false;
+        const end = Math.min(span.endLine, hunk.end);
+        let line = Math.max(span.startLine, hunk.start);
+        for (const child of nested) {
+            if (child.endLine < line)
+                continue;
+            if (child.startLine > line)
+                return true;
+            line = child.endLine + 1;
+            if (line > end)
+                return false;
+        }
+        return line <= end;
+    });
 }
 // implements REQ-cli-staged-impact-enforcement
 function sourceSymbolLocator(symbol, symbols, filePath, lookup) {
@@ -267,10 +316,15 @@ function sourceSymbolLocator(symbol, symbols, filePath, lookup) {
         return symbol.name;
     if (lookup?.has(`${filePath}:${qualified}`))
         return qualified;
-    // Preserve an authored legacy unqualified locator only when unambiguous.
-    if (symbols.filter((candidate) => candidate.name === symbol.name).length ===
-        1 &&
-        lookup?.has(`${filePath}:${symbol.name}`))
-        return symbol.name;
+    // Another title sync places on this declaration alone: a Terraform
+    // address, a bare name no other declaration shares, a class named like
+    // its constructors.
+    for (const title of [...declarationTitleAliases(symbol), symbol.name]) {
+        if (!lookup?.has(`${filePath}:${title}`))
+            continue;
+        const match = matchDeclarationTitle(title, symbols, filePath);
+        if ("symbol" in match && match.symbol === symbol)
+            return title;
+    }
     return qualified;
 }

package/dist/traceability/validate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../src/traceability/validate.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,aAAa,EAAmB,MAAM,cAAc,CAAC;AACnE,OAAO,EACL,KAAK,eAAe,EAIrB,MAAM,oBAAoB,CAAC;AAE5B,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,aAAa,CAAC;CACvB;AAED,MAAM,WAAW,SAAS;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,iBAAS,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAO1C;AAED,iBAAS,kBAAkB,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CA0B/C;AAED,iBAAS,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CA8CnD;AAED,iBAAS,sBAAsB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,EAAE,CAuBzD;AAGD,wBAAsB,qBAAqB,CACzC,OAAO,EAAE,iBAAiB,GACzB,OAAO,CAAC,SAAS,EAAE,CAAC,CAgDtB;AAED;;;;;GAKG;AAEH,wBAAsB,4BAA4B,CAAC,OAAO,EAAE;IAC1D,MAAM,EAAE,aAAa,CAAC;IACtB,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACpC,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC,CAgB7B;AAED,8EAA8E;AAE9E,wBAAgB,wBAAwB,CACtC,UAAU,EAAE,SAAS,eAAe,EAAE,GACrC,MAAM,CAaR;AAED,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,SAAS,EAAE,GAAG,MAAM,CAkBhE;AAGD,eAAO,MAAM,QAAQ;;;;;CAKpB,CAAC"}
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../src/traceability/validate.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,aAAa,EAAmB,MAAM,cAAc,CAAC;AACnE,OAAO,EACL,KAAK,eAAe,EAIrB,MAAM,oBAAoB,CAAC;AAE5B,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,aAAa,CAAC;CACvB;AAED,MAAM,WAAW,SAAS;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,iBAAS,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAO1C;AAED,iBAAS,kBAAkB,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CA0B/C;AAED,iBAAS,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CA8CnD;AAED,iBAAS,sBAAsB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,EAAE,CAuBzD;AAGD,wBAAsB,qBAAqB,CACzC,OAAO,EAAE,iBAAiB,GACzB,OAAO,CAAC,SAAS,EAAE,CAAC,CAgDtB;AAED;;;;;GAKG;AAEH,wBAAsB,4BAA4B,CAAC,OAAO,EAAE;IAC1D,MAAM,EAAE,aAAa,CAAC;IACtB,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACpC,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC,CAgB7B;AAED,8EAA8E;AAE9E,wBAAgB,wBAAwB,CACtC,UAAU,EAAE,SAAS,eAAe,EAAE,GACrC,MAAM,CAaR;AAED,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,SAAS,EAAE,GAAG,MAAM,CAoBhE;AAGD,eAAO,MAAM,QAAQ;;;;;CAKpB,CAAC"}

package/dist/traceability/validate.js

@@ -188,15 +188,13 @@ export function formatViolations(violations) {
         return "";
     const total = violations.length;
     const minLinks = violations[0]?.requiredLinks ?? 0;
-    const lines = [];
-    lines.push(`Traceability failed: ${total}/${total} staged symbols unlinked (minLinks=${minLinks})`);
+    const lines = [
+        `Traceability failed: ${total} changed symbol(s) have fewer than ${minLinks} requirement link(s) (minLinks=${minLinks}):`,
+    ];
     for (const v of violations) {
-        const loc = `${v.file}:${v.line}`;
-        const name = `${v.name}()`;
-        // Suggest adding requirement links with role-specific guidance
-        const suggestion = "Add ownership: implements: REQ-<area>-<behavior> (production code), use covered_by for production coverage, or executable_for for executable test code";
-        lines.push(`${loc}  ${name}  -> ${suggestion}`);
+        lines.push(`  ${v.file}:${v.line}  ${v.name}  (${v.currentLinks} of ${v.requiredLinks} link(s))`);
     }
+    lines.push("To link a symbol, give it an owning requirement, stage the change and re-run kibi check --staged:", `  - Add a .kb/symbols.yaml entry with kb_upsert (CLI: kibi upsert --input -): title as listed above (e.g. ${JSON.stringify(violations[0]?.name ?? "")}), sourceFile, and the relationship implements -> REQ-<area>-<behavior> for production code or executable_for -> TEST-<area>-<behavior> for executable test code. Stage .kb/symbols.yaml with the code.`, "  - Or write a comment `implements REQ-<area>-<behavior>` directly above the declaration.", "  If no requirement fits, find one with kb_search or create it with kb_upsert (type req) first; production symbols also need covered_by -> TEST-<area>-<behavior>.");
     return lines.join("\n");
 }
 // Test helpers for edge-case coverage

package/dist/utils/first-sentence.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The first sentence of prose, used to title a requirement. A sentence ends
+ * at `.`, `!` or `?` followed by whitespace and an uppercase letter, or at
+ * the end of the text, so the dot in a path (`src/match.c`), a dotted name
+ * (`console.log`, `exec.Command`), a version (`v1.2`), an abbreviation or
+ * backticks never cuts it. A closing dot is dropped.
+ */
+export declare function firstSentence(text: string): string;
+//# sourceMappingURL=first-sentence.d.ts.map

package/dist/utils/first-sentence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"first-sentence.d.ts","sourceRoot":"","sources":["../../src/utils/first-sentence.ts"],"names":[],"mappings":"AAyBA;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAmBlD"}

package/dist/utils/first-sentence.js

@@ -0,0 +1,52 @@
+/*
+ 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/>.
+*/
+/** Abbreviations whose dot does not end a sentence. */
+const ABBREVIATION = /(?:^|[\s(])(?:e\.g|i\.e|etc|vs|cf|approx)\.$/i;
+/** After a sentence end: whitespace, then an uppercase letter (maybe quoted). */
+const NEXT_SENTENCE = /^\s+["'(“]?\p{Lu}/u;
+// implements REQ-mcp-semantic-advisor-preflight
+/**
+ * The first sentence of prose, used to title a requirement. A sentence ends
+ * at `.`, `!` or `?` followed by whitespace and an uppercase letter, or at
+ * the end of the text, so the dot in a path (`src/match.c`), a dotted name
+ * (`console.log`, `exec.Command`), a version (`v1.2`), an abbreviation or
+ * backticks never cuts it. A closing dot is dropped.
+ */
+export function firstSentence(text) {
+    const value = text.trim();
+    let quoted = false;
+    for (let index = 0; index < value.length; index += 1) {
+        const char = value[index] ?? "";
+        if (char === "`") {
+            quoted = !quoted;
+            continue;
+        }
+        if (quoted || (char !== "." && char !== "!" && char !== "?"))
+            continue;
+        const rest = value.slice(index + 1);
+        const atEnd = rest.trim() === "";
+        if (!atEnd && !NEXT_SENTENCE.test(rest))
+            continue;
+        if (char === "." && ABBREVIATION.test(value.slice(0, index + 1)))
+            continue;
+        return (char === "." ? value.slice(0, index) : value.slice(0, index + 1))
+            .replace(/\.+$/, "")
+            .trim();
+    }
+    return value;
+}

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

@@ -18,6 +18,12 @@ export declare const GENERATED_RULES: readonly [{
     readonly description: "A symbol with traceability relationships must not link its source file coarsely while narrower behavioral symbols are available, unless it carries an allowed granularity_reason; the staged gate's symbol_granularity_violation evaluated KB-wide";
     readonly enforcementClass: "canonical";
     readonly category: "traceability";
+}, {
+    readonly name: "symbol-coordinates-missing";
+    readonly description: "Advisory: an active symbol names a source file that exists, but Kibi could not place it there (the declaration was not found, the file is unreadable to the analyzer, or a declared plugin or grammar pack is missing), so its link is checked against no code";
+    readonly enforcementClass: "advisory";
+    readonly category: "traceability";
+    readonly diagnosticSeverity: "warning";
 }, {
     readonly name: "no-dangling-refs";
     readonly description: "All relationship targets must exist in the KB";

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

@@ -1 +1 @@
-{"version":3,"file":"rule-registry.generated.d.ts","sourceRoot":"","sources":["../../src/utils/rule-registry.generated.ts"],"names":[],"mappings":"AAUA,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA0ZlB,CAAC"}
+{"version":3,"file":"rule-registry.generated.d.ts","sourceRoot":"","sources":["../../src/utils/rule-registry.generated.ts"],"names":[],"mappings":"AAUA,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAkalB,CAAC"}

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

@@ -32,6 +32,13 @@ export const GENERATED_RULES = [
         enforcementClass: "canonical",
         category: "traceability",
     },
+    {
+        name: "symbol-coordinates-missing",
+        description: "Advisory: an active symbol names a source file that exists, but Kibi could not place it there (the declaration was not found, the file is unreadable to the analyzer, or a declared plugin or grammar pack is missing), so its link is checked against no code",
+        enforcementClass: "advisory",
+        category: "traceability",
+        diagnosticSeverity: "warning",
+    },
     {
         name: "no-dangling-refs",
         description: "All relationship targets must exist in the KB",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kibi-cli",
-  "version": "2.39.0",
+  "version": "2.40.0",
   "type": "module",
   "description": "Kibi CLI for knowledge base management",
   "engines": {
@@ -239,14 +239,14 @@
     "fast-glob": "^3.2.12",
     "gray-matter": "^4.0.3",
     "js-yaml": "^4.1.0",
-    "kibi-core": "^0.28.0",
-    "kibi-plugin-builtin": "^0.5.3",
-    "kibi-plugin-sdk": "^0.5.1",
+    "kibi-core": "^0.29.0",
+    "kibi-plugin-builtin": "^0.5.4",
+    "kibi-plugin-sdk": "^0.6.0",
     "kibi-swipl": "^1.0.1",
     "saxes": "^6.0.0",
     "ignore": "^5.3.0",
     "yaml": "^2.9.1",
-    "kibi-agent-core": "^0.11.0"
+    "kibi-agent-core": "^0.11.1"
   },
   "devDependencies": {
     "@types/node": "latest",

package/src/public/operations/check-executor.ts

@@ -61,6 +61,7 @@ import {
   collectSourcePathDanglingViolations,
 } from "./source-path-dangling.js";
 import { collectSourceRelationshipParityViolations } from "./source-relationship-parity.js";
+import { collectSymbolCoordinatesMissingViolations } from "./symbol-coordinates-check.js";
 import { collectSymbolGranularityViolations } from "./symbol-granularity-check.js";
 import type { OperationResult } from "./types.js";
 import { readWorkspaceSnapshot } from "./workspace-snapshot.js";
@@ -414,6 +415,12 @@ export async function executeCheck(
       rulesAllowlist,
       analysisCacheDir(context, workspaceRoot, options),
     );
+    const symbolCoordinateFindings =
+      await collectSymbolCoordinatesMissingViolations(
+        prolog,
+        workspaceRoot,
+        rulesAllowlist,
+      );
     const originReviewFindings = await collectOriginReviewViolations(
       prolog,
       rulesAllowlist,
@@ -449,6 +456,7 @@ export async function executeCheck(
       ...sourceRelationshipParityViolations,
       ...sourcePathFindings,
       ...symbolGranularityFindings,
+      ...symbolCoordinateFindings,
       ...predicateConformanceFindings,
       ...originReviewFindings,
       ...entityContextFindings,

package/src/public/operations/evidence-floor.ts

@@ -46,6 +46,12 @@ export type EvidenceFloorRow = Readonly<{
   proofGaps: readonly string[];
   /** The tests and symbols behind the gaps; empty lists are left out. */
   gapDetails?: Readonly<Record<string, readonly string[]>>;
+  /** Claims a proof refuted: the test, the claim and what the test read. */
+  refutations?: readonly Readonly<{
+    test: string;
+    claimKey: string;
+    reason: string;
+  }>[];
 }>;
 
 type EvidenceFloorPayload = {
@@ -100,7 +106,28 @@ export function gapDetailLines(row: EvidenceFloorRow): string[] {
   );
 }
 
+/** Gaps a refuted claim leaves that a derived proof would have covered. */
+const REFUTATION_GAPS = new Set(["happy_path_only", "uncovered_case"]);
+
+/** Each refuted claim in plain words: which test refutes it and why. */
+// implements REQ-kibi-claim-bound-proofs
+export function refutationText(row: EvidenceFloorRow): string | undefined {
+  const refutations = row.refutations ?? [];
+  if (refutations.length === 0) return undefined;
+  return refutations
+    .map(
+      (refutation) =>
+        `${refutation.test} refutes ${refutation.claimKey}: ${refutation.reason}`,
+    )
+    .join("; ");
+}
+
 function suggestionFor(row: EvidenceFloorRow): string {
+  const refuted = refutationText(row);
+  if (refuted !== undefined) {
+    const following = row.proofGaps.filter((gap) => REFUTATION_GAPS.has(gap));
+    return `The code breaks a claim of ${row.id} (${refuted}). Fix the code so it keeps the claim, or, with the person who owns the rule, change the requirement, then run kibi prove${following.length > 0 ? `; ${following.join(" and ")} ${following.length > 1 ? "clear" : "clears"} once the proof derives the claim` : ""}. kibi proof explain ${row.id} shows each claim's bindings.`;
+  }
   if (row.status === "pending_reproof")
     return `Run kibi prove for the tests behind ${row.id} so its receipts match the current code, then rerun kibi check --fresh-evidence.`;
   switch (row.requiredEvidence) {
@@ -127,7 +154,7 @@ export function evidenceFloorViolations(
       description:
         row.status === "pending_reproof"
           ? `${row.id} is ${row.evidenceLevel} but needs ${row.requiredEvidence} (${floorSource(row)}); its receipts are older than the code`
-          : `${row.id} is ${row.evidenceLevel} but needs ${row.requiredEvidence} (${floorSource(row)})`,
+          : `${row.id} is ${row.evidenceLevel} but needs ${row.requiredEvidence} (${floorSource(row)})${refutationText(row) === undefined ? "" : `; its proof refutes a claim: ${refutationText(row)}`}`,
       suggestion: suggestionFor(row),
       evidence: {
         evidenceLevel: row.evidenceLevel,
@@ -137,6 +164,7 @@ export function evidenceFloorViolations(
         proofStatus: row.proofStatus,
         proofGaps: row.proofGaps,
         ...(row.gapDetails === undefined ? {} : { gapDetails: row.gapDetails }),
+        ...(row.refutations?.length ? { refutations: row.refutations } : {}),
       },
     }));
 }

package/src/public/operations/specs/check-rules.generated.ts

@@ -14,6 +14,7 @@ export const SELECTABLE_RULE_NAMES: readonly string[] = [
   "symbol-coverage",
   "symbol-traceability",
   "symbol-granularity",
+  "symbol-coordinates-missing",
   "no-dangling-refs",
   "source-relationship-parity",
   "branch-store-not-compiled",
@@ -73,4 +74,4 @@ export const SELECTABLE_RULE_NAMES: readonly string[] = [
 // implements REQ-006
 /** Comma-separated "Allowed:" fragment for the kb_check rules description. */
 export const SELECTABLE_RULES_ALLOWED =
-  "must-priority-coverage, symbol-coverage, symbol-traceability, symbol-granularity, no-dangling-refs, source-relationship-parity, branch-store-not-compiled, source-path-dangling, no-cycles, required-fields, deprecated-adr-no-successor, superseded-requirement-open, scenario-feasibility, scenario-feasibility-unknown, scenario-outcome-mismatch, exception-claim-keys, numeric-string-value, rule-key-arguments-missing, domain-contradictions, logic-coverage, rule-safety, rule-verifiability, query-plan-safety, req-status-vocabulary, strict-fact-shape, strict-req-fact-pairing, predicate-verifiability, strict-readiness, semantic-completeness, related-requirement-unmodeled, proof-contract-symbols, entity-id-style, domain-redundancy, domain-implication, subject-key-identity, subject-key-shape, ontology-quality, exception-unapproved, exception-approval-self-attested, agent-requirement-unapproved, requirement-rationale-missing, symbol-owner-superseded, adr-unlinked, adr-proposed, predicate-schema-conformance, entity-context-missing, entity-context-acknowledged, decision-firm-unreferenced, decision-firm-superseded, decision-firm-edited, supersedes-reason-missing, supersedes-reason-acknowledged, policy-ownership, policy-markers, kb-consistency, kb-consistency-unresolved, evidence-floor, proof-contract-claims";
+  "must-priority-coverage, symbol-coverage, symbol-traceability, symbol-granularity, symbol-coordinates-missing, no-dangling-refs, source-relationship-parity, branch-store-not-compiled, source-path-dangling, no-cycles, required-fields, deprecated-adr-no-successor, superseded-requirement-open, scenario-feasibility, scenario-feasibility-unknown, scenario-outcome-mismatch, exception-claim-keys, numeric-string-value, rule-key-arguments-missing, domain-contradictions, logic-coverage, rule-safety, rule-verifiability, query-plan-safety, req-status-vocabulary, strict-fact-shape, strict-req-fact-pairing, predicate-verifiability, strict-readiness, semantic-completeness, related-requirement-unmodeled, proof-contract-symbols, entity-id-style, domain-redundancy, domain-implication, subject-key-identity, subject-key-shape, ontology-quality, exception-unapproved, exception-approval-self-attested, agent-requirement-unapproved, requirement-rationale-missing, symbol-owner-superseded, adr-unlinked, adr-proposed, predicate-schema-conformance, entity-context-missing, entity-context-acknowledged, decision-firm-unreferenced, decision-firm-superseded, decision-firm-edited, supersedes-reason-missing, supersedes-reason-acknowledged, policy-ownership, policy-markers, kb-consistency, kb-consistency-unresolved, evidence-floor, proof-contract-claims";

package/src/public/operations/specs/reporting.ts

@@ -37,6 +37,32 @@ const ENTITY_TYPES = [
 ] as const;
 const ENTITY_TYPE_SET: ReadonlySet<string> = new Set(ENTITY_TYPES);
 
+/**
+ * The engine names the attached store by its directory key (a SHA-256 of the
+ * branch name); meta.branch carries the branch name, as kb_status does, and
+ * the key moves to meta.branchStoreKey.
+ */
+// implements REQ-kibi-verification-evidence-contract
+export function withBranchName<
+  T extends { readonly meta?: Readonly<Record<string, unknown>> },
+>(payload: T, context: Pick<OperationContext, "branchAttachment">): T {
+  const meta = payload.meta;
+  const name = context.branchAttachment?.kbBranch;
+  if (meta === undefined || name === undefined || meta.branch === name)
+    return payload;
+  const key = typeof meta.branch === "string" ? meta.branch : undefined;
+  return {
+    ...payload,
+    meta: {
+      ...meta,
+      branch: name,
+      ...(key !== undefined && key !== "unknown"
+        ? { branchStoreKey: key }
+        : {}),
+    },
+  };
+}
+
 export type FindGapsInput = {
   readonly type?: string;
   readonly missingRelationships?: readonly string[];
@@ -161,7 +187,10 @@ export async function executeFindGaps(
               : `Found ${payload.count ?? rows.length} gap rows. Showing ${rows.length}: ${rows.map((row) => row.id).join(", ")}.${stubNote}`,
         },
       ],
-      structuredContent: confirmMetaFreshness(payload, context.workspaceRoot),
+      structuredContent: withBranchName(
+        confirmMetaFreshness(payload, context.workspaceRoot),
+        context,
+      ),
     };
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
@@ -418,7 +447,10 @@ export async function executeCoverage(
     const migrationPlan = statusPlan
       ? mergeMigrationPlans([statusPlan, coveragePlan])
       : coveragePlan;
-    const confirmed = confirmMetaFreshness(payload, context.workspaceRoot);
+    const confirmed = withBranchName(
+      confirmMetaFreshness(payload, context.workspaceRoot),
+      context,
+    );
     const enrichedPayload = {
       ...confirmed,
       rows,
@@ -581,7 +613,10 @@ export async function executeGraph(
               : `Graph traversal returned ${nodes.length} nodes and ${edges.length} edges from ${input.seedIds.join(", ")}.`,
         },
       ],
-      structuredContent: confirmMetaFreshness(payload, context.workspaceRoot),
+      structuredContent: withBranchName(
+        confirmMetaFreshness(payload, context.workspaceRoot),
+        context,
+      ),
     };
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);

package/src/public/operations/specs/semantic.ts

@@ -7,6 +7,7 @@ import type {
   SemanticAdvisorReceipt,
 } from "../../../operations/semantic-advisor/types.js";
 import { publicCapabilityStamp } from "../../../plugins/compose-semantic-classifier.js";
+import { firstSentence } from "../../../utils/first-sentence.js";
 import type { OperationContext, PrologPort } from "../runtime-types.js";
 import type { OperationSpec } from "../types.js";
 
@@ -59,7 +60,7 @@ export async function executeSemanticAdvisor(
 ): Promise<SemanticAdvisorOperationResult> {
   const text = requiredText(args.text);
   const id = optionalString(args.id) ?? "REQ-SEMANTIC-ADVISOR-PREVIEW";
-  const title = optionalString(args.title) ?? text.split(/[.!?]/, 1)[0] ?? text;
+  const title = optionalString(args.title) ?? (firstSentence(text) || text);
   const source = optionalString(args.source) ?? "mcp://kibi/semantic-advisor";
   const orchestrated = await analyzeSemanticAdvisorInputWithPlugins(
     {

package/src/public/operations/symbol-coordinates-check.ts

@@ -0,0 +1,79 @@
+/*
+ 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 { existsSync, statSync } from "node:fs";
+import * as path from "node:path";
+import { parseEntityFromList, parseListOfLists } from "../../prolog/codec.js";
+import type { Violation } from "../../utils/rule-registry.js";
+import type { PrologPort } from "./runtime-types.js";
+
+/**
+ * A symbol whose source file exists but which Kibi could not place in it is
+ * linked to no code: impact review, coverage and proofs never see it there.
+ * kibi sync names it in its refresh output only, so the check reports every
+ * such symbol as a warning (advisory, non-blocking).
+ */
+// implements REQ-cli-check, REQ-generated-coordinate-persistence
+export const SYMBOL_COORDINATES_MISSING_RULE = "symbol-coordinates-missing";
+
+const SYMBOL_PLACEMENT_QUERY =
+  "findall([Id,symbol,Fields], (kb_entity(Id, symbol, Props), include([Key=_]>>memberchk(Key, [title,status,sourceFile,sourceLine]), Props, Fields)), Rows)";
+
+const INACTIVE_STATUSES = new Set([
+  "deprecated",
+  "removed",
+  "retired",
+  "superseded",
+]);
+
+// implements REQ-cli-check
+export async function collectSymbolCoordinatesMissingViolations(
+  prolog: Pick<PrologPort, "query">,
+  workspaceRoot: string,
+  rules: ReadonlySet<string>,
+): Promise<Violation[]> {
+  if (!rules.has(SYMBOL_COORDINATES_MISSING_RULE)) return [];
+  const rows = await prolog.query(SYMBOL_PLACEMENT_QUERY);
+  if (!rows.success)
+    throw new Error(
+      `symbol-coordinates-missing symbol projection failed: ${rows.error ?? "unknown error"}`,
+    );
+  const violations: Violation[] = [];
+  for (const row of parseListOfLists(rows.bindings.Rows ?? "[]")) {
+    const entity = parseEntityFromList(row);
+    const id = typeof entity.id === "string" ? entity.id : "";
+    const sourceFile =
+      typeof entity.sourceFile === "string" ? entity.sourceFile : "";
+    const status = typeof entity.status === "string" ? entity.status : "";
+    if (id === "" || sourceFile === "" || INACTIVE_STATUSES.has(status))
+      continue;
+    if (entity.sourceLine !== undefined && entity.sourceLine !== null) continue;
+    const absolute = path.resolve(workspaceRoot, sourceFile);
+    if (!existsSync(absolute) || !statSync(absolute).isFile()) continue;
+    const title = typeof entity.title === "string" ? entity.title : id;
+    violations.push({
+      rule: SYMBOL_COORDINATES_MISSING_RULE,
+      entityId: id,
+      source: sourceFile,
+      description: `${id} (${title}) has no symbol coordinates in ${sourceFile}: Kibi could not place it, so its links are checked against no code`,
+      suggestion:
+        "Run kibi sync --refresh-symbol-coordinates and read its failed lines; use the name the extractor gives the declaration, install the plugins and grammar packs kibi doctor names, or add symbol_role and granularity_reason for a file-level link.",
+    });
+  }
+  return violations;
+}

package/src/public/proof-protocol-types.d.ts

@@ -99,13 +99,21 @@ export type ProofContract = Readonly<{
     | "state_machine"
     | "regex"
     | "source";
-  domain_source?: Readonly<{ symbol_id: string; export?: string; field?: string }>;
+  domain_source?: Readonly<{
+    symbol_id: string;
+    export?: string;
+    field?: string;
+    /** A SWI-Prolog predicate's argument (1-based) that names each member. */
+    arg?: number;
+  }>;
   witness?: Readonly<{ path: string }>;
   constraint_source?: Readonly<{ fact_ids: readonly string[] }>;
   value_source?: readonly (
     | Readonly<{
         symbol_id: string;
         export?: string;
+        /** A SWI-Prolog predicate's argument (1-based) that holds the value. */
+        arg?: number;
         /** value (default): the export is a number; count: the size of a list, set, map or object. */
         measure?: "value" | "count";
       }>
@@ -130,12 +138,20 @@ export type ProofContract = Readonly<{
   domains?: Readonly<
     Record<
       string,
-      | Readonly<{ symbol_id: string; export?: string }>
+      | Readonly<{ symbol_id: string; export?: string; arg?: number }>
       | Readonly<{ source: ProofSourceSpec }>
     >
   >;
-  initial_source?: Readonly<{ symbol_id: string; export?: string }>;
-  pattern_source?: Readonly<{ symbol_id: string; export?: string }>;
+  initial_source?: Readonly<{
+    symbol_id: string;
+    export?: string;
+    arg?: number;
+  }>;
+  pattern_source?: Readonly<{
+    symbol_id: string;
+    export?: string;
+    arg?: number;
+  }>;
   /** kind source: the project source Kibi reads. */
   source?: ProofSourceSpec;
 }>;
@@ -151,7 +167,8 @@ export type ProofSourceSpec = Readonly<Record<string, unknown>> &
       | "references"
       | "schema"
       | "routes"
-      | "validator";
+      | "validator"
+      | "prolog";
   }>;
 
 export type ProofBinding = Readonly<{