kibi-agent-core 0.3.1 → 0.5.0

package/CHANGELOG.md

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

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