kibi-agent-core 0.5.0 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # kibi-agent-core
 
+## 0.7.0
+
+### Minor Changes
+
+- b9ec91d: The Claude Code hooks now act on recorded decisions while the work happens, not only after it.
+  - **Firm requirements are confirmed before the edit.** When an `Edit`, `MultiEdit`, `Write` or in-place shell write lands in a symbol that implements a current firm requirement (marked `firmness: firm`, or written by a person rather than an agent), the `PreToolUse` hook returns `permissionDecision: "ask"` with the symbol and requirement in the prompt, so the person decides before the code changes. Once an edit is allowed, that requirement is not asked about again in the session; a declined edit is asked again. The agent is told that a declined edit means the requirement stands. In a `claude -p` run with nobody to answer, Claude Code refuses the edit and the agent reads the reason. Set `KIBI_CONFIRM_FIRM_EDITS=0` to turn the prompt off.
+  - **Stated rules are captured.** A new `UserPromptSubmit` hook tells the agent, when a prompt reads as a rule ("must", "never", "from now on"), that recording it with `kb_upsert` is part of the change. At `Stop`, a session that changed source files and wrote nothing to the knowledge base is asked once to record the decision or say there was none.
+  - **An unlinked file is no longer an all-clear.** The discovery note for a file no symbol links ranks candidate requirements by the latest prompt's words as well as the path's, and, when nothing matches, says that nothing recorded is known to cover the file and that a decision made for it is recorded before the work is reported done (Codex shows the same note).
+
+  `kibi-agent-core`: `requestTopicWords`; `rankRequirementCandidates` and `requirementCandidatesForPath` take optional request words (a requirement sharing only request words needs two of them).
+
+## 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,33 @@
+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;
+};
+/**
+ * Topic words of the person's request (`Users must not delete the last
+ * owner` -> `user`, `delete`, `last`, `owner`), for ranking requirements an
+ * unlinked file's path alone does not reach.
+ */
+export declare function requestTopicWords(text: string, limit?: number): string[];
+/**
+ * Current requirements ranked by how many of the path's topic words their
+ * title shares, then by how many of the request's topic words it shares, then
+ * by how often the title uses them, then by id. A requirement sharing a path
+ * word is returned; one sharing only request words needs two of them, since a
+ * request names many words and one in common is chance.
+ */
+export declare function rankRequirementCandidates(relativePath: string, requirements: readonly RequirementHead[], limit?: number, requestWords?: readonly string[]): RequirementHead[];
+/**
+ * Candidate requirements for a file no symbol links, read from the canonical
+ * requirement documents (`.kb/requirements/*.md`), ranked by the path's words
+ * and, when given, the request's. 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, requestWords?: readonly string[]): RequirementHead[];

package/dist/requirement-candidates.js

@@ -0,0 +1,311 @@
+// 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-claude-request-topic-candidates
+/**
+ * Topic words of the person's request (`Users must not delete the last
+ * owner` -> `user`, `delete`, `last`, `owner`), for ranking requirements an
+ * unlinked file's path alone does not reach.
+ */
+export function requestTopicWords(text, limit = 40) {
+    const found = words(text).filter((word) => !FILLER_WORDS.has(word) && !REQUEST_FILLER_WORDS.has(word));
+    return [...new Set(found)].slice(0, limit);
+}
+/** Request words that carry no topic of their own. */
+const REQUEST_FILLER_WORDS = new Set([
+    "please",
+    "could",
+    "would",
+    "you",
+    "your",
+    "our",
+    "have",
+    "has",
+    "make",
+    "sure",
+    "change",
+    "update",
+    "add",
+    "fix",
+    "now",
+    "need",
+    "want",
+    "like",
+    "also",
+    "just",
+    "then",
+    "than",
+    "there",
+    "here",
+    "what",
+    "which",
+    "why",
+    "how",
+    "will",
+    "use",
+    "using",
+    "new",
+    "file",
+    "code",
+    "never",
+    "always",
+    "only",
+    "any",
+    "but",
+    "they",
+    "them",
+    "was",
+    "were",
+    "been",
+    "being",
+    "does",
+    "don",
+    "doesn",
+    "let",
+    "get",
+    "set",
+    "one",
+    "out",
+    "about",
+    "over",
+    "same",
+    "still",
+    "too",
+    "very",
+]);
+// implements REQ-kb-unowned-file-candidates, REQ-claude-request-topic-candidates
+/**
+ * Current requirements ranked by how many of the path's topic words their
+ * title shares, then by how many of the request's topic words it shares, then
+ * by how often the title uses them, then by id. A requirement sharing a path
+ * word is returned; one sharing only request words needs two of them, since a
+ * request names many words and one in common is chance.
+ */
+export function rankRequirementCandidates(relativePath, requirements, limit = MAX_REQUIREMENT_CANDIDATES, requestWords = []) {
+    const topic = new Set(pathTopicWords(relativePath));
+    const request = new Set(requestWords.filter((word) => !topic.has(word)));
+    if (topic.size === 0 && request.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);
+        const pathHits = titleWords.filter((word) => topic.has(word));
+        const requestHits = titleWords.filter((word) => request.has(word));
+        const shared = new Set(pathHits).size;
+        const asked = new Set(requestHits).size;
+        if (shared > 0 || asked >= 2) {
+            scored.push({
+                head,
+                shared,
+                asked,
+                uses: pathHits.length + requestHits.length,
+            });
+        }
+    }
+    scored.sort((a, b) => b.shared - a.shared ||
+        b.asked - a.asked ||
+        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, REQ-claude-request-topic-candidates
+/**
+ * Candidate requirements for a file no symbol links, read from the canonical
+ * requirement documents (`.kb/requirements/*.md`), ranked by the path's words
+ * and, when given, the request's. Empty when the KB has none or is too large
+ * to scan from a hook.
+ */
+export function requirementCandidatesForPath(workspaceRoot, relativePath, limit = MAX_REQUIREMENT_CANDIDATES, requestWords = []) {
+    if (pathTopicWords(relativePath).length === 0 && requestWords.length < 2)
+        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, requestWords);
+}

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,12 +125,37 @@ 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) {
+// implements REQ-claude-code-kibi-plugin-v1, REQ-codex-kibi-plugin-v1, REQ-kb-unowned-file-candidates, REQ-claude-request-topic-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 words with this path or the request: ${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;
+    }
+    if (candidates.length > 0)
+        return [head, search].join("\n");
+    // implements REQ-claude-request-topic-candidates
+    // Nothing found is not an all-clear: say that nothing recorded is known to
+    // cover the file, and that what this change decides for it is recorded now.
     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).`,
+        head,
+        "No requirement title matches this file, so nothing recorded is known to cover it.",
+        `kb_search({query:"<behavior being changed>", sourceLocations:[{path:${jsonString(relativePath)}}]}) finds a rule recorded under other words. A decision this change makes for this code (a rule the person states, a limit, who may do what) is recorded with kb_upsert (requirement + scenario + symbol implements link) before the work is reported done.`,
     ].join("\n");
 }
 // implements REQ-kibi-hooks-flow-manifest, REQ-claude-code-kibi-plugin-v1, REQ-codex-kibi-plugin-v1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kibi-agent-core",
-  "version": "0.5.0",
+  "version": "0.7.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"