kibi-cli 2.19.0 → 2.20.0

package/dist/search-answer.js

@@ -65,6 +65,7 @@ export const SEARCH_ANSWER_LIMITS = {
     rationale: 3,
     notGoverning: 5,
     observations: 3,
+    ungoverned: 5,
     /** Entity rows loaded per answer, the matched seeds included. */
     entityLoads: 70,
     maxBytes: 16_384,
@@ -513,11 +514,12 @@ export async function buildSearchAnswer(prolog, matches, options = {}) {
             candidates.set(owner, { score, via });
     };
     const observations = [];
+    const ungoverned = [];
     const rationaleRows = new Map();
     // A matched test may verify a scenario rather than a requirement; its
     // targets are resolved to their governing requirements after the loop.
     const testTargets = [];
-    for (const match of seeds) {
+    for (const [index, match] of seeds.entries()) {
         const id = text(match.entity.id);
         const entity = graph.row(id) ?? match.entity;
         const type = text(entity.type || match.entity.type);
@@ -548,6 +550,18 @@ export async function buildSearchAnswer(prolog, matches, options = {}) {
             testTargets.push({ id, score: match.score, targets: owners });
             continue;
         }
+        if (owners.length === 0 && ["fact", "scenario", "symbol"].includes(type)) {
+            if (ungoverned.length < limits.ungoverned)
+                ungoverned.push({
+                    ...brief(entity),
+                    ...(type === "fact" ? factDetail(entity) : {}),
+                    type,
+                    rank: index + 1,
+                });
+            else
+                truncated = true;
+            continue;
+        }
         for (const owner of owners)
             propose(owner, match.score * 0.9, `${type} ${id}`);
     }
@@ -562,6 +576,15 @@ export async function buildSearchAnswer(prolog, matches, options = {}) {
     });
     const targetEdges = graph.edgesOf(targetIds);
     for (const test of testTargets) {
+        if (test.targets.length === 0) {
+            const row = graph.row(test.id);
+            const rank = seedIds.indexOf(test.id) + 1;
+            if (row !== null && ungoverned.length < limits.ungoverned)
+                ungoverned.push({ ...brief(row), type: "test", rank });
+            else if (row !== null)
+                truncated = true;
+            continue;
+        }
         for (const target of test.targets) {
             // A target that some requirement specifies is a scenario: lift the
             // test to that requirement. Anything else is a directly verified
@@ -746,20 +769,36 @@ export async function buildSearchAnswer(prolog, matches, options = {}) {
             ? verdicts.scope.syncedAt
             : null,
     };
+    ungoverned.sort((left, right) => left.rank - right.rank);
     const answer = {
         version: "kibi.search-answer.v1",
         governing,
         rationale,
         notGoverning,
         observations: observations.slice(0, limits.observations),
+        ungoverned,
         scope,
         truncated: truncated || graph.truncated,
-        note: governing.length === 0
-            ? "No current requirement matched or owns a matched entity. Absence here is not evidence that nothing governs the change; refine the query or pass sourceLocations."
-            : "Governing requirements are current requirements matched by the query or linked to a matched entity. Links are discovery, not proof. A verdict lists the contradiction and scenario-feasibility witnesses that name the requirement; none means no check named it, not that it is proven. Use kb_check and kb_coverage for consistency and proof status.",
+        note: answerNote(governing.length, ungoverned),
     };
     return fitSearchAnswer(answer, limits.maxBytes);
 }
+// implements REQ-search-answer-hygiene
+/**
+ * How to read the layer. When the top-ranked match is owned by no
+ * requirement, the note says so first: the governing list, if any, came from
+ * lower-ranked matches and is not the top match's requirement.
+ */
+function answerNote(governingCount, ungoverned) {
+    const top = ungoverned.find((entry) => entry.rank === 1);
+    const lead = top === undefined
+        ? ""
+        : `The top-ranked match ${top.id} (${top.type}) is linked to no requirement${governingCount === 0 ? "" : "; the governing requirements below were reached through lower-ranked matches"}. `;
+    return (lead +
+        (governingCount === 0
+            ? "No current requirement matched or owns a matched entity. Absence here is not evidence that nothing governs the change; refine the query or pass sourceLocations."
+            : "Governing requirements are current requirements matched by the query or linked to a matched entity. Links are discovery, not proof. A verdict lists the contradiction and scenario-feasibility witnesses that name the requirement; none means no check named it, not that it is proven. Use kb_check and kb_coverage for consistency and proof status."));
+}
 function byteSize(value) {
     return Buffer.byteLength(JSON.stringify(value), "utf8");
 }
@@ -784,6 +823,7 @@ function withoutExcerpt(entity) {
 const ANSWER_TRIM_ORDER = [
     "observations",
     "notGoverning",
+    "ungoverned",
     "rationale",
 ];
 const REQUIREMENT_TRIM_ORDER = [
@@ -838,6 +878,7 @@ export function fitSearchAnswer(answer, maxBytes = SEARCH_ANSWER_LIMITS.maxBytes
         rationale: current.rationale.map((adr) => clipRationale(adr, titleChars)),
         notGoverning: clipAll(current.notGoverning),
         observations: clipAll(current.observations),
+        ungoverned: clipAll(current.ungoverned),
     };
     // Excerpts are the most expendable text: drop them before any entry.
     for (let index = current.rationale.length - 1; index >= 0 && over(); index -= 1) {

package/dist/utils/branch-store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"branch-store.d.ts","sourceRoot":"","sources":["../../src/utils/branch-store.ts"],"names":[],"mappings":"AA0BA,mEAAmE;AACnE,eAAO,MAAM,yBAAyB,8BAA8B,CAAC;AACrE,yCAAyC;AACzC,eAAO,MAAM,8BAA8B,8BAA8B,CAAC;AAE1E,MAAM,MAAM,gBAAgB,GACxB,SAAS,GACT,SAAS,GACT,YAAY,GACZ,YAAY,CAAC;AAEjB,MAAM,MAAM,qBAAqB,GAAG,QAAQ,CAAC;IAC3C,KAAK,EAAE,gBAAgB,CAAC;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gBAAgB,EAAE,OAAO,CAAC;CAC3B,CAAC,CAAC;AAEH;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,aAAa,EAAE,MAAM,EACrB,MAAM,EAAE,MAAM,GACb,qBAAqB,CA0GvB;AAED;;;;GAIG;AAEH,wBAAgB,sBAAsB,CACpC,SAAS,EAAE,MAAM,GAChB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAiBhC;AAED;;;;;;GAMG;AAEH,wBAAgB,uBAAuB,CACrC,SAAS,EAAE,MAAM,EACjB,GAAG,GAAE,IAAiB,GACrB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAehC;AAED,wBAAgB,iBAAiB,CAC/B,UAAU,EAAE,qBAAqB,GAChC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAWhC;AA6BD;;;;GAIG;AAEH,wBAAgB,sBAAsB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAOpE;AAED,MAAM,MAAM,sBAAsB,GAAG,QAAQ,CAAC;IAC5C,oEAAoE;IACpE,QAAQ,EAAE,OAAO,CAAC;IAClB,0EAA0E;IAC1E,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B,CAAC,CAAC;AAEH;;;;;;GAMG;AAEH,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,qBAAqB,GAChC,sBAAsB,CAwBxB;AAkBD;;;;;;GAMG;AAEH,wBAAgB,2BAA2B,CACzC,aAAa,EAAE,MAAM,EACrB,UAAU,EAAE,qBAAqB,EACjC,MAAM,EAAE,MAAM,GACb,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAwBhC"}
+{"version":3,"file":"branch-store.d.ts","sourceRoot":"","sources":["../../src/utils/branch-store.ts"],"names":[],"mappings":"AA2BA,mEAAmE;AACnE,eAAO,MAAM,yBAAyB,8BAA8B,CAAC;AACrE,yCAAyC;AACzC,eAAO,MAAM,8BAA8B,8BAA8B,CAAC;AAE1E,MAAM,MAAM,gBAAgB,GACxB,SAAS,GACT,SAAS,GACT,YAAY,GACZ,YAAY,CAAC;AAEjB,MAAM,MAAM,qBAAqB,GAAG,QAAQ,CAAC;IAC3C,KAAK,EAAE,gBAAgB,CAAC;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gBAAgB,EAAE,OAAO,CAAC;CAC3B,CAAC,CAAC;AAEH;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,aAAa,EAAE,MAAM,EACrB,MAAM,EAAE,MAAM,GACb,qBAAqB,CA0GvB;AAED;;;;GAIG;AAEH,wBAAgB,sBAAsB,CACpC,SAAS,EAAE,MAAM,GAChB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAiBhC;AAED;;;;;;GAMG;AAEH,wBAAgB,uBAAuB,CACrC,SAAS,EAAE,MAAM,EACjB,GAAG,GAAE,IAAiB,GACrB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAmBhC;AAED,wBAAgB,iBAAiB,CAC/B,UAAU,EAAE,qBAAqB,GAChC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAWhC;AA6BD;;;;GAIG;AAEH,wBAAgB,sBAAsB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAOpE;AAED,MAAM,MAAM,sBAAsB,GAAG,QAAQ,CAAC;IAC5C,oEAAoE;IACpE,QAAQ,EAAE,OAAO,CAAC;IAClB,0EAA0E;IAC1E,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B,CAAC,CAAC;AAEH;;;;;;GAMG;AAEH,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,qBAAqB,GAChC,sBAAsB,CAwBxB;AAkBD;;;;;;GAMG;AAEH,wBAAgB,2BAA2B,CACzC,aAAa,EAAE,MAAM,EACrB,UAAU,EAAE,qBAAqB,EACjC,MAAM,EAAE,MAAM,GACb,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAwBhC"}

package/dist/utils/branch-store.js

@@ -4,7 +4,7 @@
 */
 import { existsSync, readFileSync, readdirSync, statSync, } from "node:fs";
 import * as path from "node:path";
-import { STORE_LOCK_TAKEOVER_VISIBLE_MS, classifyStoreLockHolder, readStoreLockOwner, readStoreLockTakeover, } from "../prolog/store-lock.js";
+import { FOREIGN_STORE_LOCK_REASON_PREFIX, STORE_LOCK_TAKEOVER_VISIBLE_MS, classifyStoreLockHolder, readStoreLockOwner, readStoreLockTakeover, } from "../prolog/store-lock.js";
 import { branchStoreManifestMatches, branchStorePath, legacyBranchStorePath, } from "./branch-store-locator.js";
 import { ENTITY_LANES, KB_ROOT } from "./kb-paths.js";
 /** Stale-reason code of a branch store that was never compiled. */
@@ -170,7 +170,9 @@ export function storeLockTakeoverReason(storePath, now = new Date()) {
         brokenPid: record.brokenPid,
         reason: record.reason,
         at: record.at,
-        detail: `Kibi broke a stale branch-store lock at ${record.at} (${record.reason || "holder no longer running"}) and reattached. Nothing needs repair; a holder that died while it held the store usually means an engine or kibi prove run crashed or was killed.`,
+        detail: `Kibi broke a stale branch-store lock at ${record.at} (${record.reason || "holder no longer running"}) and reattached. Nothing needs repair; ${record.reason.startsWith(FOREIGN_STORE_LOCK_REASON_PREFIX)
+            ? "the lock files were copied with the .kb directory (for example by cp -a) while another workspace's engine held its own store."
+            : "a holder that died while it held the store usually means an engine or kibi prove run crashed or was killed."}`,
     };
 }
 export function branchStoreReason(inspection) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kibi-cli",
-  "version": "2.19.0",
+  "version": "2.20.0",
   "type": "module",
   "description": "Kibi CLI for knowledge base management",
   "engines": {
@@ -235,8 +235,8 @@
     "fast-glob": "^3.2.12",
     "gray-matter": "^4.0.3",
     "js-yaml": "^4.1.0",
-    "kibi-core": "^0.20.0",
-    "kibi-plugin-builtin": "^0.5.0",
+    "kibi-core": "^0.21.0",
+    "kibi-plugin-builtin": "^0.5.1",
     "kibi-plugin-sdk": "^0.5.0",
     "kibi-swipl": "^1.0.1",
     "saxes": "^6.0.0",

package/src/public/operations/check-executor.ts

@@ -26,6 +26,7 @@ import type { Violation } from "../check-types.js";
 import { collectFullKbQualityDiagnostics } from "../impact-diagnostics.js";
 import {
   type CheckDiagnostic,
+  type CheckEvaluated,
   type CheckStructuredContent,
   buildStructuredContent,
   buildSummary,
@@ -70,7 +71,7 @@ export type CheckInput = {
 };
 
 export type CheckPayload = CheckStructuredContent;
-export type { CheckDiagnostic, CheckStructuredContent };
+export type { CheckDiagnostic, CheckEvaluated, CheckStructuredContent };
 export {
   buildStructuredContent,
   buildSummary,
@@ -90,6 +91,38 @@ export type CheckExecutionOptions = {
   readonly branchStoreAttached?: boolean;
 };
 
+// implements REQ-search-answer-hygiene
+/**
+ * What this run evaluated: the rules that ran, in registry order, and for
+ * `domain-contradictions` the number of requirement fact pairs the rule
+ * compared, read from the engine after the rules ran on the same store. A
+ * count the engine cannot give (an older engine) is left out rather than
+ * reported as zero.
+ */
+async function describeEvaluation(
+  prolog: PrologPort,
+  rules: ReadonlySet<string>,
+): Promise<CheckEvaluated> {
+  const evaluated: {
+    rules: string[];
+    domainContradictions?: { factPairsExamined: number };
+  } = {
+    rules: [...rules],
+  };
+  if (!rules.has("domain-contradictions")) return evaluated;
+  try {
+    const result = await prolog.query(
+      "kb_domain_contradiction_pairs_examined(Count)",
+    );
+    const count = Number(result.bindings.Count);
+    if (result.success && Number.isInteger(count) && count >= 0)
+      evaluated.domainContradictions = { factPairsExamined: count };
+  } catch {
+    // An engine without the predicate leaves the count out.
+  }
+  return evaluated;
+}
+
 function requireProlog(context: OperationContext): PrologPort {
   if (context.prolog === undefined) {
     throw new Error("Check operation requires a Prolog runtime");
@@ -226,12 +259,15 @@ export async function executeCheck(
         [],
         statusPlan,
       );
+      // Every store-backed rule was skipped: only this one was evaluated.
+      const evaluated = { rules: [BRANCH_STORE_NOT_COMPILED_RULE] };
       return {
         content: [
           {
             type: "text",
             text: buildSummary({
               violations,
+              evaluated,
               impactResult,
               qualityDiagnostics: [],
             }),
@@ -239,6 +275,7 @@ export async function executeCheck(
         ],
         structuredContent: buildStructuredContent({
           violations,
+          evaluated,
           diagnostics: [
             {
               category: "SYNC_ERROR",
@@ -283,12 +320,14 @@ export async function executeCheck(
         >[],
         statusPlan,
       );
+      const evaluated = { rules: [] };
       return {
         content: [
           {
             type: "text",
             text: buildSummary({
               violations: [],
+              evaluated,
               impactResult,
               qualityDiagnostics,
             }),
@@ -296,6 +335,7 @@ export async function executeCheck(
         ],
         structuredContent: buildStructuredContent({
           violations: [],
+          evaluated,
           diagnostics: [],
           qualityDiagnostics,
           impactResult,
@@ -351,6 +391,7 @@ export async function executeCheck(
       ...checkPolicyFindings,
     ]);
     const violations: Violation[] = partitioned.violations;
+    const evaluated = await describeEvaluation(prolog, rulesAllowlist);
 
     const diagnostics: CheckDiagnostic[] = violations.map((v) => ({
       category: "SYNC_ERROR",
@@ -396,6 +437,7 @@ export async function executeCheck(
           type: "text",
           text: buildSummary({
             violations,
+            evaluated,
             impactResult,
             qualityDiagnostics,
           }),
@@ -403,6 +445,7 @@ export async function executeCheck(
       ],
       structuredContent: buildStructuredContent({
         violations,
+        evaluated,
         diagnostics,
         qualityDiagnostics,
         impactResult,

package/src/public/operations/check-format-shared.ts

@@ -29,10 +29,22 @@ export interface CheckDiagnostic {
   readonly suggestion?: string;
 }
 
-// implements REQ-mcp-tool-check
+/**
+ * What a check run evaluated, so "no violations" can be told apart from
+ * "nothing evaluated": the rules that ran, and for `domain-contradictions`
+ * how many pairs of requirement facts it compared.
+ */
+// implements REQ-search-answer-hygiene
+export interface CheckEvaluated {
+  readonly rules: readonly string[];
+  readonly domainContradictions?: Readonly<{ factPairsExamined: number }>;
+}
+
+// implements REQ-mcp-tool-check, REQ-search-answer-hygiene
 export interface CheckStructuredContent {
   readonly violations: readonly Violation[];
   readonly count: number;
+  readonly evaluated: CheckEvaluated;
   readonly diagnostics: readonly CheckDiagnostic[];
   readonly qualityDiagnostics?: readonly QualityDiagnostic[];
   readonly impactDiagnostics?: ChangedFileImpactResult["impactDiagnostics"];
@@ -139,6 +151,7 @@ export function formatViolationText(violations: readonly Violation[]): string {
 // implements REQ-mcp-tool-check
 export function buildStructuredContent(input: {
   violations: readonly Violation[];
+  evaluated: CheckEvaluated;
   diagnostics: readonly CheckDiagnostic[];
   qualityDiagnostics?: readonly QualityDiagnostic[];
   impactResult: ChangedFileImpactResult | undefined;
@@ -148,6 +161,12 @@ export function buildStructuredContent(input: {
   return {
     violations: [...input.violations],
     count: input.violations.length,
+    evaluated: {
+      rules: [...input.evaluated.rules],
+      ...(input.evaluated.domainContradictions !== undefined
+        ? { domainContradictions: input.evaluated.domainContradictions }
+        : {}),
+    },
     diagnostics: formatDiagnostics(input.diagnostics),
     ...(qualityDiagnostics.length > 0
       ? { qualityDiagnostics: [...qualityDiagnostics] }
@@ -168,12 +187,27 @@ export function buildStructuredContent(input: {
 }
 
 // implements REQ-mcp-tool-check
+// implements REQ-search-answer-hygiene
+/** One line saying what the check evaluated, so a clean result is readable. */
+export function formatEvaluatedText(evaluated: CheckEvaluated): string {
+  const rules =
+    evaluated.rules.length === 0
+      ? "Evaluated no rules"
+      : `Evaluated ${evaluated.rules.length} rule${evaluated.rules.length === 1 ? "" : "s"}`;
+  const pairs = evaluated.domainContradictions;
+  if (pairs === undefined) return `${rules}.`;
+  return `${rules}; domain-contradictions compared ${pairs.factPairsExamined} fact pair${pairs.factPairsExamined === 1 ? "" : "s"}${pairs.factPairsExamined === 0 ? " (no two current requirements constrain the same subject or predicate case)" : ""}.`;
+}
+
 export function buildSummary(input: {
   readonly violations: readonly Violation[];
+  readonly evaluated?: CheckEvaluated;
   readonly impactResult: ChangedFileImpactResult | undefined;
   readonly qualityDiagnostics: readonly QualityDiagnostic[];
 }): string {
   const sections = [formatViolationText(input.violations)];
+  if (input.evaluated !== undefined)
+    sections.push(formatEvaluatedText(input.evaluated));
   if (input.impactResult !== undefined) {
     sections.push(formatImpactText(input.impactResult));
   }

package/src/public/operations/contracts.ts

@@ -449,6 +449,7 @@ const BASE_DATA_SCHEMAS: Readonly<
     {
       results: valueArray,
       count: integerValue,
+      returned: integerValue,
       truncated: booleanValue,
       queryAnalysis: recordValue,
       answer: recordValue,
@@ -573,6 +574,11 @@ const BASE_DATA_SCHEMAS: Readonly<
     recommendedPredicateSchema: { type: ["object", "null"] },
     applyPlan: recordArray,
     relationshipPlan: { type: ["object", "null"] },
+    plan: {
+      type: ["object", "null"],
+      description:
+        "With requirementId and a complete candidate: the hash-bound kibi.compile-plan.v1 that writes the predicate fact and links requires_predicate in one kb_apply_plan call (approvedPlanHash = plan.planHash). Its contradictionAnalysis is the what-if over the current KB plus the plan; a conflict leaves the plan blocked. Null when no plan applies.",
+    },
     relationshipTarget: {
       type: ["string", "null"],
       description:
@@ -629,6 +635,8 @@ const BASE_DATA_SCHEMAS: Readonly<
     warnings: valueArray,
     semanticAdvisor: nullableJsonSchema(recordValue),
     normalizedPreview: nullableJsonSchema(recordValue),
+    stagedFacts: stringArray,
+    whatIf: recordValue,
   }),
   kb_upsert: {
     description:
@@ -653,6 +661,8 @@ const BASE_DATA_SCHEMAS: Readonly<
           warnings: valueArray,
           semanticAdvisor: nullableJsonSchema(recordValue),
           normalizedPreview: nullableJsonSchema(recordValue),
+          stagedFacts: stringArray,
+          whatIf: recordValue,
           dryRun: { const: true },
           skippedEffects: stringArray,
         },
@@ -683,6 +693,7 @@ const BASE_DATA_SCHEMAS: Readonly<
       objectData({
         violations: valueArray,
         count: integerValue,
+        evaluated: recordValue,
         diagnostics: recordArray,
         qualityDiagnostics: recordArray,
         impactDiagnostics: recordArray,

package/src/public/operations/discovery-executors.ts

@@ -151,7 +151,10 @@ export type SearchInput = {
 
 export type SearchPayload = {
   readonly results: readonly (SearchMatch | IntentSearchMatch)[];
+  /** Matches in the whole ranking, before `limit` and `offset`. */
   readonly count: number;
+  /** Rows in `results`: the page this call returned. */
+  readonly returned: number;
   readonly truncated?: boolean;
   readonly queryAnalysis?: IntentSearchAnalysis;
   readonly answer?: SearchAnswer;
@@ -772,7 +775,7 @@ export async function executeSearch(
   const {
     query,
     type,
-    limit = 20,
+    limit = 10,
     offset = 0,
     rankingMode = "intent-v1",
     semanticFacets,
@@ -829,6 +832,11 @@ export async function executeSearch(
           : undefined;
       // The structured payload carries every row; the text is a short
       // human-readable digest instead of a second copy of the results.
+      // A top match no requirement owns is said in the digest too, so the
+      // governing list is never read as the top match's requirement.
+      const topUngoverned = answerLayer?.ungoverned.find(
+        (entry) => entry.rank === 1,
+      );
       const text = `${
         intentResult.matches.length === 0
           ? `No intent search results for '${trimmedQuery}' (abstained).`
@@ -837,13 +845,14 @@ export async function executeSearch(
               .map((match) => String(match.entity.id ?? ""))
               .join(
                 ", ",
-              )}${answerLayer ? `. Governing: ${answerLayer.governing.map((req) => req.id).join(", ") || "none found"}` : ""}.`
+              )}${answerLayer ? `. Governing: ${answerLayer.governing.map((req) => req.id).join(", ") || "none found"}` : ""}${topUngoverned ? ` (the top match ${topUngoverned.id} is linked to no requirement)` : ""}.`
       }${storeNote}`;
       return {
         content: [{ type: "text", text }],
         structuredContent: {
           results: await projectMatches(prolog, paginated, fields),
           count: intentResult.matches.length,
+          returned: paginated.length,
           truncated: offset + paginated.length < intentResult.matches.length,
           queryAnalysis: intentResult.analysis,
           ...(answerLayer ? { answer: answerLayer } : {}),
@@ -883,6 +892,7 @@ export async function executeSearch(
       structuredContent: {
         results: await projectMatches(prolog, paginated, fields),
         count: matches.length,
+        returned: paginated.length,
         truncated: offset + paginated.length < matches.length,
         ...branchFields,
       },

package/src/public/operations/specs/composite.ts

@@ -217,7 +217,7 @@ export const modelSpec = {
   name: "kb_model",
   cliName: "model",
   description:
-    "Turn requirement prose into checkable structure without writing the KB. mode:analyze returns the semantic advisor receipt: the clause ledger, what is grounded, what is ambiguous and suggested modeling (pass clauses for compound prose and optional typed kibi.logic.v1 interpretations). mode:requirement converts one claim (subjectKey, propertyKey, operator, value, or typed logic) into a strict-lane write set and applyPlan. mode:predicates ranks ontology predicate schemas and returns an applicable predicate-fact plan only for reviewed bindings, otherwise an ontology-gap observation. Apply returned plans with kb_upsert.",
+    "Turn requirement prose into checkable structure without writing the KB. mode:analyze returns the semantic advisor receipt: the clause ledger, what is grounded, what is ambiguous and suggested modeling (pass clauses for compound prose and optional typed kibi.logic.v1 interpretations). mode:requirement converts one claim (subjectKey, propertyKey, operator, value, or typed logic) into a strict-lane write set and applyPlan. mode:predicates ranks ontology predicate schemas and returns an applicable predicate-fact plan only for reviewed bindings, otherwise an ontology-gap observation. With requirementId, mode:predicates also returns a hash-bound plan (fact write plus requires_predicate link) for kb_apply_plan, whose contradictionAnalysis is the what-if over the current KB; other returned plans apply with kb_upsert, and kb_upsert dryRun with plannedFacts previews a requirement before its facts exist.",
   businessInputSchema: {
     type: "object",
     required: ["mode", "text"],

package/src/public/operations/specs/discovery.ts

@@ -165,8 +165,9 @@ export const searchSpec = {
       limit: {
         type: "integer",
         minimum: 0,
-        default: 20,
-        description: "Optional max rows to return after ranking. Default: 20.",
+        default: 10,
+        description:
+          "Optional max rows to return after ranking. Default: 10; raise it or page with offset when the answer layer is not enough.",
       },
       offset: {
         type: "integer",

package/src/public/operations/specs/upsert.ts

@@ -38,6 +38,21 @@ export const upsertSpec = {
         description:
           "Validate the payload and return schema/modeling errors, a normalized preview and the semantic advisor receipt without writing the KB or workspace. Use it as the preflight before the real write.",
       },
+      plannedFacts: {
+        type: "array",
+        description:
+          "dryRun only. Fact upsert payloads (type, id, properties, optional relationships) that will be written before this payload, typically the applyPlan entries kb_model returned. They are validated in order and staged with the payload, so a requires_predicate or requires_property target that does not exist yet resolves, its claim_key is read from the plan, and the contradiction preview runs against the KB as it would be after the whole batch (result: stagedFacts, whatIf). A conflict the batch would introduce, such as an allow and a deny permission_rule on the same key, is refused as the commit would refuse it. Rejected without dryRun: write the facts first.",
+        items: {
+          type: "object",
+          required: ["type", "id", "properties"],
+          properties: {
+            type: { type: "string", const: "fact" },
+            id: { type: "string", minLength: 1 },
+            properties: { type: "object" },
+            relationships: RELATIONSHIPS_SCHEMA,
+          },
+        },
+      },
       document: {
         type: "object",
         additionalProperties: false,

package/src/public/skills/kibi-usage/SKILL.md

@@ -2,7 +2,7 @@
 id: kibi-usage
 name: Kibi Usage
 description: Use Kibi's source-first, exact-Git, migration-aware, proof-aware operations safely across MCP or the trusted local CLI, including partial completion repair.
-version: 2.15.0
+version: 2.15.2
 kibiCompatibility: ">=1.0.0"
 tags:
   - kibi
@@ -82,6 +82,41 @@ different workspace than the one you asked for; its `detail.reason` says why.
 Use the CLI from your working directory instead: `npx --no-install kibi ...`
 runs where you are and needs no `workspaceRoot`.
 
+## Reading a hook snippet
+
+On hosts where Kibi hooks are installed, a short block
+arrives before you read or edit a file whose symbols are linked to
+requirements. It is projected from `.kb/symbols.yaml`, not from the store, so
+it is a pointer to the knowledge, never proof. Each line answers one question:
+
+- `Kibi knowledge for <path> (symbol manifest):` and the `- REQ-… — <symbol
+  titles>` rows: the requirements the file's symbols implement, lead
+  requirement first. Read the lead requirement with `kb_query({id})` before
+  changing behavior.
+- `REQ-… must keep true: FACT-…` (edit only): the ground facts the lead
+  requirement requires. An edit that breaks one of them is a requirement
+  change: supersede and remodel the requirement, do not code around the fact.
+- `Decision: ADR-…` (edit only): the decision behind the lead requirement.
+- `Covered by: TEST-…` and `Test code for: …`: the tests that prove the
+  file's symbols; run or update them with the edit.
+- `The edit is inside <symbol>, which implements REQ-…`: the symbol the edit
+  lands in.
+- `Next layer: …`: the exact `kb_query` and `kb_search(... sourceLocations)`
+  calls that return the full detail.
+- The `kb_check({sourceFiles:[…], includeImpactDiagnostics:true,
+  includeWorkingTreeDiff:true})` line (edit only): run it after the edit. The
+  Stop hook reminds you once per session of files edited without it.
+
+A file already shown this session gets only the one-line `Kibi: this edit to
+<path> is inside <symbol>` update; the facts and tests from its first snippet
+still apply. `Kibi: no symbol in <path> is linked to a requirement yet` means
+the file is unowned: find the governing requirement with `kb_search` and
+`sourceLocations`, then link a symbol to it with `implements` through
+`kb_upsert`. Without a readable manifest (`Kibi: the hook could not read
+.kb/symbols.yaml`) snippets are off for this session; `kb_query({sourceFile})`
+still answers and `kibi sync` regenerates the manifest. The search tip and the
+`.kb/` note appear once per session and need no action.
+
 ## Safe workflow
 
 1. Always discover before you mutate: start with `kb_search`, then exact-filter with `kb_query`. Use

package/src/public/skills/kibi-usage/resources/fact-lanes.md

@@ -68,14 +68,16 @@ id: FACT-SUSPENDED-PUBLISH-DENIED
 status: active
 fact_kind: predicate
 predicate_name: permission_rule
-predicate_args: [suspended_user, publish, articles, deny]
+predicate_args: [suspended_user, publish, article, deny]
 polarity: deny
-canonical_key: permission_rule(suspended_user,publish,articles,deny)
+canonical_key: permission_rule(suspended_user,publish,article,deny)
 claim_key: <advisor-issued key for this exact clause>
 claim_text: Suspended users must not publish articles.
 relationship: { type: requires_predicate, from: REQ-SUSPENDED-PUBLISH-DENIED, to: FACT-SUSPENDED-PUBLISH-DENIED }
 ```
 
+Inferred bindings drop the article and singularise the resource (`articles` becomes `article`, `any analysis request` and `analysis requests` both become `analysis_request`), so an allow and a deny on the same actor, action and resource share one key. Grants read the same as `allowed`: `may`, `can`, `is allowed to`, `are permitted to`, `must be able to`, `are able to`, `have permission to` and `are entitled to` all select `permission_rule` with `polarity: assert`.
+
 If another current requirement links an `assert` fact with the same predicate namespace, name, and ordered arguments, `domain-contradictions` reports the pair. More complex semantic conflicts require a shared canonical schema and arguments; do not assume Kibi can prove arbitrary equivalence between differently shaped predicates.
 
 The full logical representation of a requirement is the conjunction of all of its linked ground property and predicate terms. Conditions, exceptions, permissions, and ordering constraints remain explicit arguments of their declared schemas. Contradiction detection therefore depends on equivalent prose reusing the same predicate name, argument roles, ordered canonical values, and opposing polarity rather than inventing synonymous terms.