kibi-agent-core 0.4.0 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # kibi-agent-core
 
+## 0.6.0
+
+### Minor Changes
+
+- d960810: A file with no linked symbols is no longer read as a file no rule covers. Before such a file is edited, the Claude Code and Codex hooks name the current requirements whose titles share the file's path words, and a `kb_check` scoped to the file reports the same candidates, so an agent changing `coach-dashboard.html` is pointed at the coach inbox requirement instead of concluding there is no knowledge-base impact. Agents are also told that recording the behavior a change adds is part of finishing it and needs no permission.
+  - `kibi-agent-core`: new `requirement-candidates` module (`pathTopicWords`, `rankRequirementCandidates`, `requirementCandidatesForPath`); `unownedSourceNote` takes the candidates, says that no link does not mean no rule, and drops candidates rather than exceed the snippet budget.
+  - `kibi-cli`: an impact-enabled `kb_check` emits `source_file_unowned` (`info`, non-blocking) for each file in `sourceFiles` that no manifest symbol links to a requirement, including files Kibi does not extract symbols from (HTML templates), with `evidence.candidates`. The unlinked-symbol `symbol_semantic_review_needed` suggestion now says recording the behavior needs no permission.
+  - `kibi-claude`, `kibi-codex`: the unlinked-file edit note names candidate requirements. The Claude Code session-start context no longer says unlinked files get no context, and says recording new behavior needs no permission; ZCode's session-start context says the same.
+  - `kibi-usage` skill 2.19.0: record new behavior without asking; confirm the candidates an unlinked-file note names.
+
+## 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/index.d.ts

@@ -3,3 +3,4 @@ export * from "./kb-mcp-tools.js";
 export * from "./knowledge-index.js";
 export * from "./path-policy.js";
 export * from "./snippets.js";
+export * from "./requirement-candidates.js";

package/dist/index.js

@@ -3,3 +3,4 @@ export * from "./kb-mcp-tools.js";
 export * from "./knowledge-index.js";
 export * from "./path-policy.js";
 export * from "./snippets.js";
+export * from "./requirement-candidates.js";

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/requirement-candidates.d.ts

@@ -0,0 +1,24 @@
+export declare const MAX_REQUIREMENT_CANDIDATES = 3;
+/**
+ * The topic words of a workspace path: its directory and file-name words,
+ * without layout, language and role words (`src/app/pages/coach-dashboard/
+ * coach-dashboard.html` -> `coach`, `dashboard`).
+ */
+export declare function pathTopicWords(relativePath: string): string[];
+export type RequirementHead = {
+    id: string;
+    title: string;
+    status?: string;
+};
+/**
+ * Current requirements ranked by how many of the path's topic words their
+ * title shares, then by how often the title uses them, then by id. Only
+ * requirements sharing at least one word are returned.
+ */
+export declare function rankRequirementCandidates(relativePath: string, requirements: readonly RequirementHead[], limit?: number): RequirementHead[];
+/**
+ * Candidate requirements for a file no symbol links, read from the canonical
+ * requirement documents (`.kb/requirements/*.md`). Empty when the KB has none
+ * or is too large to scan from a hook.
+ */
+export declare function requirementCandidatesForPath(workspaceRoot: string, relativePath: string, limit?: number): RequirementHead[];

package/dist/requirement-candidates.js

@@ -0,0 +1,225 @@
+// implements REQ-kb-unowned-file-candidates
+import fs from "node:fs";
+import path from "node:path";
+/**
+ * Requirements that may govern a file no symbol links yet, found by the words
+ * its path shares with their titles. A file without links is not a file
+ * without rules: `coach-dashboard.html` may implement "The coach inbox must
+ * list the analysis requests assigned to the coach." The match is lexical and
+ * cheap enough for a hook; it names candidates to confirm, never owners.
+ */
+const REQUIREMENTS_DIR = path.join(".kb", "requirements");
+/** Bytes of each requirement read for its front matter. */
+const HEAD_BYTES = 4096;
+/** A KB larger than this is not scanned from a hook. */
+const MAX_SCANNED = 2000;
+export const MAX_REQUIREMENT_CANDIDATES = 3;
+/** Path words that name a layout, a language or a role, not a behavior. */
+const LAYOUT_WORDS = new Set([
+    "src",
+    "app",
+    "apps",
+    "lib",
+    "libs",
+    "source",
+    "page",
+    "pages",
+    "component",
+    "components",
+    "view",
+    "views",
+    "screen",
+    "screens",
+    "package",
+    "packages",
+    "main",
+    "index",
+    "shared",
+    "common",
+    "core",
+    "util",
+    "utils",
+    "helper",
+    "helpers",
+    "public",
+    "static",
+    "asset",
+    "assets",
+    "web",
+    "client",
+    "server",
+    "frontend",
+    "backend",
+    "module",
+    "modules",
+    "feature",
+    "features",
+    "internal",
+    "service",
+    "services",
+    "test",
+    "tests",
+    "spec",
+    "specs",
+    "dist",
+    "build",
+    "html",
+    "htm",
+    "tsx",
+    "jsx",
+    "mjs",
+    "cjs",
+    "vue",
+    "svelte",
+    "css",
+    "scss",
+    "less",
+    "json",
+    "yaml",
+    "yml",
+    "java",
+    "swift",
+    "php",
+]);
+/** Words of a title that carry no topic. */
+const FILLER_WORDS = new Set([
+    "the",
+    "and",
+    "for",
+    "with",
+    "must",
+    "should",
+    "shall",
+    "may",
+    "can",
+    "are",
+    "is",
+    "its",
+    "their",
+    "that",
+    "this",
+    "from",
+    "into",
+    "when",
+    "each",
+    "every",
+    "all",
+    "not",
+    "req",
+    "auto",
+]);
+/** Lowercase word stems of an identifier, path segment or title. */
+function words(text) {
+    return text
+        .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .filter((word) => word.length >= 3 && !/\d/.test(word))
+        .map((word) => word.length > 4 && word.endsWith("s") && !word.endsWith("ss")
+        ? word.slice(0, -1)
+        : word);
+}
+// implements REQ-kb-unowned-file-candidates
+/**
+ * The topic words of a workspace path: its directory and file-name words,
+ * without layout, language and role words (`src/app/pages/coach-dashboard/
+ * coach-dashboard.html` -> `coach`, `dashboard`).
+ */
+export function pathTopicWords(relativePath) {
+    const segments = relativePath.split(/[\\/]/).filter(Boolean);
+    const last = segments.pop() ?? "";
+    const stem = last.includes(".") ? last.slice(0, last.indexOf(".")) : last;
+    const roles = last.includes(".") ? last.slice(last.indexOf(".") + 1) : "";
+    const found = [...segments, stem, roles]
+        .flatMap(words)
+        .filter((word) => !LAYOUT_WORDS.has(word) && !FILLER_WORDS.has(word));
+    return [...new Set(found)];
+}
+function unquote(value) {
+    const trimmed = value.trim();
+    return /^(["']).*\1$/.test(trimmed) ? trimmed.slice(1, -1) : trimmed;
+}
+function readHead(file) {
+    let head;
+    try {
+        const descriptor = fs.openSync(file, "r");
+        try {
+            const buffer = Buffer.alloc(HEAD_BYTES);
+            const bytes = fs.readSync(descriptor, buffer, 0, buffer.length, 0);
+            head = buffer.subarray(0, bytes).toString("utf8");
+        }
+        finally {
+            fs.closeSync(descriptor);
+        }
+    }
+    catch {
+        return undefined;
+    }
+    const lines = head.split(/\r?\n/);
+    if (lines[0]?.trim() !== "---")
+        return undefined;
+    const fields = {};
+    for (const line of lines.slice(1)) {
+        if (line.trim() === "---")
+            break;
+        const match = /^(id|title|status):\s*(.+)$/.exec(line);
+        if (match?.[1] && match[2])
+            fields[match[1]] = unquote(match[2]);
+    }
+    if (!fields.id || !fields.title)
+        return undefined;
+    return {
+        id: fields.id,
+        title: fields.title,
+        ...(fields.status ? { status: fields.status } : {}),
+    };
+}
+const RETIRED_STATUS = /supersed|deprecat|reject|obsolete|retired|archived|removed/i;
+// implements REQ-kb-unowned-file-candidates
+/**
+ * Current requirements ranked by how many of the path's topic words their
+ * title shares, then by how often the title uses them, then by id. Only
+ * requirements sharing at least one word are returned.
+ */
+export function rankRequirementCandidates(relativePath, requirements, limit = MAX_REQUIREMENT_CANDIDATES) {
+    const topic = new Set(pathTopicWords(relativePath));
+    if (topic.size === 0)
+        return [];
+    const scored = [];
+    for (const head of requirements) {
+        if (head.status !== undefined && RETIRED_STATUS.test(head.status))
+            continue;
+        const titleWords = words(head.title).filter((word) => topic.has(word));
+        const shared = new Set(titleWords).size;
+        if (shared > 0)
+            scored.push({ head, shared, uses: titleWords.length });
+    }
+    scored.sort((a, b) => b.shared - a.shared ||
+        b.uses - a.uses ||
+        a.head.id.localeCompare(b.head.id));
+    return scored.slice(0, limit).map((entry) => entry.head);
+}
+// implements REQ-kb-unowned-file-candidates
+/**
+ * Candidate requirements for a file no symbol links, read from the canonical
+ * requirement documents (`.kb/requirements/*.md`). Empty when the KB has none
+ * or is too large to scan from a hook.
+ */
+export function requirementCandidatesForPath(workspaceRoot, relativePath, limit = MAX_REQUIREMENT_CANDIDATES) {
+    if (pathTopicWords(relativePath).length === 0)
+        return [];
+    const directory = path.join(workspaceRoot, REQUIREMENTS_DIR);
+    let names;
+    try {
+        names = fs.readdirSync(directory).filter((name) => name.endsWith(".md"));
+    }
+    catch {
+        return [];
+    }
+    if (names.length > MAX_SCANNED)
+        return [];
+    const heads = names
+        .map((name) => readHead(path.join(directory, name)))
+        .filter((head) => head !== undefined);
+    return rankRequirementCandidates(relativePath, heads, limit);
+}

package/dist/snippets.d.ts

@@ -1,4 +1,5 @@
 import { type EntitySummary, type IndexedSymbol } from "./knowledge-index.js";
+import type { RequirementHead } from "./requirement-candidates.js";
 export declare const MAX_SNIPPET_CHARS = 1200;
 export type LineRange = {
     start: number;
@@ -26,12 +27,18 @@ 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. */
-export declare function unownedSourceNote(relativePath: string): string;
+/**
+ * Discovery note for a source file none of whose symbols implement a
+ * requirement. No link is not no rule, so the note names the current
+ * requirements whose titles share the path's words, when there are any.
+ */
+export declare function unownedSourceNote(relativePath: string, candidates?: readonly RequirementHead[]): 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. */

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
@@ -119,13 +125,29 @@ 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-claude-code-kibi-plugin-v1, REQ-codex-kibi-plugin-v1, REQ-kb-unowned-file-candidates
+/**
+ * Discovery note for a source file none of whose symbols implement a
+ * requirement. No link is not no rule, so the note names the current
+ * requirements whose titles share the path's words, when there are any.
+ */
+export function unownedSourceNote(relativePath, candidates = []) {
+    const head = `Kibi: no symbol in ${relativePath} is linked to a requirement yet; that does not mean no recorded rule covers the behavior it implements.`;
+    const search = `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 + scenario + symbol implements link) as part of the change.`;
+    // Fewer candidates rather than a note over the snippet budget.
+    for (let shown = candidates.length; shown > 0; shown--) {
+        const named = candidates
+            .slice(0, shown)
+            .map((candidate) => `${candidate.id}: ${truncate(candidate.title, MAX_TITLE)}`);
+        const note = [
+            head,
+            `Requirements whose titles share this path's words: ${named.join("; ")}. kb_query({id:${jsonString(candidates[0]?.id ?? "")}}) shows whether one describes the behavior being changed; one that does is traced by an implements link from the symbol that implements it (for markup, the component that renders it).`,
+            search,
+        ].join("\n");
+        if (note.length <= MAX_SNIPPET_CHARS)
+            return note;
+    }
+    return [head, search].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. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kibi-agent-core",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Shared low-latency hook helpers for Kibi agent adapters",
   "type": "module",
   "main": "./dist/index.js",
@@ -26,6 +26,10 @@
       "types": "./dist/path-policy.d.ts",
       "default": "./dist/path-policy.js"
     },
+    "./requirement-candidates": {
+      "types": "./dist/requirement-candidates.d.ts",
+      "default": "./dist/requirement-candidates.js"
+    },
     "./snippets": {
       "types": "./dist/snippets.d.ts",
       "default": "./dist/snippets.js"