kibi-agent-core 0.3.0 → 0.3.1

package/CHANGELOG.md

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

package/dist/knowledge-index.d.ts

@@ -71,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

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