kibi-agent-core 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,11 +1,26 @@
 # kibi-agent-core
 
+## 0.3.0
+
+### Minor Changes
+
+- e00adf2: Projects set up with kibi-cli before 2.18.0 keep every symbol on one flow-sequence line of `.kb/symbols.yaml`, and the host hooks read none of it: the Claude Code hooks told agents that no symbol in a linked file was tied to a requirement, on every edit, when the opposite was true. The shared hook scanner now reads flow-layout manifests like block ones, the Claude Code edit hook no longer calls a file unowned when the manifest is unreadable or when the coordinate artifact binds a symbol to it that the scanner could not read (it says once per session that the manifest could not be read instead), and a plain `kibi sync` rewrites such a manifest in block layout once, keeping comments and order.
+
+  Technical summary: `kibi-agent-core` `knowledge-index` gains a flow-collection reader for `symbols: [ … ]` sections (single or multi-line, CRLF safe) and for flow values inside block records, the index reports `manifest` (`missing` | `empty` | `indexed` | `unreadable`), `coordinateFiles` and `unlinkedFiles`, and the cache format moves to v2 so stale indexes rebuild. `kibi-claude` adds `unreadableManifestNote` (once per session) in place of `unownedSourceNote` for an unreadable manifest or a coordinate-bound file with no indexed record; the Claude and Codex hook bundles are rebuilt. `kibi sync` calls `normalizeManifestLayout` on every tracked symbol manifest ahead of its no-op fast path, through the same `blockifySymbolManifest` helper `kb_upsert`'s manifest writer uses.
+
+## 0.2.1
+
+### Patch Changes
+
+- 2a2b2db: Every Kibi package page on npm now has a README that says what the package is for and how to install it, and links to the documentation site. Package metadata now points npm's "Homepage" link at the documentation site, its "Repository" link at the package's own folder on GitHub, and adds an "Issues" link.
+
+  Adds READMEs to `kibi-cli`, `kibi-mcp`, `kibi-core`, `kibi-runtime`, `kibi-agent-core`, `kibi-codex`, `kibi-plugin-builtin` and `kibi-plugin-sdk`. Sets `homepage` to https://looted.github.io/kibi/, adds `repository.directory` and `bugs` to every package, and refreshes the `kibi-plugin-treesitter` integrity manifest and source-analyzer approval for its changed `package.json`.
+
 ## 0.2.0
 
 ### Minor Changes
 
 - f8fff87: The telemetry acceptance and remediation reports now show whether agents look requirements up before they change requirement-linked code. A new `lookup_before_first_edit` metric gives, per host session, the share of sessions that ran `kb_search` or `kb_query` (through MCP or the CLI) before their first edit of a file whose symbols implement a requirement. Sessions that edited first appear in the report with the file and its exact `.kb/usage.log` line. The data comes from opt-in hook rows that every Kibi host plugin now writes when `KIBI_DIAGNOSTIC_MODE` is set; nothing is recorded otherwise.
-
   - `kibi usage-metrics` / `kb_check` telemetry acceptance: new metric `lookup_before_first_edit` (threshold `>=` policy `lookupBeforeFirstEditMinimum`, default 1) with evidence `unguidedEditPaths` and `lookupOperations`. It is `not_applicable` when no host hook recorded a requirement-linked edit, so logs without hook rows are judged as before. A failed metric adds the advisory diagnostic `lookup_before_first_edit_bypassed` (rank 35).
   - `kibi usage-remediation`: one event item per session whose first linked edit had no earlier lookup, pointing at that hook row.
   - `parseTelemetryUsageLog` still returns only Kibi operation rows; hook rows stay attached to the returned array (read them with `partitionTelemetryUsage`). Remediation `logLine` values now count hook rows and blank lines, so they match the file.
@@ -13,7 +28,6 @@
   - Claude Code: `edited` rows now carry the file's `requirement_ids`, and every row names its `host`. Cursor (`postToolUse`), Codex and ZCode (`PostToolUse`) and OpenCode (`tool.execute.after`) now write the same `kb_usage` and `edited` rows.
 
 - 1012d1c: When an agent edits a file that implements a requirement, every Kibi host plugin (Claude Code, Cursor, Codex, ZCode and OpenCode) now says what that requirement must keep true and the decision behind it, not just its ID. The extra lines come from the requirement's linked facts and ADR, so agents see the constraint before they change the code. All hosts build the snippet with one shared builder in `kibi-agent-core`, so they show the same lines within each host's size limits, and none of them presents a superseded or retired requirement as current.
-
   - New `kibi-agent-core/snippets` export: `fileKnowledgeSnippet`, `requirementGroundingLines`, `editKnowledgeContext`, `editFocus` and `createEntitySummarizer`. Edit snippets add "`<REQ>` must keep true: …" (up to two facts linked via `constrains`, `requires_property`, `requires_predicate` or `requires_rule`) and "Decision: `<ADR>`" for the lead requirement. Read snippets keep the requirement and test lines only.
   - A superseded, deprecated or retired lead requirement gets no "must keep true" or "Decision" lines, so retired policy is not shown as current.
   - Claude Code: the `PreToolUse` edit snippet now comes from the shared builder (no change in content).
@@ -27,7 +41,6 @@
 ### Patch Changes
 
 - 15356de: Host hooks no longer ask for a `kb_check` after a `kb_upsert` dry run. A dry run only validates, so the Cursor, Codex, ZCode and OpenCode hooks now count it as validation rather than a KB write.
-
   - `extractKbMcpToolCall` reports `kb_upsert` with `dryRun: true` as `kb_validate_upsert`.
   - OpenCode's freshness evidence records a dry-run upsert as `kb_validate_upsert`, which carries no mutation evidence.
 

package/README.md

@@ -0,0 +1,17 @@
+# kibi-agent-core
+
+Shared, low-latency helpers for [Kibi](https://looted.github.io/kibi/) agent-host adapters. The Claude Code, Cursor, Codex, OpenCode and ZCode integrations use it to build the short requirement snippets their hooks show before an agent reads or edits linked code (the requirement, what it must keep true, the decision behind it and its tests), to classify paths, and to log opt-in hook usage.
+
+Entry points: `kibi-agent-core`, plus the subpaths `/snippets`, `/knowledge-index`, `/path-policy`, `/kb-mcp-tools` and `/hook-usage-log`.
+
+It is an internal building block of the host plugins, not something you install by hand. To use Kibi, see the [quick start](https://looted.github.io/kibi/guide/quick-start.html).
+
+## Links
+
+- [Documentation](https://looted.github.io/kibi/)
+- [Source](https://github.com/Looted/kibi)
+- [Issues](https://github.com/Looted/kibi/issues)
+
+## License
+
+AGPL-3.0-or-later

package/dist/knowledge-index.d.ts

@@ -13,10 +13,30 @@ export type IndexedSymbol = {
     coveredBy: string[];
     executableFor: string[];
 };
+/**
+ * What the scanner made of `.kb/symbols.yaml`: `missing` (no file), `empty`
+ * (no symbol records, such as the `symbols: []` that `kibi init` writes),
+ * `indexed` (records were read) or `unreadable` (the file has content the
+ * line scanner could not turn into a single record, so an empty index must
+ * not be read as "nothing is linked").
+ */
+export type ManifestState = "missing" | "empty" | "indexed" | "unreadable";
 export type KnowledgeIndex = {
     /** Workspace-relative source file -> symbols with at least one relationship. */
     files: Record<string, IndexedSymbol[]>;
     symbolCount: number;
+    manifest: ManifestState;
+    /**
+     * Workspace-relative source files that `.kb/symbol-coordinates.yaml` binds
+     * a symbol to, whether or not the manifest record for it could be indexed.
+     */
+    coordinateFiles: string[];
+    /**
+     * Workspace-relative source files that have a manifest record but no
+     * symbol with a relationship, so an edit hook can tell "not linked yet"
+     * from "the record could not be read".
+     */
+    unlinkedFiles: string[];
 };
 type RawRecord = Record<string, unknown>;
 /**
@@ -27,11 +47,17 @@ export declare function scanSymbolsManifest(text: string): RawRecord[];
 export type Coordinates = Record<string, {
     line?: number;
     endLine?: number;
+    sourceFile?: string;
 }>;
-/** Scan `coordinates:` -> `<symbol id>:` -> `sourceLine` / `sourceEndLine`. */
+/** Scan `coordinates:` -> `<symbol id>:` -> `sourceLine` / `sourceEndLine` / `sourceFile`. */
 export declare function scanSymbolCoordinates(text: string): Coordinates;
+/**
+ * Manifest state for a scan result: `unreadable` when the file holds content
+ * beyond comments and an empty `symbols` value yet yielded no record.
+ */
+export declare function manifestStateOf(text: string | undefined, recordCount: number): ManifestState;
 /** Collapse raw manifest records and coordinates into the file-keyed index. */
-export declare function buildKnowledgeIndex(records: readonly RawRecord[], coordinates?: Coordinates, options?: KnowledgeIndexOptions): KnowledgeIndex;
+export declare function buildKnowledgeIndex(records: readonly RawRecord[], coordinates?: Coordinates, options?: KnowledgeIndexOptions, manifest?: ManifestState): KnowledgeIndex;
 /**
  * Load the index for a workspace, reusing the cache in `cacheDir` while both
  * manifests keep their size and mtime.

package/dist/knowledge-index.js

@@ -13,14 +13,17 @@ import path from "node:path";
  * file plus a JSON parse.
  *
  * The scanner understands the subset the Kibi writer emits (block mappings and
- * sequences, quoted scalars, no line folding) plus hand-authored flow lists
- * such as `links: [REQ-001]`. The manifest is a hint for progressive
- * disclosure, not the source of truth: snippets always point at kb_query for
- * the authoritative view.
+ * sequences, quoted scalars, no line folding), flow collections wherever a
+ * value starts with `[` or `{` (hand-authored `links: [REQ-001]`, typed
+ * `relationships: [{type: implements, target: REQ-1}]`), and a whole manifest
+ * written as one flow sequence: kibi-cli before 2.18.0 appended to the
+ * `symbols: []` that `kibi init` writes and kept every symbol on that line.
+ * The manifest is a hint for progressive disclosure, not the source of truth:
+ * snippets always point at kb_query for the authoritative view.
  */
 const SYMBOLS_MANIFEST = ".kb/symbols.yaml";
 const SYMBOL_COORDINATES = ".kb/symbol-coordinates.yaml";
-const INDEX_FORMAT = "kibi-agent-core.knowledge-index.v1";
+const INDEX_FORMAT = "kibi-agent-core.knowledge-index.v2";
 const CACHE_FILE = "knowledge-index.json";
 function unquote(raw) {
     const value = raw.trim();
@@ -39,23 +42,157 @@ function unquote(raw) {
     const comment = value.search(/\s#/);
     return comment >= 0 ? value.slice(0, comment).trimEnd() : value;
 }
-function parseFlowList(raw) {
-    const value = raw.trim();
-    if (!value.startsWith("[") || !value.endsWith("]"))
+// implements REQ-kibi-hooks-flow-manifest
+function parseFlow(text, start = 0) {
+    let pos = start;
+    const skip = () => {
+        while (pos < text.length) {
+            const char = text[pos];
+            if (char === "#") {
+                while (pos < text.length && text[pos] !== "\n")
+                    pos += 1;
+            }
+            else if (char === " " ||
+                char === "\t" ||
+                char === "\n" ||
+                char === "\r") {
+                pos += 1;
+            }
+            else {
+                break;
+            }
+        }
+    };
+    const scalar = (stops) => {
+        const quote = text[pos];
+        if (quote === '"' || quote === "'") {
+            let cursor = pos + 1;
+            while (cursor < text.length) {
+                if (quote === '"' && text[cursor] === "\\")
+                    cursor += 2;
+                else if (text[cursor] === quote) {
+                    if (quote === "'" && text[cursor + 1] === "'")
+                        cursor += 2;
+                    else
+                        break;
+                }
+                else
+                    cursor += 1;
+            }
+            if (cursor >= text.length)
+                return undefined;
+            const raw = text.slice(pos, cursor + 1);
+            pos = cursor + 1;
+            return unquote(raw);
+        }
+        let cursor = pos;
+        while (cursor < text.length) {
+            const char = text[cursor] ?? "";
+            if ((stops.includes(char) && char !== ":") ||
+                char === "\n" ||
+                char === "\r")
+                break;
+            // A plain mapping key ends at the first `: ` (or `:` before a stop).
+            if (stops.includes(":") &&
+                char === ":" &&
+                (cursor + 1 >= text.length || /[\s,\]}]/.test(text[cursor + 1] ?? "")))
+                break;
+            if (char === "#" && /\s/.test(text[cursor - 1] ?? ""))
+                break;
+            cursor += 1;
+        }
+        const raw = text.slice(pos, cursor).trim();
+        pos = cursor;
+        return raw;
+    };
+    const value = () => {
+        skip();
+        const open = text[pos];
+        if (open === "[") {
+            pos += 1;
+            const items = [];
+            for (;;) {
+                skip();
+                if (text[pos] === "]") {
+                    pos += 1;
+                    return items;
+                }
+                if (pos >= text.length)
+                    throw new SyntaxError("unterminated flow sequence");
+                const item = value();
+                if (item !== undefined)
+                    items.push(item);
+                skip();
+                if (text[pos] === ",")
+                    pos += 1;
+                else if (text[pos] !== "]")
+                    throw new SyntaxError("expected , or ]");
+            }
+        }
+        if (open === "{") {
+            pos += 1;
+            const record = {};
+            for (;;) {
+                skip();
+                if (text[pos] === "}") {
+                    pos += 1;
+                    return record;
+                }
+                if (pos >= text.length)
+                    throw new SyntaxError("unterminated flow mapping");
+                const key = scalar(":,}");
+                if (key === undefined)
+                    throw new SyntaxError("unterminated key");
+                skip();
+                let entry;
+                if (text[pos] === ":") {
+                    pos += 1;
+                    skip();
+                    entry = text[pos] === "," || text[pos] === "}" ? undefined : value();
+                }
+                if (key.length > 0)
+                    record[key] = entry;
+                skip();
+                if (text[pos] === ",")
+                    pos += 1;
+                else if (text[pos] !== "}")
+                    throw new SyntaxError("expected , or }");
+            }
+        }
+        const raw = scalar(",]}");
+        if (raw === undefined)
+            throw new SyntaxError("unterminated scalar");
+        return raw;
+    };
+    try {
+        const parsed = value();
+        return { value: parsed, end: pos };
+    }
+    catch {
         return undefined;
-    const inner = value.slice(1, -1).trim();
-    if (inner.length === 0)
-        return [];
-    return inner
-        .split(",")
-        .map(unquote)
-        .filter((item) => item.length > 0);
+    }
+}
+/** True when `raw` opens a flow collection the rest of the line does not close. */
+function opensFlow(raw) {
+    const value = raw.trim();
+    return value.startsWith("[") || value.startsWith("{");
 }
 const keyValue = /^([A-Za-z0-9_"'-][^:]*?):(?:\s+(.*))?$/;
+/** The flow value `raw` holds, or undefined when it is not a complete one. */
+function completeFlowValue(raw) {
+    if (!opensFlow(raw))
+        return undefined;
+    const parsed = parseFlow(raw);
+    if (parsed === undefined)
+        return undefined;
+    const rest = raw.slice(parsed.end).trim();
+    // `[WIP] fix rounding` is a plain scalar that merely starts with `[`.
+    return rest.length === 0 || rest.startsWith("#") ? parsed : undefined;
+}
 function parseScalarOrFlow(raw) {
     if (raw === undefined || raw.trim().length === 0)
         return undefined;
-    return parseFlowList(raw) ?? unquote(raw);
+    return completeFlowValue(raw)?.value ?? unquote(raw);
 }
 /**
  * Scan the symbols manifest into raw records. Accepts both the canonical
@@ -64,11 +201,65 @@ function parseScalarOrFlow(raw) {
 export function scanSymbolsManifest(text) {
     return scanRecordSequence(text, "symbols");
 }
+function unbalancedFlow(raw) {
+    return opensFlow(raw) && parseFlow(raw) === undefined;
+}
+/** Records of a manifest whose `<sectionKey>:` value (or whole root) is a flow sequence. */
+function flowRecords(text, start) {
+    const parsed = parseFlow(text, start);
+    if (!Array.isArray(parsed?.value))
+        return undefined;
+    return parsed.value.filter((item) => item !== null && typeof item === "object" && !Array.isArray(item));
+}
+/**
+ * Records of a manifest whose `<sectionKey>:` value (or whole root) is a flow
+ * sequence, possibly spanning several lines; undefined when the section is
+ * block-style or absent.
+ */
+// implements REQ-kibi-hooks-flow-manifest
+function scanFlowSection(text, sectionKey) {
+    const escapedKey = sectionKey.replaceAll(/[.*+?^$(){}|[\]\\]/g, "\\$&");
+    const header = new RegExp(`^${escapedKey}:[ \\t]*(\\[)?`);
+    let offset = 0;
+    let first = true;
+    let afterHeader = false;
+    // Keep the separators so offsets stay exact for CRLF files.
+    for (const piece of text.split(/(\r?\n)/)) {
+        const content = piece.trim();
+        const indent = piece.length - piece.trimStart().length;
+        if (content.length > 0 && !content.startsWith("#")) {
+            if (afterHeader) {
+                // `symbols:` with its value on a later line: flow only when that
+                // line opens the sequence.
+                return content.startsWith("[")
+                    ? flowRecords(text, offset + piece.indexOf("["))
+                    : undefined;
+            }
+            if (first && content.startsWith("[")) {
+                return flowRecords(text, offset + piece.indexOf("["));
+            }
+            first = false;
+            if (indent === 0) {
+                const match = header.exec(piece);
+                if (match) {
+                    if (match[1] !== undefined)
+                        return flowRecords(text, offset + piece.indexOf("["));
+                    afterHeader = true;
+                }
+            }
+        }
+        offset += piece.length;
+    }
+    return undefined;
+}
 /**
  * Scan the block sequence under top-level `sectionKey` (or a bare root
  * sequence) into raw records.
  */
 function scanRecordSequence(text, sectionKey) {
+    const flowSection = scanFlowSection(text, sectionKey);
+    if (flowSection !== undefined)
+        return flowSection;
     const records = [];
     let itemIndent;
     let keyIndent = 0;
@@ -78,12 +269,31 @@ function scanRecordSequence(text, sectionKey) {
     // Top-level section: records are the `<sectionKey>:` sequence or a bare
     // root sequence; sequences under any other top-level key are ignored.
     let section = "root";
+    // A flow value (`relationships: [` …) that the writer wrapped over several
+    // lines is collected until its brackets balance, then parsed as one value.
+    let pendingFlow;
     for (const rawLine of text.split(/\r?\n/)) {
         const content = rawLine.trim();
         if (content.length === 0 || content.startsWith("#"))
             continue;
         const indent = rawLine.length - rawLine.trimStart().length;
         const dash = /^(\s*)-(\s+)(.*)$/.exec(rawLine);
+        if (pendingFlow !== undefined && current !== undefined) {
+            const target = pendingFlow.onListItem && listItem !== undefined ? listItem : current;
+            if (indent > (itemIndent ?? 0) && !(dash && indent === itemIndent)) {
+                pendingFlow.text += `\n${content}`;
+                const parsed = parseFlow(pendingFlow.text);
+                if (parsed === undefined)
+                    continue;
+                target[pendingFlow.key] = parsed.value;
+                pendingFlow = undefined;
+                continue;
+            }
+            // The next record or section started before the brackets balanced:
+            // keep the opening line as a plain scalar and read on.
+            target[pendingFlow.key] = unquote(pendingFlow.first);
+            pendingFlow = undefined;
+        }
         if (indent === 0 && !dash) {
             const pair = keyValue.exec(content);
             section =
@@ -105,11 +315,21 @@ function scanRecordSequence(text, sectionKey) {
             listItem = undefined;
             const pair = keyValue.exec(dash[3] ?? "");
             if (pair?.[1] !== undefined) {
+                const key = unquote(pair[1]);
+                if (pair[2] !== undefined && unbalancedFlow(pair[2])) {
+                    pendingFlow = {
+                        key,
+                        first: pair[2],
+                        text: pair[2],
+                        onListItem: false,
+                    };
+                    continue;
+                }
                 const value = parseScalarOrFlow(pair[2]);
                 if (value !== undefined)
-                    current[unquote(pair[1])] = value;
+                    current[key] = value;
                 else
-                    listKey = unquote(pair[1]);
+                    listKey = key;
             }
             continue;
         }
@@ -124,14 +344,21 @@ function scanRecordSequence(text, sectionKey) {
                 ? current[listKey]
                 : [];
             current[listKey] = list;
-            const pair = keyValue.exec(dash[3] ?? "");
-            if (pair?.[1] !== undefined && pair[2] !== undefined) {
-                listItem = { [unquote(pair[1])]: unquote(pair[2]) };
+            const item = dash[3] ?? "";
+            const flowItem = completeFlowValue(item);
+            const pair = flowItem === undefined ? keyValue.exec(item) : null;
+            if (flowItem !== undefined) {
+                // `- { type: implements, target: REQ-1 }`
+                listItem = undefined;
+                list.push(flowItem.value);
+            }
+            else if (pair?.[1] !== undefined && pair[2] !== undefined) {
+                listItem = { [unquote(pair[1])]: parseScalarOrFlow(pair[2]) };
                 list.push(listItem);
             }
             else {
                 listItem = undefined;
-                list.push(unquote(dash[3] ?? ""));
+                list.push(unquote(item));
             }
             continue;
         }
@@ -141,6 +368,16 @@ function scanRecordSequence(text, sectionKey) {
         const key = unquote(pair[1]);
         if (indent === keyIndent) {
             listItem = undefined;
+            if (pair[2] !== undefined && unbalancedFlow(pair[2])) {
+                pendingFlow = {
+                    key,
+                    first: pair[2],
+                    text: pair[2],
+                    onListItem: false,
+                };
+                listKey = undefined;
+                continue;
+            }
             const value = parseScalarOrFlow(pair[2]);
             if (value === undefined) {
                 listKey = key;
@@ -151,12 +388,16 @@ function scanRecordSequence(text, sectionKey) {
             }
         }
         else if (listItem !== undefined && pair[2] !== undefined) {
-            listItem[key] = unquote(pair[2]);
+            if (unbalancedFlow(pair[2])) {
+                pendingFlow = { key, first: pair[2], text: pair[2], onListItem: true };
+                continue;
+            }
+            listItem[key] = parseScalarOrFlow(pair[2]);
         }
     }
     return records;
 }
-/** Scan `coordinates:` -> `<symbol id>:` -> `sourceLine` / `sourceEndLine`. */
+/** Scan `coordinates:` -> `<symbol id>:` -> `sourceLine` / `sourceEndLine` / `sourceFile`. */
 export function scanSymbolCoordinates(text) {
     const coordinates = {};
     let inCoordinates = false;
@@ -188,6 +429,13 @@ export function scanSymbolCoordinates(text) {
         if (currentId === undefined || indent < idIndent)
             continue;
         const entry = coordinates[currentId] ?? {};
+        if (key === "sourceFile") {
+            const sourceFile = normalizeSourceFile(unquote(pair[2] ?? ""));
+            if (sourceFile.length > 0)
+                entry.sourceFile = sourceFile;
+            coordinates[currentId] = entry;
+            continue;
+        }
         const numeric = Number.parseInt(unquote(pair[2] ?? ""), 10);
         if (!Number.isFinite(numeric))
             continue;
@@ -207,18 +455,49 @@ function pushUnique(list, value) {
     if (!list.includes(value))
         list.push(value);
 }
+function normalizeSourceFile(value) {
+    return value.replaceAll("\\", "/").replace(/^\.\//, "");
+}
+/**
+ * Manifest state for a scan result: `unreadable` when the file holds content
+ * beyond comments and an empty `symbols` value yet yielded no record.
+ */
+// implements REQ-kibi-hooks-flow-manifest
+export function manifestStateOf(text, recordCount) {
+    if (text === undefined)
+        return "missing";
+    if (recordCount > 0)
+        return "indexed";
+    const meaningful = text
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0 && !line.startsWith("#"))
+        .filter((line) => !/^symbols:\s*(\[\s*\])?$/.test(line))
+        .filter((line) => line !== "[]")
+        // Document markers and a version stamp do not make a manifest unreadable.
+        .filter((line) => !/^(?:---|\.\.\.|%\S.*|version:\s*\S+)$/.test(line));
+    return meaningful.length === 0 ? "empty" : "unreadable";
+}
 /** Collapse raw manifest records and coordinates into the file-keyed index. */
-export function buildKnowledgeIndex(records, coordinates = {}, options = {}) {
+export function buildKnowledgeIndex(records, coordinates = {}, options = {}, manifest = records.length > 0 ? "indexed" : "empty") {
     const files = {};
     let symbolCount = 0;
+    const recordedFiles = new Set();
+    const coordinateFiles = [];
+    for (const entry of Object.values(coordinates)) {
+        if (entry.sourceFile !== undefined)
+            pushUnique(coordinateFiles, entry.sourceFile);
+    }
+    coordinateFiles.sort();
     for (const record of records) {
         const id = typeof record.id === "string" ? record.id : undefined;
         const sourceFile = typeof record.sourceFile === "string"
-            ? record.sourceFile.replaceAll("\\", "/").replace(/^\.\//, "")
+            ? normalizeSourceFile(record.sourceFile)
             : undefined;
         if (!id || !sourceFile)
             continue;
         symbolCount += 1;
+        recordedFiles.add(sourceFile);
         const symbol = {
             id,
             title: typeof record.title === "string" ? record.title : id,
@@ -281,7 +560,10 @@ export function buildKnowledgeIndex(records, coordinates = {}, options = {}) {
         bucket.push(symbol);
         files[sourceFile] = bucket;
     }
-    return { files, symbolCount };
+    const unlinkedFiles = [...recordedFiles]
+        .filter((file) => files[file] === undefined)
+        .sort();
+    return { files, symbolCount, manifest, coordinateFiles, unlinkedFiles };
 }
 function fileSignature(filePath) {
     try {
@@ -337,9 +619,8 @@ export function loadKnowledgeIndex(workspaceRoot, cacheDir, options = {}) {
         }
     }
     const symbolsText = readText(symbolsPath);
-    const index = symbolsText === undefined
-        ? { files: {}, symbolCount: 0 }
-        : buildKnowledgeIndex(scanSymbolsManifest(symbolsText), scanSymbolCoordinates(readText(coordinatesPath) ?? ""), options);
+    const records = symbolsText === undefined ? [] : scanSymbolsManifest(symbolsText);
+    const index = buildKnowledgeIndex(records, scanSymbolCoordinates(readText(coordinatesPath) ?? ""), options, manifestStateOf(symbolsText, records.length));
     if (cachePath) {
         writeCacheAtomically(cachePath, JSON.stringify({ signature, index }));
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kibi-agent-core",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Shared low-latency hook helpers for Kibi agent adapters",
   "type": "module",
   "main": "./dist/index.js",
@@ -31,10 +31,7 @@
       "default": "./dist/snippets.js"
     }
   },
-  "files": [
-    "dist",
-    "CHANGELOG.md"
-  ],
+  "files": ["dist", "CHANGELOG.md"],
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "typecheck": "tsc -p tsconfig.json --noEmit",
@@ -45,9 +42,14 @@
   },
   "license": "AGPL-3.0-or-later",
   "author": "Piotr Franczyk",
+  "homepage": "https://looted.github.io/kibi/",
   "repository": {
     "type": "git",
-    "url": "https://github.com/Looted/kibi.git"
+    "url": "https://github.com/Looted/kibi.git",
+    "directory": "packages/agent-core"
+  },
+  "bugs": {
+    "url": "https://github.com/Looted/kibi/issues"
   },
   "publishConfig": {
     "access": "public"