kibi-agent-core 0.6.0 → 0.7.0

package/CHANGELOG.md

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

package/dist/requirement-candidates.d.ts

@@ -10,15 +10,24 @@ export type RequirementHead = {
     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 often the title uses them, then by id. Only
- * requirements sharing at least one word are returned.
+ * 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): RequirementHead[];
+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`). Empty when the KB has none
- * or is too large to scan from a hook.
+ * 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): RequirementHead[];
+export declare function requirementCandidatesForPath(workspaceRoot: string, relativePath: string, limit?: number, requestWords?: readonly string[]): RequirementHead[];

package/dist/requirement-candidates.js

@@ -175,38 +175,124 @@ function readHead(file) {
     };
 }
 const RETIRED_STATUS = /supersed|deprecat|reject|obsolete|retired|archived|removed/i;
-// implements REQ-kb-unowned-file-candidates
+// 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 often the title uses them, then by id. Only
- * requirements sharing at least one word are returned.
+ * 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) {
+export function rankRequirementCandidates(relativePath, requirements, limit = MAX_REQUIREMENT_CANDIDATES, requestWords = []) {
     const topic = new Set(pathTopicWords(relativePath));
-    if (topic.size === 0)
+    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).filter((word) => topic.has(word));
-        const shared = new Set(titleWords).size;
-        if (shared > 0)
-            scored.push({ head, shared, uses: titleWords.length });
+        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
+// 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`). Empty when the KB has none
- * or is too large to scan from a hook.
+ * 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) {
-    if (pathTopicWords(relativePath).length === 0)
+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;
@@ -221,5 +307,5 @@ export function requirementCandidatesForPath(workspaceRoot, relativePath, limit
     const heads = names
         .map((name) => readHead(path.join(directory, name)))
         .filter((head) => head !== undefined);
-    return rankRequirementCandidates(relativePath, heads, limit);
+    return rankRequirementCandidates(relativePath, heads, limit, requestWords);
 }

package/dist/snippets.js

@@ -125,7 +125,7 @@ export function describeEntity(summary) {
 function jsonString(value) {
     return JSON.stringify(value);
 }
-// implements REQ-claude-code-kibi-plugin-v1, REQ-codex-kibi-plugin-v1, REQ-kb-unowned-file-candidates
+// 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
@@ -141,13 +141,22 @@ export function unownedSourceNote(relativePath, candidates = []) {
             .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).`,
+            `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;
     }
-    return [head, search].join("\n");
+    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 [
+        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
 /** 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.6.0",
+  "version": "0.7.0",
   "description": "Shared low-latency hook helpers for Kibi agent adapters",
   "type": "module",
   "main": "./dist/index.js",