kibi-agent-core 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # kibi-agent-core
 
+## 0.4.0
+
+### Minor Changes
+
+- 5ad4319: Requirements and ADRs can now say how firmly they were decided, so a later agent knows whether it may change a decision on evidence or must ask a human first. Mark a rule a person stated `firmness: firm` (it must cite their words in `origin.ref`, or `approval_ref` on a requirement), a guess `firmness: exploratory`, and leave the rest unset (`default`). `kibi check` now blocks a firm decision without that reference (Kibi checks that it is present, not that it is genuine), a decision that is not firm superseding a firm one, and a current requirement or ADR that supersedes another without a `## Why this changed` section naming the evidence. `kb_search` and `kb_query` show the firmness of each decision; the editor hooks label firm and exploratory ones.
+
+  Migration: this is a hard rollout with KB schema 9. Run `kibi migrate --yes` once; it records every supersede edge that predates the rule in the manifest (`supersedesReasonAcknowledged`, as `FROM -> TO`), so those do not block, and an advisory `supersedes-reason-acknowledged` diagnostic counts them. No source file is rewritten and no reason is invented. New supersedes must explain themselves, including a new one on an acknowledged decision.
+
+  Technical summary: new optional `firmness` property (`firm` | `default` | `exploratory`) on `req` and `adr` in the JSON schema, the `kb_upsert` input schema, the markdown extractor and the Prolog entity schema; the schema rejects it on other types. `kb_upsert` judges firmness as it will be written: an update that omits `firmness` keeps the stored value (also in the compiled store), and a write that leaves a decision firm without a reference is rejected. `decision-firm-superseded` checks every superseder, retired ones included, so a chain cannot launder a firm decision; shard edges from deleted entities are ignored. New rules `decision-firm-unreferenced`, `decision-firm-superseded` and `supersedes-reason-missing` (canonical, blocking) and `supersedes-reason-acknowledged` (info) read authored requirements, ADRs, front-matter `supersedes` links and relationship shards, so they agree before a sync. `LATEST_KB_SCHEMA_VERSION` is 9; the `decision-firmness-v9` migration step and the `supersedes-reason-acknowledge` fragment action write only `.kb/manifest.json`. Search answer rows and `kb_query` results carry the effective firmness of requirements and ADRs; hook snippets append `[firm]` or `[exploratory]`. The `kibi-usage` skill gains a "Decision firmness" section.
+
+## 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.4.0",
   "description": "Shared low-latency hook helpers for Kibi agent adapters",
   "type": "module",
   "main": "./dist/index.js",