kibi-agent-core 0.2.1 → 0.3.1

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # kibi-agent-core
 
+## 0.3.1
+
+### Patch Changes
+
+- dbfe490: Claude Code: when the agent reads a requirement-linked file and then edits it, the edit hook now still says what the lead requirement must keep true (its linked facts and decision) and names the `kb_check` impact call, alongside the symbol the edit lands in; before, the earlier read suppressed everything but that one line, so an agent that read first never saw the facts or the check. A `SessionStart` after a compact or clear resets the session's "already shown" memory, so the next read or edit of a linked file shows its snippet again instead of returning nothing into a context that no longer holds it; a resume keeps the memory. Codex: an `apply_patch` (or `Write`/`Edit`) to a source file no symbol links to a requirement now gets the same one-time discovery note as Claude Code, with the `kb_search` call that finds requirements for it (an unreadable manifest is reported once instead), and `Stop` now reminds of the `kb_check` impact call after `apply_patch` edits, which were not tracked because the patch names its files only in the patch text.
+
+  Technical summary: `kibi-agent-core/snippets` gains `editKnowledgeUpdate` (focus line, `requirementGroundingLines`, impact-check line), the shared `unownedSourceNote` and `unreadableManifestNote` (re-exported by `kibi-claude`), and an optional `noteFor` callback on `editKnowledgeContext` that claims the same once-per-file slot for a file without a snippet. The Claude session journal gets a `context_reset` event that clears the shown, notice and explored sets but keeps pending edits and their reminders; `dispatchHook` appends it for `source: "compact" | "clear"`. The Codex runner passes `noteFor` from the knowledge index's manifest state and tracks dirty paths (and direct `.kb/` edits) through `extractEditedPaths`, which reads `apply_patch` headers.
+
+## 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.
@@ -45,6 +71,8 @@ export type EntitySummary = {
     id: string;
     title?: string;
     status?: string;
+    /** Requirement or ADR firmness as authored (absent reads as default). */
+    firmness?: string;
     /**
      * Frontmatter `links` (plain string entries read as `relates_to`) merged
      * with canonical relationship-shard records whose `from` is this entity.

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 }));
     }
@@ -437,11 +718,14 @@ export function readEntitySummary(workspaceRoot, entityId) {
     for (const line of lines.slice(1)) {
         if (line.trim() === "---")
             break;
-        const match = /^(title|status):\s*(.*)$/.exec(line);
+        const match = /^(title|status|firmness):\s*(.*)$/.exec(line);
         if (match?.[1] === "title" && match[2])
             summary.title = unquote(match[2]);
         if (match?.[1] === "status" && match[2])
             summary.status = unquote(match[2]);
+        // implements REQ-kb-decision-firmness
+        if (match?.[1] === "firmness" && match[2])
+            summary.firmness = unquote(match[2]);
         if (/^\S/.test(line)) {
             flushLink(authored, pending);
             pending = undefined;

package/dist/snippets.d.ts

@@ -24,8 +24,16 @@ export declare function focusedSymbols(symbols: readonly IndexedSymbol[], focus:
 export declare function editFocus(absolutePath: string, toolInput: unknown): LineRange[] | undefined;
 /** True for a status that marks an entity as no longer current policy. */
 export declare function isRetiredStatus(status: string | undefined): boolean;
-/** `ID (status): title`, with the status shown only when it is retired. */
+/**
+ * `ID (status) [firmness]: title`, with the status shown only when it is
+ * retired and the firmness only when it is firm or exploratory (unlabeled
+ * decisions are `default`).
+ */
 export declare function describeEntity(summary: EntitySummary): string;
+/** Discovery note for a source file none of whose symbols implement a requirement. */
+export declare function unownedSourceNote(relativePath: string): string;
+/** Shown instead of the discovery note when the manifest itself could not be read. */
+export declare function unreadableManifestNote(relativePath: string): string;
 /** Link types through which a requirement is grounded in semantic facts. */
 export declare const GROUNDING_LINK_TYPES: readonly string[];
 /**
@@ -49,6 +57,15 @@ export declare function createEntitySummarizer(workspaceRoot: string): Summarize
  * when the manifest links nothing to it.
  */
 export declare function fileKnowledgeSnippet(input: SnippetInput): string | undefined;
+/**
+ * Reduced edit snippet for a file whose descriptive snippet (requirements,
+ * symbols, tests, next-layer calls) was already shown this session: which
+ * symbol the edit lands in, what the lead requirement must keep true and the
+ * decision behind it, and the impact check. The descriptive parts are not
+ * repeated. Undefined when no symbol of the file implements a requirement
+ * and the edit lands in no symbol.
+ */
+export declare function editKnowledgeUpdate(input: SnippetInput): string | undefined;
 /**
  * One-line focus update for a file whose snippet was already shown this
  * session: only the new fact (which symbol the edit lands in) is repeated.
@@ -69,11 +86,17 @@ export type EditKnowledgeInput = {
     /** Most files described in one call (an `apply_patch` may touch many). */
     maxFiles?: number | undefined;
     maxChars?: number | undefined;
+    /**
+     * Note for a file that gets no snippet (for example an unlinked source
+     * file), shown under the same once-per-file-per-session rule.
+     */
+    noteFor?: ((relativePath: string) => string | undefined) | undefined;
 };
 /**
  * Pre-edit context for hosts without their own snippet memory: the shared
- * edit snippet for each linked file the call targets, shown once per file per
- * session, at most `maxFiles` per call.
+ * edit snippet for each linked file the call targets (or `noteFor`'s note for
+ * a file without one), shown once per file per session, at most `maxFiles`
+ * per call.
  */
 export declare function editKnowledgeContext(input: EditKnowledgeInput): string | undefined;
 /**

package/dist/snippets.js

@@ -100,10 +100,18 @@ const RETIRED_STATUS = /supersed|deprecat|reject|obsolete|retired/i;
 export function isRetiredStatus(status) {
     return status !== undefined && RETIRED_STATUS.test(status);
 }
-// implements REQ-agent-core-edit-snippets, REQ-claude-code-kibi-plugin-v1, REQ-opencode-kibi-plugin-v1
-/** `ID (status): title`, with the status shown only when it is retired. */
+// implements REQ-agent-core-edit-snippets, REQ-claude-code-kibi-plugin-v1, REQ-opencode-kibi-plugin-v1, REQ-kb-decision-firmness
+/**
+ * `ID (status) [firmness]: title`, with the status shown only when it is
+ * retired and the firmness only when it is firm or exploratory (unlabeled
+ * decisions are `default`).
+ */
 export function describeEntity(summary) {
-    const notable = isRetiredStatus(summary.status) ? ` (${summary.status})` : "";
+    const retired = isRetiredStatus(summary.status) ? ` (${summary.status})` : "";
+    const firmness = summary.firmness === "firm" || summary.firmness === "exploratory"
+        ? ` [${summary.firmness}]`
+        : "";
+    const notable = `${retired}${firmness}`;
     return summary.title
         ? `${summary.id}${notable}: ${truncate(summary.title, MAX_TITLE)}`
         : `${summary.id}${notable}`;
@@ -111,6 +119,26 @@ export function describeEntity(summary) {
 function jsonString(value) {
     return JSON.stringify(value);
 }
+// implements REQ-claude-code-kibi-plugin-v1, REQ-codex-kibi-plugin-v1
+/** Discovery note for a source file none of whose symbols implement a requirement. */
+export function unownedSourceNote(relativePath) {
+    return [
+        `Kibi: no symbol in ${relativePath} is linked to a requirement yet.`,
+        `kb_search({query:"<behavior being changed>", sourceLocations:[{path:${jsonString(relativePath)}}]}) surfaces requirements that may already describe it; new behavior is recorded with kb_upsert (requirement + symbol implements link).`,
+    ].join("\n");
+}
+// implements REQ-kibi-hooks-flow-manifest, REQ-claude-code-kibi-plugin-v1, REQ-codex-kibi-plugin-v1
+/** Shown instead of the discovery note when the manifest itself could not be read. */
+export function unreadableManifestNote(relativePath) {
+    return [
+        "Kibi: the hook could not read .kb/symbols.yaml, so requirement snippets are unavailable this session.",
+        `kb_query({sourceFile:${jsonString(relativePath)}}) still lists what ${relativePath} implements; \`kibi sync\` rewrites the manifest in the canonical block layout.`,
+    ].join("\n");
+}
+/** The impact-check line that closes every edit snippet. */
+function impactCheckLine(relativePath) {
+    return `Behavior changes here are traced to these requirements; kb_check({sourceFiles:[${jsonString(relativePath)}], includeImpactDiagnostics:true, includeWorkingTreeDiff:true}) reports ownership drift after the edit.`;
+}
 // implements REQ-agent-core-edit-snippets, REQ-claude-code-kibi-plugin-v1, REQ-opencode-kibi-plugin-v1
 /** Link types through which a requirement is grounded in semantic facts. */
 export const GROUNDING_LINK_TYPES = [
@@ -176,15 +204,11 @@ export function createEntitySummarizer(workspaceRoot) {
         return summary;
     };
 }
-// implements REQ-agent-core-edit-snippets, REQ-claude-code-kibi-plugin-v1, REQ-cursor-kibi-plugin-v1, REQ-codex-kibi-plugin-v1, REQ-zcode-kibi-plugin-v1
 /**
- * Knowledge snippet for a file with requirement-linked symbols, or undefined
- * when the manifest links nothing to it.
+ * Requirement -> symbol titles, with the requirement IDs ranked so the focus
+ * symbols' owners lead, then the requirements with the most symbols.
  */
-export function fileKnowledgeSnippet(input) {
-    const { relativePath, symbols, surface, summarize } = input;
-    const focus = focusedSymbols(symbols, input.focus);
-    // Requirement -> symbol titles, focus symbols first so their owners lead.
+function requirementOwners(symbols, focus) {
     const owners = new Map();
     const ordered = [
         ...focus,
@@ -198,6 +222,24 @@ export function fileKnowledgeSnippet(input) {
             owners.set(requirement, titles);
         }
     }
+    const focusOwners = new Set(focus.flatMap((symbol) => symbol.implements));
+    const requirementIds = [...owners.keys()].sort((left, right) => {
+        const focusOrder = Number(focusOwners.has(right)) - Number(focusOwners.has(left));
+        return focusOrder !== 0
+            ? focusOrder
+            : (owners.get(right)?.length ?? 0) - (owners.get(left)?.length ?? 0);
+    });
+    return { owners, requirementIds };
+}
+// implements REQ-agent-core-edit-snippets, REQ-claude-code-kibi-plugin-v1, REQ-cursor-kibi-plugin-v1, REQ-codex-kibi-plugin-v1, REQ-zcode-kibi-plugin-v1
+/**
+ * Knowledge snippet for a file with requirement-linked symbols, or undefined
+ * when the manifest links nothing to it.
+ */
+export function fileKnowledgeSnippet(input) {
+    const { relativePath, symbols, surface, summarize } = input;
+    const focus = focusedSymbols(symbols, input.focus);
+    const { owners, requirementIds } = requirementOwners(symbols, focus);
     const tests = [
         ...new Set(symbols.flatMap((symbol) => symbol.coveredBy)),
     ].sort();
@@ -207,13 +249,6 @@ export function fileKnowledgeSnippet(input) {
     if (owners.size === 0 && tests.length === 0 && executes.length === 0) {
         return undefined;
     }
-    const focusOwners = new Set(focus.flatMap((symbol) => symbol.implements));
-    const requirementIds = [...owners.keys()].sort((left, right) => {
-        const focusOrder = Number(focusOwners.has(right)) - Number(focusOwners.has(left));
-        return focusOrder !== 0
-            ? focusOrder
-            : (owners.get(right)?.length ?? 0) - (owners.get(left)?.length ?? 0);
-    });
     const lines = [
         `Kibi knowledge for ${relativePath} (symbol manifest):`,
     ];
@@ -252,9 +287,36 @@ export function fileKnowledgeSnippet(input) {
         `kb_search({query:"<topic>", sourceLocations:[${location}]}) answers with governing requirements, facts, decisions, and tests`,
     ].filter((part) => part !== undefined);
     lines.push(`Next layer: ${next.join("; ")}.`);
-    if (surface === "edit") {
-        lines.push(`Behavior changes here are traced to these requirements; kb_check({sourceFiles:[${jsonString(relativePath)}], includeImpactDiagnostics:true, includeWorkingTreeDiff:true}) reports ownership drift after the edit.`);
+    if (surface === "edit")
+        lines.push(impactCheckLine(relativePath));
+    return truncate(lines.join("\n"), input.maxChars ?? MAX_SNIPPET_CHARS);
+}
+// implements REQ-claude-code-kibi-plugin-v1
+/**
+ * Reduced edit snippet for a file whose descriptive snippet (requirements,
+ * symbols, tests, next-layer calls) was already shown this session: which
+ * symbol the edit lands in, what the lead requirement must keep true and the
+ * decision behind it, and the impact check. The descriptive parts are not
+ * repeated. Undefined when no symbol of the file implements a requirement
+ * and the edit lands in no symbol.
+ */
+export function editKnowledgeUpdate(input) {
+    const { relativePath, symbols, summarize } = input;
+    const focus = focusedSymbols(symbols, input.focus);
+    const { requirementIds } = requirementOwners(symbols, focus);
+    const leadId = requirementIds[0];
+    const lines = [];
+    const focused = focusUpdate(relativePath, symbols, input.focus);
+    if (focused) {
+        lines.push(focused);
     }
+    else if (leadId) {
+        lines.push(`Kibi: this edit to ${relativePath} changes code that implements ${formatList(requirementIds, 2)}.`);
+    }
+    if (!leadId)
+        return lines[0];
+    lines.push(...requirementGroundingLines(leadId, summarize));
+    lines.push(impactCheckLine(relativePath));
     return truncate(lines.join("\n"), input.maxChars ?? MAX_SNIPPET_CHARS);
 }
 // implements REQ-claude-code-kibi-plugin-v1
@@ -274,8 +336,9 @@ export function focusUpdate(relativePath, symbols, focus) {
 // implements REQ-agent-core-edit-snippets, REQ-codex-kibi-plugin-v1, REQ-zcode-kibi-plugin-v1
 /**
  * Pre-edit context for hosts without their own snippet memory: the shared
- * edit snippet for each linked file the call targets, shown once per file per
- * session, at most `maxFiles` per call.
+ * edit snippet for each linked file the call targets (or `noteFor`'s note for
+ * a file without one), shown once per file per session, at most `maxFiles`
+ * per call.
  */
 export function editKnowledgeContext(input) {
     const snippets = [];
@@ -283,22 +346,23 @@ export function editKnowledgeContext(input) {
         if (snippets.length >= (input.maxFiles ?? 3))
             break;
         const symbols = input.symbolsFor(relativePath);
-        if (symbols.length === 0)
-            continue;
-        const snippet = fileKnowledgeSnippet({
-            relativePath,
-            symbols,
-            surface: "edit",
-            focus: input.focusFor?.(relativePath),
-            summarize: input.summarize,
-            maxChars: input.maxChars,
-        });
-        if (!snippet)
+        const snippet = symbols.length > 0
+            ? fileKnowledgeSnippet({
+                relativePath,
+                symbols,
+                surface: "edit",
+                focus: input.focusFor?.(relativePath),
+                summarize: input.summarize,
+                maxChars: input.maxChars,
+            })
+            : undefined;
+        const text = snippet ?? input.noteFor?.(relativePath);
+        if (!text)
             continue;
         const key = `${input.sessionId ?? ""}\u0000edit\u0000${relativePath}`;
         if (!claimSnippetSlot(input.stateDir, key))
             continue;
-        snippets.push(snippet);
+        snippets.push(text);
     }
     return snippets.length > 0 ? snippets.join("\n\n") : undefined;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kibi-agent-core",
-  "version": "0.2.1",
+  "version": "0.3.1",
   "description": "Shared low-latency hook helpers for Kibi agent adapters",
   "type": "module",
   "main": "./dist/index.js",