kibi-agent-core 0.6.0 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # kibi-agent-core
 
+## 0.8.0
+
+### Minor Changes
+
+- 00d2871: The Codex, Cursor and ZCode hooks now act on recorded decisions while the work happens, as the Claude Code hooks do.
+  - **Firm requirements before the edit.** When an edit changes code that implements a current firm requirement, the pre-edit hook tells the agent to ask the person before an edit that breaks that rule, naming the rule; once per requirement per session. These hosts cannot put the question to the person from a hook (Codex has no "ask", Cursor does not enforce one, and the ZCode adapter stays advisory), so this is a notice to the agent. Set `KIBI_CONFIRM_FIRM_EDITS=0` to turn it off.
+  - **Stated rules are captured.** A prompt that reads as a rule ("must", "never", "from now on") gets the note that recording it with `kb_upsert` is part of the change: through a new `UserPromptSubmit` hook in Codex and ZCode, and in Cursor through a new `beforeSubmitPrompt` hook whose note arrives with the next pre-edit message. When a session changed source files and wrote nothing with `kb_upsert`, the stop hook asks once for the decision to be recorded (Codex continues the turn with it; Cursor adds it to the stop follow-up; ZCode adds it to the Stop context).
+  - **Codex unlinked-file candidates** are ranked by the latest prompt's words as well as the path's.
+
+  `kibi-agent-core`: new `kibi-agent-core/decision-guard` entry with the host-neutral pieces (`firmRequirementsTouched`, `firmEditNotice`, `confirmFirmEdits`, the prompt and stop notes, and per-session markers). `kibi-claude` now imports its firm-edit and capture texts from it; behavior is unchanged.
+
+## 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/decision-guard.d.ts

@@ -0,0 +1,90 @@
+import type { EntitySummary, IndexedSymbol } from "./knowledge-index.js";
+import { type LineRange, type Summarize } from "./snippets.js";
+/**
+ * Host-neutral pieces of the hooks that act on recorded decisions while the
+ * work happens: which firm requirements an edit changes, the confirmation and
+ * agent texts for it, and the prompt-time and stop-time capture notes. Each
+ * host adapter decides how to put the confirmation to the person.
+ */
+/** Set to `0`, `false` or `off` to stop asking before edits of firm requirements. */
+export declare const CONFIRM_FIRM_EDITS_ENV = "KIBI_CONFIRM_FIRM_EDITS";
+/** False when the operator turned the firm-edit confirmation off. */
+export declare function confirmFirmEdits(env: NodeJS.ProcessEnv): boolean;
+/**
+ * The current firm requirements an edit changes that are not in `confirmed`:
+ * those implemented by the symbols the edit lands in, or by every symbol of
+ * the file for a whole-file write. An edit whose location is unknown, or
+ * outside every symbol, changes none.
+ */
+export declare function firmRequirementsTouched(input: {
+    symbols: readonly IndexedSymbol[];
+    focus: readonly LineRange[] | undefined;
+    wholeFile: boolean;
+    summarize: Summarize;
+    confirmed?: ReadonlySet<string>;
+}): {
+    ids: string[];
+    symbol: IndexedSymbol | undefined;
+};
+/**
+ * The permission-prompt text for an edit of a firm requirement's code: what
+ * the edit changes, the requirements, and what allowing it means. The person
+ * reads it, so it names the rule rather than the mechanism.
+ */
+export declare function firmEditConfirmation(where: string, requirements: readonly EntitySummary[]): string;
+/** What the agent is told when its edit was put to the person. */
+export declare function firmEditContext(ids: readonly string[]): string;
+/** The phrase that makes `prompt` read as a rule, or undefined. */
+export declare function statedRule(prompt: string): string | undefined;
+/** Prompt-time note for a request that reads as a rule or decision. */
+export declare function rulePromptNote(phrase: string): string;
+/**
+ * Stop-time note for a session that changed source files and wrote nothing
+ * to the knowledge base.
+ */
+export declare function captureReminder(rulePrompt: boolean): string;
+/**
+ * Pre-edit context for hosts whose pre-tool hook cannot put a call to the
+ * person: the edit is named as a change to the person's rule, and the agent
+ * is told to ask before making it unless it keeps the rule.
+ */
+export declare function firmEditNotice(where: string, requirements: readonly EntitySummary[]): string;
+/** Where one host session's decision-guard markers live. */
+export type DecisionSession = {
+    stateDir: string | undefined;
+    sessionId: string | undefined;
+};
+/** Session markers the decision guard keeps. */
+export type DecisionFlag = "source-edited" | "kb-recorded" | "rule-prompt" | "capture-asked";
+/** Set a session marker; best effort. */
+export declare function markDecisionFlag(session: DecisionSession, flag: DecisionFlag): void;
+export declare function hasDecisionFlag(session: DecisionSession, flag: DecisionFlag): boolean;
+/**
+ * True the first time `flag` is claimed in the session. Without a state
+ * directory nothing can be remembered, so nothing is claimed.
+ */
+export declare function claimDecisionFlag(session: DecisionSession, flag: DecisionFlag): boolean;
+/**
+ * Remember a submitted prompt's topic words (for unlinked-file candidates)
+ * and whether it read as a rule. Returns the rule phrase, if any.
+ */
+export declare function recordRequest(session: DecisionSession, prompt: string): string | undefined;
+/** Topic words of the session's latest prompt, or none. */
+export declare function requestWords(session: DecisionSession): string[];
+/**
+ * Whether the stop should ask for the session's decision to be recorded:
+ * source changed, nothing was written with kb_upsert, and the session has
+ * not been asked yet (claiming the ask).
+ */
+export declare function claimCaptureReminder(session: DecisionSession): boolean;
+/** Firm requirements the agent was already told about this session. */
+export declare function settledFirmRequirements(session: DecisionSession): Set<string>;
+/** Remember that the agent was told about these firm requirements. */
+export declare function settleFirmRequirements(session: DecisionSession, ids: readonly string[]): void;
+/**
+ * Keep a prompt's rule note for a host whose prompt hook cannot add context,
+ * so the next hook that can speak to the agent delivers it.
+ */
+export declare function holdRuleNote(session: DecisionSession, phrase: string): void;
+/** The held rule note, removed so it is delivered once; or undefined. */
+export declare function takeRuleNote(session: DecisionSession): string | undefined;

package/dist/decision-guard.js

@@ -0,0 +1,274 @@
+// implements REQ-claude-firm-edit-confirmation, REQ-claude-decision-capture-nudges, REQ-agent-hosts-decision-guard
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { requestTopicWords } from "./requirement-candidates.js";
+import { focusedSymbols, implementedRequirementIds, isRetiredStatus, } from "./snippets.js";
+/**
+ * Host-neutral pieces of the hooks that act on recorded decisions while the
+ * work happens: which firm requirements an edit changes, the confirmation and
+ * agent texts for it, and the prompt-time and stop-time capture notes. Each
+ * host adapter decides how to put the confirmation to the person.
+ */
+/** Set to `0`, `false` or `off` to stop asking before edits of firm requirements. */
+export const CONFIRM_FIRM_EDITS_ENV = "KIBI_CONFIRM_FIRM_EDITS";
+// implements REQ-claude-firm-edit-confirmation, REQ-agent-hosts-decision-guard
+/** False when the operator turned the firm-edit confirmation off. */
+export function confirmFirmEdits(env) {
+    const value = env[CONFIRM_FIRM_EDITS_ENV]?.trim().toLowerCase();
+    return !(value === "0" || value === "false" || value === "off");
+}
+// implements REQ-claude-firm-edit-confirmation, REQ-agent-hosts-decision-guard
+/**
+ * The current firm requirements an edit changes that are not in `confirmed`:
+ * those implemented by the symbols the edit lands in, or by every symbol of
+ * the file for a whole-file write. An edit whose location is unknown, or
+ * outside every symbol, changes none.
+ */
+export function firmRequirementsTouched(input) {
+    const touched = input.wholeFile
+        ? input.symbols
+        : focusedSymbols(input.symbols, input.focus);
+    const ids = implementedRequirementIds(touched).filter((id) => {
+        if (input.confirmed?.has(id))
+            return false;
+        const summary = input.summarize(id);
+        return summary.firmness === "firm" && !isRetiredStatus(summary.status);
+    });
+    return { ids, symbol: input.wholeFile ? undefined : touched[0] };
+}
+// implements REQ-claude-firm-edit-confirmation
+/**
+ * The permission-prompt text for an edit of a firm requirement's code: what
+ * the edit changes, the requirements, and what allowing it means. The person
+ * reads it, so it names the rule rather than the mechanism.
+ */
+export function firmEditConfirmation(where, requirements) {
+    // Every one is firm, so each is named by id and title only.
+    const shown = requirements
+        .slice(0, 2)
+        .map((summary) => summary.title ? `${summary.id}: ${summary.title}` : summary.id);
+    const more = requirements.length > shown.length
+        ? ` (+${requirements.length - shown.length} more)`
+        : "";
+    const noun = requirements.length === 1 ? "a firm requirement" : "firm requirements";
+    return `Kibi: this edit changes ${where}, which implements ${noun} recorded in the knowledge base: ${shown.join("; ")}${more}. Allow it if the change keeps ${requirements.length === 1 ? "that requirement" : "them"}, or if you mean to change ${requirements.length === 1 ? "the requirement" : "them"} too.`;
+}
+// implements REQ-claude-firm-edit-confirmation
+/** What the agent is told when its edit was put to the person. */
+export function firmEditContext(ids) {
+    const named = ids.slice(0, 2).join(", ");
+    return [
+        `Kibi asked the person to confirm this edit because it changes code that implements firm ${ids.length === 1 ? "requirement" : "requirements"} ${named}.`,
+        "If the edit was declined or could not be confirmed, the requirement stands: name it and ask the person how to proceed, rather than reaching the same change another way. If it was allowed and the change alters what the requirement says, the requirement is updated with kb_upsert in this change.",
+    ].join("\n");
+}
+/**
+ * Phrases that make a request read as a rule or decision. Matching is
+ * deliberately loose: the note it triggers only asks whether there is
+ * something to record.
+ */
+const RULE_PHRASES = /\b(?:from now on|going forward|must(?:n['’]t| not)?|should (?:always|never)|never|always|is not allowed|are not allowed|not be allowed|only (?:allow|admins?|owners?)|is required|are required|has to|have to)\b/i;
+// implements REQ-claude-decision-capture-nudges, REQ-agent-hosts-decision-guard
+/** The phrase that makes `prompt` read as a rule, or undefined. */
+export function statedRule(prompt) {
+    const match = RULE_PHRASES.exec(prompt);
+    return match ? match[0].toLowerCase() : undefined;
+}
+// implements REQ-claude-decision-capture-nudges, REQ-agent-hosts-decision-guard
+/** Prompt-time note for a request that reads as a rule or decision. */
+export function rulePromptNote(phrase) {
+    return [
+        `Kibi: this request reads as a rule or decision (it says "${phrase}").`,
+        "A rule the person states is project knowledge: kb_search shows whether a recorded requirement already says something about it (changing a firm one is a question for the person first), and a new or changed rule is recorded with kb_upsert (a requirement, firm because the person stated it, with the implements link from the code that enforces it) as part of this change, not after it.",
+    ].join("\n");
+}
+// implements REQ-claude-decision-capture-nudges, REQ-agent-hosts-decision-guard
+/**
+ * Stop-time note for a session that changed source files and wrote nothing
+ * to the knowledge base.
+ */
+export function captureReminder(rulePrompt) {
+    return [
+        rulePrompt
+            ? "Kibi: a request this session read as a rule or decision, the session changed source files, and nothing was recorded in the knowledge base."
+            : "Kibi: this session changed source files and recorded nothing in the knowledge base.",
+        "A decision the person stated or this change made (a rule, a limit, a default, who may do what) is recorded with kb_upsert as a requirement linked to the code that implements it before the work is reported done; when there was none, the final report says so in one line.",
+    ].join("\n");
+}
+// implements REQ-agent-hosts-decision-guard
+/**
+ * Pre-edit context for hosts whose pre-tool hook cannot put a call to the
+ * person: the edit is named as a change to the person's rule, and the agent
+ * is told to ask before making it unless it keeps the rule.
+ */
+export function firmEditNotice(where, requirements) {
+    const shown = requirements
+        .slice(0, 2)
+        .map((summary) => summary.title ? `${summary.id}: ${summary.title}` : summary.id);
+    const more = requirements.length > shown.length
+        ? ` (+${requirements.length - shown.length} more)`
+        : "";
+    const one = requirements.length === 1;
+    return [
+        `Kibi: this edit changes ${where}, which implements ${one ? "a firm requirement" : "firm requirements"}, a rule the person set: ${shown.join("; ")}${more}.`,
+        `Unless the edit keeps ${one ? "that rule" : "those rules"}, ask the person before making it and name the rule; change the requirement with kb_upsert in this change only when they say so.`,
+    ].join("\n");
+}
+function sessionPath(session, name) {
+    if (!session.stateDir)
+        return undefined;
+    const key = createHash("sha256")
+        .update(session.sessionId?.trim() || "unattributed")
+        .digest("hex")
+        .slice(0, 32);
+    return path.join(session.stateDir, "decision-guard", key, name);
+}
+function writeMarker(file, content, flag) {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, content, { flag });
+}
+// implements REQ-agent-hosts-decision-guard
+/** Set a session marker; best effort. */
+export function markDecisionFlag(session, flag) {
+    const file = sessionPath(session, flag);
+    if (!file)
+        return;
+    try {
+        writeMarker(file, "", "w");
+    }
+    catch {
+        // Markers are best effort; a lost one means a note may repeat or skip.
+    }
+}
+// implements REQ-agent-hosts-decision-guard
+export function hasDecisionFlag(session, flag) {
+    const file = sessionPath(session, flag);
+    return file !== undefined && fs.existsSync(file);
+}
+// implements REQ-agent-hosts-decision-guard
+/**
+ * True the first time `flag` is claimed in the session. Without a state
+ * directory nothing can be remembered, so nothing is claimed.
+ */
+export function claimDecisionFlag(session, flag) {
+    const file = sessionPath(session, flag);
+    if (!file)
+        return false;
+    try {
+        writeMarker(file, "", "wx");
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+// implements REQ-agent-hosts-decision-guard
+/**
+ * Remember a submitted prompt's topic words (for unlinked-file candidates)
+ * and whether it read as a rule. Returns the rule phrase, if any.
+ */
+export function recordRequest(session, prompt) {
+    const rule = statedRule(prompt);
+    const file = sessionPath(session, "request-words.json");
+    if (file) {
+        try {
+            writeMarker(file, JSON.stringify(requestTopicWords(prompt)), "w");
+        }
+        catch {
+            // Best effort.
+        }
+    }
+    if (rule !== undefined)
+        markDecisionFlag(session, "rule-prompt");
+    return rule;
+}
+// implements REQ-agent-hosts-decision-guard
+/** Topic words of the session's latest prompt, or none. */
+export function requestWords(session) {
+    const file = sessionPath(session, "request-words.json");
+    if (!file)
+        return [];
+    try {
+        const parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+        return Array.isArray(parsed)
+            ? parsed.filter((word) => typeof word === "string")
+            : [];
+    }
+    catch {
+        return [];
+    }
+}
+// implements REQ-agent-hosts-decision-guard
+/**
+ * Whether the stop should ask for the session's decision to be recorded:
+ * source changed, nothing was written with kb_upsert, and the session has
+ * not been asked yet (claiming the ask).
+ */
+export function claimCaptureReminder(session) {
+    return (hasDecisionFlag(session, "source-edited") &&
+        !hasDecisionFlag(session, "kb-recorded") &&
+        claimDecisionFlag(session, "capture-asked"));
+}
+function readSettled(file) {
+    if (!file)
+        return [];
+    try {
+        const parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+        return Array.isArray(parsed)
+            ? parsed.filter((id) => typeof id === "string")
+            : [];
+    }
+    catch {
+        return [];
+    }
+}
+// implements REQ-agent-hosts-decision-guard
+/** Firm requirements the agent was already told about this session. */
+export function settledFirmRequirements(session) {
+    return new Set(readSettled(sessionPath(session, "firm-settled.json")));
+}
+// implements REQ-agent-hosts-decision-guard
+/** Remember that the agent was told about these firm requirements. */
+export function settleFirmRequirements(session, ids) {
+    const file = sessionPath(session, "firm-settled.json");
+    if (!file)
+        return;
+    try {
+        writeMarker(file, JSON.stringify([...new Set([...readSettled(file), ...ids])]), "w");
+    }
+    catch {
+        // Best effort: a lost write means the notice may repeat.
+    }
+}
+// implements REQ-agent-hosts-decision-guard
+/**
+ * Keep a prompt's rule note for a host whose prompt hook cannot add context,
+ * so the next hook that can speak to the agent delivers it.
+ */
+export function holdRuleNote(session, phrase) {
+    const file = sessionPath(session, "rule-note");
+    if (!file)
+        return;
+    try {
+        writeMarker(file, rulePromptNote(phrase), "w");
+    }
+    catch {
+        // Best effort.
+    }
+}
+// implements REQ-agent-hosts-decision-guard
+/** The held rule note, removed so it is delivered once; or undefined. */
+export function takeRuleNote(session) {
+    const file = sessionPath(session, "rule-note");
+    if (!file)
+        return undefined;
+    try {
+        const note = fs.readFileSync(file, "utf8");
+        fs.rmSync(file, { force: true });
+        return note || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+export * from "./decision-guard.js";
 export * from "./hook-usage-log.js";
 export * from "./kb-mcp-tools.js";
 export * from "./knowledge-index.js";

package/dist/index.js

@@ -1,3 +1,4 @@
+export * from "./decision-guard.js";
 export * from "./hook-usage-log.js";
 export * from "./kb-mcp-tools.js";
 export * from "./knowledge-index.js";

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.8.0",
   "description": "Shared low-latency hook helpers for Kibi agent adapters",
   "type": "module",
   "main": "./dist/index.js",
@@ -10,6 +10,10 @@
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
+    "./decision-guard": {
+      "types": "./dist/decision-guard.d.ts",
+      "default": "./dist/decision-guard.js"
+    },
     "./hook-usage-log": {
       "types": "./dist/hook-usage-log.d.ts",
       "default": "./dist/hook-usage-log.js"