kibi-agent-core 0.5.0 → 0.6.0

package/CHANGELOG.md

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

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/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;
@@ -32,8 +33,12 @@ export declare function isRetiredStatus(status: string | undefined): boolean;
  * 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

@@ -125,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.5.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"