kibi-agent-core 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # kibi-agent-core
 
+## 0.5.0
+
+### Minor Changes
+
+- cd4723e: Rules a person wrote or imported are no longer treated as an agent's own default choice when they carry no `firmness`. A requirement or ADR without `firmness` now reads as `firm` unless an agent wrote it, so an agent asks before replacing it, and bootstrap records the rules it imports from your documents as firm with a reference to the passage. The usage skill now treats any request that conflicts with a recorded rule as a question: the agent names the rule and asks, whatever the rule's firmness, and changes it only when the person says so. Run `kibi migrate --yes` to move a KB to schema 10; existing supersedes are acknowledged and no source file is rewritten.
+  - `effectiveFirmness` takes the entity's origin: an absent value is `default` for `origin.kind: agent` and `firm` otherwise (human, import, migration or no origin). `kb_query` rows and `kb_search` answers show the derived value.
+  - Hook snippets label a current firm decision `[firm: ask before changing]` (was `[firm]`) and no longer label retired decisions. The Claude Code and ZCode session-start context adds one sentence: a request that conflicts with a recorded requirement or ADR is a question, so the agent names the rule and asks before changing the code or the rule.
+  - `decision-firm-superseded` applies to origin-derived firm targets; `decision-firm-unreferenced` still applies only to an explicit `firmness: firm`.
+  - KB schema 10: the `firmness-from-origin-v10` step and the automatic `firm_supersede_acknowledge` plan action record pre-existing supersedes of such decisions in `.kb/manifest.json` `firmSupersedeAcknowledged` (`FROM -> TO`); only listed edges are exempt, and never an explicitly firm target.
+  - Bootstrap intent-claim and normative-markdown requirement steps write `origin: {kind: import, ref}` and `firmness: firm`.
+  - Skills: `kibi-usage` 2.17.0 (conflicting request means ask; firmness from origin; write firmness explicitly), `kibi-bootstrap` 3.13.0 (imported rules are firm imports, including hand-authored follow-ups).
+
 ## 0.4.0
 
 ### Minor Changes

package/dist/knowledge-index.d.ts

@@ -71,7 +71,11 @@ export type EntitySummary = {
     id: string;
     title?: string;
     status?: string;
-    /** Requirement or ADR firmness as authored (absent reads as default). */
+    /**
+     * Requirement or ADR firmness: as authored, else what the origin implies
+     * (`default` when an agent wrote it, `firm` otherwise). Absent when the
+     * front matter could not be read whole.
+     */
     firmness?: string;
     /**
      * Frontmatter `links` (plain string entries read as `relates_to`) merged

package/dist/knowledge-index.js

@@ -714,10 +714,24 @@ export function readEntitySummary(workspaceRoot, entityId) {
     const summary = { id: entityId };
     const authored = [];
     let inLinks = false;
+    let inOrigin = false;
+    let originKind;
+    let closed = false;
     let pending;
     for (const line of lines.slice(1)) {
-        if (line.trim() === "---")
+        if (line.trim() === "---") {
+            closed = true;
             break;
+        }
+        // implements REQ-kb-decision-firmness-from-origin
+        const flowOrigin = /^origin:\s*\{.*\bkind:\s*["']?([a-z]+)/.exec(line);
+        if (flowOrigin)
+            originKind = flowOrigin[1];
+        const nestedKind = inOrigin ? /^\s+kind:\s*["']?([a-z]+)/.exec(line) : null;
+        if (nestedKind)
+            originKind = nestedKind[1];
+        if (/^\S/.test(line))
+            inOrigin = /^origin:\s*$/.test(line);
         const match = /^(title|status|firmness):\s*(.*)$/.exec(line);
         if (match?.[1] === "title" && match[2])
             summary.title = unquote(match[2]);
@@ -754,6 +768,13 @@ export function readEntitySummary(workspaceRoot, entityId) {
             pending.bare = unquote(body);
     }
     flushLink(authored, pending);
+    // A decision without authored firmness is a person's (firm) unless an
+    // agent wrote it; with the front matter cut off, the origin is unknown.
+    // implements REQ-kb-decision-firmness-from-origin
+    if (summary.firmness === undefined &&
+        closed &&
+        (lane[1] === "requirements" || lane[1] === "adr"))
+        summary.firmness = originKind === "agent" ? "default" : "firm";
     const links = [];
     const seen = new Set();
     for (const link of [

package/dist/snippets.d.ts

@@ -26,8 +26,10 @@ export declare function editFocus(absolutePath: string, toolInput: unknown): Lin
 export declare function isRetiredStatus(status: string | undefined): boolean;
 /**
  * `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`).
+ * retired and the firmness only on a current decision: `[firm: ask before
+ * changing]` says what a firm rule asks of the agent where it reads it, and
+ * `[exploratory]` marks a guess. An unlabeled current decision is `default`,
+ * an agent's choice.
  */
 export declare function describeEntity(summary: EntitySummary): string;
 /** Discovery note for a source file none of whose symbols implement a requirement. */

package/dist/snippets.js

@@ -100,16 +100,22 @@ 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, REQ-kb-decision-firmness
+// implements REQ-agent-core-edit-snippets, REQ-claude-code-kibi-plugin-v1, REQ-opencode-kibi-plugin-v1, REQ-kb-decision-firmness, REQ-kb-decision-firmness-from-origin
 /**
  * `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`).
+ * retired and the firmness only on a current decision: `[firm: ask before
+ * changing]` says what a firm rule asks of the agent where it reads it, and
+ * `[exploratory]` marks a guess. An unlabeled current decision is `default`,
+ * an agent's choice.
  */
 export function describeEntity(summary) {
     const retired = isRetiredStatus(summary.status) ? ` (${summary.status})` : "";
-    const firmness = summary.firmness === "firm" || summary.firmness === "exploratory"
-        ? ` [${summary.firmness}]`
+    // A retired decision binds nothing, however firmly it was once made.
+    const firmness = !retired &&
+        (summary.firmness === "firm" || summary.firmness === "exploratory")
+        ? summary.firmness === "firm"
+            ? " [firm: ask before changing]"
+            : " [exploratory]"
         : "";
     const notable = `${retired}${firmness}`;
     return summary.title

package/package.json

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