kibi-agent-core 0.2.1 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # 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

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.1",
+  "version": "0.3.0",
   "description": "Shared low-latency hook helpers for Kibi agent adapters",
   "type": "module",
   "main": "./dist/index.js",